@sprigr/apps-app-sdk 0.1.0

package/README.md

@@ -0,0 +1,10 @@
+# @sprigr/apps-app-sdk
+
+Shared handler types + helpers for apps in this repo.
+
+Scaffold today: just the type contracts the Sprigr wrapper expects. P1 adds:
+
+- `fetchWithRetry` (rate-limit-header-aware, jittered retry)
+- `constantTimeEqual(a, b)` for bearer-secret verification
+- `encodeState` / `decodeState` for OAuth state base64url
+- Anything else extracted from `apps/procore` once it stabilises

package/dist/index.d.ts

@@ -0,0 +1,629 @@
+/**
+ * Crypto helpers for marketplace-app handlers.
+ *
+ * All operations use SubtleCrypto from the Web Crypto API — available in
+ * Cloudflare Workers and Node 20+. No node:crypto imports.
+ */
+/**
+ * Constant-time string compare. Use for bearer-secret / signature
+ * verification — never `a === b` with secrets, that leaks length via
+ * early exit.
+ */
+declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * HMAC-SHA256 → lowercase hex string. Useful for verifying signed
+ * payloads from providers that DO sign (Shopify, Slack, etc.). Procore
+ * does NOT sign webhook bodies — for Procore we mint our own bearer
+ * secret and constant-time-compare.
+ */
+declare function hmacSha256Hex(secret: string, message: string): Promise<string>;
+/**
+ * Cryptographically random hex string. Used for minting webhook
+ * secrets, OAuth state CSRF tokens, etc.
+ */
+declare function randomHex(bytes?: number): string;
+
+/**
+ * OAuth `state` parameter encode / decode.
+ *
+ * Carries a small bag of context (install_id, csrf, target environment,
+ * return URL) through the provider's authorize → callback round trip.
+ * Base64url-encoded JSON so it survives URL encoding without escaping.
+ *
+ * IMPORTANT: state is observable by the user — never include secrets,
+ * tokens, or PII. The CSRF token is the only "secret" and is checked
+ * against the install's pending-flow store, not used to authorize
+ * anything directly.
+ */
+interface OAuthState {
+    /** Sprigr install ID this OAuth flow belongs to. */
+    installId: string;
+    /** Random CSRF token; the callback compares it against the install's stored pending value. */
+    csrf: string;
+    /** Procore environment to use ('prod' | 'sandbox' | 'monthly'). */
+    environment?: string;
+    /** Optional return URL after the flow completes. */
+    returnTo?: string;
+    /** Issued-at — useful for expiring stale state. */
+    iat: number;
+    /**
+     * Sprigr actor initiating the flow — the OIDC sub of the user clicking
+     * "Connect". Used by apps with per-actor OAuth (simPRO) so the callback
+     * knows which actor's token row to write. Absent for apps with one
+     * connection per install (procore, shopify).
+     */
+    actorPlatformUserId?: string;
+    /**
+     * Agent id when the flow was initiated by an unbound agent (no platform
+     * user). Apps that key per-actor state fall back to this when
+     * actorPlatformUserId is absent.
+     */
+    actorAgentId?: string;
+    /**
+     * Per-tenant provider host (e.g. simPRO's `https://acme.simprosuite.com`).
+     * Carried in state so the callback can re-use the same host the start
+     * route validated, without re-querying the user.
+     */
+    buildUrl?: string;
+    /**
+     * Auth method discriminator for providers that support multiple flows
+     * (simPRO: oauth / client_credentials / api_key). Absent for single-
+     * method providers.
+     */
+    authMethod?: string;
+}
+declare function encodeState(state: OAuthState): string;
+declare function decodeState(encoded: string): OAuthState;
+
+/**
+ * fetchWithRetry — rate-limit-header-aware retry wrapper around fetch.
+ *
+ * Retries on:
+ *   - 429 Too Many Requests — honors `Retry-After` (seconds) and
+ *     `X-RateLimit-Reset` (epoch seconds) when present, else
+ *     exponential-backoff with jitter.
+ *   - 5xx — exponential backoff.
+ *   - Network errors (TypeError thrown by fetch) — exponential backoff.
+ *
+ * Does NOT retry: 4xx other than 429 (caller's bug), redirects, 401
+ * (auth — caller decides whether to refresh + retry).
+ */
+interface FetchWithRetryOptions {
+    maxAttempts?: number;
+    /** Base backoff in ms; doubled each attempt and jittered ±30%. */
+    baseBackoffMs?: number;
+    /** Hard cap on total wait across all retries (ms). */
+    maxTotalWaitMs?: number;
+    /** Called with each attempt's failure metadata; useful for logging. */
+    onRetry?: (info: {
+        attempt: number;
+        status: number | null;
+        waitMs: number;
+        reason: string;
+    }) => void;
+}
+declare function fetchWithRetry(input: RequestInfo | URL, init?: RequestInit, opts?: FetchWithRetryOptions): Promise<Response>;
+
+/**
+ * File helpers for marketplace apps that move binary blobs (attachment
+ * upload/download, document fetch). Centralises two foot-guns that bit the
+ * platform's own agent runtime before they were caught:
+ *
+ * 1. Encoding bytes to base64 with `String.fromCharCode(...bytes)` (throws
+ *    `RangeError` past ~64 KB) or a byte-at-a-time `binary += ...` loop
+ *    (O(n^2) — a 15 MB file pegged the isolate and OOM'd it). `bytesToBase64`
+ *    builds the binary string in 32 KB chunks: linear and arity-safe.
+ *
+ * 2. Fetching a caller-supplied URL with no size limit and holding the whole
+ *    body in memory. `fetchFileBytes` enforces a byte ceiling (checks the
+ *    Content-Length header up front AND the materialised body) so an oversized
+ *    file fails fast with a clear error instead of OOMing the worker.
+ *
+ * App workers run under Worker-for-Platforms dispatch with the same ~128 MB
+ * memory ceiling and a ~25-30 s wall as the agent isolate, so the same
+ * discipline applies: never base64 with a byte-at-a-time loop, never pull an
+ * unbounded remote file fully into memory. For files larger than a few MB,
+ * prefer a Sprigr file-proxy URL reference over inline bytes.
+ */
+/** Encode raw bytes as a standard base64 string. */
+declare function bytesToBase64(input: ArrayBuffer | Uint8Array): string;
+/** Decode a base64 string back to bytes. Tolerates embedded whitespace. */
+declare function base64ToBytes(b64: string): Uint8Array;
+/**
+ * Default ceiling for a single file an app pulls into memory. simPRO/Procore
+ * non-segmented uploads are practical only up to a few MB anyway; this leaves
+ * headroom while still refusing the multi-tens-of-MB file that would OOM the
+ * dispatch worker.
+ */
+declare const DEFAULT_MAX_FILE_BYTES: number;
+interface FetchFileResult {
+    bytes: Uint8Array;
+    contentType: string;
+    size: number;
+}
+/**
+ * Fetch a URL into memory with a hard byte ceiling. Throws (with a message the
+ * agent can read) when the file is over `maxBytes`, checking the declared
+ * Content-Length first to avoid even downloading an oversized body when the
+ * server reports its size.
+ *
+ * Use this for any "the app fetches a caller-supplied URL" path — e.g. a
+ * Sprigr file-proxy signed URL passed in lieu of inline base64.
+ */
+declare function fetchFileBytes(url: string, opts?: {
+    maxBytes?: number;
+    init?: RequestInit;
+}): Promise<FetchFileResult>;
+/** Convenience: {@link fetchFileBytes} then base64-encode the result. */
+declare function fetchFileAsBase64(url: string, opts?: {
+    maxBytes?: number;
+    init?: RequestInit;
+}): Promise<{
+    base64: string;
+    contentType: string;
+    size: number;
+}>;
+
+/**
+ * Per-env resolver for the platform webhook host that marketplace
+ * apps use as the callback URL when registering provider webhooks.
+ *
+ * Why this exists:
+ * Every app that registers webhooks with a third-party provider at
+ * OAuth-completion time has to tell the provider "POST inbound events
+ * to <some URL>". For the apps that route through the marketplace
+ * runtime's dispatcher (e.g. shopify -> /webhook/marketplace/{installId}/{topic}),
+ * that URL has to point at the env-correct platform host:
+ *
+ *   - prod    : https://webhooks.sprigr.com
+ *   - staging : https://staging-webhooks.sprigr.com
+ *
+ * The marketplace build-runner already injects this value as
+ * `env.SPRIGR_PLATFORM_BASE` on every per-install WFP upload (platform
+ * build-runner). Apps
+ * just need to read it.
+ *
+ * The bug this prevents:
+ * Hardcoding `'https://webhooks.sprigr.com'` as the default makes a
+ * staging install register prod-pointing webhook subscriptions with
+ * the provider. The provider duly fires events at prod; prod's
+ * platform doesn't know the staging install id, so the webhooks
+ * silently fail (404s land in the *prod* tail, invisible to the
+ * staging operator). The staging chain stays dead until someone
+ * notices the empty inbound queue and traces it back.
+ *
+ * When NOT to use this:
+ * Apps that receive webhooks on their OWN per-install URL (e.g.
+ * procore POSTs to `<procore-XXX.staging-apps.sprigr.com>/api/webhook/procore`)
+ * don't go through the marketplace runtime dispatcher. Those apps
+ * derive the callback URL from the inbound request's `Host` header
+ * instead, which is naturally env-correct. This helper is only for
+ * the marketplace-dispatcher pattern.
+ */
+/**
+ * Minimal env shape this helper reads. Apps' ShopifyEnv /
+ * ProcoreEnv / etc. all extend this; passing the full env is fine.
+ */
+interface PlatformHostEnv {
+    SPRIGR_PLATFORM_BASE?: string;
+}
+/**
+ * Returns the marketplace platform's webhook ingest host for the
+ * current env. Trailing slash is always stripped so callers can
+ * concatenate path segments directly.
+ *
+ *   const base = resolvePlatformWebhookBase(env);
+ *   // staging: "https://staging-webhooks.sprigr.com"
+ *   // prod:    "https://webhooks.sprigr.com"
+ *   const callbackUrl = `${base}/webhook/marketplace/${installId}/${topicPath}`;
+ *
+ * Caller-supplied `override` wins over the env var, useful for
+ * one-off migration scripts and tests.
+ */
+declare function resolvePlatformWebhookBase(env: PlatformHostEnv, override?: string | null): string;
+/**
+ * Convenience wrapper for the most common shape: build the full
+ * marketplace-dispatcher webhook URL for a given install + topic
+ * path.
+ *
+ *   buildMarketplaceWebhookUrl(env, 'inst_abc', 'orders-create')
+ *   // -> "https://staging-webhooks.sprigr.com/webhook/marketplace/inst_abc/orders-create"
+ *
+ * The `topicPath` argument is the manifest path segment (e.g.
+ * `orders-create`, not `orders/create`). Apps that need the slash
+ * form should pre-translate before calling.
+ */
+declare function buildMarketplaceWebhookUrl(env: PlatformHostEnv, installId: string, topicPath: string, override?: string | null): string;
+
+/**
+ * Caller identity stamped by the platform on agent-initiated WFP dispatches.
+ *
+ * Three platform-controlled headers carry the actor on every dispatch:
+ *
+ *   x-sprigr-actor-agent-id           — calling agent's id (always present
+ *                                       when an agent is the caller)
+ *   x-sprigr-actor-platform-user-id   — OIDC sub of the user the agent is
+ *                                       bound to (absent for unbound agents)
+ *   x-sprigr-actor-role               — bound user's display role at the
+ *                                       company; informational only
+ *
+ * The sprigr-wrapper parses these and surfaces an `Actor` via `args.actor`
+ * to handler code. Apps that need per-user scoping (per-actor OAuth tokens,
+ * per-user audit) must read identity from `args.actor` only — body fields
+ * are agent-supplied and spoofable.
+ *
+ * Wired in the platform dispatch wrapper.
+ */
+interface Actor {
+    /** Calling agent's id. Always present when dispatch is agent-initiated. */
+    agentId?: string;
+    /** OIDC sub of the user the agent is bound to. Apps key per-user state on
+     *  this when set; falls back to agentId when the agent has no bound user. */
+    platformUserId?: string;
+    /** Bound user's display role at the company. Display + audit only — apps
+     *  must not gate authorisation on this without server-side verification. */
+    role?: string;
+}
+/**
+ * Parse the platform-stamped actor headers off an incoming request. Returns
+ * undefined when no actor headers are present (webhook receivers, schedule
+ * firers, event consumers — no per-call user). Returns a partial actor when
+ * at least one header is set.
+ *
+ * Apps that require caller identity must treat `undefined` as a hard fail
+ * (return 412 with a clear hint) rather than fall back to install-wide
+ * tokens — see plan risk R13.
+ *
+ *   const actor = parseActor(args);
+ *   if (!actor?.platformUserId && !actor?.agentId) {
+ *     return jsonError(412, 'no_caller_identity');
+ *   }
+ *
+ * Usage: pass the wrapper's `args` object directly. The wrapper writes
+ * `args.actor` from the headers; this helper just narrows the type and
+ * normalises the shape.
+ */
+declare function parseActor(args: unknown): Actor | undefined;
+/**
+ * Stable key for per-actor state in per-install D1. Prefers platformUserId
+ * (durable across agent rebinds) and falls back to agentId for unbound
+ * agents (orchestrator, system).
+ *
+ *   const tokens = await db
+ *     .prepare('SELECT * FROM simpro_actor_tokens WHERE actor_key = ?')
+ *     .bind(actorKey(actor))
+ *     .first();
+ *
+ * Returns null when the actor has neither field set — callers should
+ * treat that as "no caller identity" and fail closed.
+ */
+declare function actorKey(actor: Actor | undefined): string | null;
+
+/**
+ * App-scoped R2 file storage (platform feature, 2026-06).
+ *
+ * Marketplace apps get a contained file store: every key is confined
+ * server-side to `_apps/{installId}/...` so an app can only ever touch
+ * its own files. The app never holds a raw R2 binding — these helpers
+ * call the platform over the same per-install token channel as
+ * `env.SPRIGR.emit` (provisioning `/internal/wfp/file/*`).
+ *
+ * Auth: `Authorization: Bearer <SPRIGR_INSTALL_TOKEN>` against
+ * `<SPRIGR_PLATFORM_BASE>/internal/wfp/file/<op>`. Both bindings are
+ * stamped onto every per-install WFP upload.
+ *
+ * Keys are app-relative (`simpro-files/123.jpg`); the platform adds and
+ * strips the `_apps/{installId}/` prefix, so the app stays unaware of it
+ * and physically cannot escape its namespace.
+ */
+interface AppFilesEnv {
+    SPRIGR_INSTALL_TOKEN?: string;
+    SPRIGR_PLATFORM_BASE?: string;
+}
+interface PutAppFileArgs {
+    /** App-relative key, e.g. "simpro-files/job-1234/55.jpg". */
+    key: string;
+    /** File bytes, base64-encoded. */
+    base64: string;
+    /** MIME type stored as the object's content-type. */
+    contentType?: string;
+    /** Optional display filename. */
+    filename?: string;
+}
+interface PutAppFileResult {
+    ok: true;
+    key: string;
+    bytes: number;
+    contentType: string;
+}
+interface PutAppFileStreamArgs {
+    /** App-relative key, e.g. "simpro-files/job-1234/55.jpg". */
+    key: string;
+    /**
+     * Raw file bytes. A `ReadableStream` is piped straight through to R2 so
+     * the bytes never fully materialise in the app isolate — use it for large
+     * blobs (full-res photos, PDFs). An `ArrayBuffer`/`Uint8Array` is also
+     * accepted when the bytes are already in hand.
+     */
+    body: ReadableStream<Uint8Array> | ArrayBuffer | Uint8Array;
+    /** MIME type stored as the object's content-type. */
+    contentType?: string;
+    /** Optional display filename. */
+    filename?: string;
+    /**
+     * Declared byte length. Forward it when known (e.g. the source's
+     * Content-Length) so the platform can enforce its size cap before opening
+     * the R2 write. Streamed bodies carry no Content-Length, so this is the
+     * only length signal the platform gets. Omit for unknown-length streams.
+     */
+    contentLength?: number;
+}
+interface AppFileUrlArgs {
+    key: string;
+    /** Seconds the signed URL stays valid (default 24h, min 60s, max ~10y, clamped server-side). */
+    expiresIn?: number;
+}
+interface AppFileUrlResult {
+    ok: true;
+    url: string;
+    expires_at: number;
+    key: string;
+}
+interface GetAppFileResult {
+    ok: true;
+    key: string;
+    base64: string;
+    contentType: string;
+    filename?: string;
+    bytes: number;
+}
+interface AppFileListItem {
+    key: string;
+    bytes: number;
+    uploaded?: string;
+    filename?: string;
+    contentType?: string;
+}
+/** Store bytes in the app's contained R2 namespace (base64 JSON). */
+declare function putAppFile(env: AppFilesEnv, args: PutAppFileArgs): Promise<PutAppFileResult>;
+/**
+ * Store bytes by streaming the raw body straight into the app's contained
+ * R2 namespace. Unlike `putAppFile`, this never base64-encodes the bytes
+ * and (with a `ReadableStream` body) never buffers them whole in the
+ * isolate — pipe a source `Response.body` directly through for multi-MB
+ * blobs. Metadata travels in headers; the body is opaque bytes.
+ */
+declare function putAppFileStream(env: AppFilesEnv, args: PutAppFileStreamArgs): Promise<PutAppFileResult>;
+/** Mint a signed, time-limited download URL for an app file. */
+declare function appFileUrl(env: AppFilesEnv, args: AppFileUrlArgs): Promise<AppFileUrlResult>;
+/** Read an app file back as base64. */
+declare function getAppFile(env: AppFilesEnv, key: string): Promise<GetAppFileResult>;
+/** List app files under an optional app-relative prefix. */
+declare function listAppFiles(env: AppFilesEnv, prefix?: string): Promise<{
+    ok: true;
+    files: AppFileListItem[];
+    truncated: boolean;
+}>;
+/** Delete an app file. */
+declare function deleteAppFile(env: AppFilesEnv, key: string): Promise<{
+    ok: true;
+    key: string;
+}>;
+
+/**
+ * @sprigr/apps-app-sdk
+ *
+ * Shared types and helpers for marketplace-app handlers in this repo.
+ */
+
+/**
+ * Identifies the upstream third-party integration that sourced a
+ * bridged marketplace event. Apps that wrap a provider webhook
+ * (Shopify orders, Procore RFI updates, ...) stamp this on each
+ * emit so subscribers can call write-backs through the platform's
+ * per-integration forwarder.
+ *
+ * Mirrors the platform-side `MarketplaceEventSourceIntegration`
+ * type in the Sprigr platform source. Keep
+ * the field set + nullability in sync — the queue-consumer's
+ * marketplace-event-handler reads these unconditionally on the
+ * dispatch path, so a missing `integrationId` or `integrationType`
+ * is a hard error (400 from /internal/wfp/emit).
+ */
+interface MarketplaceEventSourceIntegration {
+    /** Stable identifier for the source integration. For marketplace-
+     *  bridged events, this is typically the source app's INSTALL_ID. */
+    integrationId: string;
+    /** Integration type / slug (e.g. 'shopify'). Matches the manifest's
+     *  `integration_dependencies[].integration_type` so the platform
+     *  forwarder can route write-backs by type. */
+    integrationType: string;
+    /** Optional human-friendly identifier (e.g. Shopify shop domain
+     *  `brand-a.myshopify.com`). Useful for app-side logging / display;
+     *  use `integrationId` for routing. */
+    shopDomain?: string;
+    /** Opaque service key the marketplace app supplied when it
+     *  registered a FulfillmentService (or equivalent per-resource
+     *  partition). Set ONLY when the event is scoped to one
+     *  registration; absent for shop-wide events. */
+    fulfillmentServiceKey?: string;
+}
+/**
+ * Optional metadata forwarded with `env.SPRIGR.emit`. The platform-
+ * side `/internal/wfp/emit` endpoint passes each field through to
+ * `emitMarketplaceEvent`.
+ */
+interface MarketplaceEventEmitOpts {
+    /** Stable identifier for the source integration; see
+     *  MarketplaceEventSourceIntegration. */
+    sourceIntegration?: MarketplaceEventSourceIntegration;
+    /** Pin delivery to a single install in the receiving tenant.
+     *  Omit for broadcast (the default). */
+    targetAppInstallationId?: string;
+    /** Reserved for future at-least-once dedup. Apps can set it now;
+     *  the platform stores it but doesn't enforce dedup yet. */
+    dedupId?: string;
+}
+/**
+ * Options for `env.SPRIGR.data.search`. Mirrors the platform's
+ * /internal/wfp/data/search body (the platform provisioning worker). All fields optional; an
+ * empty call returns the first page of everything.
+ */
+interface SprigrDataSearchOpts {
+    /** Full-text query. Combine with `semantic: true` for hybrid search. */
+    query?: string;
+    /** Facet filter string, e.g. 'status:active,type:customer'. */
+    filters?: string;
+    /** Hybrid keyword + vector search. Best for fuzzy human references. */
+    semantic?: boolean;
+    /** Sort expression, e.g. 'updatedAt:desc'. */
+    sortBy?: string;
+    /** Facet names to count in the response. */
+    facets?: string[];
+    /** Restrict returned fields to keep responses lean. */
+    attributesToRetrieve?: string[];
+    /** Zero-based page. Default 0. */
+    page?: number;
+    /** Results per page. Default 20, platform-clamped to 100. */
+    hitsPerPage?: number;
+}
+interface SprigrDataSearchResult {
+    ok: boolean;
+    hits: Array<{
+        objectID: string;
+        [key: string]: unknown;
+    }>;
+    nbHits: number;
+    page: number;
+    facetCounts?: Record<string, Record<string, number>>;
+    /** The private index that was queried (informational). */
+    index: string;
+}
+/**
+ * The marketplace install's PRIVATE per-company datastore: a Sprigr
+ * index named `<companyId>-app-<slug>`, reachable only through these
+ * methods (agents have no direct index access). Injected on
+ * `env.SPRIGR` by the platform wrapper for /__sprigr/* dispatch.
+ *
+ * Intended pattern: the app syncs lean provider objects via `import`,
+ * its tool handlers call `search` to resolve a fuzzy human reference
+ * ("customer Joe Bloggs") to an entity ID, then fetch live detail from
+ * the provider REST API by that ID. The index is a resolver, not a
+ * cache of record.
+ */
+interface SprigrDataApi {
+    /**
+     * Upsert objects into the private index. Each object MUST carry a
+     * unique string `objectID`. The index is auto-created on first
+     * import from the manifest's `data_index` settings; re-imports
+     * upsert by objectID. Max 1000 objects per call.
+     */
+    import(objects: Array<{
+        objectID: string;
+        [key: string]: unknown;
+    }>): Promise<{
+        ok: boolean;
+        indexed: number;
+        index: string;
+    }>;
+    /**
+     * Search the private index. A never-imported index yields an empty
+     * hit list, not an error.
+     */
+    search(opts?: SprigrDataSearchOpts): Promise<SprigrDataSearchResult>;
+    /** Fetch one object by objectID. `object` is null when absent. */
+    get(objectID: string): Promise<{
+        ok: boolean;
+        object: Record<string, unknown> | null;
+        index: string;
+    }>;
+}
+/**
+ * Durable app file storage exposed on `env.SPRIGR.files` by the platform
+ * wrapper (the platform build-runner). Persists bytes into the install's
+ * contained R2 namespace (every key is confined server-side to
+ * `_apps/{installId}/...`, so an app can only ever touch its own files) and
+ * mints signed, time-limited download URLs.
+ *
+ * Use it to re-host an ephemeral third-party asset (e.g. a provider render
+ * URL the upstream deletes after a short retention window) so the URL your
+ * app hands back keeps resolving.
+ *
+ * This is the in-isolate bridge surface, injected on `env.SPRIGR` for
+ * `/__sprigr/*` tool / webhook / event handlers. The standalone
+ * `putAppFileStream` / `appFileUrl` helpers in this package call the same
+ * `/internal/wfp/file/*` endpoints over HTTP for code that runs outside the
+ * injected bridge (e.g. inline Next.js route handlers).
+ */
+interface SprigrFilesApi {
+    /**
+     * Stream bytes into the app's store under `key` (app-relative; the platform
+     * adds/strips the `_apps/{installId}/` prefix). A `ReadableStream` is piped
+     * straight through to R2 without buffering whole in the isolate, so use it
+     * for multi-MB blobs (videos, full-res photos, PDFs). Size cap: 50 MB.
+     * `opts.length` declares the byte length so the platform can enforce the cap
+     * before opening the write; forward it for streamed bodies, which carry no
+     * Content-Length (`bytes` comes back `null` when it is omitted).
+     */
+    putStream(key: string, body: ReadableStream | ArrayBuffer | Uint8Array | string, opts?: {
+        contentType?: string;
+        length?: number;
+        filename?: string;
+    }): Promise<{
+        ok: boolean;
+        key: string;
+        bytes: number | null;
+        contentType: string;
+    }>;
+    /**
+     * Mint a signed, time-limited download URL for a previously-stored `key`.
+     * `opts.expiresIn` is seconds, clamped server-side (default 24h, min 60s,
+     * max ~10y). The URL expires, so re-mint on demand rather than caching it.
+     */
+    url(key: string, opts?: {
+        expiresIn?: number;
+    }): Promise<{
+        ok: boolean;
+        url: string;
+        expires_at: number;
+        key: string;
+    }>;
+}
+/** Narrow structural type for the per-install D1 binding. */
+interface D1Like {
+    prepare(sql: string): D1PreparedStatementLike;
+}
+interface D1PreparedStatementLike {
+    bind(...args: unknown[]): D1PreparedStatementLike;
+    run(): Promise<unknown>;
+    first<T = unknown>(): Promise<T | null>;
+    all<T = unknown>(): Promise<{
+        results: T[];
+    }>;
+}
+interface WebhookArgs {
+    body: string;
+    signature?: string;
+    headers?: Record<string, string>;
+}
+interface ScheduleArgs {
+    name: string;
+    scheduled_at?: string;
+}
+interface EventArgs {
+    event: string;
+    payload: unknown;
+    eventId: string;
+}
+/**
+ * ExecutionContext shape narrowed to what most handlers need
+ * (`waitUntil` for fire-and-forget tasks). Keeps the type usable
+ * without depending on @cloudflare/workers-types here.
+ */
+interface ExecutionContextLike {
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException?(): void;
+}
+type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
+
+export { type Actor, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type D1Like, type D1PreparedStatementLike, DEFAULT_MAX_FILE_BYTES, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, type OAuthState, type PlatformHostEnv, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ScheduleArgs, type SprigrDataApi, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type WebhookArgs, actorKey, appFileUrl, base64ToBytes, buildMarketplaceWebhookUrl, bytesToBase64, constantTimeEqual, decodeState, deleteAppFile, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, listAppFiles, parseActor, putAppFile, putAppFileStream, randomHex, resolvePlatformWebhookBase };

package/dist/index.js

@@ -0,0 +1,298 @@
+// src/crypto.ts
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+async function hmacSha256Hex(secret, message) {
+  const keyData = new TextEncoder().encode(secret);
+  const msgData = new TextEncoder().encode(message);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sigBuf = await crypto.subtle.sign("HMAC", key, msgData);
+  return [...new Uint8Array(sigBuf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function randomHex(bytes = 32) {
+  const arr = new Uint8Array(bytes);
+  crypto.getRandomValues(arr);
+  return [...arr].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/state.ts
+function base64urlEncode(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecode(input) {
+  const padded = input.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((input.length + 3) % 4);
+  const bin = atob(padded);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function encodeState(state) {
+  const json = JSON.stringify(state);
+  return base64urlEncode(new TextEncoder().encode(json));
+}
+function decodeState(encoded) {
+  const bytes = base64urlDecode(encoded);
+  const json = new TextDecoder().decode(bytes);
+  return JSON.parse(json);
+}
+
+// src/fetch.ts
+var DEFAULT_OPTS = {
+  maxAttempts: 4,
+  baseBackoffMs: 500,
+  maxTotalWaitMs: 3e4
+};
+async function fetchWithRetry(input, init, opts = {}) {
+  const cfg = { ...DEFAULT_OPTS, ...opts };
+  let totalWait = 0;
+  let lastError = null;
+  for (let attempt = 1; attempt <= cfg.maxAttempts; attempt++) {
+    try {
+      const resp = await fetch(input, init);
+      if (resp.status === 429 || resp.status >= 500) {
+        if (attempt === cfg.maxAttempts) return resp;
+        const wait = waitForResponse(resp, attempt, cfg);
+        if (totalWait + wait > cfg.maxTotalWaitMs) return resp;
+        opts.onRetry?.({ attempt, status: resp.status, waitMs: wait, reason: resp.status === 429 ? "rate_limited" : "server_error" });
+        await sleep(wait);
+        totalWait += wait;
+        continue;
+      }
+      return resp;
+    } catch (err) {
+      lastError = err;
+      if (attempt === cfg.maxAttempts) throw err;
+      const wait = expBackoff(attempt, cfg.baseBackoffMs);
+      if (totalWait + wait > cfg.maxTotalWaitMs) throw err;
+      opts.onRetry?.({ attempt, status: null, waitMs: wait, reason: "network_error" });
+      await sleep(wait);
+      totalWait += wait;
+    }
+  }
+  throw lastError ?? new Error("fetchWithRetry exhausted");
+}
+function waitForResponse(resp, attempt, cfg) {
+  const retryAfter = resp.headers.get("retry-after");
+  if (retryAfter) {
+    const seconds = parseInt(retryAfter, 10);
+    if (!Number.isNaN(seconds) && seconds > 0) return seconds * 1e3;
+  }
+  const reset = resp.headers.get("x-ratelimit-reset");
+  if (reset) {
+    const resetEpoch = parseInt(reset, 10);
+    if (!Number.isNaN(resetEpoch)) {
+      const waitMs = resetEpoch * 1e3 - Date.now();
+      if (waitMs > 0 && waitMs < 6e4) return waitMs;
+    }
+  }
+  return expBackoff(attempt, cfg.baseBackoffMs);
+}
+function expBackoff(attempt, base) {
+  const expo = base * Math.pow(2, attempt - 1);
+  const jitter = 0.7 + Math.random() * 0.6;
+  return Math.floor(expo * jitter);
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/file.ts
+var CHUNK = 32768;
+function bytesToBase64(input) {
+  const u8 = input instanceof Uint8Array ? input : new Uint8Array(input);
+  let binary = "";
+  for (let i = 0; i < u8.length; i += CHUNK) {
+    binary += String.fromCharCode.apply(
+      null,
+      u8.subarray(i, i + CHUNK)
+    );
+  }
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const binary = atob(b64.replace(/\s/g, ""));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+var DEFAULT_MAX_FILE_BYTES = 20 * 1024 * 1024;
+async function fetchFileBytes(url, opts = {}) {
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_FILE_BYTES;
+  const res = await fetch(url, opts.init);
+  if (!res.ok) {
+    throw new Error(`fetchFileBytes: HTTP ${res.status} fetching file URL`);
+  }
+  const declared = Number(res.headers.get("content-length") || "");
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    throw new Error(
+      `fetchFileBytes: file is ${declared} bytes, over the ${maxBytes}-byte cap \u2014 use a smaller file or a segmented upload`
+    );
+  }
+  const buf = await res.arrayBuffer();
+  if (buf.byteLength > maxBytes) {
+    throw new Error(
+      `fetchFileBytes: file is ${buf.byteLength} bytes, over the ${maxBytes}-byte cap \u2014 use a smaller file or a segmented upload`
+    );
+  }
+  const contentType = res.headers.get("content-type")?.split(";")[0]?.trim() || "application/octet-stream";
+  return { bytes: new Uint8Array(buf), contentType, size: buf.byteLength };
+}
+async function fetchFileAsBase64(url, opts = {}) {
+  const { bytes, contentType, size } = await fetchFileBytes(url, opts);
+  return { base64: bytesToBase64(bytes), contentType, size };
+}
+
+// src/platform-host.ts
+var FALLBACK_PLATFORM_BASE = "https://webhooks.sprigr.com";
+function resolvePlatformWebhookBase(env, override) {
+  const raw = (override ?? env.SPRIGR_PLATFORM_BASE ?? FALLBACK_PLATFORM_BASE).trim();
+  return raw.replace(/\/$/, "");
+}
+function buildMarketplaceWebhookUrl(env, installId, topicPath, override) {
+  const base = resolvePlatformWebhookBase(env, override);
+  return `${base}/webhook/marketplace/${installId}/${topicPath}`;
+}
+
+// src/actor.ts
+function parseActor(args) {
+  if (!args || typeof args !== "object") return void 0;
+  const a = args.actor;
+  if (!a || typeof a !== "object") return void 0;
+  const obj = a;
+  const out = {};
+  if (typeof obj.agentId === "string" && obj.agentId.length > 0) out.agentId = obj.agentId;
+  if (typeof obj.platformUserId === "string" && obj.platformUserId.length > 0) {
+    out.platformUserId = obj.platformUserId;
+  }
+  if (typeof obj.role === "string" && obj.role.length > 0) out.role = obj.role;
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function actorKey(actor) {
+  if (!actor) return null;
+  if (actor.platformUserId) return `u:${actor.platformUserId}`;
+  if (actor.agentId) return `a:${actor.agentId}`;
+  return null;
+}
+
+// src/app-files.ts
+var DEFAULT_PLATFORM_BASE = "https://webhooks.sprigr.com";
+function platformBase(env) {
+  return (env.SPRIGR_PLATFORM_BASE ?? DEFAULT_PLATFORM_BASE).trim().replace(/\/+$/, "");
+}
+var AppFilesError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "AppFilesError";
+    this.status = status;
+  }
+};
+function requireToken(env) {
+  const token = env.SPRIGR_INSTALL_TOKEN;
+  if (!token) {
+    throw new AppFilesError("app file storage unavailable: SPRIGR_INSTALL_TOKEN unset", 500);
+  }
+  return token;
+}
+async function parseResult(res, op) {
+  const text = await res.text();
+  let parsed = void 0;
+  try {
+    parsed = text ? JSON.parse(text) : void 0;
+  } catch {
+  }
+  if (!res.ok) {
+    const detail = parsed && typeof parsed === "object" ? parsed.hint ?? parsed.detail ?? parsed.error : text.slice(0, 200);
+    throw new AppFilesError(`app file ${op} failed (${res.status}): ${String(detail)}`, res.status);
+  }
+  return parsed;
+}
+async function call(env, op, body) {
+  const token = requireToken(env);
+  const res = await fetch(`${platformBase(env)}/internal/wfp/file/${op}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(body ?? {})
+  });
+  return parseResult(res, op);
+}
+function putAppFile(env, args) {
+  return call(env, "put", {
+    key: args.key,
+    base64: args.base64,
+    contentType: args.contentType,
+    filename: args.filename
+  });
+}
+async function putAppFileStream(env, args) {
+  const token = requireToken(env);
+  const headers = {
+    authorization: `Bearer ${token}`,
+    "content-type": args.contentType || "application/octet-stream",
+    "x-app-file-key": args.key,
+    "x-app-file-content-type": args.contentType || "application/octet-stream"
+  };
+  if (args.filename) headers["x-app-file-name"] = encodeURIComponent(args.filename);
+  if (typeof args.contentLength === "number" && Number.isFinite(args.contentLength)) {
+    headers["x-app-file-length"] = String(args.contentLength);
+  }
+  const res = await fetch(`${platformBase(env)}/internal/wfp/file/put-stream`, {
+    method: "POST",
+    headers,
+    body: args.body,
+    // Required by the Workers runtime when sending a streaming request body.
+    ...args.body instanceof ReadableStream ? { duplex: "half" } : {}
+  });
+  return parseResult(res, "put-stream");
+}
+function appFileUrl(env, args) {
+  return call(env, "url", { key: args.key, expiresIn: args.expiresIn });
+}
+function getAppFile(env, key) {
+  return call(env, "get", { key });
+}
+function listAppFiles(env, prefix) {
+  return call(env, "list", { prefix });
+}
+function deleteAppFile(env, key) {
+  return call(env, "delete", { key });
+}
+export {
+  DEFAULT_MAX_FILE_BYTES,
+  actorKey,
+  appFileUrl,
+  base64ToBytes,
+  buildMarketplaceWebhookUrl,
+  bytesToBase64,
+  constantTimeEqual,
+  decodeState,
+  deleteAppFile,
+  encodeState,
+  fetchFileAsBase64,
+  fetchFileBytes,
+  fetchWithRetry,
+  getAppFile,
+  hmacSha256Hex,
+  listAppFiles,
+  parseActor,
+  putAppFile,
+  putAppFileStream,
+  randomHex,
+  resolvePlatformWebhookBase
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@sprigr/apps-app-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist --clean --tsconfig tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20240909.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sprigr/sprigr-app-kit.git",
+    "directory": "packages/app-sdk"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}