@sprigr/apps-app-sdk 0.3.0 → 0.4.0

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.
@@ -873,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, canEmit, constantTimeEqual, createMarketplaceEmitter, 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) {
@@ -417,6 +441,7 @@ export {
   getAppFile,
   hmacSha256Hex,
   installTokenPost,
+  isStagingHost,
   listAppFiles,
   overlaySprigr,
   parseActor,
@@ -424,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.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",