@receiz/sdk 94.0.0 → 96.0.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { buildReceizIdContinueRequest, createReceizIdIdentity, projectReceizIdentityAccount, readReceizIdentityArtifact, signReceizIdentityLoginProof, verifyReceizIdentityLoginProof, } from "./identity.js";
 export * from "./identity.js";
-export const RECEIZ_SDK_VERSION = "94.0.0";
+export const RECEIZ_SDK_VERSION = "96.0.0";
 export const RECEIZ_DEFAULT_BASE_URL = "https://receiz.com";
 export const RECEIZ_WEBHOOK_SIGNATURE_HEADER = "x-receiz-signature";
 export const RECEIZ_WEBHOOK_TIMESTAMP_HEADER = "x-receiz-timestamp";
@@ -19,12 +19,34 @@ export const RECEIZ_ASSET_MANIFEST_SCHEMA = {
         },
         proof: {
             type: "object",
-            required: ["kind"],
+            required: [
+                "kind",
+                "payloadVersion",
+                "createdAtMs",
+                "ts",
+                "code",
+                "slug",
+                "verifyPath",
+                "verifyUrl",
+                "kaiPulseEternal",
+                "kaiKlok",
+                "receizClaimId",
+                "sigilClaimSeed",
+            ],
             additionalProperties: true,
             properties: {
-                kind: { type: "string", minLength: 1 },
+                kind: { const: "receiz.proof_bundle" },
+                payloadVersion: { enum: ["v2", "v1"] },
+                createdAtMs: { type: "number" },
+                ts: { type: "string", minLength: 1 },
+                code: { type: "string", minLength: 1 },
+                slug: { type: "string", minLength: 1 },
+                verifyPath: { type: "string", minLength: 1 },
                 verifyUrl: { type: "string" },
-                kaiPulseEternal: { type: ["number", "string"] },
+                kaiPulseEternal: { type: "string", minLength: 1 },
+                kaiKlok: { type: "string", minLength: 1 },
+                receizClaimId: { type: "string", minLength: 1 },
+                sigilClaimSeed: { type: "string", minLength: 1 },
             },
         },
         owner: { type: ["object", "null"], additionalProperties: true },
@@ -208,6 +230,79 @@ function failIfIssues(label, issues) {
     if (issues.length > 0)
         throw new ReceizValidationError(label, issues);
 }
+function asSdkHex(value, length) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase();
+    const pattern = new RegExp(`^[0-9a-f]{${length}}$`);
+    return pattern.test(normalized) ? normalized : null;
+}
+function validateOptionalSdkHex(record, key, length, issues, path) {
+    if (record[key] === undefined)
+        return;
+    if (!asSdkHex(record[key], length))
+        issues.push(`${path}.${key} must be ${length} lowercase hex characters`);
+}
+function validateReceizProofBundleShape(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push(`${path} must be an object`);
+        return null;
+    }
+    if (value.kind !== "receiz.proof_bundle")
+        issues.push(`${path}.kind must be receiz.proof_bundle`);
+    if (value.payloadVersion !== "v2" && value.payloadVersion !== "v1") {
+        issues.push(`${path}.payloadVersion must be v2 or v1`);
+    }
+    const createdAtMs = value.createdAtMs;
+    if (typeof createdAtMs !== "number" || !Number.isFinite(createdAtMs)) {
+        issues.push(`${path}.createdAtMs must be a finite number`);
+    }
+    for (const key of ["ts", "code", "slug", "verifyPath", "kaiPulseEternal", "kaiKlok", "receizClaimId", "sigilClaimSeed"]) {
+        const fieldValue = value[key];
+        if (typeof fieldValue !== "string" || !fieldValue.trim())
+            issues.push(`${path}.${key} must be a non-empty string`);
+    }
+    if (typeof value.verifyUrl !== "string")
+        issues.push(`${path}.verifyUrl must be a string`);
+    if (value.tsDisplay !== undefined && (typeof value.tsDisplay !== "string" || !value.tsDisplay.trim())) {
+        issues.push(`${path}.tsDisplay must be a non-empty string when present`);
+    }
+    if (value.tzMinutesEast !== undefined && (typeof value.tzMinutesEast !== "number" || !Number.isFinite(value.tzMinutesEast))) {
+        issues.push(`${path}.tzMinutesEast must be a finite number when present`);
+    }
+    validateOptionalSdkHex(value, "signerKeyId", 12, issues, path);
+    validateOptionalSdkHex(value, "anchorId", 8, issues, path);
+    validateOptionalSdkHex(value, "groth16ProofDigest", 64, issues, path);
+    validateOptionalSdkHex(value, "artifactSha256Basis", 64, issues, path);
+    if (value.zkPoseidonHash !== undefined && (typeof value.zkPoseidonHash !== "string" || !value.zkPoseidonHash.trim())) {
+        issues.push(`${path}.zkPoseidonHash must be a non-empty string when present`);
+    }
+    if (value.signatureV3 !== undefined && !isRecord(value.signatureV3)) {
+        issues.push(`${path}.signatureV3 must be an object when present`);
+    }
+    if (value.signatureV4 !== undefined && !isRecord(value.signatureV4)) {
+        issues.push(`${path}.signatureV4 must be an object when present`);
+    }
+    if (value.wireproof !== undefined) {
+        const wireproof = value.wireproof;
+        if (!isRecord(wireproof)) {
+            issues.push(`${path}.wireproof must be an object when present`);
+        }
+        else {
+            if (wireproof.schema !== "wireproof.v1")
+                issues.push(`${path}.wireproof.schema must be wireproof.v1`);
+            if (!asSdkHex(wireproof.anchorId, 8))
+                issues.push(`${path}.wireproof.anchorId must be 8 lowercase hex characters`);
+            if (!asSdkHex(wireproof.claimHashSha256, 64)) {
+                issues.push(`${path}.wireproof.claimHashSha256 must be 64 lowercase hex characters`);
+            }
+            if (typeof wireproof.verifierPath !== "string" || !wireproof.verifierPath.trim()) {
+                issues.push(`${path}.wireproof.verifierPath must be a non-empty string`);
+            }
+        }
+    }
+    return value;
+}
 const WEBHOOK_EVENT_TYPES = new Set([
     "asset.created",
     "asset.transferred",
@@ -330,6 +425,11 @@ export class ReceizClient {
     };
     proofMemory = {
         createRegister: createReceizProofRegister,
+        createMemory: createReceizProofMemory,
+        createInMemoryStorage: createReceizInMemoryProofMemoryStorage,
+        createLocalStorage: createReceizLocalStorageProofMemoryStorage,
+        assertSnapshot: assertReceizProofRegisterSnapshot,
+        additionsQuery: receizProofMemoryAdditionsQuery,
     };
     constructor(options = {}) {
         this.baseUrl = trimTrailingSlash(options.baseUrl ?? RECEIZ_DEFAULT_BASE_URL);
@@ -441,6 +541,21 @@ export async function loadReceizOpenApi(baseUrl = RECEIZ_DEFAULT_BASE_URL, fetch
         throw new ReceizHttpError(response.status, await readPayload(response));
     return response.json();
 }
+export function assertReceizProofBundle(value) {
+    const issues = [];
+    const proof = validateReceizProofBundleShape(value, "proof", issues);
+    failIfIssues("ReceizProofBundle", issues);
+    return proof;
+}
+export function isReceizProofBundle(value) {
+    try {
+        assertReceizProofBundle(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export function assertReceizAssetManifest(value) {
     const record = ensureRecord(value, "ReceizAssetManifest");
     const issues = [];
@@ -449,8 +564,7 @@ export function assertReceizAssetManifest(value) {
     ensureString(record, "assetId", issues);
     ensureString(record, "assetType", issues);
     const proof = record.proof;
-    if (!isRecord(proof) || typeof proof.kind !== "string" || !proof.kind.trim())
-        issues.push("proof.kind must be a non-empty string");
+    validateReceizProofBundleShape(proof, "proof", issues);
     ensureOptionalRecord(record, "owner", issues);
     ensureOptionalRecord(record, "media", issues);
     ensureOptionalRecord(record, "settlement", issues);
@@ -754,6 +868,67 @@ function normalizeRegisterEntry(value) {
         projection: isRecord(projection) ? projection : null,
     };
 }
+export function assertReceizProofRegisterSnapshot(value) {
+    const record = ensureRecord(value, "ReceizProofRegisterSnapshot");
+    const issues = [];
+    if (record.schema !== "receiz.sdk.proof_register.v1")
+        issues.push("schema must be receiz.sdk.proof_register.v1");
+    const ownerId = record.ownerId;
+    if (ownerId !== null && ownerId !== undefined && typeof ownerId !== "string") {
+        issues.push("ownerId must be a string or null when present");
+    }
+    const createdAt = ensureString(record, "createdAt", issues);
+    const updatedAt = ensureString(record, "updatedAt", issues);
+    const head = record.head;
+    if (!isRecord(head)) {
+        issues.push("head must be an object");
+    }
+    else {
+        const entryId = head.entryId;
+        if (entryId !== null && entryId !== undefined && typeof entryId !== "string") {
+            issues.push("head.entryId must be a string or null");
+        }
+        const kaiUpulse = head.kaiUpulse;
+        if (kaiUpulse !== null && kaiUpulse !== undefined && typeof kaiUpulse !== "string" && typeof kaiUpulse !== "number") {
+            issues.push("head.kaiUpulse must be a string, number, or null");
+        }
+        const headCreatedAt = head.createdAt;
+        if (headCreatedAt !== null && headCreatedAt !== undefined && typeof headCreatedAt !== "string") {
+            issues.push("head.createdAt must be a string or null");
+        }
+        if (typeof head.count !== "number" || !Number.isInteger(head.count) || head.count < 0) {
+            issues.push("head.count must be a non-negative integer");
+        }
+    }
+    if (!Array.isArray(record.entries))
+        issues.push("entries must be an array");
+    failIfIssues("ReceizProofRegisterSnapshot", issues);
+    const entries = record.entries.map((entry) => normalizeRegisterEntry(entry));
+    return {
+        schema: "receiz.sdk.proof_register.v1",
+        ownerId: typeof ownerId === "string" || ownerId === null ? ownerId : null,
+        createdAt: createdAt ?? "",
+        updatedAt: updatedAt ?? "",
+        head: {
+            entryId: isRecord(head) && typeof head.entryId === "string" ? head.entryId : null,
+            kaiUpulse: isRecord(head) && (typeof head.kaiUpulse === "string" || typeof head.kaiUpulse === "number") ? head.kaiUpulse : null,
+            createdAt: isRecord(head) && typeof head.createdAt === "string" ? head.createdAt : null,
+            count: isRecord(head) && typeof head.count === "number" ? head.count : entries.length,
+        },
+        entries,
+    };
+}
+function parseProofMemoryStorageValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return null;
+        return assertReceizProofRegisterSnapshot(JSON.parse(trimmed));
+    }
+    return assertReceizProofRegisterSnapshot(value);
+}
 function mergeRegisterEntry(existing, incoming) {
     return {
         id: existing.id,
@@ -813,6 +988,11 @@ function registerEntryFromWebhookEvent(event) {
         },
     };
 }
+function errorDetail(error) {
+    if (error instanceof Error)
+        return { name: error.name, message: error.message };
+    return { message: String(error) };
+}
 export class ReceizProofRegister {
     ownerId;
     createdAt;
@@ -829,6 +1009,16 @@ export class ReceizProofRegister {
         this.entriesById.set(normalized.id, existing ? mergeRegisterEntry(existing, normalized) : normalized);
         return this;
     }
+    admit(value) {
+        if (isReceizAssetManifest(value))
+            return this.admitAssetManifest(value);
+        if (isReceizSportsCardManifest(value))
+            return this.admitSportsCardManifest(value);
+        if (isReceizWebhookEvent(value))
+            return this.admitWebhookEvent(value);
+        const schema = isRecord(value) && typeof value.schema === "string" ? value.schema : "unknown";
+        throw new ReceizValidationError("ReceizProofAdmission", [`unsupported proof object schema ${schema}`]);
+    }
     admitAssetManifest(value) {
         return this.append(registerEntryFromAssetManifest(assertReceizAssetManifest(value)));
     }
@@ -868,6 +1058,193 @@ export class ReceizProofRegister {
 export function createReceizProofRegister(input = {}) {
     return new ReceizProofRegister(input);
 }
+export class ReceizProofMemory {
+    register;
+    storage;
+    autoPersist;
+    onPersistError;
+    onObservation;
+    persistChain = Promise.resolve();
+    constructor(register, options = {}) {
+        this.register = register;
+        this.storage = options.storage ?? null;
+        this.autoPersist = options.autoPersist ?? true;
+        this.onPersistError = options.onPersistError ?? null;
+        this.onObservation = options.onObservation ?? null;
+    }
+    append(entry) {
+        const startedAtMs = Date.now();
+        try {
+            this.register.append(entry);
+            this.observe("proof_memory.append", startedAtMs, "ok");
+            return this.schedulePersist();
+        }
+        catch (error) {
+            this.observe("proof_memory.append", startedAtMs, "error", errorDetail(error));
+            throw error;
+        }
+    }
+    admit(value) {
+        const startedAtMs = Date.now();
+        try {
+            this.register.admit(value);
+            this.observe("proof_memory.admit", startedAtMs, "ok");
+            return this.schedulePersist();
+        }
+        catch (error) {
+            this.observe("proof_memory.admit", startedAtMs, "error", errorDetail(error));
+            throw error;
+        }
+    }
+    admitAssetManifest(value) {
+        return this.admit(value);
+    }
+    admitSportsCardManifest(value) {
+        return this.admit(value);
+    }
+    admitWebhookEvent(value) {
+        return this.admit(value);
+    }
+    has(entryId) {
+        return this.register.has(entryId);
+    }
+    entries() {
+        return this.register.entries();
+    }
+    snapshot() {
+        return this.register.snapshot();
+    }
+    knownHead(limit) {
+        return receizProofMemoryAdditionsQuery(this.snapshot(), limit);
+    }
+    async persist() {
+        const startedAtMs = Date.now();
+        try {
+            const snapshot = this.snapshot();
+            if (this.storage)
+                await this.storage.write(snapshot);
+            this.observe("proof_memory.persist", startedAtMs, "ok", { persisted: Boolean(this.storage) });
+            return snapshot;
+        }
+        catch (error) {
+            this.observe("proof_memory.persist", startedAtMs, "error", errorDetail(error));
+            throw error;
+        }
+    }
+    async flush() {
+        await this.persistChain;
+    }
+    async clear() {
+        const startedAtMs = Date.now();
+        try {
+            if (this.storage?.remove)
+                await this.storage.remove();
+            this.observe("proof_memory.clear", startedAtMs, "ok", { removed: Boolean(this.storage?.remove) });
+        }
+        catch (error) {
+            this.observe("proof_memory.clear", startedAtMs, "error", errorDetail(error));
+            throw error;
+        }
+    }
+    toJSON() {
+        return this.snapshot();
+    }
+    schedulePersist() {
+        if (!this.autoPersist || !this.storage)
+            return this;
+        this.persistChain = this.persistChain
+            .then(async () => {
+            await this.persist();
+        })
+            .catch((error) => {
+            this.onPersistError?.(error);
+        });
+        return this;
+    }
+    observe(operation, startedAtMs, status, detail) {
+        if (!this.onObservation)
+            return;
+        const endedAtMs = Date.now();
+        const snapshot = this.snapshot();
+        const observation = {
+            schema: "receiz.sdk.observation.v1",
+            operation,
+            status,
+            startedAt: new Date(startedAtMs).toISOString(),
+            endedAt: new Date(endedAtMs).toISOString(),
+            durationMs: Math.max(0, endedAtMs - startedAtMs),
+            ownerId: this.register.ownerId,
+            entryCount: snapshot.head.count,
+            headEntryId: snapshot.head.entryId,
+            headKaiUpulse: snapshot.head.kaiUpulse,
+        };
+        if (detail)
+            observation.detail = detail;
+        try {
+            this.onObservation(observation);
+        }
+        catch {
+            // Observation callbacks are passive evidence only; they must never affect proof admission.
+        }
+    }
+}
+export async function createReceizProofMemory(options = {}) {
+    const storedSnapshot = options.storage ? parseProofMemoryStorageValue(await options.storage.read()) : null;
+    const input = storedSnapshot
+        ? {
+            ...storedSnapshot,
+            ownerId: options.ownerId ?? storedSnapshot.ownerId ?? null,
+        }
+        : {
+            ownerId: options.ownerId ?? null,
+            ...(options.createdAt === undefined ? {} : { createdAt: options.createdAt }),
+            ...(options.entries === undefined ? {} : { entries: options.entries }),
+        };
+    return new ReceizProofMemory(createReceizProofRegister(input), options);
+}
+export function createReceizInMemoryProofMemoryStorage(initialValue = null) {
+    let storedText = typeof initialValue === "string"
+        ? initialValue
+        : initialValue
+            ? JSON.stringify(assertReceizProofRegisterSnapshot(initialValue))
+            : null;
+    return {
+        read: () => storedText,
+        write: (snapshot) => {
+            storedText = JSON.stringify(assertReceizProofRegisterSnapshot(snapshot));
+        },
+        remove: () => {
+            storedText = null;
+        },
+        readText: () => storedText,
+    };
+}
+export function createReceizLocalStorageProofMemoryStorage(key = "receiz:proof-memory:v1", storage = globalThis.localStorage) {
+    if (!storage)
+        throw new Error("receiz_local_storage_unavailable");
+    return {
+        read: () => storage.getItem(key),
+        write: (snapshot) => {
+            storage.setItem(key, JSON.stringify(assertReceizProofRegisterSnapshot(snapshot)));
+        },
+        remove: () => {
+            storage.removeItem(key);
+        },
+    };
+}
+export function receizProofMemoryAdditionsQuery(value, limit) {
+    const snapshot = value instanceof ReceizProofRegister
+        ? value.snapshot()
+        : value instanceof ReceizProofMemory
+            ? value.snapshot()
+            : assertReceizProofRegisterSnapshot(value);
+    return {
+        afterEntryId: snapshot.head.entryId,
+        afterKaiUpulse: snapshot.head.kaiUpulse,
+        afterCreatedAt: snapshot.head.createdAt,
+        ...(limit === undefined ? {} : { limit }),
+    };
+}
 function bodyToString(body) {
     if (typeof body === "string")
         return body;

package/docs/cli-and-conformance.md

@@ -0,0 +1,108 @@
+# CLI And Local Conformance
+
+The Receiz SDK ships an executable `receiz` command for local proof inspection, fixture conformance, and starter generation.
+
+The CLI is convenience, not authority. It uses the same SDK validators, projections, and durable proof memory APIs that developer apps import from `@receiz/sdk`. It does not create a new conformance system, issuer, verifier, server confirmation, database confirmation, or truth layer.
+
+## Install
+
+```bash
+npm install @receiz/sdk
+```
+
+Run without a local install:
+
+```bash
+npx @receiz/sdk conformance
+```
+
+## Run Local Fixture Conformance
+
+```bash
+npx @receiz/sdk conformance
+```
+
+This validates the packaged fixtures:
+
+- `receiz.asset_manifest.v1`
+- `receiz.sports_arena.card_manifest.v1`
+- `receiz.webhook_event.v1`
+
+Each fixture is admitted into durable proof memory, persisted through the same storage interface developer apps use, reopened from the stored proof register, and summarized with its known Kai/proof head.
+
+Expected shape:
+
+```json
+{
+  "ok": true,
+  "schema": "receiz.sdk.cli.conformance.v1",
+  "summary": {
+    "fixtures": 3,
+    "proofMemoryEntries": 3,
+    "networkCalls": 0,
+    "dbCalls": 0
+  }
+}
+```
+
+`networkCalls` and `dbCalls` are zero by design. Local conformance proves the SDK can admit and project proof objects from carried truth without asking a weaker layer whether the proof is true.
+
+## Inspect A Proof Payload
+
+```bash
+npx @receiz/sdk inspect ./receiz-asset-manifest.json
+```
+
+The command validates one JSON payload, projects display-ready rows, admits the payload into in-memory proof memory, and prints the known head:
+
+```json
+{
+  "ok": true,
+  "schema": "receiz.sdk.cli.inspect.v1",
+  "kind": "asset_manifest",
+  "knownHead": {
+    "afterEntryId": "asset:asset_example_01JZ_RECEIZ",
+    "afterKaiUpulse": "123456",
+    "afterCreatedAt": "2026-06-25T00:00:00.000Z",
+    "limit": 100
+  }
+}
+```
+
+The known head is the append-sync boundary. Your app asks for verified additions after this head; it does not rediscover the admitted prefix.
+
+## Generate A Starter
+
+```bash
+npx @receiz/sdk init ./receiz-integration
+```
+
+This writes:
+
+```txt
+receiz-proof-memory.ts
+```
+
+The starter:
+
+- opens durable proof memory through `createReceizProofMemory`
+- persists through `createReceizLocalStorageProofMemoryStorage`
+- admits asset manifests, Sports card manifests, and webhook events
+- projects proof objects immediately after admission
+- exposes `knownHead()` for append-only sync
+
+It does not include Supabase, service-role keys, or a parallel source of truth.
+
+## Production Rule
+
+Use the CLI to prove your local integration shape, then use the typed SDK APIs in your app:
+
+1. Verify stronger proof truth when bytes come from an untrusted transport.
+2. Validate the manifest or event shape.
+3. Project display-ready rows from the verified object.
+4. Admit the proof object into durable proof memory.
+5. Persist the proof memory snapshot.
+6. Resume from the known Kai/proof head.
+7. Append later verified additions without rediscovering known truth.
+
+That is the same law Receiz uses internally: first admission only, then append forever.