@on-belay/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,531 @@
+/**
+ * @on-belay/sdk — Exported Types
+ *
+ * All types used by fieldset authors are exported from here.
+ * Fieldsets import from "@on-belay/sdk" only — never from platform internals.
+ */
+type ProxyResult = {
+    status: number;
+    data: unknown;
+    blocked?: boolean;
+    error?: string;
+};
+type ConnectedIntegration = {
+    slug: string;
+    status: "active" | "error" | "pending";
+    extraConfig: Record<string, string | null>;
+};
+type OrgContext = {
+    orgId: string;
+    orgName: string;
+    connectedIntegrations: ConnectedIntegration[];
+};
+type PortfolioOrg = {
+    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;
+        }>;
+    };
+    /**
+     * 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.
+     */
+    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. */
+    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. */
+    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>;
+};
+
+/**
+ * @on-belay/sdk — executeProxyCall
+ *
+ * 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.
+ *
+ * Fieldsets never construct AuthResult objects or touch proxy-handler.ts directly.
+ *
+ * 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).
+ */
+
+/**
+ * Execute an authenticated API call to a third-party integration on behalf of an org.
+ *
+ * This is the ONLY way a fieldset may call any external API.
+ *
+ * Dispatches to external HTTP mode when ONBELAY_FIELDSET_TOKEN is set in the environment,
+ * otherwise falls back to direct internal platform imports (monorepo mode).
+ *
+ * @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.
+ */
+declare function executeProxyCall(orgId: string, fieldsetSlug: 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>;
+
+/**
+ * @on-belay/sdk — validateWebhookSignature
+ *
+ * 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.
+ *
+ * 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
+ *   })
+ */
+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)
+ */
+declare function validateWebhookSignature(rawBody: string | Buffer, signatureHeader: string, secret: string, timestamp?: string, options?: WebhookVerifyOptions): boolean;
+
+/**
+ * @on-belay/sdk — validateDashboardToken
+ *
+ * Browser and Node.js compatible JWT verification using jose.
+ * Validates a dashboard context token issued by the On Belay platform.
+ *
+ * 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.
+ *
+ * @param token  - The JWT string received via postMessage from the platform
+ * @param secret - process.env.ONBELAY_DASHBOARD_SECRET
+ */
+declare function validateDashboardToken(token: string, secret: string): Promise<{
+    orgId: string;
+    userId: string;
+    fieldsetSlug: string;
+} | null>;
+
+/**
+ * @on-belay/sdk — getOrgContext
+ *
+ * Returns org name and connected integrations for a given org.
+ * Read-only. Does not expose encrypted fields or credentials.
+ */
+
+/**
+ * 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.
+ */
+declare function getOrgContext(orgId: string): Promise<OrgContext>;
+
+/**
+ * @on-belay/sdk — getFieldsetConfig / setFieldsetConfig
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * @throws If orgId does not exist.
+ */
+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.
+ *
+ * @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.
+ */
+declare function setFieldsetConfig<T = Record<string, unknown>>(orgId: string, fieldsetSlug: string, patch: Partial<T>): Promise<void>;
+
+/**
+ * @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.
+ *
+ * Call at writeback time, NOT at generation time.
+ */
+/**
+ * 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.
+ *
+ * IMPORTANT: Call this at writeback time, not generation time. Billing is
+ * triggered by publish-to-live, not by content generation.
+ *
+ * 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).
+ *
+ * @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.
+ */
+declare function recordPublish(orgId: string, fieldsetSlug: string, contentType: string, metadata?: Record<string, unknown>): Promise<void>;
+
+/**
+ * @on-belay/sdk — isEnrolled / getEnrolledOrgs
+ *
+ * Enrollment state queries for fieldset schedulers and runners.
+ */
+/**
+ * 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.
+ *
+ * Use this inside runners to gate execution. Do NOT use it to gate proxy calls —
+ * the proxy already enforces enrollment.
+ *
+ * @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.
+ *
+ * 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.
+ *
+ * @param fieldsetSlug - The fieldset slug.
+ * @returns Array of org IDs with active enrollment.
+ */
+declare function getEnrolledOrgs(fieldsetSlug: string): Promise<string[]>;
+
+/**
+ * @on-belay/sdk — getPortfolioOrgs
+ *
+ * Returns client orgs for a portfolio (AGENCY) org. Used by portfolio runners
+ * to discover which client orgs to iterate over.
+ */
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @param parentOrgId - The enrolled AGENCY org.
+ * @returns Array of client orgs. Returns [] if no clients — not an error.
+ *
+ * @throws If parentOrgId does not exist.
+ * @throws If parentOrgId resolves to a non-AGENCY org.
+ */
+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.
+ *
+ * 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.
+ */
+
+/**
+ * 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 () => { ... })
+ *   },
+ * })
+ */
+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" },
+ *   ],
+ * })
+ */
+
+/**
+ * Define a fieldset manifest. This is a typed identity function — it returns
+ * the manifest object unchanged but provides TypeScript type checking at
+ * authoring time.
+ *
+ * The platform reads the default export of fieldset.manifest.ts at registration
+ * and enrollment time.
+ */
+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 };