@sprigr/apps-app-sdk 0.8.0 → 0.8.1

package/README.md

@@ -72,7 +72,8 @@ 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.
-- `runUndoApply(args, { env, journal, specs, pin })` is the body of your `internal: true` reverse tool: load, re-pin to the journalled connection, restore, drop.
+- `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.
+- `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`.
 
 **Never offer `_undo` for money or messages.** Refunds, captures, cancellations, sent mail: the approval gate is the only control there.

package/dist/index.d.ts

@@ -1190,19 +1190,28 @@ declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, sp
  * `pin`, a replay lands on the install's CURRENT default and rebuilds the
  * object in the wrong customer account, and nothing errors.
  *
+ * `E` is the env the tool receives; `P` is what `pin` hands to `restore`. For
+ * a store-pinned env they are the same type (Shopify). For an app that
+ * re-authenticates per actor and organisation, `P` is the fresh token state
+ * (Xero), which is why they are separate parameters.
+ *
  * Extracted from the Shopify and Xero `undo-apply.ts` handlers, which were
  * byte-similar apart from their restore call and their pin.
  */
 
-interface RestoreSpec<E, T = Record<string, unknown>> {
+interface RestoreSpec<P, T = Record<string, unknown>> {
     resource: string;
     fidelity: UndoFidelity;
-    /** Rebuild or write back, through the PINNED env. */
-    restore: (pinnedEnv: E, before: T, row: JournalRowLike<T>) => Promise<{
+    /**
+     * Rebuild or write back, through the PINNED connection. May return
+     * `{ ok: false, error }` or throw; both become `restore_failed` and the
+     * before-image is kept.
+     */
+    restore: (pinned: P, before: T, row: JournalRowLike<T>) => Promise<{
         ok: boolean;
         newId?: string;
         error?: string;
-    }>;
+    } | void>;
     /** What the restore does NOT bring back, folded into the note verbatim. */
     notRestored?: string;
 }
@@ -1212,19 +1221,20 @@ interface JournalRowLike<T = unknown> {
     connection: string | null;
     before: T;
 }
-interface UndoApplyOptions<E> {
+interface UndoApplyOptions<E, P = E> {
     env: E;
     journal: {
         loadBefore<T = unknown>(ref: string): Promise<JournalRowLike<T> | null>;
         dropBefore(ref: string): Promise<void>;
     };
-    specs: Record<string, RestoreSpec<E>>;
+    specs: Record<string, RestoreSpec<P>>;
     /**
-     * Re-pin the env to the journalled connection. May be async (re-auth per
-     * actor, as Xero does) and may throw or return null to REFUSE, e.g. a
-     * session-stateful app whose current business differs from the row's.
+     * Re-pin to the journalled connection. May be async (re-auth per actor, as
+     * Xero does). Throw to report `connection_unavailable`; return null to
+     * REFUSE with `connection_mismatch`, e.g. a session-stateful app whose
+     * current business differs from the row's.
      */
-    pin: (env: E, connection: string | null, args: ToolArgs) => Promise<E | null> | E | null;
+    pin: (env: E, connection: string | null, args: ToolArgs) => Promise<P | null> | P | null;
 }
 type UndoApplyResult = {
     ok: true;
@@ -1241,7 +1251,7 @@ type UndoApplyResult = {
     note: string;
 };
 /** Run the reversal. Every failure names what it was and states that nothing changed. */
-declare function runUndoApply<E>(args: ToolArgs, opts: UndoApplyOptions<E>): Promise<UndoApplyResult>;
+declare function runUndoApply<E, P = E>(args: ToolArgs, opts: UndoApplyOptions<E, P>): Promise<UndoApplyResult>;
 
 /**
  * Declare a dispatcher tool's confirmation policy beside its action registry,
@@ -1300,6 +1310,55 @@ interface PolicyCheckInput {
  */
 declare function checkConfirmationPolicy(input: PolicyCheckInput): string[];
 
+/**
+ * The two halves of offering an undo, for handlers that are not behind an
+ * approval card (a dispatcher's `update_*` actions, for instance). The order
+ * is the whole contract:
+ *
+ *   const before = await safeCapture(scope, action, id, () => read(pinned, id));
+ *   const result = await write(pinned, input);              // happens regardless
+ *   const _undo  = await offerUndo({ journal, entity: action, id, before, connection, ... });
+ *   return { ok: true, result, ...(_undo ? { _undo } : {}) };
+ *
+ * `requireApproval` uses the same two functions on its granted pass.
+ */
+/**
+ * Read the before-image, degrading to null on any failure. A capture that
+ * throws (404, scope denied, network) is not a reason to refuse a write the
+ * user asked for; it is a reason to offer no undo, and to say so in the log.
+ */
+declare function safeCapture(scope: string, name: string, id: string, capture: () => Promise<unknown>): Promise<Record<string, unknown> | null>;
+interface OfferUndoArgs {
+    journal: CaptureJournal;
+    /** The tool or action that captured; the reverse tool looks the spec up by it. */
+    entity: string;
+    id: string;
+    /** From `safeCapture`. Null means no undo is offered, deliberately. */
+    before: Record<string, unknown> | null;
+    /** The resolved store / organisation / business, or null for a single-connection app. */
+    connection: string | null;
+    fidelity: UndoFidelity;
+    resource: string;
+    /** How the change reads in `list_undoable_changes`; the connection is appended when present. */
+    describe: (before: Record<string, unknown>, id: string) => string;
+    /** Relayed verbatim; never empty. */
+    warning: string;
+    /** Word between the description and the connection: "on" for a store, "in" for an organisation. */
+    connectionPreposition?: 'on' | 'in';
+    /**
+     * What `describes` calls the connection, when the journalled id is not
+     * readable by a person (a Xero tenantId). Defaults to `connection`. The
+     * journal row always stores `connection` itself, because that is the pin.
+     */
+    connectionLabel?: string;
+}
+/**
+ * Store the before-image and build the `_undo` envelope, or return undefined
+ * when there is nothing to offer. Never returns an envelope for a null capture
+ * or a journal that could not store the copy.
+ */
+declare function offerUndo(args: OfferUndoArgs): Promise<AppUndoEnvelope | undefined>;
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -1700,4 +1759,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 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 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 MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, 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, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, seq, set, tool, undoEnvelope, withSprigrEmitFallback };
+export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, 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 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 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 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, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, safeCapture, seq, set, tool, undoEnvelope, withSprigrEmitFallback };

package/dist/index.js

@@ -575,6 +575,37 @@ function refuseWithoutForce(deleteAction, inner, opts) {
   };
 }
 
+// src/write-protection/undo-capture.ts
+async function safeCapture(scope, name, id, capture) {
+  try {
+    const got = await capture();
+    return got && typeof got === "object" ? got : null;
+  } catch (err) {
+    console.warn(`[${scope}] ${name} ${id}: capture failed, writing without undo: ${String(err)}`);
+    return null;
+  }
+}
+async function offerUndo(args) {
+  if (!args.before) return void 0;
+  const captured = await args.journal.captureBefore({
+    entity: args.entity,
+    originalId: args.id,
+    before: args.before,
+    connection: args.connection
+  });
+  if (!captured) return void 0;
+  const base = args.describe(args.before, args.id);
+  const prep = args.connectionPreposition ?? "on";
+  const label = args.connectionLabel ?? args.connection;
+  return undoEnvelope({
+    fidelity: args.fidelity,
+    warning: args.warning,
+    describes: label ? `${base} ${prep} ${label}` : base,
+    resource: args.resource,
+    ref: captured.ref
+  });
+}
+
 // src/write-protection/require-approval.ts
 function rawIdOf(args, keys) {
   for (const k of keys) {
@@ -635,33 +666,22 @@ async function granted(name, spec, args, env, ctx, inner, opts) {
   const id = rawIdOf(args, spec.keys);
   if (!undo || !id) return stamp(await inner(args, env, ctx));
   const pinned = connection ? opts.pinEnv(env, connection) : env;
-  let before = null;
-  try {
-    const got = await undo.capture(pinned, id, args);
-    before = got && typeof got === "object" ? got : null;
-  } catch (err) {
-    console.warn(`[${opts.scope}] ${name} ${id}: capture failed, writing without undo: ${String(err)}`);
-  }
+  const before = await safeCapture(opts.scope, name, id, () => undo.capture(pinned, id, args));
   const result = await inner(args, env, ctx);
   if (!isOk(result) || !before) return stamp(result);
-  const captured = await opts.journal(env).captureBefore({
+  const envelope = await offerUndo({
+    journal: opts.journal(env),
     entity: name,
-    originalId: id,
+    id,
     before,
-    connection: connection || null
+    connection: connection || null,
+    fidelity: undo.fidelity,
+    resource: undo.resource,
+    describe: undo.describe,
+    warning: undo.warning(id, before)
   });
-  if (!captured) return stamp(result);
-  const describes = connection ? `${undo.describe(before, id)} on ${connection}` : undo.describe(before, id);
-  return {
-    ...stamp(result),
-    _undo: undoEnvelope({
-      fidelity: undo.fidelity,
-      warning: undo.warning(id, before),
-      describes,
-      resource: undo.resource,
-      ref: captured.ref
-    })
-  };
+  if (!envelope) return stamp(result);
+  return { ...stamp(result), _undo: envelope };
 }
 
 // src/write-protection/undo-apply.ts
@@ -698,14 +718,19 @@ async function runUndoApply(args, opts) {
       note: `Could not reach the connection this change was made in${row.connection ? ` (${row.connection})` : ""}: ${String(err)}. Nothing was changed.`
     };
   }
-  if (!pinned) {
+  if (pinned === null || pinned === void 0) {
     return {
       ok: false,
       error: "connection_mismatch",
       note: `This change was made in ${row.connection ?? "a different connection"}, which is not the one currently selected. Switch to it and retry. Nothing was changed.`
     };
   }
-  const result = await spec.restore(pinned, before, row);
+  let result;
+  try {
+    result = await spec.restore(pinned, before, row) ?? { ok: true };
+  } catch (err) {
+    result = { ok: false, error: String(err) };
+  }
   if (!result.ok) {
     return {
       ok: false,
@@ -922,6 +947,7 @@ export {
   isNotConnectedError,
   isStagingHost,
   listAppFiles,
+  offerUndo,
   overlaySprigr,
   ownerFromActorKey,
   parseActor,
@@ -936,6 +962,7 @@ export {
   resolveOAuthBouncerCallbackUrl,
   resolvePlatformWebhookBase,
   runUndoApply,
+  safeCapture,
   seq,
   set,
   tool,

package/package.json

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