fix: normalize funding receipt from/to/for field types

[holkexyz]

Summary

• from and to on funding.receipt are now both plain strings accepting a DID or name — symmetric and consistent with how contributorInformation.identifier works elsewhere in the protocol.
• from is now optional (removed from required), allowing anonymous funding.
• for changed from at-uri string to strongRef for content-hash verification, consistent with all other cross-record references in the protocol.

Why

from/to symmetry: from was a typed DID ref while to was a free-text string. This asymmetry forced the sender to have an AT Protocol identity while the recipient could be anyone — the opposite of how funding often works (anonymous donors, named recipients). Making both plain strings with the same constraints treats senders and recipients uniformly.

from optional: Required from prevented recording anonymous donations. The previous workaround ("leave empty") contradicted the required constraint.

for as strongRef: An at-uri only identifies a record by path — it doesn't pin to a specific version. If the referenced activity is updated, the funding receipt's meaning could drift. strongRef includes a content hash (CID), ensuring the receipt always points to the exact state of the activity it funded.

Test plan

• npm run check passes
• Generated types reflect all field type changes

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Normalized funding receipt fields: from is now optional and may be a DID or a strong reference (allowing omission), to accepts DID or strong references instead of plain text, and for is a structured strong reference for stronger linkage.

• Tests

  • Updated validation tests to reflect the new typed formats and added positive cases for DID and strong-reference variants.

• Chores

  • Added a release changeset for this minor update.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4408f61

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hypercerts-org/lexicon	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: eccee1fc-fce1-4248-881d-aaece955877c

📥 Commits

Reviewing files that changed from the base of the PR and between 0d20609 and 4408f61.

📒 Files selected for processing (1)

• tests/validate-funding-receipt.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/validate-funding-receipt.test.ts

---

📝 Walkthrough

Walkthrough

The PR normalizes the org.hypercerts.funding.receipt lexicon: from becomes an optional union (DID | strongRef), to becomes a union (DID | strongRef), and for becomes a strongRef ref. Changes include schema, docs/changeset, and updated tests.

Changes

Cohort / File(s)	Summary
Schema Definition lexicons/org/hypercerts/funding/receipt.json	Changed from from ref → union [app.certified.defs#did,com.atproto.repo.strongRef]; to from string → same union; for from string → ref com.atproto.repo.strongRef.
Documentation & Metadata .changeset/funding-receipt-field-types.md, SCHEMAS.md	Added a minor changeset documenting the normalization; updated SCHEMAS.md to reflect new types and descriptions for from, to, and for.
Tests tests/validate-funding-receipt.test.ts	Updated fixtures and assertions to use typed DID and strongRef objects, added positive tests for union variants, and adjusted negative cases to match new structure.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• refactor: improve acknowledgement schema #153 — Modifies the same funding.receipt fields (from, to, for) to adjust types and references.
• add funding receipt schema #37 — Earlier PR that introduced the funding.receipt lexicon now being updated.
• [HYPER-120] add app.certified.link.evm lexicon for ATProto-EVM identity linking #166 — Adds/defines app.certified.defs#did, which this PR references in from/to unions.

Suggested reviewers

• aspiers
• pheuberger

Poem

🐰 Hoppity schema, neat and bright,
From, to, and for now sleep alright.
DIDs and strongRefs twine and play,
Tests updated to light the way,
A rabbit cheers this tidy sight!

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 1 warning)

Check name	Status	Explanation	Resolution
Lexicon Documentation Sync	❌ Error	README.md entry for org.hypercerts.funding.receipt lexicon is out of sync with updated schema changes in the JSON lexicon file.	Update README.md to document that from/to are unions of DID or strongRef, from is optional for anonymity, and for is an optional strong reference.
Lexicons Styleguide Compliance	⚠️ Warning	The for field's strongRef description lacks required lexicon type documentation as mandated by ATProto style guide.	Update the description to explicitly document target lexicon types using 'lexicon' or 'conform' keywords, e.g., 'must conform with lexicon org.hypercerts.claim.activity'.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: normalization of funding receipt field types (from/to/for). It is concise, clear, and directly reflects the changeset's core objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/funding-receipt-field-types

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[s-adamantine]

This PR implemented it in the wrong direction. During the call we

• Decided to make from, to, and for consistent by moving them all toward the more structured, ref‑based pattern, not plain strings.
• Direction was: change from and to to a union that can handle both DIDs and strongRefs, and change for to a strongRef as well, so all three behave consistently and align with other cross‑record references.

This is a breaking change.

[s-adamantine]

As we didn't realize that this is a breaking change during the call, this PR will be deferred until I can check that the breaking change is not too breaking

[aspiers]

Marked as draft to align with the above comments.

[s-adamantine]

Marked as draft to align with the above comments.

Thanks Adam. Just synced with Satyam, and this is good to merge.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@tests/validate-funding-receipt.test.ts`:
- Around line 133-136: The test currently passes an invalid `to` shape so
validation can fail for the wrong reason; update the "should reject a record
missing the required 'createdAt' field" test to use a valid `to` object shape
matching the updated union fixtures (instead of the current `{ to: { did: ... }
}`) and remove only the `createdAt` property so the validator (call site:
validate, schema identifier: ids.OrgHypercertsFundingReceipt) fails specifically
due to the missing `createdAt` field.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 291383bb-c787-481b-8f40-63462e2acff5

📥 Commits

Reviewing files that changed from the base of the PR and between 9ea4051 and 0d20609.

📒 Files selected for processing (4)

• .changeset/funding-receipt-field-types.md
• SCHEMAS.md
• lexicons/org/hypercerts/funding/receipt.json
• tests/validate-funding-receipt.test.ts