Merge pull request #199 from hypercerts-org/fix/funding-receipt-field-types-clean

feat: add #text variant to funding receipt from/to unions

Author: s-adamantine

.changeset/funding-receipt-text-variant.md

@@ -0,0 +1,5 @@
+---
+"@hypercerts-org/lexicon": minor
+---
+
+Add `#text` variant to funding receipt `from`/`to` unions for free-text identifiers (names, wallet addresses, etc.)

SCHEMAS.md

@@ -265,8 +265,8 @@ Overall score for an evaluation on a numeric scale.
 
 | Property         | Type     | Required | Description                                                                                                                                                                             | Comments       |
 | ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `from`           | `union`  | ❌       | The sender of the funds (either an account DID or a strong reference to a record). Optional — omit to represent anonymity.                                                              |                |
-| `to`             | `union`  | ✅       | The recipient of the funds (either an account DID or a strong reference to a record).                                                                                                   |                |
+| `from`           | `union`  | ❌       | The sender of the funds (a free-text string, an account DID, or a strong reference to a record). Optional — omit to represent anonymity.                                                |                |
+| `to`             | `union`  | ✅       | The recipient of the funds (a free-text string, an account DID, or a strong reference to a record).                                                                                     |                |
 | `amount`         | `string` | ✅       | Amount of funding received as a numeric string (e.g. '1000.50').                                                                                                                        | maxLength: 50  |
 | `currency`       | `string` | ✅       | Currency of the payment (e.g. EUR, USD, ETH).                                                                                                                                           | maxLength: 10  |
 | `paymentRail`    | `string` | ❌       | How the funds were transferred (e.g. bank_transfer, credit_card, onchain, cash, check, payment_processor).                                                                              | maxLength: 50  |
@@ -277,6 +277,16 @@ Overall score for an evaluation on a numeric scale.
 | `occurredAt`     | `string` | ❌       | Timestamp when the payment occurred.                                                                                                                                                    |                |
 | `createdAt`      | `string` | ✅       | Client-declared timestamp when this receipt record was created.                                                                                                                         |                |
 
+#### Defs
+
+##### `org.hypercerts.funding.receipt#text`
+
+A free-text string value (e.g. a display name, wallet address, or other identifier).
+
+| Property | Type     | Required | Description       |
+| -------- | -------- | -------- | ----------------- |
+| `value`  | `string` | ✅       | The string value. |
+
 ---
 
 ### `org.hypercerts.workscope.cel`

lexicons/org/hypercerts/funding/receipt.json

@@ -12,13 +12,21 @@
         "properties": {
           "from": {
             "type": "union",
-            "description": "The sender of the funds (either an account DID or a strong reference to a record). Optional — omit to represent anonymity.",
-            "refs": ["app.certified.defs#did", "com.atproto.repo.strongRef"]
+            "description": "The sender of the funds (a free-text string, an account DID, or a strong reference to a record). Optional — omit to represent anonymity.",
+            "refs": [
+              "#text",
+              "app.certified.defs#did",
+              "com.atproto.repo.strongRef"
+            ]
           },
           "to": {
             "type": "union",
-            "description": "The recipient of the funds (either an account DID or a strong reference to a record).",
-            "refs": ["app.certified.defs#did", "com.atproto.repo.strongRef"]
+            "description": "The recipient of the funds (a free-text string, an account DID, or a strong reference to a record).",
+            "refs": [
+              "#text",
+              "app.certified.defs#did",
+              "com.atproto.repo.strongRef"
+            ]
           },
           "amount": {
             "type": "string",
@@ -67,6 +75,18 @@
           }
         }
       }
+    },
+    "text": {
+      "type": "object",
+      "description": "A free-text string value (e.g. a display name, wallet address, or other identifier).",
+      "required": ["value"],
+      "properties": {
+        "value": {
+          "type": "string",
+          "description": "The string value.",
+          "maxLength": 2048
+        }
+      }
     }
   }
 }

tests/validate-funding-receipt.test.ts

@@ -74,6 +74,32 @@ describe("org.hypercerts.funding.receipt", () => {
     expect(result.success).toBe(true);
   });
 
+  it("should accept 'to' as a text string", () => {
+    const result = FundingReceipt.validateMain({
+      $type: ids.OrgHypercertsFundingReceipt,
+      to: {
+        $type: "org.hypercerts.funding.receipt#text",
+        value: "Alice",
+      },
+      amount: "1000.00",
+      currency: "USD",
+      createdAt: "2024-01-01T00:00:00Z",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("should accept 'from' as a text string", () => {
+    const result = FundingReceipt.validateMain({
+      $type: ids.OrgHypercertsFundingReceipt,
+      ...validBase,
+      from: {
+        $type: "org.hypercerts.funding.receipt#text",
+        value: "0x1234567890abcdef1234567890abcdef12345678",
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+
   it("should accept a valid record with all optional fields present", () => {
     const result = FundingReceipt.validateMain({
       $type: ids.OrgHypercertsFundingReceipt,