@sprigr/apps-app-sdk 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -669,6 +669,12 @@ declare function withSprigrLogFallback<E extends WfpBridgeEnv & object>(env: E,
  * fails with `shard_field_invalid`: a patch cannot be routed to its shard
  * otherwise. The per-call cap is the same 1000 objects as `import`.
  *
+ * `withAcl: true` is a narrower mode: it re-stamps `acl_principals` on rows
+ * already in the app's `-acl-files` index and nothing else. Every patch must
+ * be exactly `{ objectID, acl_principals }`, and `createIfNotExists` and
+ * `index` cannot be combined with it. Content is written only by an ACL
+ * `import`, whole.
+ *
  * This module carries two things:
  *
  *   1. `buildPartialUpdateBody`, the wire body both transports send, with
@@ -687,10 +693,13 @@ declare function withSprigrLogFallback<E extends WfpBridgeEnv & object>(env: E,
  * swallow.
  *
  * Wire contract (workers/provisioning/src/wfp-data.ts in sprigr-team):
- *   POST { index?, objects, createIfNotExists? }
+ *   POST { index?, objects, createIfNotExists?, withAcl? }
  *   200 { ok: true, updated, skippedMissing, index, physical_indexes? }
  *   400 { error, detail, index? } with error one of too_many_objects,
- *       invalid_object, unknown_data_index, shard_field_invalid, ...
+ *       invalid_object, unknown_data_index, shard_field_invalid,
+ *       acl_partial_update_fields, acl_partial_update_create_unsupported,
+ *       acl_index_combination_unsupported, missing_acl_principals,
+ *       invalid_acl_principal, ...
  *   401 / 404 bad token / inactive install
  */
 
@@ -708,6 +717,8 @@ interface SprigrDataPartialUpdateBody {
     index?: string;
     objects: SprigrDataPatch[];
     createIfNotExists: boolean;
+    /** Present (and true) only for an ACL re-stamp. */
+    withAcl?: true;
 }
 interface PartialUpdateDataOptions extends SprigrDataPartialUpdateOpts {
     /** Ceiling on the HTTP fallback. No default: a data write is awaited for its result. */
@@ -2085,6 +2096,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
  *
@@ -2244,6 +2517,17 @@ interface SprigrDataPartialUpdateOpts extends SprigrDataIndexOpts {
      * missing target is counted in `skippedMissing` instead of being written.
      */
     createIfNotExists?: boolean;
+    /**
+     * Re-stamp `acl_principals` on rows already in the app's `-acl-files`
+     * index without rewriting the rest of each row. Every object must be
+     * exactly `{ objectID, acl_principals }` with a non-empty, valid principal
+     * list; `createIfNotExists` and `index` are refused alongside it. Use it
+     * when the source changes who may see an item without reporting the item
+     * as changed (OneDrive's delta omits sharing-only changes). Needs a
+     * platform with sprigr/sprigr-team#9843; older wrappers drop the flag,
+     * which `partialUpdateData` detects and throws on.
+     */
+    withAcl?: boolean;
 }
 /** Reply of `env.SPRIGR.data.partialUpdate` (`POST /internal/wfp/data/partial-update`). */
 interface SprigrDataPartialUpdateResult {
@@ -2614,4 +2898,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

@@ -512,6 +512,7 @@ function withSprigrLogFallback(env, opts) {
 // src/platform-data.ts
 var DATA_PARTIAL_UPDATE_PATH = "/internal/wfp/data/partial-update";
 var SPRIGR_DATA_MAX_OBJECTS_PER_CALL = 1e3;
+var ACL_INDEX_SUFFIX = "-acl-files";
 var SprigrDataValidationError = class extends Error {
   error;
   index;
@@ -556,12 +557,51 @@ function buildPartialUpdateBody(objects, opts) {
       error: "unknown_data_index"
     });
   }
+  const withAcl = opts?.withAcl === true;
+  if (withAcl) checkAclRestamp(objects, opts, at);
   return {
     ...opts?.index !== void 0 ? { index: opts.index } : {},
     objects,
-    createIfNotExists: opts?.createIfNotExists === true
+    createIfNotExists: opts?.createIfNotExists === true,
+    ...withAcl ? { withAcl: true } : {}
   };
 }
+function checkAclRestamp(objects, opts, at) {
+  if (opts?.createIfNotExists === true) {
+    throw new SprigrDataValidationError(
+      `${at}: withAcl only re-stamps existing rows; createIfNotExists would create a row with principals and no content`,
+      { error: "acl_partial_update_create_unsupported" }
+    );
+  }
+  if (opts?.index !== void 0) {
+    throw new SprigrDataValidationError(`${at}: withAcl targets the reserved -acl-files index and cannot be combined with index`, {
+      error: "acl_index_combination_unsupported"
+    });
+  }
+  for (let i = 0; i < objects.length; i++) {
+    const o = objects[i];
+    const extra = Object.keys(o).find((k) => k !== "objectID" && k !== "acl_principals");
+    if (extra !== void 0) {
+      throw new SprigrDataValidationError(
+        `${at}: objects[${i}] carries "${extra}"; a withAcl partial update sets only objectID and acl_principals (write content with data.import withAcl)`,
+        { error: "acl_partial_update_fields", index: i }
+      );
+    }
+    const principals = o.acl_principals;
+    if (!Array.isArray(principals) || principals.length === 0) {
+      throw new SprigrDataValidationError(`${at}: objects[${i}] needs a non-empty acl_principals: string[]`, {
+        error: "missing_acl_principals",
+        index: i
+      });
+    }
+  }
+}
+function assertAclIndex(result) {
+  if (typeof result?.index === "string" && result.index.endsWith(ACL_INDEX_SUFFIX)) return result;
+  throw new Error(
+    `data.partialUpdate withAcl landed on ${String(result?.index)}, not the ${ACL_INDEX_SUFFIX} index: this app was built by a platform wrapper that drops withAcl. Republish the app to pick up the current wrapper.`
+  );
+}
 function bindingPartialUpdate(env) {
   const data = env.SPRIGR?.data;
   return typeof data?.partialUpdate === "function" ? data.partialUpdate.bind(data) : null;
@@ -579,10 +619,12 @@ async function partialUpdateData(env, objects, opts) {
   const body = buildPartialUpdateBody(objects, dataOpts);
   const injected = bindingPartialUpdate(env);
   if (injected) {
-    return injected(body.objects, {
+    const result = await injected(body.objects, {
       ...body.index !== void 0 ? { index: body.index } : {},
-      createIfNotExists: body.createIfNotExists
+      createIfNotExists: body.createIfNotExists,
+      ...body.withAcl ? { withAcl: true } : {}
     });
+    return body.withAcl ? assertAclIndex(result) : result;
   }
   const bridge = resolveInstallBridge(env);
   if (!bridge) {
@@ -1446,6 +1488,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,
@@ -1454,6 +1599,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,
@@ -1483,10 +1630,13 @@ export {
   canPartialUpdate,
   checkConfirmationPolicy,
   commonDestructiveVerbs,
+  connectComplete,
+  connectDisconnect,
   constantTimeEqual,
   createMarketplaceEmitter,
   createToolWrappers,
   decodeState,
+  defineInboxSendHandler,
   deleteAppFile,
   deriveConfirmationPolicy,
   describeMissingBridge,
@@ -1533,5 +1683,6 @@ export {
   validateLogEntry,
   verifyViewerToken,
   withSprigrEmitFallback,
+  withSprigrInboxFallback,
   withSprigrLogFallback
 };

package/package.json

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