@sprigr/apps-app-sdk 0.2.0 → 0.3.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

@@ -364,6 +364,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 +873,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 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 };

package/dist/index.js

@@ -262,6 +262,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 +403,9 @@ export {
   base64ToBytes,
   buildMarketplaceWebhookUrl,
   bytesToBase64,
+  canEmit,
   constantTimeEqual,
+  createMarketplaceEmitter,
   decodeState,
   deleteAppFile,
   describeMissingBridge,

package/package.json

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