@sprigr/apps-app-sdk 0.9.0 → 0.10.0

package/README.md

@@ -69,6 +69,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.
+- 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.
 - `refuseWithoutForce(name, handler, opts)` / `archiveOfferRefusal(...)`: a delete refuses once and offers the vendor's native archive unless `force: true`.

package/dist/index.d.ts

@@ -1250,12 +1250,25 @@ declare function refuseWithoutForce<E>(deleteAction: string, inner: ToolHandler<
  *    `_undo` ON A NULL CAPTURE. A failed capture does not fail the write: the
  *    user asked for it and a human approved it. It degrades to no token.
  *
+ * Every resolver here is gate-level by default and overridable per spec:
+ * `ApprovalSpec.resolveConnection` / `.describeTarget` / `.stampConnection`
+ * win over the gate's for that spec alone. One rule cannot describe two
+ * families of write truthfully, and both consumers of the resolved value are
+ * safety surfaces (the card a person reads, and the grant hash).
+ *
  * Generalised from the Shopify app's `require-approval.ts`; the per-tool
  * questions stay in the app, because only the app knows what cannot be walked
  * back.
  */
-/** Per-tool (or per-action) spec: how the card reads, and (optionally) how to journal a before-image. */
-interface ApprovalSpec<P = unknown> {
+/**
+ * Per-tool (or per-action) spec: how the card reads, and (optionally) how to
+ * journal a before-image.
+ *
+ * `P` is the pinned connection handed to `capture` / `describeTarget`; `E` is
+ * the env a spec-level `resolveConnection` receives. `E` defaults to `unknown`
+ * so `ApprovalSpec<MyState>` keeps working unchanged.
+ */
+interface ApprovalSpec<P = unknown, E = unknown> {
     /**
      * Arg names that may carry the target id, most specific first. ONE list, used
      * for both the card label and the grant hash, so the two cannot drift apart
@@ -1284,6 +1297,27 @@ interface ApprovalSpec<P = unknown> {
      * can ever cover it, which is the safe side but not the useful one.
      */
     count?: (args: ToolArgs) => number;
+    /**
+     * Overrides the gate's `resolveConnection` for THIS spec only; the gate's
+     * value stays the default for every spec that omits it.
+     *
+     * One gate serves every spec, so a gate-level resolver has to pick one rule.
+     * That is wrong the moment an app has two families of write that reach a
+     * connection differently: in meta-ads (sprigr-apps#1462) six creates POST
+     * under an ad account and three address a Graph object by id on a path that
+     * carries no account at all, so the account resolved for the creates was
+     * printed on the delete's card and mixed into its hash while being false.
+     * A resolver returning '' here is the honest answer for such a spec.
+     */
+    resolveConnection?: (env: E, args: ToolArgs) => Promise<string>;
+    /** Overrides the gate's `describeTarget` for this spec only. */
+    describeTarget?: (pinned: P, id: string, name: string) => Promise<string>;
+    /**
+     * Overrides the gate's `stampConnection` for this spec only. The stamp
+     * repeats the card's claim in the agent's "done" report, so a spec that
+     * resolves its own connection usually wants to stamp it its own way too.
+     */
+    stampConnection?: (result: unknown, connection: string) => unknown;
     /** Present only for tools whose write can be (partly) reversed. */
     undo?: UndoCaptureSpec<P>;
 }
@@ -1322,6 +1356,10 @@ interface ApprovalGateOptions<E, P = E> {
      * arguments and the install, canonicalised (a label like "EU store" becomes
      * the real domain). Return '' for a single-connection app. Never read it off
      * the arguments alone: on the retry the model usually omits it.
+     *
+     * This is the DEFAULT for every spec. A spec whose write reaches a
+     * connection by another rule overrides it with
+     * `ApprovalSpec.resolveConnection`.
      */
     resolveConnection: (env: E, args: ToolArgs) => Promise<string>;
     /**
@@ -1334,7 +1372,8 @@ interface ApprovalGateOptions<E, P = E> {
      * 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. `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).
+     * the id alone does not say what it is (an Asana gid). Overridable per
+     * spec.
      */
     describeTarget?: (pinned: P, id: string, name: string) => Promise<string>;
     /**
@@ -1345,7 +1384,8 @@ interface ApprovalGateOptions<E, P = E> {
     journal?: (env: E) => CaptureJournal;
     /**
      * Stamp the resolved connection onto a successful result (e.g. `{ store }`)
-     * so an agent reporting "deleted it" can name where. Optional.
+     * so an agent reporting "deleted it" can name where. Optional, and
+     * overridable per spec.
      */
     stampConnection?: (result: unknown, connection: string) => unknown;
 }
@@ -1382,7 +1422,7 @@ interface DispatcherApprovalGate<E> {
  * rename that quietly ungated a permanent delete is exactly the failure this
  * guard exists to prevent, and it would look identical to working.
  */
-declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, specs: Record<string, ApprovalSpec<E>>, opts: RequireApprovalOptions<E>): Record<string, ToolHandler<E>>;
+declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, specs: Record<string, ApprovalSpec<E, E>>, opts: RequireApprovalOptions<E>): Record<string, ToolHandler<E>>;
 /**
  * The same gate for a dispatcher tool (one tool, many actions selected by an
  * input field). Build it once beside the action registry and call `run` from
@@ -1396,7 +1436,7 @@ declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, sp
  * params are read from `opts.inputField` (default `input`), or from the
  * top-level args when that field is absent (the flat-verb envelope).
  */
-declare function dispatcherApproval<E, P = E>(specs: Record<string, ApprovalSpec<P>>, opts: DispatcherApprovalOptions<E, P>): DispatcherApprovalGate<E>;
+declare function dispatcherApproval<E, P = E>(specs: Record<string, ApprovalSpec<P, E>>, opts: DispatcherApprovalOptions<E, P>): DispatcherApprovalGate<E>;
 
 /**
  * The reversal entry point every adopting app declares as `undo.reverse_tool`.

package/dist/index.js

@@ -758,10 +758,11 @@ async function pin(opts, env, connection) {
   return opts.pinEnv(env, connection);
 }
 async function askPass(name, spec, params, env, opts, hashPrefix) {
-  const connection = await opts.resolveConnection(env, params);
+  const connection = await (spec.resolveConnection ?? 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, name) : rawId || "(unknown id)";
+  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 count = countOf(spec, params, rawId);
   return {
@@ -774,8 +775,9 @@ async function askPass(name, spec, params, env, opts, hashPrefix) {
   };
 }
 async function grantedPass(name, spec, params, env, opts, write) {
-  const connection = await opts.resolveConnection(env, params);
-  const stamp = (r) => connection && opts.stampConnection ? opts.stampConnection(r, connection) : r;
+  const connection = await (spec.resolveConnection ?? opts.resolveConnection)(env, params);
+  const stampConnection = spec.stampConnection ?? opts.stampConnection;
+  const stamp = (r) => connection && stampConnection ? stampConnection(r, connection) : r;
   const undo = spec.undo;
   const id = rawIdOf(params, spec.keys);
   if (!undo || !id) return stamp(await write());

package/package.json

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