@receiz/sdk 94.0.0 → 96.0.0

package/docs/copy-paste-integrations.md

@@ -0,0 +1,205 @@
+# Copy-Paste Integrations
+
+These examples are intentionally small. They let a developer build with Receiz proof objects without inventing a parallel authority model.
+
+The rule is the same in every example:
+
+```txt
+verify or validate carried proof truth -> project immediately -> admit into durable proof memory -> sync verified additions after knownHead
+```
+
+The SDK is convenience, not authority. Proof objects, verified appends, ownership appends, settlement rows, and identity artifacts remain stronger truth.
+
+## React Hook: `useReceizProofMemory`
+
+```tsx
+import { useEffect, useMemo, useState } from "react";
+import {
+  createReceizLocalStorageProofMemoryStorage,
+  createReceizProofMemory,
+  type ReceizProofMemory,
+  type ReceizSdkObservation,
+} from "@receiz/sdk";
+
+export function useReceizProofMemory(ownerId: string) {
+  const [memory, setMemory] = useState<ReceizProofMemory | null>(null);
+  const [observations, setObservations] = useState<ReceizSdkObservation[]>([]);
+
+  const storageKey = useMemo(() => `receiz:proof-memory:${ownerId}:v1`, [ownerId]);
+
+  useEffect(() => {
+    let active = true;
+
+    void createReceizProofMemory({
+      ownerId,
+      storage: createReceizLocalStorageProofMemoryStorage(storageKey),
+      onObservation: (observation) => {
+        setObservations((current) => [...current.slice(-24), observation]);
+      },
+    }).then((opened) => {
+      if (active) setMemory(opened);
+    });
+
+    return () => {
+      active = false;
+    };
+  }, [ownerId, storageKey]);
+
+  return {
+    memory,
+    observations,
+    entries: memory?.entries() ?? [],
+    knownHead: memory?.knownHead(100) ?? null,
+  };
+}
+```
+
+Use `entries` for immediate first paint. Use `knownHead` for append-only sync. Do not ask the server whether those entries are still true.
+
+## Browser Proof Object Admission
+
+```ts
+import {
+  assertReceizAssetManifest,
+  createReceizLocalStorageProofMemoryStorage,
+  createReceizProofMemory,
+  projectReceizAssetManifest,
+} from "@receiz/sdk";
+
+const memory = await createReceizProofMemory({
+  ownerId: "workspace-or-user-id",
+  storage: createReceizLocalStorageProofMemoryStorage("receiz:proof-memory:v1"),
+});
+
+export async function admitAssetManifest(value: unknown) {
+  const manifest = assertReceizAssetManifest(value);
+  const projection = projectReceizAssetManifest(manifest);
+
+  memory.admitAssetManifest(manifest);
+  await memory.flush();
+
+  return {
+    projection,
+    knownHead: memory.knownHead(100),
+  };
+}
+```
+
+This is not cache. The persisted register is admitted proof memory.
+
+## Next Route: Append Sync After Known Head
+
+```ts
+import { createReceizClient } from "@receiz/sdk";
+
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const afterKaiUpulse = url.searchParams.get("afterKaiUpulse");
+  const afterEntryId = url.searchParams.get("afterEntryId");
+
+  const receiz = createReceizClient({
+    accessToken: process.env.RECEIZ_CONNECT_ACCESS_TOKEN,
+  });
+
+  const ledger = await receiz.wallet.publicLedger({
+    limit: 100,
+    cursor: afterEntryId ?? undefined,
+    since: afterKaiUpulse ?? undefined,
+  });
+
+  return Response.json({
+    ok: true,
+    additions: ledger.events,
+  });
+}
+```
+
+Use this as transport. Do not let this route replace local proof memory. It only returns possible additions.
+
+## Webhook Receiver
+
+```ts
+import {
+  assertReceizWebhookEvent,
+  createReceizProofMemory,
+  createReceizLocalStorageProofMemoryStorage,
+  verifyReceizWebhookSignature,
+} from "@receiz/sdk";
+
+export async function receiveReceizWebhook(request: Request) {
+  const body = await request.text();
+  const signature = request.headers.get("x-receiz-signature") ?? "";
+  const timestamp = request.headers.get("x-receiz-timestamp") ?? "";
+
+  const ok = await verifyReceizWebhookSignature({
+    secret: process.env.RECEIZ_WEBHOOK_SECRET!,
+    timestamp,
+    signature,
+    body,
+    toleranceSeconds: 300,
+  });
+
+  if (!ok) return new Response("invalid signature", { status: 401 });
+
+  const event = assertReceizWebhookEvent(JSON.parse(body));
+  const memory = await createReceizProofMemory({
+    ownerId: "webhook-worker",
+    storage: createReceizLocalStorageProofMemoryStorage("receiz:webhook-proof-memory:v1"),
+  });
+
+  memory.admitWebhookEvent(event);
+  await memory.flush();
+
+  return Response.json({
+    ok: true,
+    knownHead: memory.knownHead(100),
+  });
+}
+```
+
+Webhook signatures verify delivery. They do not become stronger than the proof bundle or append payload being admitted.
+
+## Sports Card Renderer
+
+This Sports card renderer keeps the proof object together while giving React developers a direct display component.
+
+```tsx
+import {
+  assertReceizSportsCardManifest,
+  projectReceizSportsCardManifest,
+} from "@receiz/sdk";
+
+export function SportsCardProof({ manifestJson }: { manifestJson: unknown }) {
+  const manifest = assertReceizSportsCardManifest(manifestJson);
+  const projection = projectReceizSportsCardManifest(manifest);
+
+  return (
+    <article>
+      <img src={projection.mediaUrl ?? ""} alt={projection.title} />
+      <h2>{projection.title}</h2>
+      <p>{projection.scoreLabel}</p>
+      <a href={projection.verifyUrl ?? manifest.links.proof}>Verify proof</a>
+      <dl>
+        {projection.rows.map((row) => (
+          <div key={row.label}>
+            <dt>{row.label}</dt>
+            <dd>{row.href ? <a href={row.href}>{row.value}</a> : row.value}</dd>
+          </div>
+        ))}
+      </dl>
+    </article>
+  );
+}
+```
+
+Keep card identity, claim hash, ownership, value basis, append summary, and event proof summary together. They are one proof object projection.
+
+## Local CLI Proof
+
+```bash
+npx @receiz/sdk conformance
+npx @receiz/sdk inspect ./receiz-asset-manifest.json
+npx @receiz/sdk init ./receiz-integration
+```
+
+These commands prove the SDK can admit and project carried Receiz proof truth without network or database authority.

package/docs/proof-memory-and-projections.md

@@ -8,6 +8,8 @@ verify proof object -> project immediately -> admit into durable proof memory ->
 
 The SDK is convenience. It is not authority. The authority remains the sealed artifact, proof bundle, verified append, ownership append, and settlement ledger record.
 
+Kai Klok is the proof object state machine. `kaiPulseEternal` is the pulse unit carried by that state machine. A complete Receiz proof object carries Kai; without its Kai coordinate it is not complete Receiz proof truth.
+
 ## Install
 
 ```bash
@@ -52,26 +54,42 @@ The projection keeps card identity, claim hash, ownership, value basis, append s
 ## Admit Once, Append Forever
 
 ```ts
-import { createReceizProofRegister } from "@receiz/sdk";
+import {
+  createReceizLocalStorageProofMemoryStorage,
+  createReceizProofMemory,
+} from "@receiz/sdk";
 
-const memory = createReceizProofRegister({ ownerId: currentUserId });
+const memory = await createReceizProofMemory({
+  ownerId: currentUserId,
+  storage: createReceizLocalStorageProofMemoryStorage(`receiz:${currentUserId}:proof-memory`),
+});
 
 memory.admitAssetManifest(assetManifest);
 memory.admitSportsCardManifest(cardManifest);
 memory.admitWebhookEvent(webhookEvent);
 
-const snapshot = memory.snapshot();
+await memory.flush();
 ```
 
-Persist `snapshot` in your app storage. On next open, reconstruct memory from `snapshot.entries` and render it immediately:
+The storage adapter only persists already-admitted truth. It does not verify, mint, rewrite, or outrank the proof object. On next open, the same call reopens the stored register and you render it immediately:
 
 ```ts
-const memory = createReceizProofRegister(savedSnapshot);
+const memory = await createReceizProofMemory({
+  ownerId: currentUserId,
+  storage: createReceizLocalStorageProofMemoryStorage(`receiz:${currentUserId}:proof-memory`),
+});
+
 const knownTruth = memory.entries();
 ```
 
 Then ask Receiz for verified additions after your known head. Do not ask whether known proof is still true.
 
+```ts
+const after = memory.knownHead(50);
+
+await fetch(`/api/receiz/additions?afterKaiUpulse=${after.afterKaiUpulse ?? ""}`);
+```
+
 ## Receiz Account Restore Boundary
 
 Receiz Key, Identity Record, and Identity Seal restore use the same law inside Receiz itself. Current restore artifacts carry `receiz.account.state.v3`, which includes profile/account state, action ledger, calendar events, wallet settlement rows and notes, Sports vault cards, pack purchases, card appends, event proofs, entries, competitions, and tournament state.
@@ -93,6 +111,23 @@ const retained = memory.snapshot().entries[0];
 
 This is intentional. Receiz proof memory is not `newest response wins`.
 
+## Storage Adapters
+
+Browser apps can use `createReceizLocalStorageProofMemoryStorage()`. Server-rendered or test environments can provide the same small interface:
+
+```ts
+import { createReceizProofMemory, type ReceizProofMemoryStorage } from "@receiz/sdk";
+
+const storage: ReceizProofMemoryStorage = {
+  read: async () => durableStore.get("proof-memory"),
+  write: async (snapshot) => durableStore.set("proof-memory", JSON.stringify(snapshot)),
+};
+
+const memory = await createReceizProofMemory({ storage });
+```
+
+For tests and demos, use `createReceizInMemoryProofMemoryStorage()`.
+
 ## Runtime Schema Exports
 
 ```ts
@@ -122,6 +157,7 @@ Use this order in every integration:
 3. Project display-ready rows from the verified object.
 4. Admit the object into proof memory.
 5. Persist the proof memory snapshot.
-6. Append later verified additions without rediscovering known truth.
+6. Resume from the known Kai/proof head.
+7. Append later verified additions without rediscovering known truth.
 
 This gives users truthful first paint and gives developers a simple integration that stays aligned with Receiz primitives.

package/fixtures/receiz-asset-manifest.example.json

@@ -4,15 +4,18 @@
   "assetType": "proof_object",
   "proof": {
     "kind": "receiz.proof_bundle",
-    "payloadVersion": 1,
+    "payloadVersion": "v2",
     "createdAtMs": 1782400000000,
     "ts": "2026-06-25T00:00:00.000Z",
     "code": "EXAMPLE",
     "slug": "developer-example",
     "verifyPath": "/v/developer-example/EXAMPLE/123456",
     "verifyUrl": "https://receiz.com/v/developer-example/EXAMPLE/123456",
-    "kaiPulseEternal": 123456,
-    "artifactSha256Basis": "sha256:example-artifact-basis"
+    "kaiPulseEternal": "123456",
+    "kaiKlok": "kai:123456",
+    "receizClaimId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "sigilClaimSeed": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    "artifactSha256Basis": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
   },
   "owner": {
     "receizSubject": "sub_example_receiz_subject",

package/fixtures/receiz-webhook-event.example.json

@@ -9,9 +9,18 @@
     "appendHash": "sha256:example-append",
     "proofBundle": {
       "kind": "receiz.proof_bundle",
+      "payloadVersion": "v2",
+      "createdAtMs": 1782400000000,
+      "ts": "2026-06-25T00:00:00.000Z",
+      "code": "EXAMPLE",
+      "slug": "developer-example",
       "verifyPath": "/v/developer-example/EXAMPLE/123456",
       "verifyUrl": "https://receiz.com/v/developer-example/EXAMPLE/123456",
-      "kaiPulseEternal": 123456
+      "kaiPulseEternal": "123456",
+      "kaiKlok": "kai:123456",
+      "receizClaimId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "sigilClaimSeed": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "artifactSha256Basis": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
     }
   }
 }

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@receiz/sdk",
-  "version": "94.0.0",
+  "version": "96.0.0",
   "description": "TypeScript SDK for Receiz proof-native artifact, public proof, wallet, sports, and Connect integrations.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "receiz": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",