@receiz/sdk 96.2.0 → 97.1.0

package/docs/app-runtime-commerce-cloud.md

@@ -0,0 +1,127 @@
+# Receiz App Runtime And Commerce Cloud Rails
+
+`@receiz/sdk` exposes typed rails for apps that want Receiz identity, public app-state, commerce, media, domains, events, proof search, jobs, and diagnostics without stitching a separate app backend together first.
+
+The SDK is convenience. It does not become proof authority. Proof objects, verified local truth, app-state projections, Connect delegated routes, wallet settlement, identity artifacts, and durable append rails remain the source of truth.
+
+## Self-Debug First
+
+```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) {
+  // Hide checkout setup or show the exact Connect fix.
+}
+```
+
+## Publish And Resolve Tenant State
+
+```ts
+await receiz.appState.publish({
+  tenantHost: "bjklock.receiz.app",
+  creatorReceizId: "bjklock.receiz.id",
+  title: "BJ Klock storefront",
+  state: { storeStateRecord },
+  idempotencyKey: `storefront:${storeStateRecord.updatedKaiUpulse}`,
+});
+
+const restored = await createReceizClient().appState.resolve<{
+  storeStateRecord: StoreStateRecord;
+}>({
+  host: "bjklock.receiz.app",
+  requiredDataKey: "storeStateRecord",
+});
+
+if (restored.ok && restored.data) {
+  renderStorefront(restored.data.storeStateRecord);
+}
+```
+
+## One-Click Checkout
+
+```ts
+const checkout = await receiz.commerce.oneClickCheckout({
+  tenantHost: "bjklock.receiz.app",
+  orderId: "order_123",
+  amountUsd: "42.00",
+  walletFirst: true,
+  cardFallback: true,
+  idempotencyKey: "order_123",
+  cart,
+});
+
+if (checkout.checkoutSession?.clientSecret) {
+  openEmbeddedCardDeltaPanel(checkout.checkoutSession.clientSecret);
+}
+```
+
+Wallet-first checkout reads the delegated wallet summary, computes the card delta, and creates an embedded Connect checkout session only when a card delta remains. Settlement truth still belongs to the Connect/payment and wallet rails returned by the backend.
+
+## Media, Domains, Events, Search, And Jobs
+
+```ts
+const logo = await receiz.media.upload(file, {
+  tenantHost: "bjklock.receiz.app",
+  purpose: "store.logo",
+  filename: "logo.png",
+  idempotencyKey: "store-logo:v1",
+});
+
+const tenantUrl = receiz.domains.tenantUrl("bjklock.receiz.app");
+const namespace = receiz.domains.namespace(tenantUrl);
+
+await receiz.events.subscribe({
+  tenantHost: "bjklock.receiz.app",
+  types: ["order.created", "payment.settled", "reward.claimed"],
+  webhookUrl: "https://bjklock.receiz.app/api/receiz/webhooks",
+  idempotencyKey: "events:v1",
+});
+
+const orders = await receiz.proof.query({
+  namespace,
+  tenantHost: "bjklock.receiz.app",
+  type: "commerce.order",
+});
+
+await receiz.jobs.enqueue({
+  tenantHost: "bjklock.receiz.app",
+  kind: "media.process",
+  payload: { mediaId: logo.media?.id },
+  idempotencyKey: "media.process:logo:v1",
+});
+```
+
+## Deterministic Sandbox
+
+```ts
+const store = receiz.sandbox.seedStore({ tenantHost: "demo.receiz.app", products: 3 });
+const wallet = receiz.sandbox.wallet({ balanceUsdCents: "5000" });
+const checkout = receiz.sandbox.checkout({ amountUsd: "19.95", outcome: "success" });
+```
+
+The sandbox is local and deterministic. Use it for tests, demos, and AI-generated apps before wiring delegated Connect access.
+
+## CLI
+
+```bash
+receiz doctor --tenant-host bjklock.receiz.app --access-token "$RECEIZ_ACCESS_TOKEN"
+receiz dev
+receiz deploy-check --tenant-host bjklock.receiz.app
+receiz seed-store --tenant-host demo.receiz.app --products 3
+receiz simulate-checkout --amount-usd 19.95
+```
+
+These commands do not make the CLI a truth authority. They are local developer diagnostics and sandbox helpers.

package/docs/app-state-public-projections.md

@@ -7,54 +7,125 @@ Use this for ecommerce storefronts, marketplaces, games, rewards, profiles, dire
 ## Publish After Admin Save
 
 ```ts
-import { createReceizClient, type ReceizAppStateFeed } from "@receiz/sdk";
+import {
+  RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
+  createReceizClient,
+  createReceizPublicStoreStateRecord,
+} from "@receiz/sdk";
 
 const receiz = createReceizClient({
   baseUrl: "https://receiz.com",
   accessToken,
 });
 
-const feed: ReceizAppStateFeed = {
-  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,
-      },
-    },
-  ],
-};
-
-const published = await receiz.appState.publish(feed);
+const storeProjection = createReceizPublicStoreStateRecord({
+  sourceUrl: "bjklock.receiz.app",
+  externalCreatorId: "bjklock.receiz.id",
+  title: "BJ Klock storefront",
+  data: {
+    storeStateRecord,
+  },
+});
+
+const published = await receiz.appState.publishRecord(storeProjection);
 if (!published.ok) throw new Error(String(published.error ?? "app_state_publish_failed"));
 ```
 
-`receiz.publicProof.registryFeed(feed)` remains supported and aliases this publish path. Use `receiz.appState.publish(feed)` for new app code because it names the primitive directly.
+`publishRecord()` wraps a single durable projection into the canonical feed envelope, derives the default object id from the URL, and normalizes a bare host such as `bjklock.receiz.app` to `https://bjklock.receiz.app`. Use `receiz.appState.publish(feed)` for batch writes. `receiz.publicProof.registryFeed(feed)` remains supported and aliases the same publish path.
+
+For Commerce Cloud and tenant apps, the shortest path is the tenant publish helper:
+
+```ts
+await receiz.appState.publish({
+  tenantHost: "bjklock.receiz.app",
+  creatorReceizId: "bjklock.receiz.id",
+  title: "BJ Klock storefront",
+  state: { storeStateRecord },
+  idempotencyKey: `storefront:${storeStateRecord.updatedKaiUpulse}`,
+});
+```
+
+The SDK turns that into the canonical public app-state feed, derives the normalized URL, derives the object id, carries the `idempotency-key` header, and keeps the projection under the public proof registry rail.
+
+For batch writes, build the canonical feed first:
+
+```ts
+import { createReceizAppStateFeed } from "@receiz/sdk";
+
+const feed = createReceizAppStateFeed([storeProjection], {
+  schema: "receiz.app.public_store_state_registry_feed.v1",
+  externalCreatorId: "bjklock.receiz.id",
+});
+
+await receiz.appState.publish(feed);
+```
+
+The same factories are available from the client namespace:
+
+```ts
+const objectId = receiz.appState.objectIdFromUrl("https://bjklock.receiz.app");
+const namespace = receiz.appState.namespaceFromUrl("https://bjklock.receiz.app");
+const url = receiz.appState.urlFromHost("bjklock.receiz.app");
+const record = receiz.appState.createPublicStoreRecord({
+  sourceUrl: url,
+  data: { storeStateRecord },
+});
+```
 
 ## Recover On Cold Start
 
 ```ts
-import { createReceizClient } from "@receiz/sdk";
+import {
+  RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
+  createReceizClient,
+} from "@receiz/sdk";
 
 const receiz = createReceizClient();
-const restored = await receiz.appState.byUrl("https://bjklock.receiz.app/");
+const restored = await receiz.appState.restoreByHost<{
+  storeStateRecord: StoreStateRecord;
+}>("bjklock.receiz.app", {
+  schema: RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
+  state: "published",
+  requiredDataKey: "storeStateRecord",
+});
 
-if (!restored.ok || !restored.record?.data) {
+if (!restored.ok || !restored.data) {
   throw new Error("storefront_state_not_found");
 }
 
-const storeStateRecord = restored.record.data.storeStateRecord;
+const storeStateRecord = restored.data.storeStateRecord;
 ```
 
 `https://bjklock.receiz.app` and `https://bjklock.receiz.app/` resolve to the same public projection. Subdomains and custom domains work through the same normalized URL key.
 
+Use `byUrl()` when the app already has a full URL. Use `byHost()` when the current request gives you only the tenant host or custom domain.
+Use `restoreByUrl()`, `restoreByHost()`, or `restoreById()` when the app should receive the typed projection data directly for first paint.
+Use `resolve()` when your app accepts host, URL, id, namespace, or creator input and wants one typed API:
+
+```ts
+const restored = await receiz.appState.resolve<{
+  storeStateRecord: StoreStateRecord;
+}>({
+  host: "bjklock.receiz.app",
+  schema: RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
+  state: "published",
+  requiredDataKey: "storeStateRecord",
+});
+```
+
+When your app already has a public projection response, unwrap it without another network call:
+
+```ts
+import { extractReceizAppStateData } from "@receiz/sdk";
+
+const data = extractReceizAppStateData<{
+  storeStateRecord: StoreStateRecord;
+}>(restored, {
+  schema: RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
+  requiredDataKey: "storeStateRecord",
+});
+```
+
 ## Namespace And Creator Reads
 
 ```ts

package/docs/cli-and-conformance.md

@@ -93,6 +93,34 @@ The starter:
 
 It does not include Supabase, service-role keys, or a parallel source of truth.
 
+## Diagnose App Runtime Wiring
+
+```bash
+npx @receiz/sdk doctor \
+  --tenant-host bjklock.receiz.app \
+  --access-token "$RECEIZ_ACCESS_TOKEN" \
+  --callback-url https://bjklock.receiz.app/api/auth/receiz/callback \
+  --scopes openid,profile,receiz:record,receiz:wallet.read
+```
+
+The doctor command prints missing token, tenant host, callback URL, and scope evidence without making network or database calls.
+
+```bash
+npx @receiz/sdk deploy-check --tenant-host bjklock.receiz.app
+npx @receiz/sdk dev
+```
+
+Use these commands before deploy to check that the app is passing the tenant coordinate and that the SDK version is pinned.
+
+## Deterministic Sandbox Commands
+
+```bash
+npx @receiz/sdk seed-store --tenant-host demo.receiz.app --products 3
+npx @receiz/sdk simulate-checkout --amount-usd 19.95
+```
+
+These commands emit deterministic sandbox app-state and checkout payloads for tests, demos, and AI-generated app scaffolds. They do not settle payments or create proof authority.
+
 ## Production Rule
 
 Use the CLI to prove your local integration shape, then use the typed SDK APIs in your app:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@receiz/sdk",
-  "version": "96.2.0",
+  "version": "97.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",