@sprigr/apps-app-sdk 0.8.4 → 0.8.5

package/README.md

@@ -73,7 +73,7 @@ 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. `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.
+- `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`.
 

package/dist/index.d.ts

@@ -1153,9 +1153,11 @@ interface ApprovalGateOptions<E, P = E> {
     /**
      * Human label for a raw id, looked up THROUGH the pinned connection. Fall
      * back to the id on any miss; never guess, a confidently wrong card is worse
-     * than a terse one. Omit to always show the raw id.
+     * than a terse one. Omit to always show the raw id. `name` is the tool, or
+     * for a dispatcher the action, so a lookup can route by resource type when
+     * the id alone does not say what it is (an Asana gid).
      */
-    describeTarget?: (pinned: P, id: string) => Promise<string>;
+    describeTarget?: (pinned: P, id: string, name: string) => Promise<string>;
     /**
      * Where before-images go. Required when any spec declares `undo`. The
      * journal's own capture returns null rather than throwing, and this wrapper
@@ -1269,6 +1271,13 @@ interface RestoreResult {
     error?: string;
     notRestored?: string;
     extra?: Record<string, unknown>;
+    /**
+     * Free-form detail appended to the runner's note (the new gid, rows it
+     * could not refile, a sticker the vendor will not remove). The runner's own
+     * sentence on fidelity stays first so the model reads "replacement, not an
+     * undo" before the detail.
+     */
+    note?: string;
 }
 interface JournalRowLike<T = unknown> {
     entity: string;

package/dist/index.js

@@ -617,9 +617,9 @@ function rawIdOf(args, keys) {
 function isOk(result) {
   return !!result && typeof result === "object" && result.ok !== false;
 }
-async function safeLabel(fn, pinned, id) {
+async function safeLabel(fn, pinned, id, name) {
   try {
-    const label = await fn(pinned, id);
+    const label = await fn(pinned, id, name);
     return label && label.trim() ? label : id;
   } catch {
     return id;
@@ -629,11 +629,11 @@ async function pin(opts, env, connection) {
   if (!connection || !opts.pinEnv) return env;
   return opts.pinEnv(env, connection);
 }
-async function askPass(spec, params, env, opts, hashPrefix) {
+async function askPass(name, spec, params, env, opts, hashPrefix) {
   const connection = await opts.resolveConnection(env, params);
   const rawId = rawIdOf(params, spec.keys);
   const pinned = await pin(opts, env, connection);
-  const target = rawId && opts.describeTarget ? await safeLabel(opts.describeTarget, pinned, rawId) : rawId || "(unknown id)";
+  const target = rawId && opts.describeTarget ? await safeLabel(opts.describeTarget, pinned, rawId, name) : rawId || "(unknown id)";
   const extra = spec.hash ? spec.hash(params) : [];
   return {
     ok: false,
@@ -688,7 +688,7 @@ function requireApproval(handlers, specs, opts) {
         const { [APPROVAL_GRANTED_KEY]: _granted, ...rest } = a;
         return grantedPass(name, spec, rest, env, opts, () => inner(rest, env, ctx));
       }
-      return askPass(spec, a, env, opts, []);
+      return askPass(name, spec, a, env, opts, []);
     };
   }
   return gated;
@@ -707,7 +707,7 @@ function dispatcherApproval(specs, opts) {
       if (a[APPROVAL_GRANTED_KEY] === true) {
         return grantedPass(action, spec, params, env, opts, write);
       }
-      return askPass(spec, params, env, opts, [action]);
+      return askPass(action, spec, params, env, opts, [action]);
     }
   };
 }
@@ -733,7 +733,7 @@ async function runUndoApply(args, opts) {
     };
   }
   const before = row.before;
-  if (!before || typeof before !== "object") {
+  if (!before || typeof before !== "object" || Array.isArray(before)) {
     return { ok: false, error: "before_image_unreadable", note: "The saved copy could not be read back. Nothing was changed." };
   }
   let pinned;
@@ -769,6 +769,7 @@ async function runUndoApply(args, opts) {
   await opts.journal.dropBefore(ref);
   const recreated = spec.fidelity === "recreated";
   const notRestored = result.notRestored ?? spec.notRestored;
+  const suffix = result.note && result.note.trim() ? ` ${result.note.trim()}` : "";
   return {
     ok: true,
     ...result.extra ?? {},
@@ -778,7 +779,7 @@ async function runUndoApply(args, opts) {
     new_id: result.newId ?? null,
     fidelity: spec.fidelity,
     ...notRestored ? { not_restored: notRestored } : {},
-    note: recreated ? `Created a NEW ${spec.resource}${result.newId ? ` (${result.newId})` : ""} from the saved copy. The original ${row.original_id} is still gone and its id will never be reissued.${notRestored ? ` Not restored: ${notRestored}.` : ""} Report this as a replacement, not as an undo.` : `Restored ${spec.resource} ${row.original_id} to its saved values.${notRestored ? ` Not restored: ${notRestored}.` : ""} Anything changed since the capture was overwritten.`
+    note: recreated ? `Created a NEW ${spec.resource}${result.newId ? ` (${result.newId})` : ""} from the saved copy. The original ${row.original_id} is still gone and its id will never be reissued.${notRestored ? ` Not restored: ${notRestored}.` : ""} Report this as a replacement, not as an undo.${suffix}` : `Restored ${spec.resource} ${row.original_id} to its saved values.${notRestored ? ` Not restored: ${notRestored}.` : ""} Anything changed since the capture was overwritten.${suffix}`
   };
 }
 

package/package.json

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