@sprigr/apps-app-sdk 0.18.0 → 0.20.0

package/README.md

@@ -15,7 +15,7 @@ The runtime injects the `env.SPRIGR` host object **only on `/__sprigr/*` dispatc
 - `canEmit(env)` — whether an emit could reach the platform by either transport. Gate work that only exists to feed an emit on this, not on `env.SPRIGR?.emit`.
 - `withSprigrEmitFallback(env)` — repair `env.SPRIGR.emit` once and leave existing call sites untouched. Matches the host object's contract (resolves `{ ok, eventId, queued }`, throws on non-2xx).
 - `logToPlatform(env, entry | entry[], opts?)`: durable app logging from either context (`env.SPRIGR.log` on dispatch, `POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/log` from an inline route). Rows land in the platform's `system_logs` Analytics Engine dataset (90-day retention, scoped to the install's company, category prefixed with the app slug), so use it instead of a per-webhook or per-tick audit row in your D1: D1 bills every row written, AE does not. Validation throws synchronously on a cap violation (summary 256, detail 4096, metadata JSON 3840, category 64 matching `[A-Za-z0-9._:-]`, 50 entries per call; nothing is ever truncated); after that the promise never rejects and resolves `{ ok: true, written }` or `{ ok: false, error, status?, detail? }`. Pass `{ waitUntil: ctx.waitUntil.bind(ctx) }` on an inline route so the send outlives the response. `withSprigrLogFallback(env, opts?)` installs `env.SPRIGR.log` once for many call sites; `canLog(env)` gates work whose only purpose is a log row; the `SprigrLogEntry` / `SprigrLogFn` types let your env interface declare the host member.
-- `partialUpdateData(env, objects, opts?)`: merge fields into objects already in the app's data index without reading them first (`env.SPRIGR.data.partialUpdate` on dispatch, `POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/data/partial-update` from an inline route). Deep merge: nested objects recurse, arrays and scalars replace wholesale, absent keys survive, `null` overwrites. `createIfNotExists` defaults to `false`; on a sharded logical index every patch must carry the `shard_field` value or the batch fails with `shard_field_invalid`; 1000 objects per call like `import`. Throws on a bad batch before sending (`SprigrDataValidationError`) and on a platform rejection (`.status`, `.error`, `.detail` on the `Error`), the same contract as `import`. `canPartialUpdate(env)` gates a patch step on either transport; the `SprigrDataPartialUpdateOpts` / `SprigrDataPartialUpdateResult` types let your env interface declare the host member.
+- `partialUpdateData(env, objects, opts?)`: merge fields into objects already in the app's data index without reading them first (`env.SPRIGR.data.partialUpdate` on dispatch, `POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/data/partial-update` from an inline route). Deep merge: nested objects recurse, arrays and scalars replace wholesale, absent keys survive, `null` overwrites. `createIfNotExists` defaults to `false`; on a sharded logical index every patch must carry the `shard_field` value or the batch fails with `shard_field_invalid`; 1000 objects per call like `import`. Throws on a bad batch before sending (`SprigrDataValidationError`) and on a platform rejection (`.status`, `.error`, `.detail` on the `Error`), the same contract as `import`. With `{ withAcl: true }` it patches existing rows of the app's `-acl-files` index: each object carries `objectID` plus `acl_principals` and/or label fields the manifest declares in `data_index.acl_patchable_fields` (never `content`), and an object that omits `acl_principals` keeps its stored ones. `canPartialUpdate(env)` gates a patch step on either transport; the `SprigrDataPartialUpdateOpts` / `SprigrDataPartialUpdateResult` types let your env interface declare the host member.
 - `resolveInstallBridge(env)` / `installTokenPost(bridge, path, body, opts?)`: build your own `/internal/wfp/*` fallback (collections, files, inbox) with the auth and error extraction handled. A non-2xx throws an `Error` whose `.status`, `.error` (the platform's code) and `.detail` are set alongside the message.
 - `overlaySprigr(env, sprigr)` — overlay a patched `SPRIGR` via `Object.create`. Never rebuild a dispatch-path env by spread: the real bindings live on the prototype and `SPRIGR` is non-enumerable, so `{ ...env }` yields an env whose `DB` is `undefined`.
 
@@ -99,8 +99,9 @@ Three platform tiers, and they are not substitutes for each other. Full guide: [
 - `undoEnvelope({...})` throws on a blank field. The platform drops the whole envelope on a blank and mints nothing, silently.
 - `refuseWithoutForce(name, handler, opts)` / `archiveOfferRefusal(...)`: a delete refuses once and offers the vendor's native archive unless `force: true`.
 - `buildConfirmationPolicy({ irreversible, always, rules })` declares a dispatcher's policy beside its action registry; `checkConfirmationPolicy({ policy, registry, ungated, requiredInput })` returns every silent failure (dead rule, `(unset)` placeholder, money threshold, unclassified write) for a one-line test.
+- **Ask once when T1 and T2 both gate an action.** Pass `approval: { covered, conditional }` to `buildConfirmationPolicy` (or `deriveConfirmationPolicy`) and to `checkConfirmationPolicy`: `covered` is your approval spec keys (`Object.keys(APPROVAL_SPECS)`), `conditional` the covered actions your app sends through the gate only under a condition of its own (simpro's `GATE_ONLY_WHEN`), `[]` when there are none. Both are required. Each covered, unconditional, gated action gets `attended: 'approval_card'`, and the platform then skips the confirmation on a turn with a person on it, so the card is the only prompt; unattended runs still confirm. The builder never marks a conditional action, and the check fails a key that no spec covers or that sits on a conditional action (no prompt at all on a call that skips the card), a covered unconditional action without one (it asks twice), and a `conditional` entry with no spec. For flat `requireApproval` tools, run `attendedFindings(tool, rule, { covered, conditional })` over each tool-level rule. Needs a platform with sprigr-team decision 0167; an older one ignores the key and keeps asking twice.
 - `runUndoApply(args, { env, journal, specs, pin })` is the body of your `internal: true` reverse tool: load, re-pin to the journalled connection, restore, drop. `pin` may hand `restore` a different type from the env (a per-actor token state), may throw (`connection_unavailable`) or return null to refuse (`connection_mismatch`); a restore that throws is `restore_failed` and the copy is kept; a successful restore may return `newId`, `notRestored`, `extra` (spread into the payload) and `note` (appended after the fidelity sentence).
 - `safeCapture(scope, name, id, read)` and `offerUndo({ journal, entity, id, before, connection, fidelity, resource, describe, warning })`: the capture-then-offer halves for a write that is not behind an approval card (a dispatcher `update_*` action). `requireApproval` uses the same two on its granted pass.
-- `sprigr-check-write-protection` (bin): every destructive-by-name tool or enumerated dispatcher action must carry a policy, or a reason in `apps/<app>/write-protection.json`; ratchets on `tools/write-protection-baseline.json`.
+- `sprigr-check-write-protection` (bin): every destructive-by-name tool or enumerated dispatcher action must carry a policy, or a reason in `apps/<app>/write-protection.json`; ratchets on `tools/write-protection-baseline.json`. It also refuses an `attended` key with any value other than `'approval_card'`, or on a rule that gates nothing (never baselined).
 
 **Never offer `_undo` for money or messages.** Refunds, captures, cancellations, sent mail: the approval gate is the only control there.

package/bin/check-write-protection.mjs

@@ -93,6 +93,33 @@ export function scanManifest(manifest) {
   return out;
 }
 
+/**
+ * Malformed `attended` keys (sprigr-team decision 0167), as `tool` or
+ * `tool:action` findings. Not baselined: no app may ship one.
+ *
+ * A manifest cannot say whether an approval card really covers the action,
+ * because the specs are code. That half is `checkConfirmationPolicy` /
+ * `attendedFindings` with `approvalCovered`, in the app's own test. What a
+ * manifest CAN show is a key the platform would ignore (any value but
+ * 'approval_card', so the person is quietly asked twice) and a key on a rule
+ * that gates nothing (so there is no confirmation for it to step aside from,
+ * which means it was written by hand).
+ */
+export function scanAttended(manifest) {
+  const out = [];
+  const check = (label, rule) => {
+    if (!rule || typeof rule !== 'object' || !('attended' in rule)) return;
+    if (rule.attended !== 'approval_card') out.push(`${label}: attended must be 'approval_card', got ${JSON.stringify(rule.attended)}`);
+    else if (!isGatedRule(rule)) out.push(`${label}: attended on a rule with no always or when, so it gates nothing`);
+  };
+  for (const tool of manifest.tools || []) {
+    if (!tool || !tool.confirmation || typeof tool.confirmation !== 'object') continue;
+    check(tool.name, tool.confirmation);
+    for (const [a, rule] of Object.entries(tool.confirmation.actions || {})) check(`${tool.name}:${a}`, rule);
+  }
+  return out;
+}
+
 /** Apply the app's allowlist. Returns { violations, stale, unreasoned }. */
 export function applyAllowlist(violations, allowlist) {
   const allow = (allowlist && allowlist.allow) || {};
@@ -151,6 +178,7 @@ export function run(argv, cwd = process.cwd()) {
     const allowlist = existsSync(allowPath) ? readJson(allowPath) : null;
     const raw = scanManifest(manifest);
     const { violations, stale, unreasoned } = applyAllowlist(raw, allowlist);
+    for (const f of scanAttended(manifest)) failures.push(`${slug}: ${f}`);
     for (const k of unreasoned) failures.push(`${slug}: write-protection.json allow entry "${k}" has no reason`);
     for (const k of stale) failures.push(`${slug}: write-protection.json allow entry "${k}" is stale (no longer destructive-and-ungated); remove it`);
 

package/dist/index.d.ts

@@ -1453,6 +1453,18 @@ interface ConfirmRule {
     describe?: string;
     /** Appends "which cannot be undone" so the model cannot undersell it. */
     irreversible?: boolean;
+    /**
+     * `'approval_card'`: this action's human-approval card (an approval spec)
+     * covers it whenever a person is on the turn, so the platform skips the
+     * confirmation there and the person is asked once, by the card. Unattended
+     * runs still confirm. Never hand-write it: pass `approval: { covered,
+     * conditional }` to `buildConfirmationPolicy` / `deriveConfirmationPolicy`
+     * so it follows the specs, and to `checkConfirmationPolicy` so a stale or
+     * conditionally gated key fails the test.
+     * Needs a platform with sprigr-team decision 0167; an older one ignores it
+     * and keeps asking twice.
+     */
+    attended?: 'approval_card';
 }
 interface ConfirmCondition {
     count: string;
@@ -2021,6 +2033,34 @@ interface PolicySource {
     always?: Record<string, string>;
     /** Full rules, for thresholds and anything the two maps above cannot express. */
     rules?: Record<string, ConfirmRule>;
+    /**
+     * Which actions an approval card covers; see {@link ApprovalCoverage}. Each
+     * covered action that also has a rule here, and is not `conditional`, gets
+     * `attended: 'approval_card'`, so the person is asked once on an attended
+     * turn (the card) instead of twice.
+     */
+    approval?: ApprovalCoverage;
+}
+/**
+ * Which actions an approval card covers, for deriving and checking
+ * `attended: 'approval_card'` (sprigr-team decision 0167).
+ *
+ * Both fields are required on purpose. The SDK can see an app's approval
+ * specs but not any condition the app wraps around the gate (simpro sends its
+ * deletes to the gate only with `force: true`), and an action marked attended
+ * whose call skips the card would skip the confirmation too: no prompt at all.
+ * So every app states its conditional actions, `[]` when it has none, and the
+ * builder and the check refuse to mark them.
+ */
+interface ApprovalCoverage {
+    /** Every action with an approval spec: the keys of the specs object you hand to the gate. */
+    covered: Iterable<string>;
+    /**
+     * Covered actions the app sends through the gate only under a condition of
+     * its own (simpro's `GATE_ONLY_WHEN`). Never marked attended; they keep the
+     * confirmation. Pass `[]` when every covered action always reaches the gate.
+     */
+    conditional: Iterable<string>;
 }
 /** Build a sorted `{ actions }` policy. An action named in two groups throws. */
 declare function buildConfirmationPolicy(src: PolicySource): ConfirmationPolicy;
@@ -2053,7 +2093,23 @@ interface PolicyCheckInput {
      */
     nestedUnderInput?: boolean;
     moneyFields?: readonly string[];
+    /**
+     * Which actions an approval card covers. With it, the check fails a rule
+     * carrying `attended: 'approval_card'` on an action no spec covers or that
+     * the app gates conditionally (either way the key removes the person's only
+     * prompt), a covered, unconditional, gated action that lacks the key (it asks
+     * twice), and a `conditional` entry with no spec. Without it, any `attended`
+     * key is itself a finding, because nothing can vouch for it.
+     */
+    approval?: ApprovalCoverage;
 }
+/**
+ * Findings for one rule's `attended` key against the approval coverage.
+ * Exported for apps whose gated tools are flat (`requireApproval`) rather than
+ * one dispatcher: run it over each tool-level rule with the tool names the
+ * specs cover and the ones gated conditionally.
+ */
+declare function attendedFindings(name: string, rule: ConfirmRule, coverage: ApprovalCoverage | null): string[];
 /**
  * Every way a policy can be wrong without erroring, as a list of findings.
  * An app's test is `expect(checkConfirmationPolicy(...)).toEqual([])`.
@@ -2233,6 +2289,8 @@ interface DerivePolicyOptions {
     exempt?: readonly string[];
     /** Explicit rules that win over the verb table (e.g. a hand-written describe). */
     overrides?: Readonly<Record<string, ConfirmRule>>;
+    /** Which actions an approval card covers; see `ApprovalCoverage`. */
+    approval?: ApprovalCoverage;
 }
 interface DerivedPolicy {
     policy: ConfirmationPolicy & {
@@ -2763,14 +2821,20 @@ interface SprigrDataPartialUpdateOpts extends SprigrDataIndexOpts {
      */
     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.
+     * Patch rows already in the app's `-acl-files` index without rewriting
+     * the rest of each row. Each object carries `objectID` plus
+     * `acl_principals` (a non-empty, valid list: re-stamps who may see it)
+     * and/or label fields the manifest declares in
+     * `data_index.acl_patchable_fields` (for example `tags`, `properties`).
+     * An object that omits `acl_principals` keeps its stored ones. `content`
+     * is never patchable, and `createIfNotExists` and `index` are refused. Use
+     * it when the source changes who may see an item, or only its labels,
+     * without changing its content (OneDrive's delta omits sharing-only
+     * changes; a Dropbox tag edit leaves the file's text as it was). The
+     * re-stamp needs a platform with sprigr/sprigr-team#9843, label fields one
+     * with #10371 (an older one answers `acl_partial_update_fields`: fall back
+     * to a whole-row import). Older wrappers drop the flag, which
+     * `partialUpdateData` detects and throws on.
      */
     withAcl?: boolean;
 }
@@ -3143,4 +3207,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 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_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 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, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorRetiredHook, actorTool, agentFileKeyFromUrl, appFileUrl, appKeyFromCallerKey, applyConfirmationPolicies, approvalHash, approvalPreview, approvalRecipients, archiveOfferRefusal, 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, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, putAppFile, putAppFileStream, randomHex, readableStoredKey, recreatedWarning, refuseWithoutForce, requireApproval, 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_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 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, 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, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, putAppFile, putAppFileStream, randomHex, readableStoredKey, 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

@@ -580,19 +580,26 @@ function checkAclRestamp(objects, opts, at) {
   }
   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) {
+    if ("content" in o) {
       throw new SprigrDataValidationError(
-        `${at}: objects[${i}] carries "${extra}"; a withAcl partial update sets only objectID and acl_principals (write content with data.import withAcl)`,
+        `${at}: objects[${i}] carries "content"; a withAcl partial update never writes extracted text (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
-      });
+    if (!Object.keys(o).some((k) => k !== "objectID")) {
+      throw new SprigrDataValidationError(
+        `${at}: objects[${i}] sets nothing; send acl_principals or a field your manifest declares in data_index.acl_patchable_fields`,
+        { error: "acl_partial_update_empty", index: i }
+      );
+    }
+    if ("acl_principals" in o) {
+      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
+        });
+      }
     }
   }
 }
@@ -1360,6 +1367,13 @@ async function runUndoApply(args, opts) {
 }
 
 // src/write-protection/confirmation-policy.ts
+function coverageSets(c) {
+  if (!c) return null;
+  if (c.covered == null || c.conditional == null) {
+    throw new Error("approval coverage needs both `covered` and `conditional` (pass [] when no action is gated conditionally)");
+  }
+  return { covered: new Set(c.covered), conditional: new Set(c.conditional) };
+}
 function buildConfirmationPolicy(src) {
   const actions = {};
   const put = (name, rule, group) => {
@@ -1369,6 +1383,10 @@ function buildConfirmationPolicy(src) {
   for (const [name, describe] of Object.entries(src.irreversible ?? {})) put(name, { always: true, describe, irreversible: true }, "irreversible");
   for (const [name, describe] of Object.entries(src.always ?? {})) put(name, { always: true, describe }, "always");
   for (const [name, rule] of Object.entries(src.rules ?? {})) put(name, rule, "rules");
+  const cov = coverageSets(src.approval);
+  for (const name of cov?.covered ?? []) {
+    if (actions[name] && !cov?.conditional.has(name)) actions[name] = { ...actions[name], attended: "approval_card" };
+  }
   return { actions: Object.fromEntries(Object.entries(actions).sort(([a], [b]) => a.localeCompare(b))) };
 }
 var DEFAULT_WRITE_PREFIXES = [
@@ -1472,6 +1490,22 @@ var PLACEHOLDER = /\{([a-zA-Z0-9_.]+)\}/g;
 function conditions(rule) {
   return !rule.when ? [] : Array.isArray(rule.when) ? rule.when : [rule.when];
 }
+function attendedFindings(name, rule, coverage) {
+  const cov = coverageSets(coverage ?? void 0);
+  const out = [];
+  const attended = rule.attended;
+  const gated = rule.always === true || conditions(rule).length > 0;
+  if (attended !== void 0 && attended !== "approval_card") {
+    out.push(`${name}: attended must be 'approval_card' (got ${JSON.stringify(attended)}); the platform ignores anything else`);
+  } else if (attended === "approval_card") {
+    if (!cov) out.push(`${name}: attended: 'approval_card' cannot be checked; pass approval: { covered, conditional }`);
+    else if (!cov.covered.has(name)) out.push(`${name}: attended: 'approval_card' but no approval spec covers it, so it removes the only prompt`);
+    else if (cov.conditional.has(name)) out.push(`${name}: attended: 'approval_card' on a conditionally gated action, so a call that skips the card gets no prompt at all`);
+  } else if (cov?.covered.has(name) && !cov.conditional.has(name) && gated) {
+    out.push(`${name}: an approval spec covers it but the rule lacks attended: 'approval_card', so it asks twice`);
+  }
+  return out;
+}
 function checkConfirmationPolicy(input) {
   const registry = new Set(input.registry);
   const ungated = input.ungated ?? [];
@@ -1479,8 +1513,13 @@ function checkConfirmationPolicy(input) {
   const nested = input.nestedUnderInput ?? true;
   const money = new Set(input.moneyFields ?? DEFAULT_MONEY_FIELDS);
   const actions = input.policy.actions ?? {};
+  const cov = coverageSets(input.approval);
   const out = [];
+  for (const name of cov?.conditional ?? []) {
+    if (!cov?.covered.has(name)) out.push(`approval.conditional: "${name}" has no approval spec (not in covered)`);
+  }
   for (const [name, rule] of Object.entries(actions)) {
+    out.push(...attendedFindings(name, rule, input.approval ?? null));
     if (!registry.has(name)) out.push(`dead rule: "${name}" is not in the registry, so it gates nothing`);
     if (!rule.always && conditions(rule).length === 0) out.push(`${name}: rule says nothing (no always, no when)`);
     if (!rule.describe || !rule.describe.trim()) out.push(`${name}: describe missing`);
@@ -1589,7 +1628,7 @@ function deriveConfirmationPolicy(registry, opts) {
     }
     if (!hit) unmatched.push(name);
   }
-  const policy = buildConfirmationPolicy({ irreversible, always, rules: overrides });
+  const policy = buildConfirmationPolicy({ irreversible, always, rules: overrides, approval: opts.approval });
   return { policy, ungated, unmatched };
 }
 function commonDestructiveVerbs(subject) {
@@ -1826,6 +1865,7 @@ export {
   approvalPreview,
   approvalRecipients,
   archiveOfferRefusal,
+  attendedFindings,
   base64ToBytes,
   buildConfirmationPolicy,
   buildMarketplaceWebhookUrl,

package/package.json

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