@sprigr/apps-app-sdk 0.14.0 → 0.15.1

package/dist/index.d.ts

@@ -1278,6 +1278,13 @@ declare function putAppFile(env: AppFilesEnv, args: PutAppFileArgs): Promise<Put
  * and (with a `ReadableStream` body) never buffers them whole in the
  * isolate — pipe a source `Response.body` directly through for multi-MB
  * blobs. Metadata travels in headers; the body is opaque bytes.
+ *
+ * The platform's put-stream route cannot retry a transient R2 fault itself
+ * (its body is spent once read), so a resendable body — `ArrayBuffer` /
+ * `Uint8Array` already in hand, not a `ReadableStream` — gets a bounded
+ * retry here instead. The key is deterministic, so a retry is a full
+ * overwrite, exactly the argument the platform's buffered `put` route makes
+ * for its own retry (wfp-files.ts, sprigr-team).
  */
 declare function putAppFileStream(env: AppFilesEnv, args: PutAppFileStreamArgs): Promise<PutAppFileResult>;
 /** Mint a signed, time-limited download URL for an app file. */
@@ -2096,6 +2103,268 @@ declare function deriveConfirmationPolicy(registry: Iterable<string>, opts: Deri
  */
 declare function commonDestructiveVerbs(subject: string): VerbRule[];
 
+/**
+ * The inbox contract for mail and ticket apps (sprigr-team decision 0150).
+ *
+ * An app that writes into the Sprigr inbox does four things, all typed here:
+ *
+ *   1. Declares each channel it writes under `capabilities.inbox_channels` in
+ *      its manifest (`InboxChannelDeclaration`). Append refuses undeclared
+ *      channels, and replies cannot send without a declared send tool.
+ *   2. Appends synced messages with `env.SPRIGR.inbox.append` (`SyncedMessage`,
+ *      `InboxOwner` on every batch). `withSprigrInboxFallback` makes that work
+ *      from an inline route too.
+ *   3. Implements the declared send tool on the one `sprigr.inbox.send/v1`
+ *      argument shape, through `defineInboxSendHandler`, which enforces the
+ *      mailbox-owner rule so it cannot be forgotten.
+ *   4. If it collects a credential on its own page (no OAuth bouncer),
+ *      reports the connection with `connectComplete`, which forwards the
+ *      platform-signed viewer token so the platform knows who connected.
+ */
+
+declare const INBOX_SEND_CONTRACT_V1: "sprigr.inbox.send/v1";
+interface InboxSendSupports {
+    bcc: boolean;
+    html: boolean;
+    recipients: boolean;
+    importance: boolean;
+    internal_note: boolean;
+}
+/** One entry of `capabilities.inbox_channels`. Validated at publish. */
+interface InboxChannelDeclaration {
+    /** Must start with your slug in snake case plus `_` (`acme-mail` -> `acme_mail_...`). */
+    channel: string;
+    kind: 'email' | 'ticket';
+    /** 1-40 printable characters, no `<` or `>`. */
+    label: string;
+    icon: 'mail' | 'ticket' | 'chat';
+    send?: {
+        tool: string;
+        contract: typeof INBOX_SEND_CONTRACT_V1;
+        returns_message_id: {
+            send: boolean;
+            reply: boolean;
+        };
+        attachments: 'file_key' | 'inline' | 'none';
+        supports: InboxSendSupports;
+    };
+    signature_family?: string;
+    attachment_repair_tool?: string;
+    /** https only, host in `permissions.network_domains`; placeholders
+     *  `{source_thread_id}` and `{source_id}`. */
+    deep_link_template?: string | null;
+}
+interface SyncedAttachment {
+    filename: string;
+    mimeType: string;
+    size: number;
+    /** Opaque to the platform; your `fetch_attachment` tool resolves it. It
+     *  must identify the connection, because that dispatch carries no actor. */
+    providerAttachmentId?: string;
+    contentId?: string;
+    inline?: boolean;
+}
+interface SyncedMessage {
+    /** Unique within the channel; the platform dedups on (channel, sourceId). */
+    sourceId: string;
+    sourceIndex: string;
+    sourceThreadId?: string;
+    /** RFC 5322 Message-ID (brackets optional). */
+    rfcMessageId?: string;
+    channel?: string;
+    direction: 'inbound' | 'outbound' | 'internal';
+    fromName?: string;
+    fromEmail?: string;
+    toRecipients?: Array<{
+        name: string;
+        email: string;
+    }>;
+    ccRecipients?: Array<{
+        name: string;
+        email: string;
+    }>;
+    subject?: string;
+    /** Plain text. May be '' when `bodyHtml` carries the content. */
+    body: string;
+    bodyHtml?: string;
+    /** ISO 8601. */
+    timestamp: string;
+    sourceIsRead?: boolean;
+    tags?: string[];
+    attachments?: SyncedAttachment[];
+}
+interface InboxAppendRequest {
+    channel?: string;
+    /** At most 500 per call. */
+    messages: SyncedMessage[];
+    /** The MAILBOX owner (from your connection row), never the dispatch caller. */
+    owner?: InboxOwner;
+}
+interface InboxAppendResult {
+    ok: boolean;
+    threadsCreated: number;
+    messagesLinked: number;
+    threadIds: string[];
+    contentlessSkipped?: number;
+}
+interface InboxFoldersRequest {
+    channel?: string;
+    /** At most 200 per call. Folder names match manual Sprigr folders. */
+    items: Array<{
+        sourceId: string;
+        addFolders?: string[];
+        removeFolders?: string[];
+    }>;
+    owner?: InboxOwner;
+}
+interface InboxFoldersResult {
+    ok: boolean;
+    filed: number;
+    unfiled: number;
+    skippedGuarded: number;
+    unknownFolders: string[];
+}
+interface SprigrInboxApi {
+    append(req: InboxAppendRequest): Promise<InboxAppendResult>;
+    folders?(req: InboxFoldersRequest): Promise<InboxFoldersResult>;
+}
+/**
+ * Return an env whose `SPRIGR.inbox` works from any execution context.
+ *
+ * `env.SPRIGR` is injected only on the `/__sprigr/*` dispatch path. An inline
+ * route (a provider push receiver, your settings page) gets the raw bindings,
+ * so this wires the same contract over the install-token HTTP bridge. Append
+ * and folders THROW on a non-2xx, so a caller never advances a sync cursor
+ * past messages the platform did not accept. With no bridge bindings the env
+ * comes back unchanged and `SPRIGR.inbox` stays undefined: fail closed.
+ */
+declare function withSprigrInboxFallback<E extends WfpBridgeEnv & object>(env: E): E;
+interface InboxAddress {
+    email: string;
+    name?: string;
+}
+/** What the platform sends your declared send tool. snake_case. */
+interface InboxSendV1Args {
+    contract: typeof INBOX_SEND_CONTRACT_V1;
+    from_email?: string;
+    to?: InboxAddress[];
+    cc?: InboxAddress[];
+    bcc?: InboxAddress[];
+    subject?: string;
+    body_text: string;
+    body_html?: string;
+    attachments?: Array<{
+        file_key: string;
+        filename: string;
+        content_type: string;
+    }> | Array<{
+        filename: string;
+        mime_type?: string;
+        base64_body: string;
+    }>;
+    /** `source_id` / `source_thread_id` are YOUR stored ids, present only when
+     *  your install received the mail being answered. */
+    reply?: {
+        source_id?: string;
+        source_thread_id?: string;
+        rfc_message_id?: string;
+        references: string[];
+    };
+    internal_note?: boolean;
+    author_email?: string;
+    importance?: 'high' | 'low';
+    idempotency_key?: string;
+}
+/** What your send tool returns. `message_id` must equal the `sourceId` your
+ *  sync will write for the sent copy, so the Sent echo dedups. */
+interface InboxSendV1Result {
+    message_id?: string;
+    internet_message_id?: string;
+    thread_id?: string;
+}
+/** Your connection record, as far as the owner check needs it. */
+interface InboxSendConnection {
+    /** `u:<platformUserId>` or `a:<agentId>`: the key the connection is filed under. */
+    actorKey: string;
+}
+interface InboxSendHandlerImpl<E, C extends InboxSendConnection> {
+    /** The connection that owns one of YOUR stored source ids, or null when the
+     *  id is not yours. Parse your own id format here. */
+    connectionForSourceId(env: E, sourceId: string): Promise<C | null>;
+    /** The connection this actor key sends a NEW mail from. When `fromEmail` is
+     *  set, return only a connection that may send as that address, else null. */
+    connectionForActor(env: E, actorKey: string, fromEmail: string | undefined): Promise<C | null>;
+    send(env: E, connection: C, args: InboxSendV1Args): Promise<InboxSendV1Result>;
+}
+declare class InboxSendRefusal extends Error {
+    readonly code: 'no_caller_identity' | 'not_your_mailbox' | 'not_connected' | 'invalid_args';
+    constructor(code: 'no_caller_identity' | 'not_your_mailbox' | 'not_connected' | 'invalid_args', message: string);
+}
+/**
+ * Build the handler for your declared `sprigr.inbox.send/v1` tool.
+ *
+ * THE MAILBOX-OWNER RULE, enforced here so no app can omit it: replies are
+ * dispatched under the WRITER's actor, and anyone who can read a thread can
+ * press Reply. So the connection you send from must be filed under one of the
+ * writer's own keys (`u:<platformUserId>`, `a:<agentId>`). A reply whose
+ * source belongs to someone else's connection is REFUSED, never re-routed to
+ * the writer's own mailbox and never sent from the owner's: either would
+ * deliver mail the writer is not entitled to send.
+ */
+declare function defineInboxSendHandler<E, C extends InboxSendConnection>(impl: InboxSendHandlerImpl<E, C>): (args: Record<string, unknown>, env: E) => Promise<ToolResult<InboxSendV1Result>>;
+interface ConnectCompleteRequest {
+    /** The raw `X-Sprigr-Viewer` header of the PAGE request that submitted the
+     *  credential. The platform takes the user only from this. */
+    viewer_token: string;
+    bind?: {
+        kind: 'user';
+    } | {
+        kind: 'agent';
+        agent_id: string;
+    };
+    account: {
+        email: string;
+        name?: string;
+    };
+    identities?: Array<{
+        email: string;
+        name?: string;
+    }>;
+}
+interface ConnectCompleteResult {
+    ok: boolean;
+    /** File your connection under this key. */
+    actor_key: string;
+    identities: {
+        inserted: number;
+        updated: number;
+        deleted: number;
+    };
+    /** The same address already connected through another app in the company. */
+    existing_mailboxes: Array<{
+        app_slug: string;
+        email: string;
+        account_email: string;
+    }>;
+}
+/**
+ * Report a mailbox connected on your own page (token paste, app password).
+ * Call it from the inline route that handled the page's POST, passing that
+ * request's `X-Sprigr-Viewer` header. Throws on a non-2xx with `.status` and
+ * `.error` (`viewer_unverified`, `viewer_not_a_member`, `agent_bind_refused`,
+ * `agent_bind_requires_admin`, ...).
+ */
+declare function connectComplete(env: WfpBridgeEnv, req: ConnectCompleteRequest): Promise<ConnectCompleteResult>;
+/** Retire a connection's From-picker identities (install token only, so a
+ *  background sync can call it when a credential dies). */
+declare function connectDisconnect(env: WfpBridgeEnv, req: {
+    actor_key: string;
+    account_email?: string;
+}): Promise<{
+    ok: boolean;
+    deleted: number;
+}>;
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -2636,4 +2905,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrFilesListItem, type SprigrFilesListResult, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, partialUpdateData, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrLogFallback };
+export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, INBOX_SEND_CONTRACT_V1, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrFilesListItem, type SprigrFilesListResult, type SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, partialUpdateData, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };

package/dist/index.js

@@ -893,6 +893,17 @@ function putAppFile(env, args) {
     filename: args.filename
   });
 }
+var STREAM_PUT_MAX_ATTEMPTS = 3;
+var STREAM_PUT_BASE_DELAY_MS = 500;
+function isTransientPutStreamFailure(status, message) {
+  if (status === 503) return true;
+  if (status !== 502) return false;
+  const msg = message.toLowerCase();
+  return msg.includes("(10001)") || msg.includes("(10043)");
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function putAppFileStream(env, args) {
   const token = requireToken(env);
   const headers = {
@@ -905,14 +916,28 @@ async function putAppFileStream(env, args) {
   if (typeof args.contentLength === "number" && Number.isFinite(args.contentLength)) {
     headers["x-app-file-length"] = String(args.contentLength);
   }
-  const res = await fetch(`${platformBase(env)}/internal/wfp/file/put-stream`, {
-    method: "POST",
-    headers,
-    body: args.body,
-    // Required by the Workers runtime when sending a streaming request body.
-    ...args.body instanceof ReadableStream ? { duplex: "half" } : {}
-  });
-  return parseResult(res, "put-stream");
+  const resendable = !(args.body instanceof ReadableStream);
+  const attempts = resendable ? STREAM_PUT_MAX_ATTEMPTS : 1;
+  let lastErr;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const res = await fetch(`${platformBase(env)}/internal/wfp/file/put-stream`, {
+      method: "POST",
+      headers,
+      body: args.body,
+      // Required by the Workers runtime when sending a streaming request body.
+      ...args.body instanceof ReadableStream ? { duplex: "half" } : {}
+    });
+    try {
+      return await parseResult(res, "put-stream");
+    } catch (err) {
+      lastErr = err;
+      if (!resendable || attempt === attempts || !(err instanceof AppFilesError) || !isTransientPutStreamFailure(err.status, err.message)) {
+        throw err;
+      }
+      await sleep2(STREAM_PUT_BASE_DELAY_MS * 2 ** (attempt - 1));
+    }
+  }
+  throw lastErr;
 }
 function appFileUrl(env, args) {
   return call(env, "url", { key: args.key, expiresIn: args.expiresIn });
@@ -1488,6 +1513,109 @@ function commonDestructiveVerbs(subject) {
     { match: "deactivate_", tier: "always", describe: (_n, rest) => `Deactivate ${rest}${where}` }
   ];
 }
+
+// src/inbox.ts
+var INBOX_SEND_CONTRACT_V1 = "sprigr.inbox.send/v1";
+function withSprigrInboxFallback(env) {
+  const bridge = resolveInstallBridge(env);
+  const existing = env.SPRIGR ?? void 0;
+  const folders = bridge ? async (req) => await installTokenPost(bridge, "/internal/wfp/inbox/folders", req, { label: "inbox folders" }) : void 0;
+  if (existing?.inbox) {
+    if (existing.inbox.folders || !folders) return env;
+    const inbox = existing.inbox;
+    return overlaySprigr(env, { ...existing, inbox: { append: inbox.append.bind(inbox), folders } });
+  }
+  if (!bridge) return env;
+  const append = async (req) => {
+    const r = await installTokenPost(bridge, "/internal/wfp/inbox/append", req, { label: "inbox append" });
+    return {
+      ok: r.ok !== false,
+      threadsCreated: r.threadsCreated ?? 0,
+      messagesLinked: r.messagesLinked ?? 0,
+      threadIds: Array.isArray(r.threadIds) ? r.threadIds : [],
+      ...typeof r.contentlessSkipped === "number" ? { contentlessSkipped: r.contentlessSkipped } : {}
+    };
+  };
+  return overlaySprigr(env, { ...existing ?? {}, inbox: { append, folders } });
+}
+var InboxSendRefusal = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "InboxSendRefusal";
+  }
+  code;
+};
+function defineInboxSendHandler(impl) {
+  return async (rawArgs, env) => {
+    try {
+      const actor = parseActor(rawArgs);
+      const keys = [
+        ...actor?.platformUserId ? [`u:${actor.platformUserId}`] : [],
+        ...actor?.agentId ? [`a:${actor.agentId}`] : []
+      ];
+      if (keys.length === 0) {
+        throw new InboxSendRefusal("no_caller_identity", "The platform stamped no sender identity on this send.");
+      }
+      const args = rawArgs;
+      if (args.contract !== INBOX_SEND_CONTRACT_V1 || typeof args.body_text !== "string") {
+        throw new InboxSendRefusal("invalid_args", `Expected ${INBOX_SEND_CONTRACT_V1} arguments.`);
+      }
+      let connection = null;
+      const sourceId = args.reply?.source_id;
+      if (sourceId) {
+        const owner = await impl.connectionForSourceId(env, sourceId);
+        if (owner) {
+          if (!keys.includes(owner.actorKey)) {
+            throw new InboxSendRefusal(
+              "not_your_mailbox",
+              "This conversation arrived in a mailbox that belongs to someone else, so you cannot reply from it."
+            );
+          }
+          if (args.from_email) {
+            const asFrom = await impl.connectionForActor(env, owner.actorKey, args.from_email);
+            if (!asFrom || asFrom.actorKey !== owner.actorKey) {
+              throw new InboxSendRefusal("not_your_mailbox", `This mailbox cannot send as ${args.from_email}.`);
+            }
+          }
+          connection = owner;
+        }
+      }
+      if (!connection) {
+        for (const key of keys) {
+          connection = await impl.connectionForActor(env, key, args.from_email);
+          if (connection) break;
+        }
+      }
+      if (!connection) {
+        throw new InboxSendRefusal(
+          "not_connected",
+          args.from_email ? `You have no connection that can send as ${args.from_email}.` : "You have not connected a mailbox with this app."
+        );
+      }
+      if (!keys.includes(connection.actorKey)) {
+        throw new InboxSendRefusal("not_your_mailbox", "Resolved connection does not belong to the sender.");
+      }
+      return { ok: true, result: await impl.send(env, connection, args) };
+    } catch (err) {
+      if (err instanceof InboxSendRefusal || err instanceof Error && err.name === "InboxSendRefusal") {
+        const code = err.code;
+        return { ok: false, error: `${code}: ${err.message}`, status: code === "invalid_args" ? 400 : 412 };
+      }
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  };
+}
+async function connectComplete(env, req) {
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) throw new Error("connectComplete: SPRIGR_PLATFORM_BASE / SPRIGR_INSTALL_TOKEN are not bound");
+  return await installTokenPost(bridge, "/internal/wfp/connect/complete", req, { label: "connect complete" });
+}
+async function connectDisconnect(env, req) {
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) throw new Error("connectDisconnect: SPRIGR_PLATFORM_BASE / SPRIGR_INSTALL_TOKEN are not bound");
+  return await installTokenPost(bridge, "/internal/wfp/connect/disconnect", req, { label: "connect disconnect" });
+}
 export {
   APPROVAL_GRANTED_KEY,
   DATA_PARTIAL_UPDATE_PATH,
@@ -1496,6 +1624,8 @@ export {
   DEFAULT_MAX_FILE_BYTES,
   DEFAULT_MONEY_FIELDS,
   DEFAULT_WRITE_PREFIXES,
+  INBOX_SEND_CONTRACT_V1,
+  InboxSendRefusal,
   InvalidUndoEnvelopeError,
   NotConnectedError,
   SPRIGR_DATA_MAX_OBJECTS_PER_CALL,
@@ -1525,10 +1655,13 @@ export {
   canPartialUpdate,
   checkConfirmationPolicy,
   commonDestructiveVerbs,
+  connectComplete,
+  connectDisconnect,
   constantTimeEqual,
   createMarketplaceEmitter,
   createToolWrappers,
   decodeState,
+  defineInboxSendHandler,
   deleteAppFile,
   deriveConfirmationPolicy,
   describeMissingBridge,
@@ -1575,5 +1708,6 @@ export {
   validateLogEntry,
   verifyViewerToken,
   withSprigrEmitFallback,
+  withSprigrInboxFallback,
   withSprigrLogFallback
 };

package/package.json

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