@receiz/sdk 94.0.0 → 96.0.0

package/README.md

@@ -17,10 +17,22 @@ const receiz = createReceizClient({
 });
 ```
 
+Local proof tooling ships with the same package:
+
+```bash
+npx @receiz/sdk conformance
+npx @receiz/sdk inspect ./receiz-asset-manifest.json
+npx @receiz/sdk init ./receiz-integration
+```
+
+These commands use packaged SDK validators, projections, and durable proof memory. `conformance` and `inspect` do not call Receiz production, Supabase, or any database; they prove the local SDK can admit and project Receiz proof objects from fixture or file-carried truth.
+
 ## Primitive Boundary
 
 The SDK is convenience, not authority. It reads public API projections, sends delegated actions, validates developer manifests, and verifies webhook delivery signatures. Sealed artifacts, proof bundles, verified appends, ownership appends, and settlement ledger records remain the stronger source of truth.
 
+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.
+
 Receiz ID is the default account-continuity rail for everyday login. It does not replace PBI/passkey, email magic-link recovery, Receiz Key, Identity Record, Identity Seal, or OIDC/Connect. Those rails all preserve the same account when bound: PBI/passkey can create or recover a Receiz account, email can recover the account, Receiz identity artifacts can restore it locally, and OIDC/Connect can delegate API access after identity proof.
 
 Receiz Key, Identity Record, and Identity Seal are Receiz identity primitives exposed through the SDK for developer apps. Their current account-state envelope is `receiz.account.state.v3`; it carries admitted account proof memory across profile, action ledger, calendar, wallet settlement, Sports vault/cards/appends/event proofs, and related entries. The SDK mirrors the same law for developer apps through local proof registers: admit verified truth once, persist it, and ask Receiz only for verified additions after the known head. Connect is delegated API access; it is not the identity proof root.
@@ -30,7 +42,8 @@ Default integration order:
 1. Verify first, then project.
 2. Render the proof object or manifest as the user-facing truth.
 3. Append public proof, wallet, sports, or Connect additions after the known truth.
-4. Never treat an SDK response as stronger than the sealed artifact, verified append, ownership append, or settlement primitive it projects.
+4. Order proof objects by Kai/Klok state; render Chronos only as display.
+5. Never treat an SDK response as stronger than the sealed artifact, verified append, ownership append, or settlement primitive it projects.
 
 ## Five-Minute Proof Object App
 
@@ -39,19 +52,24 @@ This is the highest-leverage SDK path for most apps:
 ```ts
 import {
   createReceizClient,
-  createReceizProofRegister,
+  createReceizLocalStorageProofMemoryStorage,
+  createReceizProofMemory,
   projectReceizAssetManifest,
 } from "@receiz/sdk";
 
 const receiz = createReceizClient({ accessToken: process.env.RECEIZ_ACCESS_TOKEN });
-const register = createReceizProofRegister({ ownerId: "local-user-or-workspace-id" });
+const memory = await createReceizProofMemory({
+  ownerId: "local-user-or-workspace-id",
+  storage: createReceizLocalStorageProofMemoryStorage("receiz:proof-memory"),
+});
 
 const verified = await receiz.verification.verifyArtifact(file);
 if (!verified.ok) throw new Error(verified.errors.join(", "));
 
 const manifest = verified.bundle?.assetManifest;
 const projection = projectReceizAssetManifest(manifest);
-register.admitAssetManifest(manifest);
+memory.admitAssetManifest(manifest);
+await memory.flush();
 
 renderReceizObject({
   title: projection.title,
@@ -65,11 +83,37 @@ The register is not a cache. It is the app's admitted verified prefix. Use it im
 
 Full quickstart: `docs/proof-memory-and-projections.md`.
 
+For complete copy-paste integrations, use `docs/copy-paste-integrations.md`. It includes a React proof memory hook, browser admission helper, Next append-sync route, webhook receiver, Sports card renderer, and local CLI proof commands.
+
+## CLI And Local Conformance
+
+```bash
+npx @receiz/sdk conformance
+```
+
+Runs the packaged asset manifest, Sports card manifest, and webhook event fixtures through the SDK validators and durable proof memory. This is existing SDK conformance exposed as an executable developer rail; it is not a new authority layer.
+
+```bash
+npx @receiz/sdk inspect ./receiz-asset-manifest.json
+```
+
+Validates one proof payload, projects display-ready rows, admits it into in-memory proof memory, and prints the known Kai/proof head your app can use to ask for verified additions.
+
+```bash
+npx @receiz/sdk init ./receiz-integration
+```
+
+Writes a local-first proof memory starter. The starter opens durable proof memory, admits verified proof objects, projects them immediately, and exposes `knownHead()` for append-only sync.
+
+Full quickstart: `docs/cli-and-conformance.md`.
+
 ## Schemas, Projections, And Proof Memory
 
 ```ts
 import {
   RECEIZ_SCHEMAS,
+  createReceizInMemoryProofMemoryStorage,
+  createReceizProofMemory,
   createReceizProofRegister,
   projectReceizSportsCardManifest,
 } from "@receiz/sdk";
@@ -82,6 +126,11 @@ memory.admitSportsCardManifest(cardManifest);
 memory.admitWebhookEvent(webhookEvent);
 
 const snapshot = memory.snapshot();
+
+const durableMemory = await createReceizProofMemory({
+  storage: createReceizInMemoryProofMemoryStorage(snapshot),
+});
+const additionsAfter = durableMemory.knownHead(50);
 ```
 
 Use schemas for developer validation, projections for display-ready proof rows, and proof memory for first-admission-then-append-forever UX.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertReceizAssetManifest, assertReceizProofRegisterSnapshot, assertReceizSportsCardManifest, assertReceizWebhookEvent, createReceizInMemoryProofMemoryStorage, createReceizProofMemory, projectReceizAssetManifest, projectReceizSportsCardManifest, receizProofMemoryAdditionsQuery, } from "./index.js";
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = moduleDir.endsWith(`${join("packages", "receiz-sdk", "dist")}`)
+    ? dirname(moduleDir)
+    : dirname(moduleDir);
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function printError(error, detail) {
+    const payload = detail
+        ? { ok: false, schema: "receiz.sdk.cli.error.v1", error, detail }
+        : { ok: false, schema: "receiz.sdk.cli.error.v1", error };
+    process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+function readJsonFile(path) {
+    return JSON.parse(readFileSync(resolve(path), "utf8"));
+}
+async function inspectProofObject(path) {
+    const value = readJsonFile(path);
+    const storage = createReceizInMemoryProofMemoryStorage();
+    const memory = await createReceizProofMemory({ storage });
+    try {
+        const manifest = assertReceizAssetManifest(value);
+        memory.admitAssetManifest(manifest);
+        await memory.flush();
+        return {
+            ok: true,
+            schema: "receiz.sdk.cli.inspect.v1",
+            kind: "asset_manifest",
+            sourcePath: resolve(path),
+            projection: projectReceizAssetManifest(manifest),
+            knownHead: memory.knownHead(100),
+        };
+    }
+    catch {
+        // Try the next implemented Receiz proof payload shape.
+    }
+    try {
+        const manifest = assertReceizSportsCardManifest(value);
+        memory.admitSportsCardManifest(manifest);
+        await memory.flush();
+        return {
+            ok: true,
+            schema: "receiz.sdk.cli.inspect.v1",
+            kind: "sports_card_manifest",
+            sourcePath: resolve(path),
+            projection: projectReceizSportsCardManifest(manifest),
+            knownHead: memory.knownHead(100),
+        };
+    }
+    catch {
+        // Try the next implemented Receiz proof payload shape.
+    }
+    try {
+        const event = assertReceizWebhookEvent(value);
+        memory.admitWebhookEvent(event);
+        await memory.flush();
+        const entry = memory.entries()[0];
+        return {
+            ok: true,
+            schema: "receiz.sdk.cli.inspect.v1",
+            kind: "webhook_event",
+            sourcePath: resolve(path),
+            projection: (entry?.projection ?? {}),
+            knownHead: memory.knownHead(100),
+        };
+    }
+    catch {
+        // Try the register snapshot shape before failing.
+    }
+    const snapshot = assertReceizProofRegisterSnapshot(value);
+    return {
+        ok: true,
+        schema: "receiz.sdk.cli.inspect.v1",
+        kind: "proof_register_snapshot",
+        sourcePath: resolve(path),
+        projection: {
+            schema: snapshot.schema,
+            ownerId: snapshot.ownerId ?? null,
+            count: snapshot.head.count,
+            head: snapshot.head,
+        },
+        knownHead: receizProofMemoryAdditionsQuery(snapshot, 100),
+    };
+}
+async function admitFixture(memory, path) {
+    const value = readJsonFile(path);
+    memory.admit(value);
+    await memory.flush();
+}
+async function runConformance() {
+    const fixtures = [
+        join(packageRoot, "fixtures", "receiz-asset-manifest.example.json"),
+        join(packageRoot, "fixtures", "receiz-sports-card-manifest.example.json"),
+        join(packageRoot, "fixtures", "receiz-webhook-event.example.json"),
+    ];
+    const failures = [];
+    const storage = createReceizInMemoryProofMemoryStorage();
+    const memory = await createReceizProofMemory({ ownerId: "receiz-sdk-conformance", storage });
+    for (const fixture of fixtures) {
+        try {
+            await admitFixture(memory, fixture);
+        }
+        catch (error) {
+            failures.push({
+                fixture,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const reopened = await createReceizProofMemory({ ownerId: "receiz-sdk-conformance", storage });
+    printJson({
+        ok: failures.length === 0,
+        schema: "receiz.sdk.cli.conformance.v1",
+        summary: {
+            fixtures: fixtures.length,
+            proofMemoryEntries: reopened.snapshot().head.count,
+            networkCalls: 0,
+            dbCalls: 0,
+        },
+        knownHead: reopened.knownHead(100),
+        failures,
+    });
+    if (failures.length > 0)
+        process.exitCode = 1;
+}
+function writeStarter(targetDir) {
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, "receiz-proof-memory.ts"), `import {
+  assertReceizAssetManifest,
+  assertReceizSportsCardManifest,
+  assertReceizWebhookEvent,
+  createReceizLocalStorageProofMemoryStorage,
+  createReceizProofMemory,
+  projectReceizAssetManifest,
+  projectReceizSportsCardManifest,
+  type ReceizProofMemory,
+} from "@receiz/sdk";
+
+export async function openReceizProofMemory(ownerId: string): Promise<ReceizProofMemory> {
+  return createReceizProofMemory({
+    ownerId,
+    storage: createReceizLocalStorageProofMemoryStorage(\`receiz:proof-memory:\${ownerId}:v1\`),
+  });
+}
+
+export async function admitVerifiedProofObject(memory: ReceizProofMemory, value: unknown) {
+  if (typeof value !== "object" || value === null) throw new Error("receiz_proof_object_required");
+  const schema = "schema" in value ? value.schema : null;
+
+  if (schema === "receiz.asset_manifest.v1") {
+    const manifest = assertReceizAssetManifest(value);
+    memory.admitAssetManifest(manifest);
+    await memory.flush();
+    return projectReceizAssetManifest(manifest);
+  }
+
+  if (schema === "receiz.sports_arena.card_manifest.v1") {
+    const manifest = assertReceizSportsCardManifest(value);
+    memory.admitSportsCardManifest(manifest);
+    await memory.flush();
+    return projectReceizSportsCardManifest(manifest);
+  }
+
+  if (schema === "receiz.webhook_event.v1") {
+    const event = assertReceizWebhookEvent(value);
+    memory.admitWebhookEvent(event);
+    await memory.flush();
+    return memory.snapshot().entries.find((entry) => entry.id === \`webhook:\${event.id}\`)?.projection ?? null;
+  }
+
+  throw new Error(\`receiz_unsupported_proof_schema:\${String(schema ?? "unknown")}\`);
+}
+
+export function verifiedAdditionsAfterKnownHead(memory: ReceizProofMemory) {
+  return memory.knownHead(100);
+}
+`, "utf8");
+}
+function printHelp() {
+    process.stdout.write(`Receiz SDK CLI
+
+Usage:
+  receiz inspect <path-to-proof-json>
+  receiz conformance
+  receiz init <target-dir>
+
+This CLI uses local Receiz SDK validators, projections, and durable proof memory.
+It does not make network or database calls for inspect or conformance.
+`);
+}
+async function main(argv) {
+    const [command, ...args] = argv;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    if (command === "inspect") {
+        const path = args[0];
+        if (!path) {
+            printError("missing_path", "Usage: receiz inspect <path-to-proof-json>");
+            process.exitCode = 1;
+            return;
+        }
+        printJson(await inspectProofObject(path));
+        return;
+    }
+    if (command === "conformance") {
+        await runConformance();
+        return;
+    }
+    if (command === "init") {
+        const targetDir = args[0];
+        if (!targetDir) {
+            printError("missing_target_dir", "Usage: receiz init <target-dir>");
+            process.exitCode = 1;
+            return;
+        }
+        writeStarter(resolve(targetDir));
+        printJson({
+            ok: true,
+            schema: "receiz.sdk.cli.init.v1",
+            targetDir: resolve(targetDir),
+            files: ["receiz-proof-memory.ts"],
+        });
+        return;
+    }
+    printError("unknown_command", command);
+    process.exitCode = 1;
+}
+main(process.argv.slice(2)).catch((error) => {
+    printError("receiz_cli_failed", error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});