@sprigr/apps-app-sdk 0.3.0 → 0.5.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.
@@ -462,6 +528,59 @@ declare function parseActor(args: unknown): Actor | undefined;
  * treat that as "no caller identity" and fail closed.
  */
 declare function actorKey(actor: Actor | undefined): string | null;
+/**
+ * Mailbox-owner attribution for one `env.SPRIGR.inbox.append` /
+ * `env.SPRIGR.inbox.folders` batch.
+ *
+ * Exactly ONE of the two fields must be set:
+ *
+ *   - `platformUserId` — OIDC sub of the user whose mailbox the batch was
+ *     synced from (a personal mailbox connection).
+ *   - `agentId` — agent id for an agent-keyed connection (a shared /
+ *     departmental mailbox connected through a shared agent rather than a
+ *     person).
+ *
+ * Why this exists: a mail app install is shared by the whole company, and
+ * several users can each connect their own mailbox to it. The platform files
+ * every appended message under the ONE integration behind the install, so
+ * without attribution it cannot tell whose mailbox a batch came from and has
+ * historically granted thread visibility to every connected user. Passing
+ * `owner` pins each synced thread's visibility to exactly the mailbox owner:
+ * user connections stay private to that user, agent-keyed connections stay
+ * visible to that agent's audience.
+ *
+ * This is the OWNER OF THE MAILBOX (the connection identity the app keyed
+ * the sync on), NOT the dispatch caller — a scheduled poll has no caller at
+ * all yet must still attribute every batch. Populate it from the per-actor
+ * connection row the sync loop is iterating, e.g.:
+ *
+ *   const owner = row.sprigr_user_id
+ *     ? { platformUserId: row.sprigr_user_id }
+ *     : { agentId: row.sprigr_agent_id };
+ *   await env.SPRIGR.inbox.append({ channel, messages, owner });
+ *
+ * Mail apps must send it on EVERY append/folders call (sync poll, push
+ * delivery, backfill, folder reports). Batches without it fall back to the
+ * platform's legacy integration-level resolution, which on a multi-user
+ * install pins nobody (fail closed) rather than everyone.
+ *
+ * Hosts older than the attribution surface ignore the field entirely, so
+ * sending it is always safe.
+ */
+interface InboxOwner {
+    /** OIDC sub (platform user id) of the mailbox's owner. */
+    platformUserId?: string;
+    /** Agent id for an agent-keyed (shared-mailbox) connection. */
+    agentId?: string;
+}
+/**
+ * Inverse of `actorKey`: turn a stored `u:<platformUserId>` / `a:<agentId>`
+ * key back into an `InboxOwner`. For apps that persist the connection
+ * identity as an actor-key string and need to attribute inbox batches from
+ * it. Returns null for null/empty/unrecognised input — callers should treat
+ * that as "owner unknown" and omit the field rather than guess.
+ */
+declare function ownerFromActorKey(key: string | null | undefined): InboxOwner | null;
 
 /**
  * App-scoped R2 file storage (platform feature, 2026-06).
@@ -873,4 +992,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 InboxOwner, 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, ownerFromActorKey, 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) {
@@ -308,6 +332,12 @@ function actorKey(actor) {
   if (actor.agentId) return `a:${actor.agentId}`;
   return null;
 }
+function ownerFromActorKey(key) {
+  if (!key) return null;
+  if (key.startsWith("u:") && key.length > 2) return { platformUserId: key.slice(2) };
+  if (key.startsWith("a:") && key.length > 2) return { agentId: key.slice(2) };
+  return null;
+}
 
 // src/app-files.ts
 var DEFAULT_PLATFORM_BASE = "https://webhooks.sprigr.com";
@@ -417,13 +447,17 @@ export {
   getAppFile,
   hmacSha256Hex,
   installTokenPost,
+  isStagingHost,
   listAppFiles,
   overlaySprigr,
+  ownerFromActorKey,
   parseActor,
   putAppFile,
   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.5.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",