@on-belay/sdk 1.0.0 → 2.0.0

package/dist/index.d.mts

@@ -1,531 +1,468 @@
 /**
- * @on-belay/sdk — Exported Types
+ * @on-belay/sdk@2.0.0 — Public types
  *
- * All types used by fieldset authors are exported from here.
- * Fieldsets import from "@on-belay/sdk" only — never from platform internals.
+ * All types used by external fieldset authors are exported from here. The
+ * surface matches `docs/onbelay-platform/specs/external-fieldset-sdk-v2-spec.md`
+ * §4 and §A5.
+ *
+ * Importantly: every type here is portable. None depend on Prisma, the
+ * Next.js runtime, or any platform internal. The SDK is consumed by services
+ * running outside the On Belay monorepo.
+ */
+/**
+ * Per-call config bag. Every HTTP-bound SDK function accepts an optional
+ * `OnbelayConfig` as its trailing argument. The defaults read from env vars on
+ * every call so a long-lived service automatically picks up rotated tokens.
+ */
+interface OnbelayConfig {
+    /** Defaults to `process.env.ONBELAY_PROXY_URL`. Base URL only — paths are appended by the SDK. */
+    proxyUrl?: string;
+    /** Defaults to `process.env.ONBELAY_FIELDSET_TOKEN`. */
+    token?: string;
+    /** Required. Declared by the developer's service so the SDK can attach defense-in-depth slug params. */
+    fieldsetSlug: string;
+    /** Override for testing. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Thrown by every HTTP-bound function after a transport-level failure has been
+ * retried once per spec §4.6 (250ms fixed delay, no jitter). Transport
+ * failures are: network error, connect refused, abort/timeout, or HTTP 502/503/504.
+ *
+ * Other 5xx responses (500, 505+) throw immediately with `attempts === 1`.
+ *
+ * Carries the last observed status, the URL the SDK was hitting, and how many
+ * attempts were made (`1` if the first failure was non-retryable, `2` after
+ * the retry was issued and also failed).
  */
-type ProxyResult = {
+declare class OnbelayTransportError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly attempts: number;
+    constructor(message: string, opts: {
+        status: number;
+        url: string;
+        attempts: number;
+    });
+}
+/**
+ * Thrown by HTTP-bound functions that return raw values (not `ProxyResult`)
+ * when the platform returns a 4xx error code. `code` is the platform's error
+ * code (e.g. `org_not_enrolled`, `fieldset_mismatch`).
+ *
+ * `executeProxyCall` does NOT throw this — it returns a typed `ProxyResult`
+ * envelope so the caller can branch without a try/catch.
+ */
+declare class OnbelayProtocolError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly code: string;
+    constructor(message: string, opts: {
+        status: number;
+        url: string;
+        code: string;
+    });
+}
+type ProxyErrorCode = "invalid_token" | "operation_not_permitted" | "org_not_enrolled" | "integration_not_connected" | "fieldset_inactive" | "invalid_request" | "upstream_error" | "proxy_error" | "rate_limit_exceeded";
+type ProxyResult<T = unknown> = {
+    ok: true;
     status: number;
-    data: unknown;
-    blocked?: boolean;
-    error?: string;
+    data: T;
+} | {
+    ok: false;
+    status: number;
+    blocked: true;
+    error: ProxyErrorCode;
+} | {
+    ok: false;
+    status: number;
+    blocked: false;
+    error: string;
 };
-type ConnectedIntegration = {
+interface ConnectedIntegration {
     slug: string;
     status: "active" | "error" | "pending";
+    /**
+     * Server-side allowlisted extra config. For v2.0.0:
+     *   shopify → `{ shopDomain }`
+     *   all others → `{}`
+     * Encrypted columns (apiKeyEnc, apiSecretEnc) are NEVER returned.
+     */
     extraConfig: Record<string, string | null>;
-};
-type OrgContext = {
+}
+interface OrgContext {
     orgId: string;
     orgName: string;
     connectedIntegrations: ConnectedIntegration[];
-};
-type PortfolioOrg = {
+}
+/**
+ * Spec §A5 lists `EnrolledOrg` in `types.ts`. The function `getEnrolledOrgs`
+ * returns `Promise<string[]>` per spec §4.4 / shim contract — `EnrolledOrg`
+ * is a forward-compatible richer shape exposed for consumers that want a
+ * named type for "an enrolled org" beyond the bare orgId list.
+ */
+interface EnrolledOrg {
     orgId: string;
-    orgName: string;
-    orgSlug: string;
-};
-type FieldsetManifest = {
-    /** Unique kebab-case slug. Immutable after first deploy. */
-    slug: string;
-    /** Display name shown in the dashboard. */
-    name: string;
-    /** Short description shown in the fieldset catalog. */
-    description: string;
-    /**
-     * Execution model.
-     * - 'per-org': standard fieldset, enrolled per STANDARD org. Default.
-     * - 'portfolio': enrolled once at an AGENCY org level; has access to all child orgs.
-     *
-     * Omitting this field is treated as 'per-org' for backward compatibility.
-     */
-    executionModel?: "per-org" | "portfolio";
-    /** Integration slugs the org must have connected before enrolling. */
-    requiredIntegrations: string[];
-    /** Integration slugs that improve the fieldset but are not required. */
-    optionalIntegrations?: string[];
-    /**
-     * Every (integrationSlug, operationKey) pair this fieldset ever calls via executeProxyCall.
-     * The proxy rejects any call not in this manifest.
-     */
-    requiredOperations: Array<{
-        slug: string;
-        operationKey: string;
-    }>;
-    /**
-     * Billing configuration. Required if the fieldset calls recordPublish().
-     * Each key is a contentType string. freeAllowance is per-org, per-contentType.
-     */
-    billing?: {
-        contentTypes: Record<string, {
-            label: string;
-            freeAllowance: number;
-        }>;
+}
+/**
+ * v2.0.0 ships with these as documented examples — `contentType` is a free-form
+ * string so developers can pick their own keys. Listed here for spec §A5
+ * compliance ("ContentType in types.ts").
+ */
+type ContentType = string;
+interface PublishResult {
+    count: number;
+    freeAllowance: number;
+    billable: boolean;
+}
+/**
+ * Body of every webhook the platform sends to an external fieldset.
+ *
+ * - `runId` (Decision D-A) — stable across Inngest retries within the same
+ *   (enrollment, calendar day, triggerType). Use this for handler-side dedupe.
+ * - `fieldsetToken` is NOT in this payload (Decision G-A). The developer reads
+ *   `process.env.ONBELAY_FIELDSET_TOKEN` directly.
+ * - `actor` is present only on `triggerType === "manual"` runs (Decision H).
+ * - `config` (Decision F-A) contains ONLY the `fieldset` namespace of
+ *   `OrgFieldset.config`. The `admin` namespace is never sent.
+ * - `neonConnectionString` is present only when `OrgFieldset.neonConnectionStringEnc`
+ *   is non-null.
+ */
+interface WebhookPayload {
+    orgId: string;
+    fieldsetSlug: string;
+    triggerType: "scheduled" | "manual" | "user_triggered" | "enrollment_changed" | "unenrollment";
+    timestamp: string;
+    runId: string;
+    neonConnectionString?: string;
+    config?: Record<string, unknown>;
+    actor?: {
+        userId: string;
+        email: string;
     };
+}
+interface WebhookHandlerContext {
+    payload: WebhookPayload;
+    rawBody: string;
+}
+interface WebhookHandlerOptions {
+    /** ONBELAY_WEBHOOK_SECRET — used for HMAC-SHA256 verification. */
+    secret: string;
     /**
-     * Default values written into OrgFieldset.config at enrollment time.
-     * The fieldset reads these back via getFieldsetConfig().
-     */
-    configDefaults?: Record<string, unknown>;
-    /**
-     * Migration file names (relative to the fieldset's migrations/ directory), in order.
-     * The platform runs these at enrollment time.
-     */
-    migrations?: string[];
-    /**
-     * Exported Inngest function names from the fieldset's inngest/ directory.
-     * The platform registers these at app startup.
+     * The fieldset this service implements. Payloads addressed to a different
+     * fieldset are rejected with 401 to defend against misrouted dispatch.
      */
-    inngestFunctions?: string[];
-};
-/** Opaque Inngest function type — returned by createScheduler / createOrgRunner / createPortfolioRunner. */
-type InngestFunction = any;
-/** Opaque Inngest step object — provided by Inngest to function handlers. */
-type InngestStep = any;
-/** Opaque Inngest event object — full event payload including data, id, ts. */
-type InngestEvent = any;
-type SchedulerConfig = {
-    /** Inngest function ID — must be unique across the platform. E.g. "content-engine-scheduler". */
-    id: string;
-    /** The fieldset slug — used to query enrolled orgs via getEnrolledOrgs. */
     fieldsetSlug: string;
-    /** Cron expression (UTC). E.g. "0 9 * * 1-5" for weekdays at 9am UTC. */
-    cron: string;
-    /** The event name to emit for each enrolled org. E.g. "content-engine/run.org". */
-    eventName: string;
-    /**
-     * Optional: extra event data to include per org event.
-     * Called once per org — return any serializable data to merge into the event payload.
-     */
-    eventData?: (orgId: string) => Record<string, unknown>;
-    /** Maximum concurrent scheduler runs. Default: 1. */
-    concurrency?: number;
-};
-type OrgRunContext = {
-    /** The org this run is for. */
+    /** User code. Throw → 500 → platform retries (§6.5). Return → 200. */
+    onTrigger: (ctx: WebhookHandlerContext) => Promise<void>;
+    /** Defaults to 300 (5 min) per spec §6.3. */
+    maxAgeSeconds?: number;
+}
+interface WebhookResult {
+    status: number;
+    body: string;
+    headers: Record<string, string>;
+}
+interface WebhookVerifyOptions {
+    maxAgeSeconds?: number;
+}
+interface DashboardTokenPayload {
     orgId: string;
-    /** Inngest step object — use step.run() to create durable, retriable steps. */
-    step: InngestStep;
-    /** Full Inngest event — includes any extra data from the scheduler. */
-    event: InngestEvent;
-};
-type OrgRunnerConfig = {
-    /** Inngest function ID. E.g. "content-engine-runner". */
-    id: string;
-    /** Event that triggers this runner. Must match scheduler's eventName. */
-    triggerEvent: string;
-    /** Fieldset slug — used for enrollment verification inside the runner. */
-    fieldsetSlug: string;
-    /**
-     * Concurrency key expression. Default: "event.data.orgId".
-     * One concurrent run per unique key value at a time.
-     */
-    concurrencyKey?: string;
-    /** Default: 1. */
-    concurrencyLimit?: number;
-    /** Number of Inngest retries on failure. Default: 2. */
-    retries?: number;
-    /** Inngest function timeout in minutes. Default: 10. */
-    timeoutMinutes?: number;
-    /** The fieldset's run logic. Receives orgId, step, and the full event. */
-    run: (context: OrgRunContext) => Promise<unknown>;
-};
-type PortfolioRunContext = {
-    /** The enrolled AGENCY org. */
-    parentOrgId: string;
-    /** Pre-fetched client orgs via getPortfolioOrgs — iterate these in isolation. */
-    clientOrgs: PortfolioOrg[];
-    /** Inngest step object. */
-    step: InngestStep;
-    /** Full Inngest event. */
-    event: InngestEvent;
-};
-type PortfolioRunnerConfig = {
-    /** Inngest function ID. E.g. "pe-revenue-tracker-runner". */
-    id: string;
-    /** Event that triggers this runner. E.g. "pe-revenue-tracker/run.portfolio". */
-    triggerEvent: string;
-    /** Fieldset slug — used for enrollment verification. */
+    userId: string;
     fieldsetSlug: string;
-    /** Default: 1. */
-    concurrencyLimit?: number;
-    /** Default: 2. */
-    retries?: number;
-    /** Default: 15 minutes (portfolio runs aggregate across N orgs). */
-    timeoutMinutes?: number;
-    /** The fieldset's portfolio run logic. */
-    run: (context: PortfolioRunContext) => Promise<unknown>;
-};
+    iat?: number;
+    exp?: number;
+}
 
 /**
- * @on-belay/sdk — executeProxyCall
+ * @on-belay/sdk@2.0.0 — executeProxyCall + shared HTTP transport
  *
- * The only way a fieldset may call a third-party API. Routes through the
- * On Belay proxy layer, which handles credential retrieval, decryption, token
- * refresh, audit logging, and org-scoping.
+ * `executeProxyCall` is the only sanctioned way for an external fieldset to call
+ * a third-party API. Every call is dispatched as
+ * `POST {ONBELAY_PROXY_URL}/api/sdk/proxy` with a Bearer token; the platform
+ * resolves credentials, refreshes tokens, audits the call, and proxies through.
  *
- * Fieldsets never construct AuthResult objects or touch proxy-handler.ts directly.
+ * The HTTP transport (`onbelayFetch`) is exported privately for the other
+ * HTTP-bound SDK modules (`org.ts`, `config.ts`, `enrollment.ts`, `billing.ts`)
+ * to share — they all enforce the same retry/timeout semantics from spec §4.6.
  *
- * Dual-mode execution:
- * - Internal mode (no ONBELAY_FIELDSET_TOKEN env var): direct import from platform
- *   internals. Used by fieldsets running inside the On Belay monorepo.
- * - External mode (ONBELAY_FIELDSET_TOKEN is set): HTTP POST to ONBELAY_PROXY_URL.
- *   Used by external fieldsets deployed as standalone services (e.g. on Railway).
+ * Spec contract: §4.4 (signature), §4.6 (network behavior), §5.2 `POST /api/sdk/proxy`.
  */
 
 /**
- * Execute an authenticated API call to a third-party integration on behalf of an org.
+ * Execute an authenticated API call to a third-party integration on behalf of
+ * an org. Returns a typed `ProxyResult` envelope — the caller MUST check `ok`
+ * before reading `data`.
  *
- * This is the ONLY way a fieldset may call any external API.
+ * Endpoint: `POST /api/sdk/proxy`. Spec §4.4, §5.2.
  *
- * Dispatches to external HTTP mode when ONBELAY_FIELDSET_TOKEN is set in the environment,
- * otherwise falls back to direct internal platform imports (monorepo mode).
+ * Returns:
+ * - `{ ok: true, status, data }` on 2xx upstream.
+ * - `{ ok: false, blocked: true, status, error: ProxyErrorCode }` on 4xx
+ *   from the platform (token, permission, enrollment, integration, etc.).
+ * - `{ ok: false, blocked: false, status, error }` on upstream errors.
  *
- * @param orgId - The org on whose behalf the call is made. For portfolio runners
- *                acting on a client, pass the clientOrgId here.
- * @param fieldsetSlug - The fieldset's slug (from its manifest). Used to construct
- *                       the fieldset-master AuthResult and enforce operation permissions.
- * @param integrationSlug - The On Belay integration slug (e.g. "shopify", "hubspot").
- * @param operationKey - The operation key declared in the fieldset manifest (e.g. "shopify.products.list").
- * @param path - The API path (e.g. "/admin/api/2024-01/products.json").
- * @param options - Optional: method, body, queryParams, _portfolioParentOrgId.
- *
- * @returns ProxyResult — check result.blocked before using result.data.
- *
- * Error behavior:
- * - result.blocked === true: integration not connected or operation not in manifest. Log and skip.
- * - result.status >= 500: upstream API error. Throw to let Inngest retry.
- * - Throws if fieldsetSlug is not registered: developer error, fix before deploying.
+ * Throws `OnbelayTransportError` on transport failure or 5xx after one retry.
  */
-declare function executeProxyCall(orgId: string, fieldsetSlug: string, integrationSlug: string, operationKey: string, path: string, options?: {
+declare function executeProxyCall<T = unknown>(orgId: string, integrationSlug: string, operationKey: string, path: string, options?: {
     method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     body?: Record<string, unknown>;
     queryParams?: Record<string, string>;
-    /**
-     * Portfolio runners only. When set, the SDK validates that orgId is a client
-     * of this parent org before dispatching the proxy call. Returns blocked: true
-     * if orgId is not a valid client of the parent.
-     *
-     * NOTE: Only available in internal mode. In external mode this field is ignored
-     * — parent validation is enforced server-side by the proxy endpoint.
-     *
-     * TODO: platform-team (P0 #15) — When proxy-handler gains native portfolio
-     * parent validation, delegate there instead of doing it here.
-     */
-    _portfolioParentOrgId?: string;
-}): Promise<ProxyResult>;
+}, config?: OnbelayConfig): Promise<ProxyResult<T>>;
 
 /**
- * @on-belay/sdk — validateWebhookSignature
+ * @on-belay/sdk@2.0.0 — getOrgContext
  *
- * Self-contained HMAC-SHA256 webhook signature verification.
- * Mirrors the implementation in src/lib/webhook-signing.ts but has zero
- * imports from platform internals — safe for npm publishing.
+ * Returns the calling fieldset's view of one enrolled org — orgName +
+ * connected integrations + server-allowlisted `extraConfig`. Encrypted
+ * credential columns are NEVER returned (spec §5.2).
  *
- * Usage:
- *   import { validateWebhookSignature } from "@on-belay/sdk"
- *
- *   app.post("/api/webhook", express.raw({ type: "application/json" }), (req, res) => {
- *     const isValid = validateWebhookSignature(
- *       req.body,
- *       req.headers["x-onbelay-signature"] as string,
- *       process.env.ONBELAY_WEBHOOK_SECRET!,
- *       req.headers["x-onbelay-timestamp"] as string,
- *       { maxAgeSeconds: 300 }
- *     )
- *     if (!isValid) return res.status(401).json({ error: "invalid_signature" })
- *     // ... handle webhook
- *   })
+ * Endpoint: `GET /api/sdk/orgs/:orgId/context`. Spec §4.4 / §5.2.
  */
-interface WebhookVerifyOptions {
-    maxAgeSeconds?: number;
-}
+
 /**
- * Verifies an inbound webhook signature from On Belay.
- * Uses constant-time comparison to prevent timing side-channel attacks.
- * Returns false (never throws) on any mismatch or error.
- *
- * @param rawBody         - Raw request body before JSON.parse (string or Buffer).
- *                          Must be the exact bytes received — do NOT parse first.
- * @param signatureHeader - Value of X-Onbelay-Signature header ("sha256=<hex>")
- * @param secret          - Your webhook secret (ONBELAY_WEBHOOK_SECRET env var)
- * @param timestamp       - Optional. Value of X-Onbelay-Timestamp header (ISO8601).
- *                          When provided, the function rejects payloads older than
- *                          maxAgeSeconds (replay-attack defense).
- * @param options         - Optional. { maxAgeSeconds?: number } — defaults to 300 (5 min).
- *
- * @returns true if the signature is valid (and timestamp is within age limit when provided)
+ * Look up the calling fieldset's view of one enrolled org.
+ *
+ * @throws `OnbelayProtocolError` on 4xx (`org_not_enrolled`, `org_not_found`,
+ *         `invalid_token`, `rate_limit_exceeded`).
+ * @throws `OnbelayTransportError` on transport failure / 5xx after one retry.
  */
-declare function validateWebhookSignature(rawBody: string | Buffer, signatureHeader: string, secret: string, timestamp?: string, options?: WebhookVerifyOptions): boolean;
+declare function getOrgContext(orgId: string, config?: OnbelayConfig): Promise<OrgContext>;
 
 /**
- * @on-belay/sdk — validateDashboardToken
+ * @on-belay/sdk@2.0.0 — getFieldsetConfig / setFieldsetConfig
  *
- * Browser and Node.js compatible JWT verification using jose.
- * Validates a dashboard context token issued by the On Belay platform.
+ * Read/write the **fieldset namespace** of `OrgFieldset.config` JSON for one
+ * enrolled org. The `admin` namespace (used by org admins for config the
+ * developer should not see) is server-protected — `setFieldsetConfig` cannot
+ * touch it.
  *
- * Usage:
- *   import { validateDashboardToken } from "@on-belay/sdk"
- *
- *   app.post("/api/my-data", express.json(), async (req, res) => {
- *     const context = await validateDashboardToken(
- *       req.body.token,
- *       process.env.ONBELAY_DASHBOARD_SECRET!
- *     )
- *     if (!context) return res.status(401).json({ error: "invalid_token" })
- *
- *     const { orgId, userId, fieldsetSlug } = context
- *     // act on behalf of this org
- *   })
- */
-interface DashboardTokenPayload {
-    orgId: string;
-    userId: string;
-    fieldsetSlug: string;
-    iat?: number;
-    exp?: number;
-}
-/**
- * Validates a dashboard context token issued by the On Belay platform.
- * Returns the decoded payload on success, or null on any validation failure
- * (expired, bad signature, malformed). Never throws.
+ * Endpoints:
+ *   GET   /api/sdk/orgs/:orgId/config?fieldset=<slug>
+ *   PATCH /api/sdk/orgs/:orgId/config
  *
- * @param token  - The JWT string received via postMessage from the platform
- * @param secret - process.env.ONBELAY_DASHBOARD_SECRET
+ * Spec §4.4, §5.2, Decision F-A (§A3 namespace migration).
  */
-declare function validateDashboardToken(token: string, secret: string): Promise<{
-    orgId: string;
-    userId: string;
-    fieldsetSlug: string;
-} | null>;
 
 /**
- * @on-belay/sdk — getOrgContext
+ * Returns the contents of `OrgFieldset.config.fieldset` (or `{}` if absent).
+ * The `admin` namespace is never returned to the SDK.
  *
- * Returns org name and connected integrations for a given org.
- * Read-only. Does not expose encrypted fields or credentials.
+ * @throws `OnbelayProtocolError` on 4xx (`org_not_enrolled`, `fieldset_mismatch`,
+ *         `invalid_token`).
+ * @throws `OnbelayTransportError` on transport failure / 5xx after one retry.
  */
-
+declare function getFieldsetConfig<T = Record<string, unknown>>(orgId: string, config?: OnbelayConfig): Promise<T>;
 /**
- * Returns the org's name and list of connected integrations with their status
- * and extraConfig. Read-only — credentials are never exposed here.
- *
- * @throws If orgId does not exist in the database.
+ * Patch-merges into the **fieldset namespace** of `OrgFieldset.config`. The
+ * server performs a transactional `SELECT FOR UPDATE → merge → UPDATE` so
+ * concurrent writes do not lose updates.
+ *
+ * Forbidden: a top-level `admin` key in the patch returns
+ * `OnbelayProtocolError` with code `forbidden_namespace` — the developer
+ * cannot write to admin-set config via this SDK.
+ *
+ * Size caps:
+ * - SDK rejects patches >32KB (serialized) before they leave the process.
+ * - Server rejects merged config.fieldset >64KB.
+ *
+ * @throws `OnbelayProtocolError` on 4xx (`org_not_enrolled`, `invalid_patch`,
+ *         `fieldset_mismatch`, `forbidden_namespace`, `config_too_large`,
+ *         `payload_too_large`).
+ * @throws `OnbelayTransportError` on transport failure / 5xx after one retry.
  */
-declare function getOrgContext(orgId: string): Promise<OrgContext>;
+declare function setFieldsetConfig<T = Record<string, unknown>>(orgId: string, patch: Partial<T>, config?: OnbelayConfig): Promise<void>;
 
 /**
- * @on-belay/sdk — getFieldsetConfig / setFieldsetConfig
+ * @on-belay/sdk@2.0.0 — isEnrolled / getEnrolledOrgs
  *
- * Read and write the OrgFieldset.config JSON blob for an org+fieldset pair.
- * Config is plaintext — do NOT store credentials, tokens, or sensitive values here.
- */
-/**
- * Returns the OrgFieldset.config for this org and fieldset.
- * Returns {} (empty object cast to T) if no config has been set yet.
+ * Enrollment-state queries scoped to the calling fieldset (the token
+ * identifies the fieldset; clients cannot list other fieldsets' enrollments).
  *
- * @param orgId - The org ID.
- * @param fieldsetSlug - The fieldset's slug.
- * @returns The config cast to T. The fieldset declares T to get type safety.
+ * Endpoints:
+ *   GET /api/sdk/orgs/:orgId/enrolled?fieldset=<slug>  → { enrolled: boolean }
+ *   GET /api/sdk/enrollments                            → { orgs: string[] }
  *
- * @throws If orgId does not exist.
+ * Spec §4.4, §5.2. `isEnrolled` returns `false` for orgs that don't exist —
+ * the platform must not leak existence (brightline §3.11).
  */
-declare function getFieldsetConfig<T = Record<string, unknown>>(orgId: string, fieldsetSlug: string): Promise<T>;
+
 /**
- * Merges patch into the existing OrgFieldset.config. Non-destructive:
- * keys not in patch are preserved.
+ * Returns `true` only when the calling fieldset has an active enrollment for
+ * this org. Returns `false` for unknown orgs, suspended enrollments, and any
+ * other non-active state.
  *
- * @param orgId - The org ID.
- * @param fieldsetSlug - The fieldset's slug.
- * @param patch - Partial config to merge in.
- *
- * @throws If the OrgFieldset row does not exist (org not enrolled in this fieldset).
- *         Call isEnrolled() before calling this if enrollment is uncertain.
+ * @throws `OnbelayProtocolError` on 4xx (`invalid_token`, `fieldset_mismatch`,
+ *         `rate_limit_exceeded`).
+ * @throws `OnbelayTransportError` on transport failure / 5xx after one retry.
  */
-declare function setFieldsetConfig<T = Record<string, unknown>>(orgId: string, fieldsetSlug: string, patch: Partial<T>): Promise<void>;
-
+declare function isEnrolled(orgId: string, config?: OnbelayConfig): Promise<boolean>;
 /**
- * @on-belay/sdk — recordPublish
- *
- * Records a billing event for a publish (writeback) action.
- * Increments the PublishCounter for this org+fieldset+contentType.
- * If Stripe metered billing is configured, fires the usage event.
+ * Returns the orgIds of every org with an active enrollment in the calling
+ * fieldset. The fieldsetId is derived server-side from the token — clients
+ * cannot list another fieldset's enrollments.
  *
- * Call at writeback time, NOT at generation time.
+ * @throws `OnbelayProtocolError` on 4xx (`invalid_token`, `rate_limit_exceeded`).
+ * @throws `OnbelayTransportError` on transport failure / 5xx after one retry.
  */
+declare function getEnrolledOrgs(config?: OnbelayConfig): Promise<string[]>;
+
 /**
- * Records a publish billing event for an org+fieldset+contentType combination.
- *
- * - Upserts a PublishCounter row (increments publishCount).
- * - Fires a Stripe metered billing event when STRIPE_SECRET_KEY is configured.
- *   Stripe failures are logged but do NOT throw — the publish proceeds regardless.
- *   If the Prisma upsert fails, it throws so the Inngest step retries.
+ * @on-belay/sdk@2.0.0 — recordPublish
  *
- * IMPORTANT: Call this at writeback time, not generation time. Billing is
- * triggered by publish-to-live, not by content generation.
+ * Increments the org's PublishCounter for this fieldset and content type.
+ * v2.0.0 does NOT support an idempotency key (Decision B in spec §15) — the
+ * server's atomic upsert on `(orgId, fieldsetId, contentType)` is the only
+ * concurrency guarantee. Strict idempotency requires a `BillingIdempotency`
+ * table that is deferred to v2.1.
  *
- * IMPORTANT: This call and the writeback itself must be inside the SAME
- * step.run() block to ensure atomicity — if the writeback fails, the billing
- * event does not fire (Inngest retries the entire step).
+ * Endpoint: `POST /api/sdk/orgs/:orgId/billing/publish`. Spec §4.4 / §5.2.
  *
- * @param orgId - The org being billed.
- * @param fieldsetSlug - The fieldset slug.
- * @param contentType - The content type (must match a key in the fieldset's
- *                      manifest billing.contentTypes). E.g. "product_description".
- * @param metadata - Optional metadata to log with the billing event.
+ * Call at writeback time (not generation time). Billing is incurred when
+ * content goes live for the org, not when it is generated.
  */
-declare function recordPublish(orgId: string, fieldsetSlug: string, contentType: string, metadata?: Record<string, unknown>): Promise<void>;
 
 /**
- * @on-belay/sdk — isEnrolled / getEnrolledOrgs
+ * Record a billable publish event. Returns the new running count, the row's
+ * `freeAllowance` (10 by default after the §A2 migration), and whether this
+ * publish is billable (`count > freeAllowance`).
  *
- * Enrollment state queries for fieldset schedulers and runners.
+ * @throws `OnbelayProtocolError` on 4xx (`org_not_enrolled`,
+ *         `invalid_content_type`, `invalid_token`, `rate_limit_exceeded`).
+ * @throws `OnbelayTransportError` on transport failure / 5xx after one retry.
  */
+declare function recordPublish(orgId: string, contentType: string, metadata?: Record<string, unknown>, config?: OnbelayConfig): Promise<PublishResult>;
+
 /**
- * Returns true if the org has an active OrgFieldset record for this fieldset.
- * Returns false for any non-active status (suspended, expired, disabled) or if
- * no record exists.
+ * @on-belay/sdk@2.0.0 — validateWebhookSignature
  *
- * Use this inside runners to gate execution. Do NOT use it to gate proxy calls —
- * the proxy already enforces enrollment.
+ * Self-contained HMAC-SHA256 webhook signature verification.
  *
- * @param orgId - The org to check.
- * @param fieldsetSlug - The fieldset slug.
- */
-declare function isEnrolled(orgId: string, fieldsetSlug: string): Promise<boolean>;
-/**
- * Returns an array of orgId strings for all orgs with an active enrollment
- * in this fieldset.
+ * Identical wire-level contract to 1.0.0 — kept verbatim per spec §4.2.
+ * Pure crypto, no platform imports, safe for npm publishing.
  *
- * Use this inside a scheduler to discover orgs to fan out to. Do NOT query
- * OrgFieldset directly from fieldset code — this is the canonical path.
+ * Usage:
+ *   import { validateWebhookSignature } from "@on-belay/sdk"
  *
- * @param fieldsetSlug - The fieldset slug.
- * @returns Array of org IDs with active enrollment.
+ *   const isValid = validateWebhookSignature(
+ *     rawBody,
+ *     req.headers["x-onbelay-signature"],
+ *     process.env.ONBELAY_WEBHOOK_SECRET!,
+ *     req.headers["x-onbelay-timestamp"],
+ *     { maxAgeSeconds: 300 }
+ *   )
  */
-declare function getEnrolledOrgs(fieldsetSlug: string): Promise<string[]>;
 
 /**
- * @on-belay/sdk — getPortfolioOrgs
+ * Verifies an inbound webhook signature from On Belay.
  *
- * Returns client orgs for a portfolio (AGENCY) org. Used by portfolio runners
- * to discover which client orgs to iterate over.
+ * - Constant-time comparison via `timingSafeEqual`.
+ * - Returns `false` (never throws) on any mismatch or error.
+ * - Optional timestamp argument enforces replay-attack defense: payloads
+ *   older than `maxAgeSeconds` (default 300) and more than 30s in the future
+ *   are rejected.
+ *
+ * @param rawBody         Raw request body before JSON.parse — exact bytes.
+ * @param signatureHeader Value of `X-Onbelay-Signature` (`sha256=<hex>`).
+ * @param secret          `ONBELAY_WEBHOOK_SECRET` env var.
+ * @param timestamp       Optional. `X-Onbelay-Timestamp` header (ISO8601).
+ * @param options         Optional. `{ maxAgeSeconds }` — defaults to 300.
  */
+declare function validateWebhookSignature(rawBody: string | Buffer, signatureHeader: string, secret: string, timestamp?: string, options?: WebhookVerifyOptions): boolean;
 
 /**
- * Returns all client orgs that are children of the given parentOrgId.
- * These are the orgs a portfolio fieldset is authorized to read from and
- * act on behalf of.
+ * @on-belay/sdk@2.0.0 — validateDashboardToken
  *
- * Data isolation law: process each client org in isolation inside its own
- * step.run() block. Aggregate only scalar outputs across client contexts —
- * never raw credential-adjacent data.
+ * Browser- and Node-compatible JWT verification using `jose`. Validates a
+ * dashboard context token issued by the On Belay platform when an org admin
+ * opens a fieldset's embedded UI.
  *
- * @param parentOrgId - The enrolled AGENCY org.
- * @returns Array of client orgs. Returns [] if no clients — not an error.
+ * Identical contract to 1.0.0 (spec §4.2). Pure crypto, no platform imports.
  *
- * @throws If parentOrgId does not exist.
- * @throws If parentOrgId resolves to a non-AGENCY org.
+ * Usage:
+ *   const ctx = await validateDashboardToken(token, process.env.ONBELAY_DASHBOARD_SECRET!)
+ *   if (!ctx) return new Response("invalid_token", { status: 401 })
+ *   // ctx.orgId, ctx.userId, ctx.fieldsetSlug
  */
-declare function getPortfolioOrgs(parentOrgId: string): Promise<PortfolioOrg[]>;
 
 /**
- * @on-belay/sdk — createScheduler / createOrgRunner / createPortfolioRunner
- *
- * Inngest function builders for fieldsets. These cover the standard
- * scheduler → fan-out → per-org runner pattern.
+ * Verify and decode a dashboard context token. Returns the decoded payload on
+ * success or `null` on any failure (expired, bad signature, malformed, wrong
+ * issuer). Never throws.
  *
- * For complex multi-stage pipelines (like the marketing agent), write
- * Inngest functions directly using inngest.createFunction — do not stretch
- * these builders to cover cases they weren't designed for.
+ * @param token  JWT string received via postMessage from the platform.
+ * @param secret `ONBELAY_DASHBOARD_SECRET` env var.
  */
+declare function validateDashboardToken(token: string, secret: string): Promise<{
+    orgId: string;
+    userId: string;
+    fieldsetSlug: string;
+} | null>;
 
 /**
- * Creates an Inngest function that runs on a cron schedule, queries enrolled
- * orgs via getEnrolledOrgs, and fans out one event per org.
- *
- * Returns the Inngest function object for registration in route.ts.
- *
- * Use this for the standard scheduler pattern. If your scheduler needs custom
- * logic beyond fan-out, write inngest.createFunction directly.
- *
- * @example
- * export const myFieldsetScheduler = createScheduler({
- *   id: "my-fieldset-scheduler",
- *   fieldsetSlug: "my-fieldset",
- *   cron: "0 9 * * 1-5",
- *   eventName: "my-fieldset/run.org",
- * })
- */
-declare function createScheduler(config: SchedulerConfig): InngestFunction;
-/**
- * Creates an Inngest function triggered by triggerEvent. Extracts orgId from
- * event.data, verifies enrollment (short-circuits if not enrolled), and calls
- * run(context) which the fieldset implements.
- *
- * @example
- * export const myFieldsetRunner = createOrgRunner({
- *   id: "my-fieldset-runner",
- *   triggerEvent: "my-fieldset/run.org",
- *   fieldsetSlug: "my-fieldset",
- *   async run({ orgId, step }) {
- *     await step.run("do-work", async () => { ... })
- *   },
- * })
+ * @on-belay/sdk@2.0.0 — createOnbelayWebhookHandler
+ *
+ * Framework-agnostic webhook handler factory. The returned function takes a
+ * raw body string + headers map and returns `{ status, body, headers }` so it
+ * can be wrapped in any framework (Next.js Route Handlers, Express, Fastify,
+ * Hono).
+ *
+ * Spec §4.4 (signature), §4.4 numbered behavior list:
+ *   1. Validate `X-Onbelay-Signature` HMAC against the raw body. Invalid → 401.
+ *   2. Validate `X-Onbelay-Timestamp` is within `maxAgeSeconds`. Stale → 401.
+ *   3. Parse JSON. Validate `payload.fieldsetSlug === options.fieldsetSlug`. Mismatch → 401.
+ *   4. Call `onTrigger(ctx)`. Throw → 500. Success → 200.
+ *
+ * The handler does NOT verify `runId` uniqueness — Inngest re-issues identical
+ * runIds on retry, and the developer is expected to dedupe in their own
+ * persistence layer (spec §6.1, §6.7).
  */
-declare function createOrgRunner(config: OrgRunnerConfig): InngestFunction;
-/**
- * Creates an Inngest function for portfolio (AGENCY org level) fieldsets.
- * Extracts parentOrgId from event.data, verifies enrollment, fetches client
- * orgs via getPortfolioOrgs, then calls run(context) with the full client list.
- *
- * The runner does NOT fan out to per-client Inngest events automatically.
- * Fieldsets receive the full client org list and iterate internally using
- * step.run() blocks for per-client retry granularity.
- *
- * @example
- * export const myPortfolioRunner = createPortfolioRunner({
- *   id: "my-portfolio-runner",
- *   triggerEvent: "my-fieldset/run.portfolio",
- *   fieldsetSlug: "my-fieldset",
- *   async run({ parentOrgId, clientOrgs, step }) {
- *     for (const client of clientOrgs) {
- *       await step.run(`process-${client.orgId}`, async () => { ... })
- *     }
- *   },
- * })
- */
-declare function createPortfolioRunner(config: PortfolioRunnerConfig): InngestFunction;
 
 /**
- * @on-belay/sdk — defineFieldset
- *
- * Helper to define a fieldset manifest with type checking.
- * Use this in every fieldset's fieldset.manifest.ts file.
- *
- * @example
- * import { defineFieldset } from "@on-belay/sdk"
- *
- * export default defineFieldset({
- *   slug: "content-engine",
- *   name: "Content Engine",
- *   description: "AI-powered product and blog content for Shopify brands.",
- *   executionModel: "per-org",
- *   requiredIntegrations: ["shopify"],
- *   requiredOperations: [
- *     { slug: "shopify", operationKey: "shopify.products.list" },
- *   ],
- * })
+ * Build a Web-Standards webhook handler bound to one fieldset.
+ *
+ * @param options.secret         `ONBELAY_WEBHOOK_SECRET`.
+ * @param options.fieldsetSlug   The fieldset this service implements; payloads
+ *                                addressed to a different slug return 401.
+ * @param options.onTrigger      User code. Throw → 500 → platform retries.
+ * @param options.maxAgeSeconds  Optional. Defaults to 300 (spec §6.3).
+ *
+ * @returns `(rawBody, headers) => Promise<WebhookResult>` — caller is
+ *           responsible for translating the result into framework-native
+ *           Request/Response objects.
  */
+declare function createOnbelayWebhookHandler(options: WebhookHandlerOptions): (rawBody: string, headers: Record<string, string | undefined>) => Promise<WebhookResult>;
 
 /**
- * Define a fieldset manifest. This is a typed identity function — it returns
- * the manifest object unchanged but provides TypeScript type checking at
- * authoring time.
+ * @on-belay/sdk@2.0.0 — OnbelayClient
+ *
+ * Convenience class that holds an `OnbelayConfig` and exposes the SDK's
+ * HTTP-bound functions as instance methods. Pure ergonomic wrapper — every
+ * method delegates to the equivalent free function with the bound config.
  *
- * The platform reads the default export of fieldset.manifest.ts at registration
- * and enrollment time.
+ * Spec §4.4.1.
+ *
+ * Use it when you have a single fieldset slug for the entire process and want
+ * to avoid passing the config bag to every call:
+ *
+ *   const onbelay = new OnbelayClient({ fieldsetSlug: "my-fieldset" })
+ *   await onbelay.recordPublish(orgId, "report")
  */
-declare function defineFieldset(manifest: FieldsetManifest): FieldsetManifest;
 
-export { type ConnectedIntegration, type DashboardTokenPayload, type FieldsetManifest, type InngestEvent, type InngestFunction, type InngestStep, type OrgContext, type OrgRunContext, type OrgRunnerConfig, type PortfolioOrg, type PortfolioRunContext, type PortfolioRunnerConfig, type ProxyResult, type SchedulerConfig, type WebhookVerifyOptions, createOrgRunner, createPortfolioRunner, createScheduler, defineFieldset, executeProxyCall, getEnrolledOrgs, getFieldsetConfig, getOrgContext, getPortfolioOrgs, isEnrolled, recordPublish, setFieldsetConfig, validateDashboardToken, validateWebhookSignature };
+declare class OnbelayClient {
+    private readonly config;
+    constructor(config: OnbelayConfig);
+    executeProxyCall<T = unknown>(orgId: string, integrationSlug: string, operationKey: string, path: string, options?: {
+        method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        body?: Record<string, unknown>;
+        queryParams?: Record<string, string>;
+    }): Promise<ProxyResult<T>>;
+    getOrgContext(orgId: string): Promise<OrgContext>;
+    getFieldsetConfig<T = Record<string, unknown>>(orgId: string): Promise<T>;
+    setFieldsetConfig<T = Record<string, unknown>>(orgId: string, patch: Partial<T>): Promise<void>;
+    recordPublish(orgId: string, contentType: string, metadata?: Record<string, unknown>): Promise<PublishResult>;
+    isEnrolled(orgId: string): Promise<boolean>;
+    getEnrolledOrgs(): Promise<string[]>;
+}
+
+export { type ConnectedIntegration, type ContentType, type DashboardTokenPayload, type EnrolledOrg, OnbelayClient, type OnbelayConfig, OnbelayProtocolError, OnbelayTransportError, type OrgContext, type ProxyErrorCode, type ProxyResult, type PublishResult, type WebhookHandlerContext, type WebhookHandlerOptions, type WebhookPayload, type WebhookResult, type WebhookVerifyOptions, createOnbelayWebhookHandler, executeProxyCall, getEnrolledOrgs, getFieldsetConfig, getOrgContext, isEnrolled, recordPublish, setFieldsetConfig, validateDashboardToken, validateWebhookSignature };