@receiz/sdk 97.0.0 → 97.2.0

package/dist/react.d.ts

@@ -0,0 +1,80 @@
+import { type ComponentPropsWithoutRef, type ReactElement, type ReactNode } from "react";
+import { type JsonObject, type ReceizAppStatePublishInput, type ReceizAppStateResolveInput, type ReceizAppStateResolveResult, type ReceizClient, type ReceizClientOptions, type ReceizMediaUploadOptions, type ReceizOneClickCheckoutRequest, type ReceizOneClickCheckoutResponse, type TwinPromotionApprovalInput } from "./index.js";
+export type ReceizReactClientOptions = ReceizClientOptions & {
+    client?: ReceizClient;
+};
+export type ReceizAsyncState<T> = {
+    loading: boolean;
+    error: Error | null;
+    data: T | null;
+};
+export type ReceizIdentityHook = {
+    client: ReceizClient;
+    login: () => void;
+    logout: () => void;
+    authorizeUrl: string | null;
+};
+export type ReceizIdentityHookOptions = ReceizReactClientOptions & {
+    authorize?: {
+        clientId: string;
+        redirectUri: string;
+        codeChallenge: string;
+        codeChallengeMethod?: "S256" | "plain";
+        state?: string;
+        scope?: string | string[];
+        usernameHint?: string;
+    };
+    logoutUrl?: string;
+};
+export type ReceizCheckoutHook = ReceizAsyncState<ReceizOneClickCheckoutResponse> & {
+    checkout: (request: ReceizOneClickCheckoutRequest) => Promise<ReceizOneClickCheckoutResponse>;
+};
+export type ReceizAppStateHook<TData extends JsonObject = JsonObject> = ReceizAsyncState<ReceizAppStateResolveResult<TData>> & {
+    resolve: (input?: ReceizAppStateResolveInput) => Promise<ReceizAppStateResolveResult<TData>>;
+    publish: (input: ReceizAppStatePublishInput) => Promise<JsonObject>;
+};
+export type ReceizAppStateHookOptions<TData extends JsonObject = JsonObject> = ReceizReactClientOptions & {
+    resolve?: ReceizAppStateResolveInput;
+    initial?: ReceizAppStateResolveResult<TData> | null;
+    autoResolve?: boolean;
+};
+export type ReceizMediaHook = ReceizAsyncState<JsonObject> & {
+    upload: (file: Blob, options?: ReceizMediaUploadOptions) => Promise<JsonObject>;
+};
+type ReceizButtonProps = Omit<ComponentPropsWithoutRef<"button">, "onClick"> & {
+    children?: ReactNode;
+};
+type ReceizIdentityButtonProps = ReceizButtonProps & ReceizIdentityHookOptions;
+type ReceizCheckoutButtonProps = ReceizButtonProps & ReceizReactClientOptions & {
+    request: ReceizOneClickCheckoutRequest;
+    onCheckout?: (response: ReceizOneClickCheckoutResponse) => void;
+};
+type ReceizWalletBalanceProps = ReceizReactClientOptions & {
+    tenantHost?: string;
+    fallback?: ReactNode;
+};
+type ReceizMediaUploaderProps = Omit<ComponentPropsWithoutRef<"input">, "type" | "onChange"> & ReceizReactClientOptions & {
+    uploadOptions?: ReceizMediaUploadOptions;
+    onUploaded?: (response: JsonObject) => void;
+};
+type ReceizDomainConnectorProps = ReceizButtonProps & ReceizReactClientOptions & {
+    host: string;
+    onStatus?: (response: JsonObject) => void;
+};
+type ReceizTwinWriterProps = Omit<ComponentPropsWithoutRef<"button">, "onClick"> & ReceizReactClientOptions & {
+    body: TwinPromotionApprovalInput;
+    onSaved?: (response: JsonObject) => void;
+    children?: ReactNode;
+};
+export declare function useReceizIdentity(options?: ReceizIdentityHookOptions): ReceizIdentityHook;
+export declare function useReceizCheckout(options?: ReceizReactClientOptions): ReceizCheckoutHook;
+export declare function useReceizAppState<TData extends JsonObject = JsonObject>(options?: ReceizAppStateHookOptions<TData>): ReceizAppStateHook<TData>;
+export declare function useReceizMedia(options?: ReceizReactClientOptions): ReceizMediaHook;
+export declare function ReceizIdentityButton(props: ReceizIdentityButtonProps): ReactElement;
+export declare function ReceizCheckoutButton(props: ReceizCheckoutButtonProps): ReactElement;
+export declare function ReceizWalletBalance(props: ReceizWalletBalanceProps): ReactElement;
+export declare function ReceizMediaUploader(props: ReceizMediaUploaderProps): ReactElement;
+export declare function ReceizDomainConnector(props: ReceizDomainConnectorProps): ReactElement;
+export declare function ReceizTwinWriter(props: ReceizTwinWriterProps): ReactElement;
+export {};
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"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"}

package/dist/react.js

@@ -0,0 +1,200 @@
+import { createElement, useCallback, useEffect, useMemo, useState, } from "react";
+import { createReceizClient, } from "./index.js";
+function useReceizClient(options = {}) {
+    const { client, baseUrl, accessToken, fetchImpl } = options;
+    return useMemo(() => client ?? createReceizClient(compactClientOptions({ baseUrl, accessToken, fetchImpl })), [client, baseUrl, accessToken, fetchImpl]);
+}
+function compactClientOptions(options) {
+    const next = {};
+    if (options.baseUrl !== undefined)
+        next.baseUrl = options.baseUrl;
+    if (options.accessToken !== undefined)
+        next.accessToken = options.accessToken;
+    if (options.fetchImpl !== undefined)
+        next.fetchImpl = options.fetchImpl;
+    return next;
+}
+function compactReactClientOptions(options) {
+    const next = compactClientOptions(options);
+    if (options.client !== undefined)
+        next.client = options.client;
+    return next;
+}
+function compactIdentityOptions(options) {
+    const next = compactReactClientOptions(options);
+    if (options.authorize !== undefined)
+        next.authorize = options.authorize;
+    if (options.logoutUrl !== undefined)
+        next.logoutUrl = options.logoutUrl;
+    return next;
+}
+function errorFromUnknown(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+export function useReceizIdentity(options = {}) {
+    const client = useReceizClient(options);
+    const authorizeUrl = options.authorize ? client.identity.authorizeUrl(options.authorize) : null;
+    const login = useCallback(() => {
+        if (!authorizeUrl || typeof window === "undefined")
+            return;
+        window.location.assign(authorizeUrl);
+    }, [authorizeUrl]);
+    const logout = useCallback(() => {
+        if (typeof window === "undefined")
+            return;
+        window.location.assign(options.logoutUrl ?? "/logout");
+    }, [options.logoutUrl]);
+    return { client, login, logout, authorizeUrl };
+}
+export function useReceizCheckout(options = {}) {
+    const client = useReceizClient(options);
+    const [state, setState] = useState({
+        loading: false,
+        error: null,
+        data: null,
+    });
+    const checkout = useCallback(async (request) => {
+        setState((current) => ({ ...current, loading: true, error: null }));
+        try {
+            const response = await client.commerce.oneClickCheckout(request);
+            setState({ loading: false, error: null, data: response });
+            return response;
+        }
+        catch (error) {
+            const nextError = errorFromUnknown(error);
+            setState({ loading: false, error: nextError, data: null });
+            throw nextError;
+        }
+    }, [client]);
+    return { ...state, checkout };
+}
+export function useReceizAppState(options = {}) {
+    const client = useReceizClient(options);
+    const [state, setState] = useState({
+        loading: false,
+        error: null,
+        data: options.initial ?? null,
+    });
+    const resolve = useCallback(async (input) => {
+        const target = input ?? options.resolve;
+        if (!target)
+            throw new Error("receiz_app_state_resolve_input_required");
+        setState((current) => ({ ...current, loading: true, error: null }));
+        try {
+            const response = await client.appState.resolve(target);
+            setState({ loading: false, error: null, data: response });
+            return response;
+        }
+        catch (error) {
+            const nextError = errorFromUnknown(error);
+            setState({ loading: false, error: nextError, data: null });
+            throw nextError;
+        }
+    }, [client, options.resolve]);
+    const publish = useCallback(async (input) => {
+        const response = await client.appState.publish(input);
+        return response;
+    }, [client]);
+    useEffect(() => {
+        if (options.autoResolve === false || !options.resolve || options.initial)
+            return;
+        let active = true;
+        const target = options.resolve;
+        queueMicrotask(() => {
+            if (!active)
+                return;
+            void resolve(target);
+        });
+        return () => {
+            active = false;
+        };
+    }, [options.autoResolve, options.initial, options.resolve, resolve]);
+    return { ...state, resolve, publish };
+}
+export function useReceizMedia(options = {}) {
+    const client = useReceizClient(options);
+    const [state, setState] = useState({
+        loading: false,
+        error: null,
+        data: null,
+    });
+    const upload = useCallback(async (file, uploadOptions = {}) => {
+        setState((current) => ({ ...current, loading: true, error: null }));
+        try {
+            const response = await client.media.upload(file, uploadOptions);
+            const data = response;
+            setState({ loading: false, error: null, data });
+            return data;
+        }
+        catch (error) {
+            const nextError = errorFromUnknown(error);
+            setState({ loading: false, error: nextError, data: null });
+            throw nextError;
+        }
+    }, [client]);
+    return { ...state, upload };
+}
+export function ReceizIdentityButton(props) {
+    const { children, client, baseUrl, accessToken, fetchImpl, authorize, logoutUrl, ...buttonProps } = props;
+    const identity = useReceizIdentity(compactIdentityOptions({ client, baseUrl, accessToken, fetchImpl, authorize, logoutUrl }));
+    return createElement("button", { ...buttonProps, type: buttonProps.type ?? "button", onClick: identity.login }, children ?? "Continue with Receiz");
+}
+export function ReceizCheckoutButton(props) {
+    const { children, client, baseUrl, accessToken, fetchImpl, request, onCheckout, ...buttonProps } = props;
+    const checkout = useReceizCheckout(compactReactClientOptions({ client, baseUrl, accessToken, fetchImpl }));
+    const onClick = useCallback(async () => {
+        const response = await checkout.checkout(request);
+        onCheckout?.(response);
+    }, [checkout, onCheckout, request]);
+    return createElement("button", { ...buttonProps, type: buttonProps.type ?? "button", disabled: buttonProps.disabled || checkout.loading, onClick }, children ?? (checkout.loading ? "Opening..." : "Checkout with Receiz"));
+}
+export function ReceizWalletBalance(props) {
+    const { client: providedClient, baseUrl, accessToken, fetchImpl, fallback = "Wallet unavailable" } = props;
+    const client = useReceizClient(compactReactClientOptions({ client: providedClient, baseUrl, accessToken, fetchImpl }));
+    const [balance, setBalance] = useState(null);
+    useEffect(() => {
+        let active = true;
+        void client.connect.wallet().then((wallet) => {
+            if (!active)
+                return;
+            setBalance(typeof wallet.balanceUsdCents === "string" ? `$${(Number(wallet.balanceUsdCents) / 100).toFixed(2)}` : null);
+        }).catch(() => {
+            if (active)
+                setBalance(null);
+        });
+        return () => {
+            active = false;
+        };
+    }, [client]);
+    return createElement("span", null, balance ?? fallback);
+}
+export function ReceizMediaUploader(props) {
+    const { client, baseUrl, accessToken, fetchImpl, uploadOptions, onUploaded, ...inputProps } = props;
+    const media = useReceizMedia(compactReactClientOptions({ client, baseUrl, accessToken, fetchImpl }));
+    const onChange = useCallback(async (event) => {
+        const file = event.currentTarget.files?.[0];
+        if (!file)
+            return;
+        const response = await media.upload(file, uploadOptions);
+        onUploaded?.(response);
+    }, [media, onUploaded, uploadOptions]);
+    return createElement("input", { ...inputProps, type: "file", onChange });
+}
+export function ReceizDomainConnector(props) {
+    const { children, client: providedClient, baseUrl, accessToken, fetchImpl, host, onStatus, ...buttonProps } = props;
+    const client = useReceizClient(compactReactClientOptions({ client: providedClient, baseUrl, accessToken, fetchImpl }));
+    const onClick = useCallback(async () => {
+        const response = await client.domains.status({ host });
+        onStatus?.(response);
+    }, [client, host, onStatus]);
+    return createElement("button", { ...buttonProps, type: buttonProps.type ?? "button", onClick }, children ?? "Check Receiz Domain");
+}
+export function ReceizTwinWriter(props) {
+    const { children, client: providedClient, baseUrl, accessToken, fetchImpl, body, onSaved, ...buttonProps } = props;
+    const client = useReceizClient(compactReactClientOptions({ client: providedClient, baseUrl, accessToken, fetchImpl }));
+    const onClick = useCallback(async () => {
+        const response = await client.twin.approvePromotion(body);
+        onSaved?.(response);
+    }, [body, client, onSaved]);
+    return createElement("button", { ...buttonProps, type: buttonProps.type ?? "button", onClick }, children ?? "Write Twin Proof");
+}

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

@@ -0,0 +1,236 @@
+# 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, permissions, audit, risk, compliance, portability, notifications, release pinning, offline proof queues, 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.
+
+## Enterprise Commerce
+
+```ts
+await receiz.customers.session({
+  tenantHost: "bjklock.receiz.app",
+  customerReceizId: "customer.receiz.id",
+  scopes: ["orders", "rewards", "assets"],
+}, { idempotencyKey: "customer-session:v1" });
+
+await receiz.merchants.onboard({
+  tenantHost: "bjklock.receiz.app",
+  receizId: "bjklock.receiz.id",
+  displayName: "BJ Klock",
+  defaultStore: { title: "BJ Klock Store" },
+}, { idempotencyKey: "merchant:bjklock:v1" });
+
+await receiz.commerce.inventory.reserve({
+  tenantHost: "bjklock.receiz.app",
+  sku: "hat-black",
+  quantity: 2,
+}, { idempotencyKey: "inventory:hat-black:cart-123" });
+
+await receiz.commerce.fulfillment.update({
+  tenantHost: "bjklock.receiz.app",
+  orderId: "order_123",
+  status: "shipped",
+}, { idempotencyKey: "fulfillment:order_123:shipped" });
+```
+
+Additional commerce rails include refunds, subscriptions, shipping quotes, tax quotes, discounts, gift cards, access passes, inventory adjustment, and merchant payouts. Every write accepts an idempotency key so retries append once.
+
+## 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",
+});
+
+await receiz.media.transform({
+  tenantHost: "bjklock.receiz.app",
+  mediaId: String(logo.media?.id),
+  resize: { width: 1200 },
+  optimize: { format: "webp" },
+  blurPlaceholder: true,
+  altText: "Store logo",
+}, { idempotencyKey: "media.transform:logo:v1" });
+
+await receiz.events.replay({
+  tenantHost: "bjklock.receiz.app",
+  types: ["order.created", "payment.settled"],
+  since: "2026-06-01T00:00:00.000Z",
+});
+```
+
+## Permissions, Audit, Risk, Compliance, And Portability
+
+```ts
+await receiz.permissions.grant({
+  tenantHost: "bjklock.receiz.app",
+  actorReceizId: "staff.receiz.id",
+  role: "fulfillment",
+}, { idempotencyKey: "grant:staff:fulfillment" });
+
+await receiz.audit.append({
+  tenantHost: "bjklock.receiz.app",
+  action: "product.updated",
+  actorReceizId: "bjklock.receiz.id",
+}, { idempotencyKey: "audit:product:update:123" });
+
+const risk = await receiz.risk.scorePayment({
+  tenantHost: "bjklock.receiz.app",
+  orderId: "order_123",
+  amountUsd: "42.00",
+});
+
+const orders = await receiz.compliance.exportOrders({
+  tenantHost: "bjklock.receiz.app",
+  from: "2026-06-01",
+  to: "2026-06-30",
+});
+
+const portableStore = await receiz.portability.exportStore({
+  tenantHost: "bjklock.receiz.app",
+});
+```
+
+Audit, risk, compliance, and portability are projections over proof-native activity. They help applications operate; they do not outrank the proof objects, wallet settlement, or verified appends they project.
+
+## Offline Queue And Release Pinning
+
+```ts
+const storage = receiz.offline.createLocalStorage("receiz:queue:bjklock");
+const queue = await receiz.offline.createQueue({
+  ownerId: "bjklock.receiz.id",
+  storage,
+});
+
+queue.enqueue({
+  id: "store-state:offline-1",
+  kind: "app_state.publish",
+  payload: {
+    tenantHost: "bjklock.receiz.app",
+    title: "Offline storefront append",
+    state: { storeStateRecord },
+  },
+  idempotencyKey: "store-state:offline-1",
+});
+await queue.flush();
+
+await queue.replay(receiz);
+
+await receiz.releases.pin({
+  tenantHost: "bjklock.receiz.app",
+  rails: { appState: "v1", commerce: "v1", media: "v1" },
+}, { idempotencyKey: "rails:pin: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

@@ -10,6 +10,7 @@ Use this for ecommerce storefronts, marketplaces, games, rewards, profiles, dire
 import {
   RECEIZ_PUBLIC_STORE_STATE_PROJECTION_SCHEMA,
   createReceizClient,
+  createReceizPublicStoreStateRecord,
 } from "@receiz/sdk";
 
 const receiz = createReceizClient({
@@ -17,39 +18,113 @@ const receiz = createReceizClient({
   accessToken,
 });
 
-const published = await receiz.appState.publishRecord({
+const storeProjection = 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 published = await receiz.appState.publishRecord(storeProjection);
 if (!published.ok) throw new Error(String(published.error ?? "app_state_publish_failed"));
 ```
 
 `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.byHost("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
 

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: