@receiz/sdk 95.0.0 → 96.1.0

package/README.md

@@ -6,7 +6,7 @@ Install:
 npm install @receiz/sdk
 ```
 
-Use one typed client for Receiz proof objects, public proof rendering, Sports Arena card/event proof integration, wallet ledger reads, Connect transfers, and webhook delivery verification.
+Use one typed client for Receiz proof objects, public proof rendering, Sports Arena card/event proof integration, wallet ledger reads, Twin and World surfaces, Connect transfers, and webhook delivery verification.
 
 ```ts
 import { createReceizClient } from "@receiz/sdk";
@@ -17,6 +17,16 @@ 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.
@@ -42,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,
@@ -68,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";
@@ -85,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.
@@ -173,6 +219,32 @@ const ledger = await receiz.wallet.publicLedger({ limit: 40 });
 
 Full quickstart: `docs/wallet-ledger-reads.md`.
 
+## Twin And World
+
+Public World/Twin reads are available without a token. Owner-scoped Twin actions require a Receiz Connect access token with `receiz:twin.read` or `receiz:twin.write`, issued through a registered OIDC client.
+
+```ts
+import { createReceizClient } from "@receiz/sdk";
+
+const publicReceiz = createReceizClient();
+const world = await publicReceiz.world.profile("bjklock");
+
+const receiz = createReceizClient({ accessToken: process.env.RECEIZ_ACCESS_TOKEN });
+const mandate = await receiz.twin.marketMandate();
+await receiz.twin.saveMarketMandate({
+  status: "active",
+  executionMode: "approve",
+  maxOrderUsd: "25.00",
+});
+const intent = await receiz.twin.createMarketIntent({
+  marketItemId: "asset_123",
+  side: "buy",
+  amountUsd: "10.00",
+});
+```
+
+Full quickstart: `docs/twin-and-world.md`.
+
 ## Connect Transfers
 
 ```ts

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;
+});