@sprigr/apps-app-sdk 0.8.6 → 0.8.8

package/dist/index.d.ts

@@ -902,6 +902,15 @@ interface AppApprovalEnvelope {
      * retry silently discards the tap. See `approvalHash`.
      */
     hash?: string;
+    /**
+     * How many records this ONE call touches, as you count them. Required for a
+     * workflow step's standing approval to cover the call on an unattended run
+     * (sprigr-team decision 0039): the platform cannot see inside your write,
+     * so an envelope with no count gets a person or nothing. The wrappers set
+     * it to 1 for a single-target spec; a batch action supplies
+     * `ApprovalSpec.count`.
+     */
+    count?: number;
 }
 /**
  * Platform-stamped marker telling an app that a human approved this call. The
@@ -1105,6 +1114,14 @@ interface ApprovalSpec<P = unknown> {
      * Use `set()` / `seq()` from `approval-hash`. Never include `confirm`.
      */
     hash?: (args: ToolArgs) => Array<string | number | undefined | null>;
+    /**
+     * How many records this call touches, for `_approval.count`. Omit for a
+     * single-target tool (the wrapper reports 1 when a `keys` id resolved, and
+     * nothing when none did). A batch action (delete these ids, tag these
+     * products) MUST supply it, or it reports nothing and no standing approval
+     * can ever cover it, which is the safe side but not the useful one.
+     */
+    count?: (args: ToolArgs) => number;
     /** Present only for tools whose write can be (partly) reversed. */
     undo?: UndoCaptureSpec<P>;
 }
@@ -1489,6 +1506,57 @@ declare function manifestIsFresh(manifest: ManifestLike, opts: ApplyPoliciesOpti
 /** The manifest, serialised the way the repo commits it (2-space, trailing newline). */
 declare function serializeManifest(manifest: ManifestLike): string;
 
+/**
+ * Derive a confirmation policy from an action registry by NAME, for apps
+ * whose registry carries no destructive flag: the verb prefix says what an
+ * action does (`delete_`, `void_`, `cancel_`, `archive_`), so the policy
+ * follows from a small table of verb rules instead of a hand-kept list
+ * that drifts the moment an action is added.
+ *
+ * Each rule names a prefix (or regex), the tier it lands in, and how to
+ * phrase the describe from the rest of the name. The first matching rule
+ * wins, so put the specific ones first.
+ */
+
+interface VerbRule {
+    /** A name prefix (`'delete_'`) or a regex tested against the whole name. */
+    match: string | RegExp;
+    /** `irreversible` marks the card "cannot be undone"; `always` is a plain confirmation. */
+    tier: 'irreversible' | 'always';
+    /**
+     * Describe for a matching action. Receives the full name and `rest`: the
+     * name with the matched prefix removed and underscores turned to spaces
+     * (for a regex match, the whole name spaced). No trailing period.
+     */
+    describe: (name: string, rest: string) => string;
+}
+interface DerivePolicyOptions {
+    /** Verb rules, most specific first. */
+    rules: readonly VerbRule[];
+    /** Actions to leave ungated even though a rule matches (returned in `ungated`). */
+    exempt?: readonly string[];
+    /** Explicit rules that win over the verb table (e.g. a hand-written describe). */
+    overrides?: Readonly<Record<string, ConfirmRule>>;
+}
+interface DerivedPolicy {
+    policy: ConfirmationPolicy & {
+        actions: Record<string, ConfirmRule>;
+    };
+    /** Registry names a rule matched but `exempt` kept ungated. */
+    ungated: string[];
+    /** Registry names no rule matched (reads and writes the table does not classify). */
+    unmatched: string[];
+}
+/** Build a policy over `registry` from the verb table; see the file comment. */
+declare function deriveConfirmationPolicy(registry: Iterable<string>, opts: DerivePolicyOptions): DerivedPolicy;
+/**
+ * The verb table most registries need: hard deletes, voids, refunds and
+ * cancellations cannot be undone; archives, removals from a parent and
+ * unassignments are plain confirmations. `subject` names the system for
+ * the describe ("in Xero").
+ */
+declare function commonDestructiveVerbs(subject: string): VerbRule[];
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -1889,4 +1957,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 AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, 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 ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type RestoreResult, type RestoreSpec, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, withSprigrEmitFallback };
+export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_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 ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type RestoreResult, type RestoreSpec, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, type VerbRule, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, commonDestructiveVerbs, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, withSprigrEmitFallback };

package/dist/index.js

@@ -614,6 +614,17 @@ function rawIdOf(args, keys) {
   }
   return "";
 }
+function countOf(spec, params, rawId) {
+  if (spec.count) {
+    try {
+      const n = spec.count(params);
+      return Number.isFinite(n) && n >= 0 ? Math.floor(n) : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  return rawId ? 1 : void 0;
+}
 function isOk(result) {
   return !!result && typeof result === "object" && result.ok !== false;
 }
@@ -635,11 +646,13 @@ async function askPass(name, spec, params, env, opts, hashPrefix) {
   const pinned = await pin(opts, env, connection);
   const target = rawId && opts.describeTarget ? await safeLabel(opts.describeTarget, pinned, rawId, name) : rawId || "(unknown id)";
   const extra = spec.hash ? spec.hash(params) : [];
+  const count = countOf(spec, params, rawId);
   return {
     ok: false,
     _approval: {
       ...spec.describe(target, params, connection),
-      hash: approvalHash(...hashPrefix, rawId, connection, ...extra)
+      hash: approvalHash(...hashPrefix, rawId, connection, ...extra),
+      ...count !== void 0 ? { count } : {}
     }
   };
 }
@@ -982,6 +995,56 @@ function serializeManifest(manifest) {
   return `${JSON.stringify(manifest, null, 2)}
 `;
 }
+
+// src/write-protection/derive-policy.ts
+function spaced(s) {
+  return s.replace(/_/g, " ");
+}
+function matchRule(name, rule) {
+  if (typeof rule.match === "string") {
+    return name.startsWith(rule.match) ? spaced(name.slice(rule.match.length)) : null;
+  }
+  return rule.match.test(name) ? spaced(name) : null;
+}
+function deriveConfirmationPolicy(registry, opts) {
+  const exempt = new Set(opts.exempt ?? []);
+  const irreversible = {};
+  const always = {};
+  const ungated = [];
+  const unmatched = [];
+  const overrides = opts.overrides ?? {};
+  for (const name of registry) {
+    if (overrides[name]) continue;
+    let hit = false;
+    for (const rule of opts.rules) {
+      const rest = matchRule(name, rule);
+      if (rest == null) continue;
+      hit = true;
+      if (exempt.has(name)) ungated.push(name);
+      else (rule.tier === "irreversible" ? irreversible : always)[name] = rule.describe(name, rest);
+      break;
+    }
+    if (!hit) unmatched.push(name);
+  }
+  const policy = buildConfirmationPolicy({ irreversible, always, rules: overrides });
+  return { policy, ungated, unmatched };
+}
+function commonDestructiveVerbs(subject) {
+  const where = subject ? ` ${subject}` : "";
+  return [
+    { match: "delete_", tier: "irreversible", describe: (_n, rest) => `Delete ${rest}${where}` },
+    { match: "void_", tier: "irreversible", describe: (_n, rest) => `Void ${rest}${where}` },
+    { match: "refund_", tier: "irreversible", describe: (_n, rest) => `Refund ${rest}${where}` },
+    { match: "cancel_", tier: "irreversible", describe: (_n, rest) => `Cancel ${rest}${where}` },
+    { match: "destroy_", tier: "irreversible", describe: (_n, rest) => `Destroy ${rest}${where}` },
+    { match: "purge_", tier: "irreversible", describe: (_n, rest) => `Purge ${rest}${where}` },
+    { match: "revoke_", tier: "irreversible", describe: (_n, rest) => `Revoke ${rest}${where}` },
+    { match: "archive_", tier: "always", describe: (_n, rest) => `Archive ${rest}${where}` },
+    { match: "remove_", tier: "always", describe: (_n, rest) => `Remove ${rest}${where}` },
+    { match: "unassign_", tier: "always", describe: (_n, rest) => `Unassign ${rest}${where}` },
+    { match: "deactivate_", tier: "always", describe: (_n, rest) => `Deactivate ${rest}${where}` }
+  ];
+}
 export {
   APPROVAL_GRANTED_KEY,
   DEFAULT_EMIT_TIMEOUT_MS,
@@ -1003,11 +1066,13 @@ export {
   bytesToBase64,
   canEmit,
   checkConfirmationPolicy,
+  commonDestructiveVerbs,
   constantTimeEqual,
   createMarketplaceEmitter,
   createToolWrappers,
   decodeState,
   deleteAppFile,
+  deriveConfirmationPolicy,
   describeMissingBridge,
   dispatcherApproval,
   emitMarketplaceEvent,

package/package.json

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