@receiz/sdk 96.2.0 → 97.1.0

package/README.md

@@ -201,34 +201,89 @@ Full quickstart: `docs/public-proof-rendering.md`.
 
 Receiz apps can publish durable public app-state projections without adding Supabase, Redis, Vercel KV, Shopify, or a custom database. Writes require delegated Connect/OIDC access with `receiz:record`; reads are public when the projection is public.
 
+```ts
+import {
+  RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
+  createReceizClient,
+  createReceizPublicStoreStateRecord,
+} from "@receiz/sdk";
+
+const receiz = createReceizClient({ accessToken });
+
+await receiz.appState.publishRecord(createReceizPublicStoreStateRecord({
+  sourceUrl: "bjklock.receiz.app",
+  externalCreatorId: "bjklock.receiz.id",
+  title: "BJ Klock storefront",
+  data: { storeStateRecord },
+}));
+
+const restored = await createReceizClient().appState.restoreByHost<{
+  storeStateRecord: StoreStateRecord;
+}>("bjklock.receiz.app", {
+  schema: RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
+  state: "published",
+  requiredDataKey: "storeStateRecord",
+});
+
+if (restored.ok && restored.data) renderStorefront(restored.data.storeStateRecord);
+```
+
+`receiz.appState.publish(feed)` remains available for batch writes. `receiz.publicProof.registryFeed(feed)` remains available and aliases the same publish path for existing integrations.
+Raw reads remain available through `byUrl()`, `byHost()`, `byCreator()`, `byNamespace()`, and `byId()` when an app needs the full public projection envelope instead of direct restored data.
+
+Full quickstart: `docs/app-state-public-projections.md`.
+
+## Receiz App Runtime Rails
+
+`@receiz/sdk@97.1.0` adds typed rails for Commerce Cloud style apps. These helpers compose existing Receiz primitives; they do not replace proof objects, local proof memory, Connect, or the public app-state projection rail.
+
 ```ts
 import { createReceizClient } from "@receiz/sdk";
 
 const receiz = createReceizClient({ accessToken });
 
+const doctor = await receiz.doctor({
+  tenantHost: "bjklock.receiz.app",
+  callbackUrl: "https://bjklock.receiz.app/api/auth/receiz/callback",
+  scopes: ["openid", "profile", "receiz:record", "receiz:wallet.read"],
+});
+if (!doctor.ok) console.table(doctor.fixes);
+
+const caps = await receiz.capabilities({ tenantHost: "bjklock.receiz.app" });
+if (caps.capabilities.commerce.available) {
+  await receiz.commerce.oneClickCheckout({
+    tenantHost: "bjklock.receiz.app",
+    orderId: "order_123",
+    amountUsd: "42.00",
+    walletFirst: true,
+    cardFallback: true,
+    idempotencyKey: "order_123",
+  });
+}
+
 await receiz.appState.publish({
-  schema: "receiz.app.public_store_state_registry_feed.v1",
-  records: [
-    {
-      id: "store_state_id:bjklock.receiz.app",
-      sourceUrl: "https://bjklock.receiz.app",
-      externalCreatorId: "bjklock.receiz.id",
-      title: "BJ Klock storefront",
-      state: "published",
-      platform: "Receiz.app Commerce Cloud",
-      schema: "receiz.app.public_store_state_projection.v1",
-      data: { storeStateRecord },
-    },
-  ],
+  tenantHost: "bjklock.receiz.app",
+  creatorReceizId: "bjklock.receiz.id",
+  title: "BJ Klock storefront",
+  state: { storeStateRecord },
+  idempotencyKey: "storefront_state_1",
 });
 
-const restored = await createReceizClient().appState.byUrl("https://bjklock.receiz.app/");
-renderStorefront(restored.record?.data?.storeStateRecord);
+const restored = await createReceizClient().appState.resolve({
+  host: "bjklock.receiz.app",
+  requiredDataKey: "storeStateRecord",
+});
 ```
 
-`receiz.publicProof.registryFeed(feed)` remains available and aliases the same publish path for existing integrations.
+Additional typed surfaces:
 
-Full quickstart: `docs/app-state-public-projections.md`.
+- `receiz.media.upload(file, { tenantHost, purpose, idempotencyKey })`
+- `receiz.domains.normalizeHost()`, `tenantUrl()`, `namespace()`, `objectId()`, `resolveTenant()`
+- `receiz.events.subscribe({ tenantHost, types, webhookUrl, idempotencyKey })`
+- `receiz.proof.query({ namespace, tenantHost, type, customerReceizId })`
+- `receiz.jobs.enqueue({ tenantHost, kind, payload, idempotencyKey })`
+- `receiz.sandbox.seedStore()`, `sandbox.wallet()`, `sandbox.checkout()`
+- CLI: `receiz doctor`, `receiz dev`, `receiz deploy-check`, `receiz seed-store`, `receiz simulate-checkout`
 
 ## Sports Card And Event Proof Integration
 

package/dist/cli.js

@@ -2,7 +2,7 @@
 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";
+import { RECEIZ_SDK_VERSION, assertReceizAssetManifest, assertReceizProofRegisterSnapshot, assertReceizSportsCardManifest, assertReceizWebhookEvent, createReceizClient, 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)
@@ -19,6 +19,27 @@ function printError(error, detail) {
 function readJsonFile(path) {
     return JSON.parse(readFileSync(resolve(path), "utf8"));
 }
+function optionValue(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0)
+        return undefined;
+    const value = args[index + 1];
+    return value && !value.startsWith("--") ? value : undefined;
+}
+function optionNumber(args, name, fallback) {
+    const value = optionValue(args, name);
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function optionScopes(args) {
+    const raw = optionValue(args, "--scopes") ?? optionValue(args, "--scope") ?? "";
+    return raw
+        .split(/[,\s]+/)
+        .map((scope) => scope.trim())
+        .filter(Boolean);
+}
 async function inspectProofObject(path) {
     const value = readJsonFile(path);
     const storage = createReceizInMemoryProofMemoryStorage();
@@ -188,9 +209,14 @@ Usage:
   receiz inspect <path-to-proof-json>
   receiz conformance
   receiz init <target-dir>
+  receiz doctor --tenant-host <host> [--access-token <token>] [--callback-url <url>] [--scopes <csv>]
+  receiz dev
+  receiz deploy-check --tenant-host <host>
+  receiz seed-store --tenant-host <host> [--products <count>]
+  receiz simulate-checkout --amount-usd <amount>
 
 This CLI uses local Receiz SDK validators, projections, and durable proof memory.
-It does not make network or database calls for inspect or conformance.
+It does not make network or database calls for inspect, conformance, doctor, deploy-check, seed-store, or simulate-checkout.
 `);
 }
 async function main(argv) {
@@ -229,6 +255,84 @@ async function main(argv) {
         });
         return;
     }
+    if (command === "doctor") {
+        const clientOptions = {};
+        const accessToken = optionValue(args, "--access-token");
+        const baseUrl = optionValue(args, "--base-url");
+        if (accessToken)
+            clientOptions.accessToken = accessToken;
+        if (baseUrl)
+            clientOptions.baseUrl = baseUrl;
+        const client = createReceizClient(clientOptions);
+        const doctorOptions = {};
+        const tenantHost = optionValue(args, "--tenant-host");
+        const callbackUrl = optionValue(args, "--callback-url");
+        const scopes = optionScopes(args);
+        if (tenantHost)
+            doctorOptions.tenantHost = tenantHost;
+        if (callbackUrl)
+            doctorOptions.callbackUrl = callbackUrl;
+        if (scopes.length > 0)
+            doctorOptions.scopes = scopes;
+        const report = await client.doctor(doctorOptions);
+        printJson({
+            ...report,
+            schema: "receiz.sdk.cli.doctor.v1",
+            sdkVersion: RECEIZ_SDK_VERSION,
+        });
+        if (!report.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (command === "dev") {
+        printJson({
+            ok: true,
+            schema: "receiz.sdk.cli.dev.v1",
+            sdkVersion: RECEIZ_SDK_VERSION,
+            networkCalls: 0,
+            dbCalls: 0,
+            message: "Use the SDK sandbox helpers for deterministic local Receiz IDs, app state, wallet balances, checkout outcomes, webhooks, and proof objects.",
+            commands: ["receiz seed-store", "receiz simulate-checkout", "receiz doctor", "receiz inspect"],
+        });
+        return;
+    }
+    if (command === "deploy-check") {
+        const tenantHost = optionValue(args, "--tenant-host");
+        const checks = [
+            { code: "tenant_host_present", ok: Boolean(tenantHost), message: "tenantHost scopes app-state, domains, commerce, permissions, search, and jobs." },
+            { code: "sdk_version_pinned", ok: true, message: `@receiz/sdk ${RECEIZ_SDK_VERSION}` },
+            { code: "network_authority_required", ok: false, level: "info", message: "Deploy check is local. Production route availability is verified by receiz.doctor() and app capability probes." },
+        ];
+        printJson({
+            ok: checks.every((check) => check.ok || check.level === "info"),
+            schema: "receiz.sdk.cli.deploy_check.v1",
+            tenantHost: tenantHost ?? null,
+            checks,
+        });
+        return;
+    }
+    if (command === "seed-store") {
+        const tenantHost = optionValue(args, "--tenant-host");
+        if (!tenantHost) {
+            printError("missing_tenant_host", "Usage: receiz seed-store --tenant-host <host> [--products <count>]");
+            process.exitCode = 1;
+            return;
+        }
+        const client = createReceizClient();
+        printJson(client.sandbox.seedStore({ tenantHost, products: optionNumber(args, "--products", 3) }));
+        return;
+    }
+    if (command === "simulate-checkout") {
+        const amountUsd = optionValue(args, "--amount-usd");
+        if (!amountUsd) {
+            printError("missing_amount_usd", "Usage: receiz simulate-checkout --amount-usd <amount>");
+            process.exitCode = 1;
+            return;
+        }
+        const client = createReceizClient();
+        printJson(client.sandbox.checkout({ amountUsd, outcome: optionValue(args, "--outcome") === "failure" ? "failure" : "success" }));
+        return;
+    }
     printError("unknown_command", command);
     process.exitCode = 1;
 }