@sprigr/apps-app-sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,10 +1,31 @@
 # @sprigr/apps-app-sdk
 
-Shared handler types + helpers for apps in this repo.
+Shared handler types + helpers for Sprigr marketplace apps.
 
-Scaffold today: just the type contracts the Sprigr wrapper expects. P1 adds:
+```bash
+npm install @sprigr/apps-app-sdk
+```
 
-- `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
+## Talking to the platform
+
+The runtime injects the `env.SPRIGR` host object **only on `/__sprigr/*` dispatch paths** (tool, schedule, event and platform-webhook handlers). Inline Next.js route handlers never get it, so an app that receives its provider webhook on an inline route has no working `env.SPRIGR` on the path that matters most.
+
+- `emitMarketplaceEvent(env, event, payload, opts?)` — emit from either context. Uses the injected binding when present, the install-token bridge (`POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/emit`) otherwise. Never throws, so a webhook ack is never at risk; times out after 5s. Returns `{ emitted, via: 'binding' | 'http' | 'none', eventId?, error? }` — record `via` in your audit row.
+- `withSprigrEmitFallback(env)` — repair `env.SPRIGR.emit` once and leave existing call sites untouched. Matches the host object's contract (resolves `{ ok, eventId, queued }`, throws on non-2xx).
+- `resolveInstallBridge(env)` / `installTokenPost(bridge, path, body, opts?)` — build your own `/internal/wfp/*` fallback (collections, files, inbox) with the auth and error extraction handled.
+- `overlaySprigr(env, sprigr)` — overlay a patched `SPRIGR` via `Object.create`. Never rebuild a dispatch-path env by spread: the real bindings live on the prototype and `SPRIGR` is non-enumerable, so `{ ...env }` yields an env whose `DB` is `undefined`.
+
+## Webhook callback URLs
+
+- `resolvePlatformWebhookBase(env)` / `buildMarketplaceWebhookUrl(env, installId, topicPath)` — env-correct platform host, so a staging install never registers prod-pointing subscriptions.
+
+## Misc
+
+- `fetchWithRetry` — rate-limit-header-aware, jittered retry
+- `constantTimeEqual(a, b)` — bearer-secret verification
+- `encodeState` / `decodeState` — OAuth state base64url
+- `parseActor` / `actorKey` — per-actor token scoping
+- `putAppFile` / `putAppFileStream` / `appFileUrl` / `getAppFile` / `listAppFiles` / `deleteAppFile` — durable app-scoped file storage from outside the injected bridge
+- `fetchFileBytes` / `fetchFileAsBase64` / `bytesToBase64` / `base64ToBytes` — file byte helpers
+
+Full platform semantics: [`docs/platform-reference.md`](../../docs/platform-reference.md).

package/dist/index.d.ts

@@ -235,6 +235,150 @@ declare function resolvePlatformWebhookBase(env: PlatformHostEnv, override?: str
  */
 declare function buildMarketplaceWebhookUrl(env: PlatformHostEnv, installId: string, topicPath: string, override?: string | null): string;
 
+/**
+ * Talking to the platform from BOTH execution contexts.
+ *
+ * The marketplace runtime injects the `SPRIGR` host object **only on
+ * `/__sprigr/*` dispatch paths** (tool, schedule, event and platform-webhook
+ * handlers). Inline Next.js route handlers (`app/api/.../route.ts`) never
+ * receive it. Any app whose provider webhook lands on an inline route (because
+ * the provider doesn't HMAC bodies, so the marketplace dispatcher can't verify
+ * the delivery) therefore has NO working `env.SPRIGR` on the one path that
+ * matters most.
+ *
+ * An app that only tries `env.SPRIGR.emit` from there emits nothing at all,
+ * silently, while still acking the provider 200. That has now shipped four
+ * separate times (shopify #478, procore, starshipit, cin7-core), so the fix
+ * lives here instead of being re-derived per app.
+ *
+ * The escape hatch: `SPRIGR_PLATFORM_BASE` and `SPRIGR_INSTALL_TOKEN` are plain
+ * script vars stamped on every per-install WFP upload, so unlike `SPRIGR` they
+ * ARE readable from an inline route. With them you can call the same
+ * `/internal/wfp/*` endpoints the host object calls under the covers:
+ *
+ *   POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/emit
+ *   Authorization: Bearer ${SPRIGR_INSTALL_TOKEN}
+ *   { event, payload, sourceIntegration?, targetAppInstallationId?, dedupId? }
+ *
+ * Use `emitMarketplaceEvent` for a single call site, or `withSprigrEmitFallback`
+ * to repair `env.SPRIGR.emit` once and leave existing call sites untouched.
+ */
+
+/** Resolved per-install bridge credentials. */
+interface InstallBridge {
+    /** Platform base, trailing slash stripped. */
+    base: string;
+    /** Per-install bearer, `<installId>.<base64url-hmac>`. */
+    token: string;
+}
+/**
+ * Minimal env shape these helpers read. Every app's own env interface
+ * (ProcoreEnv, ShopifyEnv, ...) already satisfies it structurally, so passing
+ * the full env is fine.
+ */
+interface WfpBridgeEnv {
+    SPRIGR?: unknown;
+    SPRIGR_PLATFORM_BASE?: string;
+    SPRIGR_INSTALL_TOKEN?: string;
+    INSTALL_ID?: string;
+    [key: string]: unknown;
+}
+/**
+ * Pull the install-token bridge off env, or null when either half is missing.
+ *
+ * Deliberately has NO production default for the base: an app that guessed
+ * `https://webhooks.sprigr.com` would have a *staging* install firing events
+ * into *prod*, where the install id is unknown and the call 404s into a tail
+ * nobody watching staging ever reads. Failing closed is louder.
+ */
+declare function resolveInstallBridge(env: WfpBridgeEnv): InstallBridge | null;
+/**
+ * Human-readable note about which half of the bridge is missing. Which binding
+ * is absent is the entire diagnosis, so never collapse this to a bare
+ * "not configured".
+ */
+declare function describeMissingBridge(env: WfpBridgeEnv): string;
+/**
+ * Overlay a replacement `SPRIGR` onto env WITHOUT rebuilding it by spread.
+ *
+ * On the `/__sprigr/*` dispatch path the platform hands handlers
+ * `Object.create(bindings)` with `SPRIGR` as a NON-ENUMERABLE own property: the
+ * real bindings (`DB`, secrets, the install token itself) live on the
+ * prototype. `{ ...env }` copies none of that — it yields an env whose `DB` is
+ * undefined. That is exactly how every scheduled `ms_index_files` run died for
+ * 24h on staging (microsoft-365 v0.12.0, fixed in v0.14.2, #758). Chaining off
+ * env via the prototype preserves whatever shape the caller had, plain or
+ * wrapped.
+ */
+declare function overlaySprigr<E extends object>(env: E, sprigr: unknown): E;
+/** Reply shape of `/internal/wfp/emit`. */
+interface WfpEmitReply {
+    ok?: boolean;
+    eventId?: string;
+    /** False when the platform accepted the call but the enqueue itself failed. */
+    queued?: boolean;
+    error?: string;
+}
+/** How the emit reached the platform. `none` means it never left. */
+type EmitTransport = 'binding' | 'http' | 'none';
+interface EmitResult {
+    emitted: boolean;
+    eventId?: string;
+    /** Which transport carried it. Worth recording in an audit row: it makes the
+     *  binding silently disappearing again visible without a redeploy. */
+    via: EmitTransport;
+    error?: string;
+}
+/** Default ceiling on the platform call. A webhook ack matters more than the
+ *  event: providers retry a failed delivery, and a slow emit must never turn
+ *  the ack into a non-2xx. */
+declare const DEFAULT_EMIT_TIMEOUT_MS = 5000;
+interface EmitMarketplaceEventOptions extends MarketplaceEventEmitOpts {
+    /** Override the 5s ceiling on the HTTP fallback. */
+    timeoutMs?: number;
+}
+/**
+ * POST a JSON body to an `/internal/wfp/*` endpoint with the install-token
+ * bearer. Returns the parsed reply and throws on a non-2xx, matching what the
+ * injected host object does, so callers can treat both paths identically.
+ *
+ * Shared by every install-token fallback (emit, inbox, collections, files) so
+ * the auth header and error-detail extraction live in exactly one place.
+ */
+declare function installTokenPost(bridge: InstallBridge, path: string, body: unknown, opts?: {
+    label?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<Record<string, unknown>>;
+/**
+ * Emit a marketplace event from any execution context, never throwing.
+ *
+ * Prefers the injected `env.SPRIGR.emit`; falls back to the install-token
+ * bridge when it is absent (i.e. on an inline Next route). Safe to call from a
+ * webhook receiver: every failure is reported in the result rather than raised,
+ * so the provider ack is never at risk.
+ *
+ *   const r = await emitMarketplaceEvent(env, 'procore.rfi.updated', payload, {
+ *     sourceIntegration: { integrationId: env.INSTALL_ID, integrationType: 'procore' },
+ *   });
+ *   await audit(env, 'emit', JSON.stringify(r));   // records `via`
+ */
+declare function emitMarketplaceEvent(env: WfpBridgeEnv, event: string, payload: unknown, opts?: EmitMarketplaceEventOptions): Promise<EmitResult>;
+/**
+ * Return an env whose `SPRIGR.emit` works even on an inline route, leaving
+ * existing `env.SPRIGR.emit(...)` call sites untouched. Use this when an app
+ * emits from many places; use `emitMarketplaceEvent` for a single call site.
+ *
+ * The installed `emit` matches the injected host object's contract: it resolves
+ * `{ ok, eventId, queued }` and THROWS on a non-2xx, so existing
+ * `queued === false` checks and try/catch blocks keep working unchanged.
+ *
+ * When the bindings are absent the env is returned as-is (`SPRIGR` stays
+ * undefined) so callers fail the same way they already do rather than
+ * discovering a new shape.
+ */
+declare function withSprigrEmitFallback<E extends WfpBridgeEnv & object>(env: E): E;
+
 /**
  * Caller identity stamped by the platform on agent-initiated WFP dispatches.
  *
@@ -601,12 +745,17 @@ interface SprigrFilesEditInput {
     /** App-relative key of the source file already in app storage. */
     file_key: string;
     /** pdf runs the PyMuPDF ops engine (list_fields / fill_form / replace_text);
-     *  docx/xlsx run python-docx / openpyxl. */
-    format: 'docx' | 'xlsx' | 'pdf';
+     *  docx/xlsx run python-docx / openpyxl; xer/pmxml/mspdi run the platform's
+     *  pure-TS schedule engine in-worker (Primavera P6 / MS Project XML, no
+     *  sandbox cold-start exposure). */
+    format: 'docx' | 'xlsx' | 'pdf' | 'xer' | 'pmxml' | 'mspdi';
     operations: Array<Record<string, unknown>>;
     output_filename?: string;
     output_key?: string;
     allow_lossy?: boolean;
+    /** Schedule formats only: write even when the FK-integrity gate finds
+     *  errors (the validation result is still returned). */
+    skip_validation?: boolean;
     /** Deterministic idempotency token: the platform persists the pipeline's
      *  terminal result under it, so a retry of the same logical edit after a
      *  dispatch timeout replays the finished result instead of re-running the
@@ -622,6 +771,10 @@ interface SprigrFilesEditResult {
     failed_operations?: Array<Record<string, unknown>>;
     warning?: string;
     error?: string;
+    /** Schedule formats only: the FK-integrity result ({errorCount, warningCount, issues}). */
+    validation?: Record<string, unknown>;
+    /** Schedule formats only: one-line engine summary incl. matched counts. */
+    summary?: string;
 }
 /** Input to `env.SPRIGR.files.create` (build a NEW docx/xlsx from a spec). */
 interface SprigrFilesCreateInput {
@@ -700,4 +853,4 @@ interface ExecutionContextLike {
 }
 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 SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type WebhookArgs, actorKey, appFileUrl, base64ToBytes, buildMarketplaceWebhookUrl, bytesToBase64, constantTimeEqual, decodeState, deleteAppFile, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, listAppFiles, parseActor, putAppFile, putAppFileStream, randomHex, resolvePlatformWebhookBase };
+export { type Actor, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InstallBridge, 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 SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, appFileUrl, base64ToBytes, buildMarketplaceWebhookUrl, bytesToBase64, constantTimeEqual, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, installTokenPost, listAppFiles, overlaySprigr, parseActor, putAppFile, putAppFileStream, randomHex, resolveInstallBridge, resolvePlatformWebhookBase, withSprigrEmitFallback };

package/dist/index.js

@@ -166,6 +166,116 @@ function buildMarketplaceWebhookUrl(env, installId, topicPath, override) {
   return `${base}/webhook/marketplace/${installId}/${topicPath}`;
 }
 
+// src/wfp-bridge.ts
+function resolveInstallBridge(env) {
+  const token = typeof env.SPRIGR_INSTALL_TOKEN === "string" ? env.SPRIGR_INSTALL_TOKEN : "";
+  const base = typeof env.SPRIGR_PLATFORM_BASE === "string" ? env.SPRIGR_PLATFORM_BASE.replace(/\/+$/, "") : "";
+  if (!token || !base) return null;
+  return { base, token };
+}
+function describeMissingBridge(env) {
+  const base = typeof env.SPRIGR_PLATFORM_BASE === "string" && env.SPRIGR_PLATFORM_BASE ? "set" : "unset";
+  const token = typeof env.SPRIGR_INSTALL_TOKEN === "string" && env.SPRIGR_INSTALL_TOKEN ? "set" : "unset";
+  return `no_emit_path (SPRIGR unbound, SPRIGR_PLATFORM_BASE=${base}, SPRIGR_INSTALL_TOKEN=${token})`;
+}
+function overlaySprigr(env, sprigr) {
+  const out = Object.create(env);
+  Object.defineProperty(out, "SPRIGR", { value: sprigr, enumerable: false, configurable: false });
+  return out;
+}
+var DEFAULT_EMIT_TIMEOUT_MS = 5e3;
+function compactOpts(opts) {
+  const out = {};
+  if (!opts) return out;
+  if (opts.sourceIntegration !== void 0) out.sourceIntegration = opts.sourceIntegration;
+  if (opts.targetAppInstallationId !== void 0) out.targetAppInstallationId = opts.targetAppInstallationId;
+  if (opts.dedupId !== void 0) out.dedupId = opts.dedupId;
+  return out;
+}
+function bindingEmit(env) {
+  const sprigr = env.SPRIGR;
+  return typeof sprigr?.emit === "function" ? sprigr.emit.bind(
+    sprigr
+  ) : null;
+}
+async function installTokenPost(bridge, path, body, opts) {
+  const label = opts?.label ?? `POST ${path}`;
+  const controller = new AbortController();
+  const timer = opts?.timeoutMs != null ? setTimeout(() => controller.abort(), opts.timeoutMs) : void 0;
+  if (opts?.signal) {
+    if (opts.signal.aborted) controller.abort();
+    else opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  try {
+    const resp = await fetch(`${bridge.base}${path}`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${bridge.token}`, "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    const text = await resp.text();
+    let parsed = null;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+      parsed = null;
+    }
+    if (!resp.ok) {
+      const detail = parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : text.slice(0, 200);
+      throw new Error(`${label} failed: ${resp.status} ${detail}`);
+    }
+    return parsed ?? {};
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+async function emitMarketplaceEvent(env, event, payload, opts) {
+  const { timeoutMs, ...emitOpts } = opts ?? {};
+  const compact = compactOpts(emitOpts);
+  const passThrough = Object.keys(compact).length > 0 ? compact : void 0;
+  const injected = bindingEmit(env);
+  if (injected) {
+    try {
+      const r = await injected(event, payload, passThrough);
+      if (r && r.queued === false) {
+        return { emitted: false, via: "binding", eventId: r.eventId, error: r.error ?? "not_queued" };
+      }
+      return { emitted: r?.ok !== false, via: "binding", eventId: r?.eventId };
+    } catch (err) {
+      return { emitted: false, via: "binding", error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) return { emitted: false, via: "none", error: describeMissingBridge(env) };
+  try {
+    const reply = await installTokenPost(
+      bridge,
+      "/internal/wfp/emit",
+      { event, payload: payload === void 0 ? null : payload, ...compact },
+      { label: "emit", timeoutMs: timeoutMs ?? DEFAULT_EMIT_TIMEOUT_MS }
+    );
+    if (reply.ok === false || reply.queued === false) {
+      return { emitted: false, via: "http", eventId: reply.eventId, error: reply.error ?? "not_queued" };
+    }
+    return { emitted: true, via: "http", eventId: reply.eventId };
+  } catch (err) {
+    return { emitted: false, via: "http", error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function withSprigrEmitFallback(env) {
+  if (bindingEmit(env)) return env;
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) return env;
+  const emit = async (event, payload, opts) => await installTokenPost(
+    bridge,
+    "/internal/wfp/emit",
+    { event, payload: payload === void 0 ? null : payload, ...compactOpts(opts) },
+    { label: "emit", timeoutMs: DEFAULT_EMIT_TIMEOUT_MS }
+  );
+  const existing = env.SPRIGR ?? {};
+  return overlaySprigr(env, { ...existing, emit });
+}
+
 // src/actor.ts
 function parseActor(args) {
   if (!args || typeof args !== "object") return void 0;
@@ -274,6 +384,7 @@ function deleteAppFile(env, key) {
   return call(env, "delete", { key });
 }
 export {
+  DEFAULT_EMIT_TIMEOUT_MS,
   DEFAULT_MAX_FILE_BYTES,
   actorKey,
   appFileUrl,
@@ -283,16 +394,22 @@ export {
   constantTimeEqual,
   decodeState,
   deleteAppFile,
+  describeMissingBridge,
+  emitMarketplaceEvent,
   encodeState,
   fetchFileAsBase64,
   fetchFileBytes,
   fetchWithRetry,
   getAppFile,
   hmacSha256Hex,
+  installTokenPost,
   listAppFiles,
+  overlaySprigr,
   parseActor,
   putAppFile,
   putAppFileStream,
   randomHex,
-  resolvePlatformWebhookBase
+  resolveInstallBridge,
+  resolvePlatformWebhookBase,
+  withSprigrEmitFallback
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprigr/apps-app-sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",