Add comprehensive Reference.md documentation #176

alexkwolfe · 2025-06-09T23:25:56Z

Created Reference.md with complete documentation for all 21 types
Includes detailed examples, component extraction, and operator information
Documents aggregation behavior and maskable types
Added link to Reference.md in README for easy discovery

🤖 Generated with Claude Code

Description of the change

Added Reference.md that includes more comprehensive documentation about how the types system works.

Type of change

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Configuration change
Technical Debt
Documentation

Related tickets

None

Checklists

Development and Testing

Lint rules pass locally.
The code changed/added as part of this pull request has been covered with tests, or this PR does not alter production code.
All tests related to the changed code pass in development, or tests are not applicable.

Code Review

This pull request has a descriptive title and information useful to a reviewer. There may be a screenshot or screencast attached.
At least two engineers have been added as "Reviewers" on the pull request.
Changes have been reviewed by at least two other engineers who did not write the code.
This branch has been rebased off master to be current.

Tracking

Issue from Shortcut/Jira has a link to this pull request.
This PR has a link to the issue in Shortcut.

QA

This branch has been deployed to staging and tested.

- Created Reference.md with complete documentation for all 21 types - Includes detailed examples, component extraction, and operator information - Documents aggregation behavior and maskable types - Added link to Reference.md in README for easy discovery 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

- Renamed document from "LeadConduit Types - Complete Documentation" to "Types Reference" - Corrected maskable type documentation for SSN, DOB, and Credential - Clarified that NO components are preserved after processing for maskable types - Updated examples to show data is only available during processing - Made it clear that all maskable data becomes asterisks with no accessible components 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

- Added Important Limitation section explaining that valid only checks area code/exchange - Clarified that the line portion (last 4 digits) is not verified for connectivity - Recommended third-party services (Trestle, Telesign, BriteVerify) for deliverability - Corrected international number handling - they return valid: false, not parsed - Added "What It Does NOT Verify" section listing connectivity limitations - Updated geographic limitation to be clearer about international numbers 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

jgrayson676

Found a few spots with incorrect or unclear information

jgrayson676 · 2025-06-10T15:19:01Z

Reference.md

+"  Chicago  " → "Chicago"  // Whitespace trimmed
+```
+
+**Field Examples:** City, Property City, Employer City


Are these examples meant to be standard fields within LC? If so, a lot of these are incorrect: Employer City, Application Date, Co-Borrower Email, etc.

jgrayson676 · 2025-06-10T15:23:23Z

Reference.md

+
+---
+
+### DOB Type (Date of Birth)


This section is incorrect, only the month and day are masked

jgrayson676 · 2025-06-10T15:24:26Z

Reference.md

+No components accessible - all values masked
+```
+
+**Field Examples:** DOB, Mortgage Co-Borrower DOB, Spouse DOB


IMO these examples are especially misleading. dob isn't currently used for any standard fields in production.

jgrayson676 · 2025-06-10T15:28:27Z

Reference.md

+
+Comprehensive phone number parsing and validation for US/Canada numbers with real-world verification.
+
+**Geographic Limitation**: Currently only supports US and Canadian phone numbers. International numbers from other countries will be marked as invalid (valid: false) and will not parse correctly, even if they have a valid format in their home country.


This is only partially correct. Parsing assumes a US or Canadian number, however if the number includes a country code that will be used instead.

jgrayson676 · 2025-06-10T15:56:32Z

Reference.md

+"$1,000 to $10,000" → min: 1000, max: 10000
+
+Special Cases:
+"787041234" → "78704-1234" (9 digits treated as ZIP+4)


I have no idea where this is coming from

jgrayson676 · 2025-06-10T16:03:02Z

Reference.md

+
+Some types contain sensitive data that are automatically masked for security:
+- **SSN**: Social Security Numbers - all components masked
+- **DOB**: Dates of birth - all components masked (including age and year)


Same issue as the dob section above

jgrayson676 · 2025-06-10T16:10:25Z

Reference.md

+  Area: "512",
+  Exchange: "789",
+  Is Tollfree: false
+}


Missing country_calling_code

cgrayson

Some questions and feedback inline; but one main thing that wasn't clear was: who this reference is for? LC app users? API users? Internal engineering? External engineering?

cgrayson · 2025-06-10T21:51:38Z

Reference.md

+**Supported Formats:**
+- US: `M/D/YYYY` (`6/2/2014`), `M/D/YY` (`6/2/14`), `MM-DD-YYYY` (`06-02-2014`)
+- ISO: `YYYY-MM-DD` (`2014-06-02`)
+- European: `D/M/YYYY` (`18/7/2014`), `D-M-YYYY` (`18-7-2014`)


Should probably specify precedence of M/D formats over D/M, & how that works.

cgrayson · 2025-06-10T21:57:05Z

Reference.md

+- Format for display: `{{Phone 1 > Area}}-{{Phone 1 > Exchange}}-{{Phone 1 > Line}}`
+- Check validity: `Phone 1 > Valid is true`
+
+**Important Limitation**: The `valid` property only confirms the area code and exchange are legitimate - it does NOT verify the full number is connected or deliverable. The "line" portion (last 4 digits) could still be invalid or disconnected. For true deliverability verification, use third-party Add-On services like Trestle, Telesign, or BriteVerify in a flow step to collect carrier-level metadata, then evaluate the appended data in a subsequent filter step to block disconnected numbers.


This is mostly duplication of validation/verification information above. I'd either merge them or cut this.

cgrayson · 2025-06-10T21:59:04Z

Reference.md

+"$1,000 to $10,000" → min: 1000, max: 10000
+
+Special Cases:
+"787041234" → "78704-1234" (9 digits treated as ZIP+4)


cgrayson · 2025-06-10T22:01:26Z

Reference.md

+- Send to integration: `{{Social Security Number > Last Four}}`
+- Check if provided: `Social Security Number > Valid is true`
+
+**Note:** After processing completes, these components are NOT available


"Processing" used throughout this section seems vague to me. "Lead-handling", maybe? And/or tied to previous core ideas above.

cgrayson · 2025-06-10T22:02:49Z

Reference.md

+- Must be HTTPS
+- Must be from valid TrustedForm domain
+- Certificate expires after 90 days
+- Environment must match (production/staging)


cgrayson · 2025-06-10T22:23:18Z

Reference.md

+IF Postal Code > Country Code equals "US" THEN use US validation
+```
+
+## Integration with LeadConduit


All this, except analytics: repetitive & introductory

cgrayson · 2025-06-10T22:24:18Z

Reference.md

+5. **Storage** uses normalized format
+6. **Delivery** can use any component
+
+### Analytics and Aggregation


Hey! New & useful info 🎉 Might belong earlier in the doc (or at least a mention of it)

cgrayson · 2025-06-10T22:26:58Z

Reference.md

+}
+```
+
+**Types That Don't Aggregate (Privacy):**


I would have put most of the rest of this section (except maybe "use cases") in the "what is?" section.

cgrayson · 2025-06-10T22:31:52Z

Reference.md

+
+This aggregation system ensures analytics remain powerful while protecting individual privacy by never storing complete personal information in reporting systems.
+
+## Best Practices


Another section that I'm afraid I see no value in. Some of it is prescriptive ("Be specific"), and some isn't ("Parse once"). And some of it is nonsense. "Plan for analytics"? No user – whether an LC end-user or a developer using this Node library – needs to plan for analytics. Or consider components, or think about validation, etc. As long as they don't use string for everything, they get all that for free, that's the whole point.

cgrayson · 2025-06-10T22:33:50Z

Reference.md

+3. **Normalize for storage**: Consistent format improves queries
+4. **Aggregate thoughtfully**: Only extract needed analytics data
+
+## Common Misconceptions


Silly, and adding very little, imo.

alexkwolfe requested review from cgrayson and jgrayson676 June 9, 2025 23:25

alexkwolfe temporarily deployed to test June 9, 2025 23:33 — with GitHub Actions Inactive

alexkwolfe temporarily deployed to test June 10, 2025 00:15 — with GitHub Actions Inactive

jgrayson676 requested changes Jun 10, 2025

View reviewed changes

cgrayson requested changes Jun 10, 2025

View reviewed changes


		Comprehensive phone number parsing and validation for US/Canada numbers with real-world verification.

		Geographic Limitation: Currently only supports US and Canadian phone numbers. International numbers from other countries will be marked as invalid (valid: false) and will not parse correctly, even if they have a valid format in their home country.


		This aggregation system ensures analytics remain powerful while protecting individual privacy by never storing complete personal information in reporting systems.

		## Best Practices

Add comprehensive Reference.md documentation #176

Are you sure you want to change the base?

Add comprehensive Reference.md documentation #176

Uh oh!

Conversation

alexkwolfe commented Jun 9, 2025

Description of the change

Type of change

Related tickets

Checklists

Development and Testing

Code Review

Tracking

QA

Uh oh!

jgrayson676 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cgrayson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants