@receiz/sdk 97.0.0 → 97.2.0

package/README.md

@@ -205,27 +205,120 @@ Receiz apps can publish durable public app-state projections without adding Supa
 import {
   RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
   createReceizClient,
+  createReceizPublicStoreStateRecord,
 } from "@receiz/sdk";
 
 const receiz = createReceizClient({ accessToken });
 
-await receiz.appState.publishRecord({
+await receiz.appState.publishRecord(createReceizPublicStoreStateRecord({
   sourceUrl: "bjklock.receiz.app",
   externalCreatorId: "bjklock.receiz.id",
   title: "BJ Klock storefront",
-  platform: "Receiz.app Commerce Cloud",
-  schema: RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
   data: { storeStateRecord },
+}));
+
+const restored = await createReceizClient().appState.restoreByHost<{
+  storeStateRecord: StoreStateRecord;
+}>("bjklock.receiz.app", {
+  schema: RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
+  state: "published",
+  requiredDataKey: "storeStateRecord",
 });
 
-const restored = await createReceizClient().appState.byHost("bjklock.receiz.app");
-renderStorefront(restored.record?.data?.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.2.0` adds the enterprise runtime 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({
+  tenantHost: "bjklock.receiz.app",
+  creatorReceizId: "bjklock.receiz.id",
+  title: "BJ Klock storefront",
+  state: { storeStateRecord },
+  idempotencyKey: "storefront_state_1",
+});
+
+const restored = await createReceizClient().appState.resolve({
+  host: "bjklock.receiz.app",
+  requiredDataKey: "storeStateRecord",
+});
+```
+
+Additional typed surfaces:
+
+- `receiz.customers.session()`, `customers.portal()`, `customers.orders()`, `customers.rewards()`, `customers.assets()`
+- `receiz.merchants.onboard()`, `merchants.profile()`, `merchants.capabilities()`
+- `receiz.commerce.refunds`, `subscriptions`, `shipping`, `tax`, `discounts`, `giftCards`, `accessPasses`, `inventory`, `fulfillment`, `payouts`
+- `receiz.media.upload(file, { tenantHost, purpose, idempotencyKey })`
+- `receiz.media.transform({ mediaId, resize, optimize, blurPlaceholder, altText, metadata })`
+- `receiz.domains.normalizeHost()`, `tenantUrl()`, `namespace()`, `objectId()`, `resolveTenant()`
+- `receiz.events.subscribe()`, `events.replay()`, `events.list()`, `events.ack()`
+- `receiz.proof.query({ namespace, tenantHost, type, customerReceizId })`
+- `receiz.jobs.enqueue()`, `jobs.status()`, `jobs.cancel()`, `jobs.list()`
+- `receiz.permissions.grant()`, `permissions.revoke()`, `permissions.check()`, `permissions.roles()`
+- `receiz.audit.append()`, `audit.query()`, `audit.export()`
+- `receiz.risk.scorePayment()`, `scoreAccountRecovery()`, `velocity()`, `proofActivity()`
+- `receiz.compliance.exportOrders()`, `exportTaxes()`, `exportPayouts()`, `exportCustomers()`, `exportAudit()`
+- `receiz.portability.exportStore()`, `portability.importStore()`
+- `receiz.search.query()`, `products()`, `pages()`, `blog()`, `orders()`, `customers()`, `proofObjects()`
+- `receiz.notifications.send()`, `notifications.subscribe()`, `notifications.templates()`
+- `receiz.releases.pin()`, `releases.check()`, `releases.supported()`
+- `receiz.sandbox.seedStore()`, `sandbox.wallet()`, `sandbox.checkout()`
+- `receiz.offline.createQueue()`, `offline.createInMemoryStorage()`, `offline.createLocalStorage()`
+- CLI: `receiz doctor`, `receiz dev`, `receiz deploy-check`, `receiz seed-store`, `receiz simulate-checkout`
+
+React apps can import optional hooks and hosted component factories from `@receiz/sdk/react`:
+
+```ts
+import {
+  ReceizCheckoutButton,
+  ReceizIdentityButton,
+  ReceizMediaUploader,
+  useReceizAppState,
+  useReceizCheckout,
+} from "@receiz/sdk/react";
+
+const storefront = useReceizAppState({
+  resolve: {
+    host: "bjklock.receiz.app",
+    requiredDataKey: "storeStateRecord",
+  },
+});
+```
+
+The React subpath is UI convenience. The core SDK client remains the primitive boundary, and proof objects / local proof memory remain stronger than component state.
+
 ## Sports Card And Event Proof Integration
 
 ```ts

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