@receiz/sdk 97.1.0 → 97.2.0

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

@@ -1,6 +1,6 @@
 # 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.
+`@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.
 
@@ -70,6 +70,37 @@ if (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
@@ -102,6 +133,84 @@ await receiz.jobs.enqueue({
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@receiz/sdk",
-  "version": "97.1.0",
+  "version": "97.2.0",
   "description": "TypeScript SDK for Receiz proof-native artifact, public proof, wallet, sports, Twin, World, and Connect integrations.",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
     "./fixtures/*": "./fixtures/*",
     "./docs/*": "./docs/*",
     "./package.json": "./package.json"