feat(lexicon): lexicon package in react sdk and readme

bitbeckers · bitbeckers · commit b1a4e38a17a5 · 2025-11-27T18:52:31.000+01:00
diff --git a/README.md b/README.md
@@ -6,6 +6,7 @@ A monorepo containing SDK packages for the Hypercerts protocol on ATProto.
 
 | Package | Description | Status |
 |---------|-------------|--------|
+| [`@hypercerts-org/lexicon`](./packages/lexicon) | ATProto lexicon definitions and generated TypeScript types for Hypercerts | ✅ Complete |
 | [`@hypercerts-org/sdk-core`](./packages/sdk-core) | Framework-agnostic core SDK for ATProto authentication, repository operations, and lexicon management | ✅ Complete |
 | [`@hypercerts-org/sdk-react`](./packages/sdk-react) | React hooks and components for ATProto integration | ✅ Complete |
 
@@ -44,9 +45,34 @@ The SDK provides a unified `Repository` that works with both server types, with
 │  - Repository (records, blobs, profiles)                │
 │  - Domain services (hypercerts, organizations)          │
 │  - Lexicon registry and validation                      │
+│  - Re-exports types from @hypercerts-org/lexicon        │
+├─────────────────────────────────────────────────────────┤
+│  @hypercerts-org/lexicon                                │
+│  - ATProto lexicon JSON definitions                     │
+│  - Generated TypeScript types (via @atproto/lex-cli)    │
+│  - Runtime validation (isRecord, validateRecord)        │
 └─────────────────────────────────────────────────────────┘
 ```
 
+### Type Inheritance
+
+Types flow from the lexicon package through sdk-core to sdk-react:
+
+```
+@hypercerts-org/lexicon          → Generated types with $type field
+    ↓                               (OrgHypercertsClaim.Main, etc.)
+@hypercerts-org/sdk-core         → Re-exports with friendly aliases
+    ↓                               (HypercertClaim, HypercertRights, etc.)
+@hypercerts-org/sdk-react        → Consumes types from sdk-core
+                                    (Hypercert extends HypercertClaim)
+```
+
+This architecture ensures:
+- **Single source of truth**: Lexicon definitions generate all types
+- **Consistent validation**: Runtime validation using `@atproto/lexicon`
+- **Clean API surface**: sdk-core provides user-friendly type aliases
+- **Simplified dependencies**: sdk-react only depends on sdk-core
+
 ## Getting Started
 
 ### Installation
@@ -215,13 +241,18 @@ Available tasks defined in `turbo.json`:
 ```
 hypercerts-sdk/
 ├── packages/
+│   ├── lexicon/            # Lexicon definitions package
+│   │   ├── lexicons/       # ATProto lexicon JSON files
+│   │   └── src/
+│   │       ├── types/      # Generated TypeScript types
+│   │       ├── lexicons.ts # Lexicon registry
+│   │       └── index.ts    # Package exports
 │   ├── sdk-core/           # Core SDK package
 │   │   ├── src/
 │   │   │   ├── auth/       # OAuth client
 │   │   │   ├── core/       # SDK class, types, errors
 │   │   │   ├── repository/ # Repository operations
-│   │   │   ├── services/   # Domain services
-│   │   │   ├── lexicons/   # Hypercert lexicons
+│   │   │   ├── services/   # Domain services (re-exports lexicon types)
 │   │   │   └── storage/    # In-memory stores
 │   │   └── tests/
 │   └── sdk-react/          # React package
diff --git a/packages/lexicon/README.md b/packages/lexicon/README.md
@@ -1,42 +1,110 @@
-# Hypercerts Lexicon Documentation
+# @hypercerts-org/lexicon
 
-This repository contains ATProto lexicon definitions for the
-Hypercerts protocol. Each lexicon defines a record type that can be
-stored on the ATProto network.
+ATProto lexicon definitions and generated TypeScript types for the Hypercerts protocol.
 
 ## Installation
 
-```
-npm i @hypercerts-org/lexicon
+```bash
+pnpm add @hypercerts-org/lexicon
 ```
 
-## Usage
+## Features
 
-```typescript
-import { AtpBaseClient } from '@hypercerts-org/lexicon'
-import type { HypercertClaim } from '@hypercerts-org/lexicon'
+- **Lexicon JSON Definitions**: ATProto-compliant lexicon schemas for all Hypercerts record types
+- **Generated TypeScript Types**: Strongly-typed interfaces generated via `@atproto/lex-cli`
+- **Runtime Validation**: `isRecord` and `validateRecord` functions for each type
+- **Lexicon Registry**: Pre-configured registry for schema validation
+
+## Usage
 
-const client = new AtpBaseClient({
-  service: 'https://bsky.social',
-  headers: { Authorization: `Bearer ${token}` }
-})
+### Using Types
 
-const hypercert: HypercertClaim = {
+```typescript
+import type { 
+  OrgHypercertsClaim,
+  OrgHypercertsCollection,
+  OrgHypercertsClaimRights 
+} from '@hypercerts-org/lexicon';
+
+// Use the Main type for full records (includes $type)
+const claim: OrgHypercertsClaim.Main = {
   $type: 'org.hypercerts.claim',
   title: 'My Impact Work',
   shortDescription: 'Description here',
   workScope: 'Scope of work',
   workTimeFrameFrom: '2023-01-01T00:00:00Z',
   workTimeFrameTo: '2023-12-31T23:59:59Z',
   createdAt: new Date().toISOString()
+};
+```
+
+### Runtime Validation
+
+```typescript
+import { OrgHypercertsClaim } from '@hypercerts-org/lexicon';
+
+// Check if a value matches the type
+if (OrgHypercertsClaim.isRecord(unknownValue)) {
+  // unknownValue is now typed as OrgHypercertsClaim.Main
+  console.log(unknownValue.title);
 }
 
-await client.org.hypercerts.claim.create(
-  { repo: 'did:plc:example' },
-  hypercert
-)
+// Validate with detailed error information
+const result = OrgHypercertsClaim.validateRecord(data);
+if (result.success) {
+  // data is valid
+} else {
+  console.error(result.error);
+}
 ```
 
+### Using Lexicon Constants
+
+```typescript
+import { HYPERCERT_LEXICONS, HYPERCERT_COLLECTIONS } from '@hypercerts-org/lexicon';
+
+// Collection names for ATProto operations
+console.log(HYPERCERT_COLLECTIONS.CLAIM);       // 'org.hypercerts.claim'
+console.log(HYPERCERT_COLLECTIONS.COLLECTION);  // 'org.hypercerts.collection'
+console.log(HYPERCERT_COLLECTIONS.RIGHTS);      // 'org.hypercerts.claim.rights'
+
+// Full lexicon documents for registry
+import { Lexicons } from '@atproto/lexicon';
+const registry = new Lexicons(HYPERCERT_LEXICONS);
+```
+
+## Type Inheritance
+
+This package is the source of truth for Hypercerts types. The SDK packages re-export these types with friendly aliases:
+
+```
+@hypercerts-org/lexicon
+├── OrgHypercertsClaim.Main      → sdk-core: HypercertClaim
+├── OrgHypercertsClaimRights.Main → sdk-core: HypercertRights
+├── OrgHypercertsCollection.Main  → sdk-core: HypercertCollection
+└── ...etc
+```
+
+**Recommendation**: Import types from `@hypercerts-org/sdk-core` for cleaner imports, unless you need direct access to validation functions.
+
+## Development
+
+### Regenerating Types
+
+Types are generated from the lexicon JSON files using `@atproto/lex-cli`:
+
+```bash
+pnpm generate  # Regenerates src/types/ from lexicons/
+pnpm build     # Build the package
+```
+
+### Adding New Lexicons
+
+1. Add lexicon JSON file to `lexicons/` directory
+2. Run `pnpm generate` to regenerate types
+3. Export new types from `src/index.ts`
+4. Update `HYPERCERT_COLLECTIONS` if adding a new collection
+
 ## Certified Lexicons
 
 Certified lexicons are common/shared lexicons that can be used across multiple protocols.
diff --git a/packages/sdk-core/README.md b/packages/sdk-core/README.md
@@ -11,13 +11,38 @@ pnpm add @hypercerts-org/sdk-core
 ```
 @hypercerts-org/sdk-core
 ├── /              → Full SDK (createATProtoSDK, Repository, types, errors)
-├── /types         → TypeScript types & Zod schemas
+├── /types         → TypeScript types (re-exported from @hypercerts-org/lexicon)
 ├── /errors        → Error classes
-├── /lexicons      → LexiconRegistry, HYPERCERT_LEXICONS
+├── /lexicons      → LexiconRegistry, HYPERCERT_LEXICONS, HYPERCERT_COLLECTIONS
 ├── /storage       → InMemorySessionStore, InMemoryStateStore
 └── /testing       → createMockSession, MockSessionStore
 ```
 
+## Type System
+
+Types are generated from ATProto lexicon definitions in `@hypercerts-org/lexicon` and re-exported with friendly aliases:
+
+| Lexicon Type | SDK Alias |
+|--------------|-----------|
+| `OrgHypercertsClaim.Main` | `HypercertClaim` |
+| `OrgHypercertsClaimRights.Main` | `HypercertRights` |
+| `OrgHypercertsClaimContribution.Main` | `HypercertContribution` |
+| `OrgHypercertsClaimMeasurement.Main` | `HypercertMeasurement` |
+| `OrgHypercertsClaimEvaluation.Main` | `HypercertEvaluation` |
+| `OrgHypercertsCollection.Main` | `HypercertCollection` |
+| `AppCertifiedLocation.Main` | `HypercertLocation` |
+
+```typescript
+import type { HypercertClaim, HypercertRights } from "@hypercerts-org/sdk-core";
+
+// For validation functions, import the namespaced types
+import { OrgHypercertsClaim } from "@hypercerts-org/sdk-core";
+
+if (OrgHypercertsClaim.isRecord(data)) {
+  // data is typed as HypercertClaim
+}
+```
+
 ## Usage
 
 ```typescript
diff --git a/packages/sdk-react/README.md b/packages/sdk-react/README.md
@@ -14,6 +14,23 @@ pnpm add @hypercerts-org/sdk-react @hypercerts-org/sdk-core @tanstack/react-quer
 └── /testing       → TestProvider, mocks, createMockATProtoReact
 ```
 
+## Type System
+
+Types are inherited from `@hypercerts-org/sdk-core` (which re-exports from `@hypercerts-org/lexicon`):
+
+```typescript
+import type { 
+  HypercertClaim,      // Base claim type from lexicon
+  HypercertCollection,
+  CreateHypercertParams,
+  Session 
+} from "@hypercerts-org/sdk-react";
+
+// The Hypercert type extends HypercertClaim with ATProto metadata
+import type { Hypercert } from "@hypercerts-org/sdk-react";
+// Hypercert = HypercertClaim & { uri: string; cid: string }
+```
+
 ## Usage
 
 ```typescript
diff --git a/packages/sdk-react/src/index.ts b/packages/sdk-react/src/index.ts
@@ -146,7 +146,7 @@ export type {
   Repository,
   Collaborator,
   CollaboratorPermissions,
-  HypercertRecord,
+  HypercertClaim,
   CreateHypercertParams,
   CreateHypercertResult,
   OrganizationInfo,
diff --git a/packages/sdk-react/src/testing/mocks.ts b/packages/sdk-react/src/testing/mocks.ts
@@ -200,14 +200,15 @@ export function createMockHypercert(overrides: Partial<Hypercert> = {}): Hyperce
   const yearAgo = new Date(now.getFullYear() - 1, now.getMonth(), now.getDate());
 
   return {
-    uri: "at://did:plc:mock123/org.hypercerts.hypercert/mock-rkey",
+    uri: "at://did:plc:mock123/org.hypercerts.claim/mock-rkey",
     cid: "bafyreimockhypercertcid123456789",
-    $type: "org.hypercerts.hypercert",
+    $type: "org.hypercerts.claim",
     title: "Mock Hypercert",
+    shortDescription: "A mock hypercert",
     description: "A mock hypercert for testing purposes",
     workScope: "Testing",
-    workTimeframeFrom: yearAgo.toISOString().split("T")[0],
-    workTimeframeTo: now.toISOString().split("T")[0],
+    workTimeFrameFrom: yearAgo.toISOString().split("T")[0],
+    workTimeFrameTo: now.toISOString().split("T")[0],
     createdAt: now.toISOString(),
     ...overrides,
   };
diff --git a/packages/sdk-react/src/types.ts b/packages/sdk-react/src/types.ts
@@ -11,7 +11,7 @@ import type {
     CollaboratorPermissions,
     CreateHypercertParams,
     CreateHypercertResult,
-    HypercertRecord,
+    HypercertClaim,
     OrganizationInfo,
     Repository,
     RepositoryRole,
@@ -298,7 +298,7 @@ export interface UseCollaboratorsResult {
 /**
  * Hypercert with metadata for display.
  */
-export interface Hypercert extends HypercertRecord {
+export interface Hypercert extends HypercertClaim {
   uri: string;
   cid: string;
 }
@@ -413,8 +413,15 @@ export interface SyncMessage {
 
 export type {
     ATProtoSDK,
-    ATProtoSDKConfig, Collaborator,
-    CollaboratorPermissions, CreateHypercertParams,
-    CreateHypercertResult, HypercertRecord, OrganizationInfo, Repository, RepositoryRole, Session
+    ATProtoSDKConfig,
+    Collaborator,
+    CollaboratorPermissions,
+    CreateHypercertParams,
+    CreateHypercertResult,
+    HypercertClaim,
+    OrganizationInfo,
+    Repository,
+    RepositoryRole,
+    Session
 };
 
diff --git a/packages/sdk-react/tests/testing/mocks.test.ts b/packages/sdk-react/tests/testing/mocks.test.ts
@@ -166,7 +166,7 @@ describe("createMockHypercert", () => {
 
     expect(hc.title).toBe("Mock Hypercert");
     expect(hc.workScope).toBe("Testing");
-    expect(hc.$type).toBe("org.hypercerts.hypercert");
+    expect(hc.$type).toBe("org.hypercerts.claim");
     expect(hc.uri).toContain("at://");
     expect(hc.cid).toBeTruthy();
   });
@@ -184,8 +184,8 @@ describe("createMockHypercert", () => {
   it("should set valid date ranges", () => {
     const hc = createMockHypercert();
 
-    const from = new Date(hc.workTimeframeFrom!);
-    const to = new Date(hc.workTimeframeTo!);
+    const from = new Date(hc.workTimeFrameFrom);
+    const to = new Date(hc.workTimeFrameTo);
 
     expect(from).toBeInstanceOf(Date);
     expect(to).toBeInstanceOf(Date);
diff --git a/packages/sdk-react/tests/utils/fixtures.ts b/packages/sdk-react/tests/utils/fixtures.ts
@@ -25,7 +25,7 @@ export function createMockSession(overrides: Partial<Session & { did?: string; h
  * Create mock collaborator permissions.
  */
 export function createMockPermissions(
-  role: "viewer" | "editor" | "admin" | "owner" = "viewer"
+  role: "viewer" | "editor" | "admin" | "owner" = "viewer",
 ): CollaboratorPermissions {
   switch (role) {
     case "viewer":
@@ -81,14 +81,15 @@ export function createMockHypercert(overrides: Partial<Hypercert> = {}): Hyperce
   const yearAgo = new Date(now.getFullYear() - 1, now.getMonth(), now.getDate());
 
   return {
-    uri: "at://did:plc:test123/org.hypercerts.hypercert/test-rkey",
+    uri: "at://did:plc:test123/org.hypercerts.claim/test-rkey",
     cid: "bafyreitesthypercertcid123456789",
-    $type: "org.hypercerts.hypercert",
+    $type: "org.hypercerts.claim",
     title: "Test Hypercert",
+    shortDescription: "A test hypercert",
     description: "A test hypercert for testing purposes",
     workScope: "Testing",
-    workTimeframeFrom: yearAgo.toISOString().split("T")[0],
-    workTimeframeTo: now.toISOString().split("T")[0],
+    workTimeFrameFrom: yearAgo.toISOString().split("T")[0],
+    workTimeFrameTo: now.toISOString().split("T")[0],
     createdAt: now.toISOString(),
     ...overrides,
   };
@@ -100,10 +101,10 @@ export function createMockHypercert(overrides: Partial<Hypercert> = {}): Hyperce
 export function createMockHypercertList(count: number = 5): Hypercert[] {
   return Array.from({ length: count }, (_, i) =>
     createMockHypercert({
-      uri: `at://did:plc:test123/org.hypercerts.hypercert/test-rkey-${i}`,
+      uri: `at://did:plc:test123/org.hypercerts.claim/test-rkey-${i}`,
       cid: `bafyreitesthypercertcid${i}`,
       title: `Test Hypercert ${i + 1}`,
-    })
+    }),
   );
 }
 
