@receiz/sdk 95.0.0 → 96.1.0

package/docs/copy-paste-integrations.md

@@ -0,0 +1,229 @@
+# 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.
+
+## Receiz World Storefront Twin
+
+Use the public World profile for first paint. Use delegated Twin methods only after the user authorizes your app through Connect.
+
+```ts
+import { createReceizClient } from "@receiz/sdk";
+
+export async function loadPublicStorefront(username: string) {
+  const receiz = createReceizClient();
+  const world = await receiz.world.profile(username);
+  if (!world.ok) throw new Error(world.error ?? "world_profile_failed");
+  return world.world;
+}
+
+export async function runDelegatedTwin(accessToken: string) {
+  const receiz = createReceizClient({ accessToken });
+  const mandate = await receiz.twin.marketMandate();
+  const intents = await receiz.twin.marketIntents();
+  return { mandate: mandate.mandate, intents: intents.intents ?? [] };
+}
+```
+
+The public surface is public proof projection. The delegated surface is scoped action permission. Do not use a Connect token as the identity proof root.
+
+## 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

@@ -54,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.
@@ -95,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

package/docs/twin-and-world.md

@@ -0,0 +1,163 @@
+# Twin And World
+
+The SDK exposes Receiz World and Live Twin without changing the authority model.
+
+Public World reads and public twin conversations are public surfaces. Owner Twin controls are delegated Connect actions and require a registered OIDC client plus the user-granted scopes your app needs.
+
+```txt
+Receiz ID / proof objects / Twin mind artifact -> projection now
+Connect token -> delegated API permission
+server routes -> sync, append, import, export, execute inside mandate
+```
+
+The SDK is convenience, not authority. A Connect token authorizes access after identity proof. It does not replace Receiz ID, the Twin mind artifact, market mandates, proof memory, or settlement primitives.
+
+## Public World Profile
+
+```ts
+import { createReceizClient } from "@receiz/sdk";
+
+const receiz = createReceizClient();
+
+const profile = await receiz.world.profile("bjklock", {
+  visitorKey: "visitor-local-id",
+  threadKey: "thread-local-id",
+});
+
+if (!profile.ok) throw new Error(profile.error);
+
+renderWorld(profile.world);
+```
+
+## Public Twin Conversation
+
+```ts
+const reply = await receiz.world.message("bjklock", {
+  visitorKey: "visitor-local-id",
+  threadKey: "thread-local-id",
+  message: "Can you show me the current offer?",
+});
+
+renderReply(reply.reply);
+renderWorld(reply.world);
+```
+
+Streaming uses the same public route and returns parsed server-sent events:
+
+```ts
+for await (const event of receiz.world.streamProfile("bjklock", {
+  visitorKey: "visitor-local-id",
+  threadKey: "thread-local-id",
+  message: "Walk me through this site.",
+})) {
+  if (event.type === "reply_delta") appendText(event.delta ?? "");
+  if (event.type === "reply_done") renderWorld(event.world);
+}
+```
+
+## OIDC Scopes
+
+For owner actions, register an app and request only the scopes your app needs:
+
+```ts
+const authorizeUrl = receiz.identity.authorizeUrl({
+  clientId: process.env.RECEIZ_CLIENT_ID!,
+  redirectUri: "https://app.example.com/auth/receiz/callback",
+  codeChallenge,
+  scope: [
+    "openid",
+    "profile",
+    "offline_access",
+    "receiz:twin.read",
+    "receiz:twin.write",
+  ],
+  state,
+});
+```
+
+`receiz:twin.read` allows delegated reads such as market mandate, intent list, Twin approval state, and Twin mind export.
+
+`receiz:twin.write` allows delegated mutations such as saving a market mandate, creating or approving market intents, importing Twin mind artifacts, and approving public Twin promotion when the owner has the required automation entitlement.
+
+## Market Twin Mandate
+
+```ts
+const receiz = createReceizClient({
+  accessToken: process.env.RECEIZ_ACCESS_TOKEN!,
+});
+
+const current = await receiz.twin.marketMandate();
+
+await receiz.twin.saveMarketMandate({
+  status: "active",
+  executionMode: "approve",
+  allowedMarketTypes: ["asset"],
+  allowedSides: ["buy", "sell"],
+  maxOrderUsd: "25.00",
+  maxDailyGrossUsd: "100.00",
+  maxDailyLossUsd: "0.00",
+});
+```
+
+This does not bypass the Market Twin mandate. It edits the mandate through the same server primitive Receiz uses.
+
+## Market Twin Intents
+
+```ts
+const created = await receiz.twin.createMarketIntent({
+  marketItemId: "asset_123",
+  marketType: "asset",
+  side: "buy",
+  amountUsd: "10.00",
+  reason: "Owner-approved storefront inventory test.",
+});
+
+if (created.intent?.status === "pending") {
+  const approved = await receiz.twin.approveMarketIntent(created.intent.id);
+  renderTrade(approved.trade);
+}
+```
+
+Intent execution remains inside the mandate, risk checks, wallet settlement, and market execution primitives. The SDK does not create a second execution engine.
+
+## Twin Mind Export And Import
+
+```ts
+const mindImage = await receiz.twin.exportMind();
+await saveFile("receiz-twin-mind.png", mindImage);
+```
+
+Import verifies the Twin mind artifact before restore:
+
+```ts
+const summary = await receiz.twin.importMind(file);
+renderImportSummary(summary.summary);
+```
+
+This is file-carried Twin memory. Treat the exported image as a proof object transport. Do not flatten it into generic profile metadata.
+
+## Public Twin Promotion
+
+```ts
+const approval = await receiz.twin.approval();
+
+await receiz.twin.approvePromotion({
+  performance: {
+    style: "photoreal",
+    score: 98,
+    reason: "Owner-approved public Twin promotion.",
+  },
+  approvalReference: "external-app-review-001",
+  evidenceAssets: [{ kind: "image", url: "https://app.example.com/evidence.png" }],
+});
+```
+
+Promotion approval still requires the owner account to have the required automation entitlement. A token with `receiz:twin.write` authorizes the app to ask; it does not remove account-level law.
+
+## Business / Developer Account Boundary
+
+Public World reads do not require a business/developer account.
+
+Delegated owner actions require an app registration so Receiz can issue OIDC tokens for that app. In practice, a business/developer account is the correct account type for creating and managing OIDC clients, redirect URIs, scopes, token lifecycle, and production app access.
+
+The user still proves identity through Receiz. The app receives delegated access only after the user authorizes it.

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@receiz/sdk",
-  "version": "95.0.0",
-  "description": "TypeScript SDK for Receiz proof-native artifact, public proof, wallet, sports, and Connect integrations.",
+  "version": "96.1.0",
+  "description": "TypeScript SDK for Receiz proof-native artifact, public proof, wallet, sports, Twin, World, 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",