@sprigr/apps-app-sdk 0.21.1 → 0.23.0

package/README.md

@@ -95,6 +95,7 @@ Three platform tiers, and they are not substitutes for each other. Full guide: [
 
 - `requireApproval(handlers, specs, opts)` wraps the named tools so each returns an `_approval` card instead of writing, then on the granted pass captures a before-image through the **pinned** connection and offers `_undo`. It resolves the connection inside itself, before the label lookup, the hash and the capture: a gate that sits outside the app's own pin names the wrong store, hashes the wrong store and captures the wrong store's copy. Register the result after the originals: `Object.assign(registry, requireApproval(registry, SPECS, opts))`.
 - `dispatcherApproval(specs, opts)`: the same gate for a one-tool-many-actions dispatcher. Build it beside the action registry and call `gate.run(action, args, env, () => def.execute(state, parsed))` from the dispatcher; params are read from `opts.inputField` (default `input`), the action name is hashed in, and `pinEnv` may return a per-actor token state rather than the env.
+- A spec with no `hash` binds the grant to its payload: every argument except the `keys` fields, the attestation flags and the gate's `connectionArgs` (e.g. `['store']`) goes into the hash canonically, so a tap on one payload cannot be spent on another (sprigr-apps#2605). See docs/write-protection.md.
 - Every resolver on the gate is a **default, overridable per spec**: `ApprovalSpec.resolveConnection`, `.describeTarget` and `.stampConnection` win over the gate's for that spec alone. Reach for it when one app has two families of write that reach a connection differently (creates that POST under an account, deletes that address a global object id on a path carrying no account). One gate-level rule has to pick one of them, and for the other it prints a false connection on the card a person taps and mixes it into the grant hash. A spec that hits no connection returns `''`.
 - `approvalHash(rawId, connection, ...parts)`, `set(values)`, `seq(values)`: a stable operation identity so a tap survives the model reordering a list or dropping an optional argument on the retry.
 - `undoEnvelope({...})` throws on a blank field. The platform drops the whole envelope on a blank and mints nothing, silently.

package/dist/index.d.ts

@@ -1890,6 +1890,14 @@ interface ApprovalSpec<P = unknown, E = unknown> {
     /**
      * Extra identity parts beyond `rawId + connection`, e.g. a sorted tag set.
      * Use `set()` / `seq()` from `approval-hash`. Never include `confirm`.
+     *
+     * Omitted, the wrapper appends a canonical form of every OTHER argument:
+     * not the `keys` fields, not `confirm` / `_approval_granted`, and not the
+     * gate's `connectionArgs` (sprigr-apps#2605). So a grant approved for one
+     * payload cannot be spent on another; before, a hash-less refund hashed the
+     * same for 10.00 and 250.00. Supply `hash` when that default is too strict
+     * (an order-insensitive set, a free-text field the model rewords) or
+     * `() => []` when the id and connection really are the whole operation.
      */
     hash?: (args: ToolArgs) => Array<string | number | undefined | null>;
     /**
@@ -1972,6 +1980,14 @@ interface ApprovalGateOptions<E, P = E> {
      * `ApprovalSpec.resolveConnection`.
      */
     resolveConnection: (env: E, args: ToolArgs) => Promise<string>;
+    /**
+     * Argument names that only CHOOSE the connection (e.g. `['store']`). They
+     * are left out of the default payload hash (see `ApprovalSpec.hash`)
+     * because the connection is already in the hash in its RESOLVED form, and
+     * the model usually omits the raw argument on the retry. Omit for a
+     * single-connection app.
+     */
+    connectionArgs?: string[];
     /**
      * Re-pin to a resolved connection so lookups and captures hit it. Omit when
      * `P` is `E` and the env needs no pin (a single-connection app).
@@ -2778,6 +2794,136 @@ declare function callerKeyRefusal(key: string, r: Extract<CallerKeyResolution, {
     ok: false;
 }>): string;
 
+/**
+ * Removing mirrored rows from an app's data index, from either execution
+ * context (sprigr/sprigr-app-kit#123).
+ *
+ * An app that mirrors an account into its search index must drop that
+ * account's rows when the install switches to another account or
+ * disconnects; otherwise the next user searches the previous account's data
+ * (sprigr/sprigr-apps#2900). Five apps each wrote the same pieces: a data
+ * client that uses `env.SPRIGR.data` on a dispatched handler and the
+ * install-token routes on an inline route, a prefix listing, and a chunked
+ * delete that reports rather than throws. This module is the one copy.
+ *
+ * The pattern it serves, "snapshot, then purge exactly that":
+ *
+ *   const before = await snapshotIndexIds(env, [{ prefix: 'trello:card:', index: 'cards' }]);
+ *   await storeNewAccountTokens(...);            // the switch
+ *   const res = await deleteSnapshotIds(env, before);
+ *
+ * Rows written after the snapshot (the new account's first sync, a late
+ * webhook) are not in it and survive. `purgeIndexByPrefix` is the one-step
+ * form for a disconnect, where nothing new is being written.
+ *
+ * Neither purge function throws. A purge runs inside a connect or disconnect
+ * flow that must finish; the result carries `error` and `truncated` so the
+ * caller can audit an incomplete purge instead of losing it in a catch.
+ *
+ * Wire contract (workers/provisioning/src/wfp-data.ts in sprigr-team):
+ *   POST /internal/wfp/data/list-ids { prefix, index?, withAcl? }
+ *     200 { objectIDs, total, truncated }   (prefix must be non-empty; cap 50000)
+ *   POST /internal/wfp/data/delete   { objectIDs, index?, withAcl? }
+ *     200 { ok, deleted, index }             (max 1000 ids; unknown ids are no-ops)
+ */
+
+/** Options for the id routes: a logical index, and the app's ACL index. */
+interface DataIdsOpts extends SprigrDataIndexOpts {
+    withAcl?: boolean;
+}
+interface DataListIdsResult {
+    objectIDs: string[];
+    total: number;
+    /** The platform returned its cap's worth and stopped: more rows exist. */
+    truncated: boolean;
+}
+/** How a data call reaches the platform. `none` means it cannot. */
+type DataTransport = 'binding' | 'http' | 'none';
+/** The data surface with every member present, whichever transport carries it. */
+interface DataClient {
+    via: Exclude<DataTransport, 'none'>;
+    import(objects: Array<{
+        objectID: string;
+        [key: string]: unknown;
+    }>, opts?: SprigrDataImportOpts): Promise<{
+        ok: boolean;
+        indexed: number;
+        index: string;
+    }>;
+    search(opts?: SprigrDataSearchOpts): Promise<SprigrDataSearchResult>;
+    get(objectID: string, opts?: SprigrDataIndexOpts): Promise<{
+        ok: boolean;
+        object: Record<string, unknown> | null;
+        index: string;
+    }>;
+    partialUpdate(objects: Array<{
+        objectID: string;
+        [key: string]: unknown;
+    }>, opts?: SprigrDataPartialUpdateOpts): Promise<SprigrDataPartialUpdateResult>;
+    delete(objectIDs: string[], opts?: DataIdsOpts): Promise<{
+        ok: boolean;
+        deleted: number;
+        index: string;
+    }>;
+    listIds(prefix: string, opts?: DataIdsOpts): Promise<DataListIdsResult>;
+}
+/** Max ids one delete call takes (the platform's per-call cap). */
+declare const DATA_DELETE_MAX_IDS = 1000;
+/**
+ * The app's data surface on either transport, or null when neither exists.
+ *
+ * Uses `env.SPRIGR.data` when it carries BOTH `listIds` and `delete` (a
+ * dispatched handler on a current wrapper build); otherwise the install-token
+ * routes, which an inline Next route can reach and an older wrapper build
+ * lacks members for. Every member then exists, so callers never feature-detect.
+ */
+declare function makeDataClient(env: WfpBridgeEnv): DataClient | null;
+/** One prefix to list, in one index. A bare string is a prefix in the default index. */
+type IdPrefixSpec = string | ({
+    prefix: string;
+} & DataIdsOpts);
+/** The ids an index held at one moment, grouped by the index they live in. */
+interface IdSnapshot {
+    groups: Array<{
+        index?: string;
+        withAcl?: boolean;
+        ids: string[];
+    }>;
+    /** Distinct ids across every group. */
+    listed: number;
+    /** A listing hit the platform's cap: the snapshot misses some rows. */
+    truncated: boolean;
+    via: DataTransport;
+    /** Set when a listing failed; the groups hold whatever was listed before it. */
+    error?: string;
+}
+interface PurgeResult {
+    deleted: number;
+    listed: number;
+    truncated: boolean;
+    via: DataTransport;
+    /** Set when the purge stopped early. `deleted` says how far it got. */
+    error?: string;
+}
+/**
+ * Every id matching the prefixes right now. Never throws. With no data path
+ * at all the app cannot have written rows, so the snapshot is empty with
+ * `via: 'none'` and no error.
+ */
+declare function snapshotIndexIds(env: WfpBridgeEnv, prefixes: readonly IdPrefixSpec[]): Promise<IdSnapshot>;
+/**
+ * Delete exactly the ids in a snapshot, in chunks of `chunk` (default and
+ * ceiling 1000). Never throws. A snapshot that carries a listing error is
+ * still purged as far as it goes, and the error is passed on.
+ */
+declare function deleteSnapshotIds(env: WfpBridgeEnv, snapshot: IdSnapshot, opts?: {
+    chunk?: number;
+}): Promise<PurgeResult>;
+/** List, then delete, everything matching the prefixes. Never throws. */
+declare function purgeIndexByPrefix(env: WfpBridgeEnv, prefixes: readonly IdPrefixSpec[], opts?: {
+    chunk?: number;
+}): Promise<PurgeResult>;
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -3092,6 +3238,19 @@ interface SprigrDataApi {
         deleted: number;
         index: string;
     }>;
+    /**
+     * List the objectIDs that start with `prefix` (non-empty, so a listing is
+     * always scoped). Returns at most 50000 with `truncated: true` past that.
+     * `?`-optional for older wrapper builds; `makeDataClient` and
+     * `purgeIndexByPrefix` fall back to the install-token route.
+     */
+    listIds?(prefix: string, opts?: SprigrDataIndexOpts & {
+        withAcl?: boolean;
+    }): Promise<{
+        objectIDs: string[];
+        total?: number;
+        truncated: boolean;
+    }>;
 }
 /**
  * Durable app file storage exposed on `env.SPRIGR.files` by the platform
@@ -3339,4 +3498,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, APPROVAL_PREVIEW_MAX, APP_FILES_ROOT, APP_OWNER_SEGMENT, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalCoverage, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CallerKeyResolution, 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_FILE_READ_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, FILE_REF_SOURCES_HELP, type FetchFileResult, type FetchWithRetryOptions, type FileRef, type FileRefContent, type FileRefEnv, FileRefError, type FileRefErrorCode, type FileRefStream, type FileRefVia, 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 ReadFileRefOptions, type RequireApprovalOptions, type ResolveFileRefOptions, type ResolveViewerOptions, type ResolvedFileRef, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_FILE_HOSTS, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, 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, WORKSPACE_FILE_HOW_TO, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, agentFileKeyFromUrl, appFileUrl, appKeyFromCallerKey, applyConfirmationPolicies, approvalHash, approvalPreview, approvalRecipients, archiveOfferRefusal, attendedFindings, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, callerKeyRefusal, 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, openFileRef, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, putAppFile, putAppFileStream, randomHex, readFileRef, readableStoredKey, recreatedWarning, refuseWithoutForce, requireApproval, resolveFileRef, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };
+export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, APPROVAL_PREVIEW_MAX, APP_FILES_ROOT, APP_OWNER_SEGMENT, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalCoverage, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CallerKeyResolution, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_DELETE_MAX_IDS, DATA_PARTIAL_UPDATE_PATH, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_FILE_READ_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DataClient, type DataIdsOpts, type DataListIdsResult, type DataTransport, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, FILE_REF_SOURCES_HELP, type FetchFileResult, type FetchWithRetryOptions, type FileRef, type FileRefContent, type FileRefEnv, FileRefError, type FileRefErrorCode, type FileRefStream, type FileRefVia, type GetAppFileResult, type HandlerFn, INBOX_SEND_CONTRACT_V1, type IdPrefixSpec, type IdSnapshot, 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 PurgeResult, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ReadFileRefOptions, type RequireApprovalOptions, type ResolveFileRefOptions, type ResolveViewerOptions, type ResolvedFileRef, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_FILE_HOSTS, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, 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, WORKSPACE_FILE_HOW_TO, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, agentFileKeyFromUrl, appFileUrl, appKeyFromCallerKey, applyConfirmationPolicies, approvalHash, approvalPreview, approvalRecipients, archiveOfferRefusal, attendedFindings, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, callerKeyRefusal, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deleteSnapshotIds, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, makeDataClient, manifestIsFresh, offerUndo, openFileRef, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, purgeIndexByPrefix, putAppFile, putAppFileStream, randomHex, readFileRef, readableStoredKey, recreatedWarning, refuseWithoutForce, requireApproval, resolveFileRef, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, snapshotIndexIds, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };

package/dist/index.js

@@ -7,9 +7,9 @@ function constantTimeEqual(a, b) {
   }
   return mismatch === 0;
 }
-async function hmacSha256Hex(secret, message) {
+async function hmacSha256Hex(secret, message2) {
   const keyData = new TextEncoder().encode(secret);
-  const msgData = new TextEncoder().encode(message);
+  const msgData = new TextEncoder().encode(message2);
   const key = await crypto.subtle.importKey(
     "raw",
     keyData,
@@ -162,8 +162,8 @@ function platformBase(env) {
 }
 var AppFilesError = class extends Error {
   status;
-  constructor(message, status) {
-    super(message);
+  constructor(message2, status) {
+    super(message2);
     this.name = "AppFilesError";
     this.status = status;
   }
@@ -210,10 +210,10 @@ function putAppFile(env, args) {
 }
 var STREAM_PUT_MAX_ATTEMPTS = 3;
 var STREAM_PUT_BASE_DELAY_MS = 500;
-function isTransientPutStreamFailure(status, message) {
+function isTransientPutStreamFailure(status, message2) {
   if (status === 503) return true;
   if (status !== 502) return false;
-  const msg = message.toLowerCase();
+  const msg = message2.toLowerCase();
   return msg.includes("(10001)") || msg.includes("(10043)");
 }
 function sleep2(ms) {
@@ -351,8 +351,8 @@ var WORKSPACE_FILE_HOW_TO = "Apps cannot open a file in your own Sprigr storage
 var FILE_REF_SOURCES_HELP = "Pass exactly one of: file_key, a key this app's own tools returned; or file_url, an https Sprigr file link (on files.sprigr.com), either the download_url another app's tool returned or, for a file in your own Sprigr storage, a short-lived link from the files tool's generate_url.";
 var FileRefError = class extends Error {
   code;
-  constructor(code, message) {
-    super(message);
+  constructor(code, message2) {
+    super(message2);
     this.name = "FileRefError";
     this.code = code;
   }
@@ -444,11 +444,11 @@ async function openFileRef(env, ref, opts) {
   const failure = (err) => {
     if (err instanceof FileRefError) return err;
     const name = err instanceof Error ? err.name : "";
-    const message = err instanceof Error ? err.message : String(err);
+    const message2 = err instanceof Error ? err.message : String(err);
     if (name === "TimeoutError" || name === "AbortError") {
       return new FileRefError("timeout", `Reading ${label} took longer than ${Math.round(timeoutMs / 1e3)}s, so it was not read.`);
     }
-    return new FileRefError("read_failed", `Could not read ${label}: ${message}`);
+    return new FileRefError("read_failed", `Could not read ${label}: ${message2}`);
   };
   const openUrl = async (url, via, filename) => {
     let res;
@@ -744,8 +744,8 @@ var SprigrLogValidationError = class extends Error {
   field;
   max;
   length;
-  constructor(message, fields) {
-    super(message);
+  constructor(message2, fields) {
+    super(message2);
     this.name = "SprigrLogValidationError";
     this.index = fields.index;
     this.field = fields.field;
@@ -869,13 +869,13 @@ async function postLog(env, entries, timeoutMs) {
     return { ok: true, written: typeof reply.written === "number" ? reply.written : entries.length };
   } catch (err) {
     const e = err;
-    const message = e instanceof Error ? e.message : String(err);
-    console.warn(`[sprigr-log] log fallback failed: ${message}`);
+    const message2 = e instanceof Error ? e.message : String(err);
+    console.warn(`[sprigr-log] log fallback failed: ${message2}`);
     return {
       ok: false,
       error: e.error ?? (e.status !== void 0 ? "log_failed" : "log_transport_failed"),
       ...e.status !== void 0 ? { status: e.status } : {},
-      detail: e.detail ?? message
+      detail: e.detail ?? message2
     };
   }
 }
@@ -924,8 +924,8 @@ var ACL_INDEX_SUFFIX = "-acl-files";
 var SprigrDataValidationError = class extends Error {
   error;
   index;
-  constructor(message, fields) {
-    super(message);
+  constructor(message2, fields) {
+    super(message2);
     this.name = "SprigrDataValidationError";
     this.error = fields.error;
     if (fields.index !== void 0) this.index = fields.index;
@@ -1098,7 +1098,7 @@ function base64urlDecode2(s) {
     return null;
   }
 }
-async function hmacBytes(secret, message) {
+async function hmacBytes(secret, message2) {
   const key = await crypto.subtle.importKey(
     "raw",
     new TextEncoder().encode(secret),
@@ -1106,7 +1106,7 @@ async function hmacBytes(secret, message) {
     false,
     ["sign"]
   );
-  return new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message)));
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message2)));
 }
 function constantTimeEqualBytes(a, b) {
   if (a.byteLength !== b.byteLength) return false;
@@ -1197,8 +1197,8 @@ async function resolveViewerUserId(headers, env, options = {}) {
 
 // src/tool-wrappers.ts
 var NotConnectedError = class extends Error {
-  constructor(message = "The calling actor has no connection with this app.") {
-    super(message);
+  constructor(message2 = "The calling actor has no connection with this app.") {
+    super(message2);
     this.name = "NotConnectedError";
   }
 };
@@ -1368,8 +1368,8 @@ function approvalPreview(value, max = APPROVAL_PREVIEW_MAX) {
 
 // src/write-protection/undo-envelope.ts
 var InvalidUndoEnvelopeError = class extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message2) {
+    super(message2);
     this.name = "InvalidUndoEnvelopeError";
   }
 };
@@ -1470,6 +1470,23 @@ async function offerUndo(args) {
 }
 
 // src/write-protection/require-approval.ts
+var ATTESTATION_KEYS = ["confirm", APPROVAL_GRANTED_KEY];
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.keys(value).filter((k) => value[k] !== void 0).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+function defaultPayloadParts(params, keys, connectionArgs = []) {
+  const skip = /* @__PURE__ */ new Set([...keys, ...ATTESTATION_KEYS, ...connectionArgs]);
+  const rest = {};
+  for (const [k, v] of Object.entries(params)) {
+    if (!skip.has(k) && v !== void 0) rest[k] = v;
+  }
+  return Object.keys(rest).length ? [canonicalJson(rest)] : [];
+}
 function rawIdOf(args, keys) {
   for (const k of keys) {
     const v = args[k];
@@ -1509,7 +1526,7 @@ async function askPass(name, spec, params, env, opts, hashPrefix) {
   const pinned = await pin(opts, env, connection);
   const describeTarget = spec.describeTarget ?? opts.describeTarget;
   const target = rawId && describeTarget ? await safeLabel(describeTarget, pinned, rawId, name) : rawId || "(unknown id)";
-  const extra = spec.hash ? spec.hash(params) : [];
+  const extra = spec.hash ? spec.hash(params) : defaultPayloadParts(params, spec.keys, opts.connectionArgs);
   const count = countOf(spec, params, rawId);
   return {
     ok: false,
@@ -1969,8 +1986,8 @@ function withSprigrInboxFallback(env) {
   return overlaySprigr(env, { ...existing ?? {}, inbox: { append, folders } });
 }
 var InboxSendRefusal = class extends Error {
-  constructor(code, message) {
-    super(message);
+  constructor(code, message2) {
+    super(message2);
     this.code = code;
     this.name = "InboxSendRefusal";
   }
@@ -2046,6 +2063,137 @@ async function connectDisconnect(env, req) {
   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" });
 }
+
+// src/data-purge.ts
+var BRIDGE_TIMEOUT_MS = 2e4;
+var DATA_DELETE_MAX_IDS = 1e3;
+function injectedData(env) {
+  const data = env.SPRIGR?.data;
+  return data && typeof data === "object" ? data : null;
+}
+function idsOpts(opts) {
+  return {
+    ...opts?.index ? { index: opts.index } : {},
+    ...opts?.withAcl ? { withAcl: true } : {}
+  };
+}
+function makeDataClient(env) {
+  const data = injectedData(env);
+  if (data && typeof data.listIds === "function" && typeof data.delete === "function") {
+    const d = data;
+    return {
+      via: "binding",
+      import: (objects, opts) => d.import(objects, opts),
+      search: (opts) => d.search(opts),
+      get: (id, opts) => d.get(id, opts),
+      partialUpdate: (objects, opts) => partialUpdateData(env, objects, opts),
+      async delete(ids, opts) {
+        const r = await d.delete(ids, opts);
+        return { ok: r?.ok !== false, deleted: typeof r?.deleted === "number" ? r.deleted : ids.length, index: String(r?.index ?? opts?.index ?? "") };
+      },
+      async listIds(prefix, opts) {
+        const r = await d.listIds(prefix, opts);
+        const objectIDs = Array.isArray(r?.objectIDs) ? r.objectIDs : [];
+        return { objectIDs, total: typeof r?.total === "number" ? r.total : objectIDs.length, truncated: r?.truncated === true };
+      }
+    };
+  }
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) return null;
+  const post = (path, body, label) => installTokenPost(bridge, path, body, { label, timeoutMs: BRIDGE_TIMEOUT_MS });
+  return {
+    via: "http",
+    async import(objects, opts) {
+      const r = await post("/internal/wfp/data/import", { objects, ...opts ?? {} }, "data.import");
+      return { ok: r.ok !== false, indexed: typeof r.indexed === "number" ? r.indexed : objects.length, index: String(r.index ?? opts?.index ?? "") };
+    },
+    async search(opts) {
+      return await post("/internal/wfp/data/search", { ...opts ?? {} }, "data.search");
+    },
+    async get(objectID, opts) {
+      const r = await post("/internal/wfp/data/get", { objectID, ...opts?.index ? { index: opts.index } : {} }, "data.get");
+      return { ok: r.ok !== false, object: r.object ?? null, index: String(r.index ?? opts?.index ?? "") };
+    },
+    partialUpdate: (objects, opts) => partialUpdateData(env, objects, opts),
+    async delete(objectIDs, opts) {
+      const r = await post("/internal/wfp/data/delete", { objectIDs, ...idsOpts(opts) }, "data.delete");
+      return { ok: r.ok !== false, deleted: typeof r.deleted === "number" ? r.deleted : objectIDs.length, index: String(r.index ?? opts?.index ?? "") };
+    },
+    async listIds(prefix, opts) {
+      const r = await post("/internal/wfp/data/list-ids", { prefix, ...idsOpts(opts) }, "data.listIds");
+      const objectIDs = Array.isArray(r.objectIDs) ? r.objectIDs : [];
+      return { objectIDs, total: typeof r.total === "number" ? r.total : objectIDs.length, truncated: r.truncated === true };
+    }
+  };
+}
+var message = (err) => err instanceof Error ? err.message : String(err);
+function groupKey(index, withAcl) {
+  return `${withAcl ? "acl" : "plain"}\0${index ?? ""}`;
+}
+async function snapshotIndexIds(env, prefixes) {
+  const client = makeDataClient(env);
+  const snap = { groups: [], listed: 0, truncated: false, via: client?.via ?? "none" };
+  if (!client) return snap;
+  const byGroup = /* @__PURE__ */ new Map();
+  try {
+    for (const spec of prefixes) {
+      const s = typeof spec === "string" ? { prefix: spec } : spec;
+      if (!s.prefix) throw new Error("every prefix must be non-empty (an empty one would list the whole index)");
+      const key = groupKey(s.index, s.withAcl);
+      let group = byGroup.get(key);
+      if (!group) {
+        group = { ...s.index ? { index: s.index } : {}, ...s.withAcl ? { withAcl: true } : {}, ids: /* @__PURE__ */ new Set() };
+        byGroup.set(key, group);
+      }
+      const r = await client.listIds(s.prefix, { index: s.index, withAcl: s.withAcl });
+      r.objectIDs.forEach((id) => {
+        if (id.startsWith(s.prefix)) group.ids.add(id);
+      });
+      snap.truncated ||= r.truncated;
+    }
+  } catch (err) {
+    snap.error = `list: ${message(err)}`;
+  }
+  for (const g of byGroup.values()) {
+    snap.groups.push({ ...g.index ? { index: g.index } : {}, ...g.withAcl ? { withAcl: true } : {}, ids: [...g.ids] });
+    snap.listed += g.ids.size;
+  }
+  return snap;
+}
+async function deleteSnapshotIds(env, snapshot, opts) {
+  const res = {
+    deleted: 0,
+    listed: snapshot.listed,
+    truncated: snapshot.truncated,
+    via: snapshot.via,
+    ...snapshot.error ? { error: snapshot.error } : {}
+  };
+  if (snapshot.listed === 0) return res;
+  const client = makeDataClient(env);
+  if (!client) {
+    res.via = "none";
+    res.error = [res.error, "delete: no data path (env.SPRIGR.data and the install token are both absent)"].filter(Boolean).join("; ");
+    return res;
+  }
+  res.via = client.via;
+  const chunk = Math.min(Math.max(Math.trunc(opts?.chunk ?? DATA_DELETE_MAX_IDS), 1), DATA_DELETE_MAX_IDS);
+  try {
+    for (const g of snapshot.groups) {
+      for (let i = 0; i < g.ids.length; i += chunk) {
+        const ids = g.ids.slice(i, i + chunk);
+        const r = await client.delete(ids, { index: g.index, withAcl: g.withAcl });
+        if (!r.ok) throw new Error(`the platform refused ${ids.length} id(s)${g.index ? ` in ${g.index}` : ""}`);
+        res.deleted += r.deleted;
+      }
+    }
+  } catch (err) {
+    res.error = [res.error, `delete: ${message(err)}`].filter(Boolean).join("; ");
+  }
+  return res;
+}
+async function purgeIndexByPrefix(env, prefixes, opts) {
+  return deleteSnapshotIds(env, await snapshotIndexIds(env, prefixes), opts);
+}
 export {
   ACTOR_RETIRED_HOOK_TOOL,
   ACTOR_RETIRE_REASONS,
@@ -2053,6 +2201,7 @@ export {
   APPROVAL_PREVIEW_MAX,
   APP_FILES_ROOT,
   APP_OWNER_SEGMENT,
+  DATA_DELETE_MAX_IDS,
   DATA_PARTIAL_UPDATE_PATH,
   DEFAULT_EMIT_TIMEOUT_MS,
   DEFAULT_FILE_READ_TIMEOUT_MS,
@@ -2110,6 +2259,7 @@ export {
   decodeState,
   defineInboxSendHandler,
   deleteAppFile,
+  deleteSnapshotIds,
   deriveConfirmationPolicy,
   describeMissingBridge,
   dispatcherApproval,
@@ -2126,6 +2276,7 @@ export {
   isStagingHost,
   listAppFiles,
   logToPlatform,
+  makeDataClient,
   manifestIsFresh,
   offerUndo,
   openFileRef,
@@ -2134,6 +2285,7 @@ export {
   parseActor,
   parseActorRetiredArgs,
   partialUpdateData,
+  purgeIndexByPrefix,
   putAppFile,
   putAppFileStream,
   randomHex,
@@ -2154,6 +2306,7 @@ export {
   seq,
   serializeManifest,
   set,
+  snapshotIndexIds,
   tool,
   undoEnvelope,
   validateLogEntries,

package/package.json

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