@sprigr/apps-app-sdk 0.2.0 → 0.4.0

package/README.md

@@ -11,6 +11,8 @@ npm install @sprigr/apps-app-sdk
 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.
+- `createMarketplaceEmitter(integrationType, defaults?)` — pre-bind an app's integration type so call sites pass only what varies; `sourceIntegration` is built per call from `env.INSTALL_ID`.
+- `canEmit(env)` — whether an emit could reach the platform by either transport. Gate work that only exists to feed an emit on this, not on `env.SPRIGR?.emit`.
 - `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`.

package/dist/index.d.ts

@@ -234,6 +234,72 @@ declare function resolvePlatformWebhookBase(env: PlatformHostEnv, override?: str
  * form should pre-translate before calling.
  */
 declare function buildMarketplaceWebhookUrl(env: PlatformHostEnv, installId: string, topicPath: string, override?: string | null): string;
+/**
+ * Is this URL (or bare hostname) served by a STAGING host?
+ *
+ * Every Sprigr staging host is `staging-<something>.sprigr.com`:
+ * `staging-apps` (per-install app sites), `staging-sites` (the
+ * preview-token host from `get_website_preview`), `staging-team` (the
+ * portal), `staging-webhooks` (the platform base). No prod host carries
+ * a `staging-` label.
+ *
+ * Tests the HOSTNAME, not a substring of the whole URL. Eight apps
+ * previously hand-rolled
+ *
+ *     reqUrl.includes('staging-apps.sprigr.com') ||
+ *     reqUrl.includes('staging-team.sprigr.com')
+ *
+ * which was wrong in BOTH directions. It missed `staging-sites`, so a
+ * staging install served from the preview host built an authorize URL
+ * pointing at the PRODUCTION bouncer — which cannot resolve a staging
+ * install id, so the connect died at the bouncer with a confusing error
+ * (observed live 2026-07-25 by reading the Location header off a
+ * deployed /oauth/start). And because it matched the whole URL, a PROD
+ * install hit with `?return_to=https://staging-team.sprigr.com/x` was
+ * classified as staging. Parsing the hostname closes both.
+ *
+ * Unparseable input resolves to `false` (prod), so a caller can never
+ * accidentally point production traffic at staging.
+ */
+declare function isStagingHost(urlOrHostname: string | null | undefined): boolean;
+/**
+ * Signals an app can offer to decide which bouncer to use. Pass whatever
+ * the call site actually has:
+ *
+ *   - `reqUrl`       an inbound browser request URL (the /oauth/start route).
+ *   - `platformBase` the platform-stamped `SPRIGR_PLATFORM_BASE`, for tool
+ *                    handlers dispatched on /__sprigr/tool/* where there is
+ *                    no browser origin. Staging value is
+ *                    `https://staging-webhooks.sprigr.com`.
+ *   - `override`     an explicit per-install redirect URI / bouncer base.
+ *                    Always wins; used for local dev and canaries.
+ *
+ * Staging wins if ANY supplied signal says staging.
+ */
+interface OAuthBouncerSignals {
+    reqUrl?: string | null;
+    platformBase?: string | null;
+    override?: string | null;
+}
+/**
+ * The bouncer ORIGIN for the environment serving this request, e.g.
+ * `https://staging-oauth-bouncer.sprigr.com`. Never has a trailing slash.
+ *
+ * `override` short-circuits everything (trailing slash stripped).
+ */
+declare function resolveOAuthBouncerBase(signals?: OAuthBouncerSignals): string;
+/**
+ * The full bouncer CALLBACK URL for a provider, which is the value that
+ * goes in an authorize URL's `redirect_uri` and must be registered as a
+ * redirect URI on the provider's developer app:
+ *
+ *   resolveOAuthBouncerCallbackUrl('simpro', { reqUrl: req.url })
+ *   // -> "https://staging-oauth-bouncer.sprigr.com/simpro/oauth/callback"
+ *
+ * `override` is returned verbatim (no provider path appended) — an app
+ * pointing at a local bouncer supplies the complete callback URL.
+ */
+declare function resolveOAuthBouncerCallbackUrl(provider: string, signals?: OAuthBouncerSignals): string;
 
 /**
  * Talking to the platform from BOTH execution contexts.
@@ -364,6 +430,26 @@ declare function installTokenPost(bridge: InstallBridge, path: string, body: unk
  *   await audit(env, 'emit', JSON.stringify(r));   // records `via`
  */
 declare function emitMarketplaceEvent(env: WfpBridgeEnv, event: string, payload: unknown, opts?: EmitMarketplaceEventOptions): Promise<EmitResult>;
+/**
+ * Whether an emit could reach the platform at all, by either transport.
+ *
+ * Use it to skip work whose only purpose is to feed an emit. Gate on this
+ * rather than on `env.SPRIGR?.emit`: the binding is absent on every inline
+ * route, so the narrower check skips the work in exactly the context where the
+ * HTTP bridge would have carried it.
+ */
+declare function canEmit(env: WfpBridgeEnv): boolean;
+/**
+ * Pre-bind an app's `integrationType` so call sites pass only what varies.
+ * `sourceIntegration` is built per call from `env.INSTALL_ID`, and omitted
+ * entirely when that is unbound (the platform 400s on a partial one).
+ *
+ *   const emit = createMarketplaceEmitter('procore');
+ *   const r = await emit(env, 'procore.rfi.updated', payload);
+ */
+declare function createMarketplaceEmitter<E extends WfpBridgeEnv = WfpBridgeEnv>(integrationType: string, defaults?: {
+    timeoutMs?: number;
+}): (env: E, eventName: string, payload: unknown) => 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
@@ -853,4 +939,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_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 };
+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 OAuthBouncerSignals, 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, canEmit, constantTimeEqual, createMarketplaceEmitter, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, installTokenPost, isStagingHost, listAppFiles, overlaySprigr, parseActor, putAppFile, putAppFileStream, randomHex, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, withSprigrEmitFallback };

package/dist/index.js

@@ -165,6 +165,30 @@ function buildMarketplaceWebhookUrl(env, installId, topicPath, override) {
   const base = resolvePlatformWebhookBase(env, override);
   return `${base}/webhook/marketplace/${installId}/${topicPath}`;
 }
+var OAUTH_BOUNCER_PROD = "https://oauth-bouncer.sprigr.com";
+var OAUTH_BOUNCER_STAGING = "https://staging-oauth-bouncer.sprigr.com";
+function isStagingHost(urlOrHostname) {
+  const raw = (urlOrHostname ?? "").trim();
+  if (!raw) return false;
+  let hostname;
+  try {
+    hostname = new URL(raw).hostname;
+  } catch {
+    hostname = /^[a-z0-9.-]+$/i.test(raw) ? raw : "";
+  }
+  return /(^|\.)staging-/.test(hostname);
+}
+function resolveOAuthBouncerBase(signals = {}) {
+  const override = (signals.override ?? "").trim();
+  if (override) return override.replace(/\/$/, "");
+  const isStaging = isStagingHost(signals.reqUrl) || isStagingHost(signals.platformBase);
+  return isStaging ? OAUTH_BOUNCER_STAGING : OAUTH_BOUNCER_PROD;
+}
+function resolveOAuthBouncerCallbackUrl(provider, signals = {}) {
+  const override = (signals.override ?? "").trim();
+  if (override) return override;
+  return `${resolveOAuthBouncerBase(signals)}/${provider}/oauth/callback`;
+}
 
 // src/wfp-bridge.ts
 function resolveInstallBridge(env) {
@@ -262,6 +286,18 @@ async function emitMarketplaceEvent(env, event, payload, opts) {
     return { emitted: false, via: "http", error: err instanceof Error ? err.message : String(err) };
   }
 }
+function canEmit(env) {
+  return bindingEmit(env) !== null || resolveInstallBridge(env) !== null;
+}
+function createMarketplaceEmitter(integrationType, defaults = {}) {
+  return (env, eventName, payload) => {
+    const installId = typeof env.INSTALL_ID === "string" ? env.INSTALL_ID : "";
+    return emitMarketplaceEvent(env, eventName, payload, {
+      ...defaults,
+      ...installId ? { sourceIntegration: { integrationId: installId, integrationType } } : {}
+    });
+  };
+}
 function withSprigrEmitFallback(env) {
   if (bindingEmit(env)) return env;
   const bridge = resolveInstallBridge(env);
@@ -391,7 +427,9 @@ export {
   base64ToBytes,
   buildMarketplaceWebhookUrl,
   bytesToBase64,
+  canEmit,
   constantTimeEqual,
+  createMarketplaceEmitter,
   decodeState,
   deleteAppFile,
   describeMissingBridge,
@@ -403,6 +441,7 @@ export {
   getAppFile,
   hmacSha256Hex,
   installTokenPost,
+  isStagingHost,
   listAppFiles,
   overlaySprigr,
   parseActor,
@@ -410,6 +449,8 @@ export {
   putAppFileStream,
   randomHex,
   resolveInstallBridge,
+  resolveOAuthBouncerBase,
+  resolveOAuthBouncerCallbackUrl,
   resolvePlatformWebhookBase,
   withSprigrEmitFallback
 };

package/package.json

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