Receiz SDK

Install:

npm install @receiz/sdk

The matching @receiz/ai-skills package is installed as a dependency. Agent hosts can load the nine authoritative skill directories from node_modules/@receiz/ai-skills; the SDK still enforces continuity even when a host does not load them.

v105 Package Architecture

Use @receiz/sdk for the universal runtime, @receiz/sdk/react for React bindings, @receiz/sdk/compiler for Node-only contract compilation and repository work, and @receiz/sdk/testing for browser-safe deterministic fixtures, emulator, and conformance support.

Application Contract Compiler

import { defineReceizApp, compileReceizAppContract } from "@receiz/sdk/compiler";

const contract = defineReceizApp({
  schema: "receiz.app.contract.v1",
  name: "My Receiz App",
  framework: "nextjs-app-router",
  features: ["identity", "proof", "proofMemory", "publicStore", "webhooks"],
  authority: { mode: "artifact-first", allowDatabaseAuthority: false },
  deployment: { target: "vercel" },
});

const plan = compileReceizAppContract(contract, { targetSdkVersion: "105.0.0" });

The compiler API also exports validateReceizAppContract, inspectReceizProject, planReceizIntegration, checkReceizIntegration, planReceizUpgrade, and explainReceizIntegrationFinding. The CLI exposes the same core through receiz app init|inspect|plan|apply|check|upgrade|explain.

Planning is read-only. Apply returns the complete preview first, requires its exact digest as confirmation, preserves unrelated code, and is idempotent. See docs/app-contract-compiler.md, docs/framework-adapters.md, and docs/generated-files-and-upgrades.md.

Use one typed client for Receiz proof objects, public proof rendering, Sports Arena card/event proof integration, wallet ledger reads, Twin and World surfaces, Connect transfers, webhook endpoint management, and webhook delivery verification.

import { createReceizClient } from "@receiz/sdk";

const receiz = createReceizClient({
  baseUrl: "https://receiz.com",
  accessToken: process.env.RECEIZ_ACCESS_TOKEN,
});

Local proof tooling ships with the same package:

npx @receiz/sdk conformance
npx @receiz/sdk inspect ./receiz-asset-manifest.json
npx @receiz/sdk init ./receiz-integration

These commands use packaged SDK validators and projections. conformance and inspect do not call Receiz production, Supabase, or any database. Historical manifests remain inspectable, but inspection never admits them as verified asset truth.

Primitive Boundary

The SDK is convenience, not authority. It reads public API projections, sends delegated actions, validates developer manifests, and verifies webhook delivery signatures. Sealed artifacts, proof bundles, verified appends, ownership appends, and settlement ledger records remain the stronger source of truth.

A manifest is inspection-only. The SDK accepts only a complete sealed proof object: canonical payload, ownership/custody, provenance/appends, and settlement state must travel inside the artifact; the artifact must pass the existing Receiz verifier; the SDK must reconstruct the same object from the returned bytes; and server admission independently repeats verification.

Kai Klok is the proof object state machine. kaiPulseEternal is the pulse unit carried by that state machine. A complete Receiz proof object carries Kai; without its Kai coordinate it is not complete Receiz proof truth.

Receiz ID is the default account-continuity rail for everyday login. It does not replace PBI/passkey, email magic-link recovery, Receiz Key, Identity Record, Identity Seal, or OIDC/Connect. Those rails all preserve the same account when bound: PBI/passkey can create or recover a Receiz account, email can recover the account, Receiz identity artifacts can restore it locally, and OIDC/Connect can delegate API access after identity proof.

Receiz Key, Identity Record, and Identity Seal are Receiz identity primitives exposed through the SDK for developer apps. Their current account-state envelope is receiz.account.state.v3; it carries admitted account proof memory across profile, action ledger, calendar, wallet settlement, Sports vault/cards/appends/event proofs, and related entries. The SDK mirrors the same law for developer apps through local proof registers: admit verified truth once, persist it, and ask Receiz only for verified additions after the known head. Connect is delegated API access; it is not the identity proof root.

Default integration order:

1. Verify first, then project.
2. Render the proof object or manifest as the user-facing truth.
3. Append public proof, wallet, sports, or Connect additions after the known truth.
4. Order proof objects by Kai/Klok state; render Chronos only as display.
5. Never treat an SDK response as stronger than the sealed artifact, verified append, ownership append, or settlement primitive it projects.

Five-Minute Proof Object App

This is the highest-leverage SDK path for most apps:

import { createReceizClient } from "@receiz/sdk";

const receiz = createReceizClient({ accessToken: process.env.RECEIZ_ACCESS_TOKEN });
const created = await receiz.assets.createProofObject({
  assetType: "proof_object",
  payload: { mimeType: file.type, bytes: new Uint8Array(await file.arrayBuffer()) },
}, { idempotencyKey: crypto.randomUUID() });

if (!created.verification.ok || created.continuity.carrier !== "native-record-seal") {
  throw new Error("verified_continuity_required");
}
saveArtifact(created.artifact);

The register is not a cache. It is the app's admitted verified prefix. Use it immediately on next open, then ask Receiz only for verified additions after the known head.

Full quickstart: docs/proof-memory-and-projections.md.

For complete copy-paste integrations, use docs/copy-paste-integrations.md. It includes a React proof memory hook, browser admission helper, Next append-sync route, webhook receiver, Sports card renderer, and local CLI proof commands.

CLI And Local Conformance

npx @receiz/sdk conformance

Runs the packaged asset manifest, Sports card manifest, and webhook event fixtures through SDK inspection and validation. Inspection-only manifests do not enter verified proof memory.

npx @receiz/sdk inspect ./receiz-asset-manifest.json

Validates one payload and projects display-ready rows. Asset and Sports manifests report admitted: false because shape validation is inspection, not proof-object admission.

npx @receiz/sdk init ./receiz-integration

Writes a local-first proof memory starter. The starter keeps manifest projection explicitly inspection-only and admits only independently verified events/register entries.

Full quickstart: docs/cli-and-conformance.md.

Schemas, Projections, And Proof Memory

import {
  RECEIZ_SCHEMAS,
  createReceizInMemoryProofMemoryStorage,
  createReceizProofMemory,
  createReceizProofRegister,
  projectReceizSportsCardManifest,
} from "@receiz/sdk";

const schema = RECEIZ_SCHEMAS.sportsCardManifest;
const projection = projectReceizSportsCardManifest(cardManifest);

const memory = createReceizProofRegister();
memory.admitWebhookEvent(webhookEvent);

const snapshot = memory.snapshot();

const durableMemory = await createReceizProofMemory({
  storage: createReceizInMemoryProofMemoryStorage(snapshot),
});
const additionsAfter = durableMemory.knownHead(50);

Use schemas for developer validation, projections for display-ready proof rows, and proof memory for first-admission-then-append-forever UX.

Receiz ID Account Creation And Recovery

Developers can let users create a fresh Receiz ID account, recover from a Receiz Key, or login with an Identity Record / Identity Seal image without inventing a parallel login model. Receiz ID is the default login path, but it does not replace the existing rails: PBI/passkey stays available for account creation, account recovery, and account signing; email magic-link stays available for recovery; OIDC/Connect stays available for delegated API access. The result is one account, not separate accounts for each rail.

import {
  buildReceizIdContinueRequest,
  createReceizIdIdentity,
  projectReceizIdentityAccount,
  readReceizIdentityArtifact,
  signReceizIdentityLoginProof,
} from "@receiz/sdk";

const identity = await createReceizIdIdentity({
  username: "builder",
  displayName: "Builder",
});

const keyFile = await readReceizIdentityArtifact(fileOrImageBytes);
const account = await projectReceizIdentityAccount(keyFile);

if (!account.portableStateVerified) throw new Error("identity proof failed");

const proof = await signReceizIdentityLoginProof({
  keyFile,
  challengeText: "your-app-login-challenge",
});

const receizPublication = await buildReceizIdContinueRequest(identity, {
  next: "/profile",
});

Use the local projection for first paint in your app. Send the continuation request to Receiz only when you need Receiz infrastructure to append global continuity or issue a Receiz session. Use Connect after proof login when your app needs delegated Receiz API access.

Full quickstart: docs/identity-login-and-recovery.md.

Artifact Verification

import { createReceizClient } from "@receiz/sdk";

const receiz = createReceizClient();
const file = new Blob([artifactBytes]);
const verified = await receiz.verification.verifyArtifact(file);

if (!verified.ok) throw new Error(verified.errors.join(", "));

In v103, assets.createProofObject uses the same native creation sequence as receiz.com: the authenticated account's real Receiz ID is resolved, its Receiz Record projection is created, and the source bytes are sealed at those exact native coordinates. Developers do not submit or invent owner, namespace, or continuity objects. Existing Profile Composer, Record, and Seal proof objects continue to verify through their native proof bundles.

Full quickstart: docs/artifact-verification.md.

Public Proof Rendering

import { createReceizClient } from "@receiz/sdk";

const receiz = createReceizClient();
const proof = await receiz.publicProof.byUrl("https://example.com/work");

Full quickstart: docs/public-proof-rendering.md.

App-State Public Projections

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:app_state.write or receiz:public_store.write; reads are public when the projection is public.

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

For commerce storefronts, use the first-party public-store recipe so every app publishes the same storeStateRecord envelope:

await receiz.publicStore.publish({
  tenantHost: "bjklock.receiz.app",
  merchantReceizId: "bjklock.receiz.id",
  title: "BJ Klock storefront",
  state: storeStateRecord,
}, { idempotencyKey: `storefront:${storeStateRecord.updatedKaiUpulse}` });

const store = await createReceizClient().publicStore.resolve<StoreStateRecord>({
  host: "bjklock.receiz.app",
});

if (store.ok && store.storeStateRecord) renderStorefront(store.storeStateRecord);

When the merchant has a Receiz Key / Identity Seal, publish with merchant proof authority instead of a server bearer token:

const result = await createReceizClient().publicStore.publishWithIdentityProof({
  keyFile,
  tenantHost: "bjklock.receiz.app",
  merchantReceizId: "bjklock.receiz.id",
  storeStateRecord,
});

console.log(result.knownHead.afterKaiUpulse, result.appendAnchorId);

This signs the exact public-store feed with the merchant proof object, posts the signed envelope to the public proof rail, and returns the Kai/anchor append head. Delegated tokens remain available for agent/server operations; merchant storefront sync does not require RECEIZ_ACCESS_TOKEN.

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 quickstarts:

• docs/app-state-public-projections.md
• docs/signed-public-store-publish.md

Receiz App Runtime Rails

@receiz/[email protected] adds dogfood-ready local-first recipes on top of 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.

import { RECEIZ_OIDC_SCOPES_BY_RAIL, 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: [
    ...RECEIZ_OIDC_SCOPES_BY_RAIL.customers,
    ...RECEIZ_OIDC_SCOPES_BY_RAIL.merchants,
    ...RECEIZ_OIDC_SCOPES_BY_RAIL.publicStore,
  ],
});
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",
});

const tenantSession = await receiz.customers.bootstrapSession({
  tenantHost: "bjklock.receiz.app",
  customerReceizId: "customer.receiz.id",
  scopes: ["orders", "rewards", "assets"],
}, { idempotencyKey: "customer-session:v1" });

const hostedIdentity = receiz.identity.ensureTenantSession({
  tenantHost: "bjklock.receiz.app",
  returnTo: "https://bjklock.receiz.app/account",
  fallback: "artifact_upload",
});

const profile = await receiz.profile.resolveLocalFirst({
  memory,
  local: admittedProfileTruth,
  sync: (knownHead) => fetchVerifiedProfileAdditions(knownHead),
});

const walletLedger = await receiz.wallet.resolveLedger({
  memory,
  local: admittedWalletLedger,
  sync: (knownHead) => fetchVerifiedWalletAdditions(knownHead),
});

const pitchDay = await receiz.sports.resolvePitchDayProof({
  local: admittedPitchDayProof,
});

Additional typed surfaces:

• RECEIZ_OIDC_SCOPES_BY_RAIL and receizOidcScopesForRails() for stable per-rail Connect/OIDC scopes
• receiz.runtime.localFirst(), profile.resolveLocalFirst(), wallet.resolveLedger(), sports.resolveCardMemory(), sports.resolvePitchDayProof()
• receiz.proofMemory.syncAdditions() for append-only sync after the known proof-memory head
• receiz.publicStore.publish(), publicStore.resolve(), publicStore.createRecord()
• receiz.identity.ensureTenantSession({ tenantHost, returnTo, fallback })
• receiz.customers.bootstrapSession(), 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.webhookEndpoints.list(), create(), update(), rotateSecret(), sendTest(), delete()
• receiz.webhooks.parseRequest(), routeEvent(), verifySignature(), eventTypes, eventGroups, presets
• 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:

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.

Agent MCP Server

Agents can use Receiz through the official MCP server:

npx -y @receiz/mcp-server

@receiz/mcp-server wraps the SDK for agent hosts. It can inspect, resolve, publish through delegated SDK calls, expose Receiz resource templates, and direct byte-bearing artifacts to SDK verification.verifyArtifact(file). MCP lookup or inspection never supplies the verification verdict. It is not a proof authority above Receiz proof objects, identity primitives, settlement primitives, ownership surfaces, or public proof surfaces.

For writes, create a Receiz-issued delegated agent token from /developers/connect with Create Delegated Agent Token. Store only the one-time access_token in the MCP host:

[mcp_servers.receiz.env]
RECEIZ_BASE_URL = "https://receiz.com"
RECEIZ_ACCESS_TOKEN = "..."

Use the returned token_id for revocation/audit and the agent:* label to identify agent-published additions.

Sports Card And Event Proof Integration

import { assertReceizSportsCardManifest, createReceizClient } from "@receiz/sdk";

const manifest = assertReceizSportsCardManifest(await response.json());
const eventProofUrl = createReceizClient().sports.eventProofUrl("event_proof_123");

Full quickstart: docs/sports-card-event-proofs.md.

Wallet Ledger Reads

import { createReceizClient } from "@receiz/sdk";

const receiz = createReceizClient();
const ledger = await receiz.wallet.publicLedger({ limit: 40 });

Full quickstart: docs/wallet-ledger-reads.md.

Twin And World

Public World/Twin reads are available without a token. Owner-scoped Twin actions require a Receiz Connect access token with receiz:twin.read or receiz:twin.write, issued through a registered OIDC client.

import { createReceizClient } from "@receiz/sdk";

const publicReceiz = createReceizClient();
const world = await publicReceiz.world.profile("bjklock");

const receiz = createReceizClient({ accessToken: process.env.RECEIZ_ACCESS_TOKEN });
const mandate = await receiz.twin.marketMandate();
await receiz.twin.saveMarketMandate({
  status: "active",
  executionMode: "approve",
  maxOrderUsd: "25.00",
});
const intent = await receiz.twin.createMarketIntent({
  marketItemId: "asset_123",
  side: "buy",
  amountUsd: "10.00",
});

Full quickstart: docs/twin-and-world.md.

Connect Transfers

import { createReceizClient } from "@receiz/sdk";

const receiz = createReceizClient({ accessToken: process.env.RECEIZ_ACCESS_TOKEN });
await receiz.connect.transfer(
  { recipientUserId: "user_123", unit: "phi", amountPhi: "10" },
  { idempotencyKey: crypto.randomUUID() },
);

Full quickstart: docs/connect-transfers.md.

Webhook Signatures

import { parseReceizWebhookRequest, routeReceizWebhookEvent } from "@receiz/sdk";

const parsed = await parseReceizWebhookRequest(request, {
  secret: process.env.RECEIZ_WEBHOOK_SECRET!,
  toleranceSeconds: 300,
});

await routeReceizWebhookEvent(parsed.event, {
  "payment.settled": async (event) => {
    // Delivery is authentic. Verify the settlement ledger event before admitting product truth.
    await verifySettlementLedgerEvent(event.data);
  },
  "proof.appended": async (event) => {
    // Delivery is authentic. Verify the proof object or append before projecting it.
    await verifyProofAppend(event.data);
  },
});

Full quickstart: docs/webhook-signatures.md.

Webhook Endpoint Management

Humans can register endpoints at /developers/webhooks. Apps and agents can use the same lifecycle through the SDK with receiz:webhooks.read and receiz:webhooks.write.

import {
  RECEIZ_WEBHOOK_EVENT_PRESETS,
  createReceizClient,
} from "@receiz/sdk";

const receiz = createReceizClient({
  accessToken: process.env.RECEIZ_ACCESS_TOKEN,
});

const created = await receiz.webhookEndpoints.create({
  label: "Production payments",
  url: "https://app.example.com/api/receiz/webhooks",
  eventTypes: RECEIZ_WEBHOOK_EVENT_PRESETS.payment,
  idempotencyKey: "webhook:production-payments:v1",
});

await saveSecretOnce(created.credentials.secret);

await receiz.webhookEndpoints.sendTest(created.endpoint.endpointId, {
  eventType: "payment.settled",
});

Create and rotate return the plaintext whsec_... value once. Store it in your app secret manager. List, update, test, and delete return endpoint configuration only.

Webhook signatures prove delivery authenticity. Payment settlement, ownership appends, proof objects, and verified ledger records remain the product truth your receiver must verify before admitting the event.

App Registration And Token Lifecycle

Use Receiz Connect OIDC for self-serve developer onboarding: register an app, redirect through Authorization Code + PKCE, exchange tokens server-side, refresh on expiry, and call delegated clients with least-privilege scopes.

Full quickstart: docs/app-registration-token-lifecycle.md.