@receiz/sdk 95.0.0 → 96.1.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 = "95.0.0";
+export const RECEIZ_SDK_VERSION = "96.1.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";
@@ -347,6 +347,29 @@ export class ReceizClient {
         publicLedger: (query = {}) => this.publicWalletLedger(query),
         actionLedger: (query = {}) => this.request(appendQuery("/api/ledger/actions/public", query)),
     };
+    world = {
+        publicSnapshot: () => this.request("/api/world/public"),
+        profile: (username, query = {}) => this.request(appendQuery(`/api/world/profile/${encodePathSegment(username)}`, {
+            visitorKey: query.visitorKey,
+            threadKey: query.threadKey,
+        })),
+        message: (username, body) => this.request(`/api/world/profile/${encodePathSegment(username)}`, {
+            method: "POST",
+            body: { ...body, action: body.action ?? "message" },
+        }),
+        welcome: (username, body = {}) => this.request(`/api/world/profile/${encodePathSegment(username)}`, {
+            method: "POST",
+            body: { ...body, action: "welcome" },
+        }),
+        book: (username, body) => this.request(`/api/world/profile/${encodePathSegment(username)}`, {
+            method: "POST",
+            body: { ...body, action: "book" },
+        }),
+        streamProfile: (username, body) => this.streamJsonEvents(`/api/world/profile/${encodePathSegment(username)}/stream`, {
+            method: "POST",
+            body: { ...body, action: body.action === "welcome" ? "welcome" : "message" },
+        }),
+    };
     connect = {
         wallet: () => this.delegated("/api/connect/wallet/me"),
         record: (body) => this.delegated("/api/connect/record", { method: "POST", body }),
@@ -359,6 +382,20 @@ export class ReceizClient {
         claimNote: (body) => this.delegated("/api/connect/payments/notes/claim", { method: "POST", body }),
         downloadNote: (noteId) => this.delegated(`/api/connect/payments/notes/${encodePathSegment(noteId)}/download`),
     };
+    twin = {
+        marketMandate: () => this.delegated("/api/connect/twin/market/mandate", { method: "GET" }),
+        saveMarketMandate: (body) => this.delegated("/api/connect/twin/market/mandate", { method: "PATCH", body }),
+        marketIntents: () => this.delegated("/api/connect/twin/market/intents", { method: "GET" }),
+        createMarketIntent: (body) => this.delegated("/api/connect/twin/market/intents", { method: "POST", body }),
+        approveMarketIntent: (intentId) => this.delegated(`/api/connect/twin/market/intents/${encodePathSegment(intentId)}/approve`, {
+            method: "POST",
+        }),
+        exportMind: () => this.delegatedBlob("/api/connect/twin/mind/export"),
+        importMindSummary: () => this.delegated("/api/connect/twin/mind/import", { method: "GET" }),
+        importMind: (file) => this.delegatedTwinMindImport(file),
+        approval: () => this.delegated("/api/connect/twin/approval", { method: "GET" }),
+        approvePromotion: (body) => this.delegated("/api/connect/twin/approval", { method: "POST", body }),
+    };
     identity = {
         createReceizId: createReceizIdIdentity,
         readArtifact: readReceizIdentityArtifact,
@@ -425,6 +462,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);
@@ -488,6 +530,88 @@ export class ReceizClient {
             throw new Error("receiz_access_token_required");
         return this.request(path, { ...options, bearerToken: this.accessToken });
     }
+    async delegatedBlob(path, options = {}) {
+        if (!this.accessToken)
+            throw new Error("receiz_access_token_required");
+        const headers = new Headers(options.headers);
+        if (!headers.has("accept"))
+            headers.set("accept", "application/octet-stream");
+        headers.set("authorization", `Bearer ${this.accessToken}`);
+        const response = await this.fetchImpl(`${this.baseUrl}${requestPath(path)}`, {
+            method: options.method ?? "GET",
+            headers,
+        });
+        if (!response.ok)
+            throw new ReceizHttpError(response.status, await readPayload(response));
+        return response.blob();
+    }
+    async delegatedTwinMindImport(file) {
+        const form = new FormData();
+        form.set("mind", file);
+        return this.delegated("/api/connect/twin/mind/import", { method: "POST", body: form });
+    }
+    async *streamJsonEvents(path, options = {}) {
+        const headers = new Headers(options.headers);
+        if (!headers.has("accept"))
+            headers.set("accept", "text/event-stream");
+        const token = options.bearerToken ?? this.accessToken;
+        if (token)
+            headers.set("authorization", `Bearer ${token}`);
+        let body = options.body;
+        if (isJsonRecordBody(body)) {
+            if (!headers.has("content-type"))
+                headers.set("content-type", "application/json");
+            body = JSON.stringify(body);
+        }
+        const url = path.startsWith("http://") || path.startsWith("https://") ? path : `${this.baseUrl}${requestPath(path)}`;
+        const response = await this.fetchImpl(url, {
+            method: options.method ?? "GET",
+            headers,
+            ...(body !== undefined ? { body: body } : {}),
+        });
+        if (!response.ok)
+            throw new ReceizHttpError(response.status, await readPayload(response));
+        if (!response.body)
+            throw new Error("receiz_stream_unavailable");
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        const parseEvent = (raw) => {
+            const data = raw
+                .split("\n")
+                .filter((line) => line.startsWith("data:"))
+                .map((line) => line.slice(5).trimStart())
+                .join("\n")
+                .trim();
+            if (!data)
+                return null;
+            return JSON.parse(data);
+        };
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+                let boundary = buffer.indexOf("\n\n");
+                while (boundary >= 0) {
+                    const raw = buffer.slice(0, boundary);
+                    buffer = buffer.slice(boundary + 2);
+                    const parsed = parseEvent(raw);
+                    if (parsed)
+                        yield parsed;
+                    boundary = buffer.indexOf("\n\n");
+                }
+            }
+            buffer += decoder.decode().replace(/\r\n/g, "\n");
+            const parsed = parseEvent(buffer);
+            if (parsed)
+                yield parsed;
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
     async continueReceizId(identity, options = {}) {
         const body = await buildReceizIdContinueRequest(identity, options);
         return this.request("/api/auth/receiz-id/continue", { method: "POST", body });
@@ -863,6 +987,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,
@@ -922,6 +1107,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;
@@ -938,6 +1128,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)));
     }
@@ -977,6 +1177,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/app-registration-token-lifecycle.md

@@ -12,7 +12,7 @@ const authorizeUrl = receiz.identity.authorizeUrl({
   clientId: process.env.RECEIZ_CLIENT_ID!,
   redirectUri: "https://app.example.com/auth/receiz/callback",
   codeChallenge,
-  scope: ["openid", "profile", "receiz:verify", "receiz:wallet.transfer"],
+  scope: ["openid", "profile", "receiz:verify", "receiz:wallet.transfer", "receiz:twin.read"],
   state,
 });
 ```
@@ -29,3 +29,5 @@ Lifecycle:
 6. Revoke tokens when the user disconnects your app.
 
 Use `sub` from OIDC as the stable external user key. Do not key your user model by mutable email.
+
+Public Receiz World reads do not require OIDC. Delegated owner actions, including Twin market mandates, Twin intents, Twin mind import/export, wallet transfers, records, seals, verification, payments, and note actions, require a registered OIDC client and a user-granted access token. Business/developer accounts are the correct place to create and manage those clients, redirect URIs, scopes, and token lifecycle.

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.