@pushary/server 1.5.0 → 2.0.0

package/README.md

@@ -140,8 +140,8 @@ const { approved, value, status } = await pushary.decisions.ask({
 if (approved) await issueRefund()
 ```
 
-`ask()` creates the decision, derives a collision-safe idempotency key, and polls
-durably until the human answers or the deadline passes (default 55s, serverless-safe).
+`ask()` creates a fresh decision per call and polls
+durably until the human answers or the deadline passes (default 55s for a positive local wait budget).
 `approved` is true only when the person actually said yes, so a declined, expired, or
 unanswered decision safely blocks the action.
 
@@ -195,8 +195,8 @@ import {
 const idempotencyKey = deterministicKey(['run-abc', 'step-3', 'user-123'])
 
 // isApproved(decision: { status, type?, value }): boolean
-// Fail-closed: true ONLY for an answered confirm whose value is yes. Pending,
-// expired, declined and free-text answers all return false.
+// For confirm: true only for an affirmative answer. For select/input: true
+// means answered, not permission to act. Check the actual value for those types.
 isApproved({ status: 'answered', type: 'confirm', value: 'yes' })  // true
 isApproved({ status: 'answered', type: 'confirm', value: 'no' })   // false
 isApproved({ status: 'pending', type: 'confirm', value: null })    // false
@@ -394,3 +394,13 @@ import {
 ## License
 
 MIT. See `LICENSE`.
+
+## Retries and deadlines
+
+For retries of one business operation, pass `idempotencyKey: deterministicKey([runId, stepId, userId])`. Independent asks get fresh keys, even with identical questions. Shared adapter durable creates require this key; missing keys fail before a request is sent. Keep a run ID unique per operation and stable across its retries.
+
+A positive `timeoutMs` covers creation and polling. `timeoutMs: 0` retains create-only behavior. A timeout during creation throws; retry with the same explicit key to recover the decision. A timeout during polling returns the known pending decision ID for later `get()` or a webhook. `signal` cancels the local wait and throws; it does not cancel the remote decision. Other HTTP calls use `requestTimeoutMs` (65 seconds by default).
+
+### Upgrading to 2.0
+
+Upgrade the framework adapter alongside this SDK. Durable helpers now require an explicit `idempotencyKey` tied to the run and step. The 0.3 LangGraph, Mastra and OpenAI adapters support this contract. Earlier adapters must keep the 1.x SDK until migrated. Independent blocking calls no longer deduplicate by question text.

package/dist/adapters.cjs

@@ -42,6 +42,7 @@ __export(adapters_exports, {
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(adapters_exports);
+var import_node_crypto = require("crypto");
 
 // src/error.ts
 var PusharyApiError = class _PusharyApiError extends Error {
@@ -92,11 +93,12 @@ var handleResponse = async (response) => {
   }
   return response.json();
 };
-var createRequest = (ctx) => async (method, path, body) => {
+var createRequest = (ctx) => async (method, path, body, options) => {
   const isGet = method === "GET";
   const url = isGet && body ? buildUrl(ctx.baseUrl, path, body) : `${ctx.baseUrl}${path}`;
   const response = await fetch(url, {
     method,
+    signal: options?.signal ?? AbortSignal.timeout(ctx.timeoutMs ?? 65e3),
     headers: ctx.headers,
     body: !isGet && body ? JSON.stringify(body) : void 0
   });
@@ -179,64 +181,80 @@ var DEFAULT_ASK_TIMEOUT_MS = 55e3;
 var createDecisionsResource = (request) => {
   const ask = async (data) => {
     const idempotencyKey = data.idempotencyKey ?? (0, import_crypto2.randomUUID)();
-    const created = await request("POST", "/decisions", {
-      question: data.question,
-      type: data.type,
-      options: data.options,
-      externalId: data.externalId,
-      email: data.email,
-      agentName: data.agentName,
-      context: data.context,
-      placeholder: data.placeholder,
-      toolName: data.toolName,
-      toolTarget: data.toolTarget,
-      actor: data.actor,
-      environment: data.environment,
-      parameters: data.parameters,
-      // Its changes name parameters rather than carrying values, so what the
-      // person sees is read from the same numbers a rule compares.
-      presentation: data.presentation,
-      approvalUrl: data.approvalUrl,
-      expiresInSeconds: data.expiresInSeconds,
-      poweredBy: data.poweredBy,
-      callbackUrl: data.callbackUrl,
-      requireReachable: data.requireReachable,
-      // Read only by a key issued on your workspace's sandbox site, where the
-      // simulator answers instead of a person. Ignored in production.
-      sandboxOutcome: data.sandboxOutcome,
-      idempotencyKey,
-      wait: false
-    });
-    const type = created.type ?? data.type ?? "confirm";
-    let status = created.status;
-    let answered = created.answered;
-    let value = created.value ?? null;
-    const deadline = Date.now() + Math.max(0, data.timeoutMs ?? DEFAULT_ASK_TIMEOUT_MS);
-    while (status === "pending" && Date.now() < deadline) {
-      const waitSeconds = Math.max(
-        1,
-        Math.min(POLL_WINDOW_SECONDS, Math.ceil((deadline - Date.now()) / 1e3))
-      );
-      const polled = await request("GET", `/decisions/${created.decisionId}`, {
-        wait: waitSeconds
-      });
-      status = polled.status;
-      answered = polled.answered;
-      value = polled.value;
+    const timeoutMs = Math.max(0, data.timeoutMs ?? DEFAULT_ASK_TIMEOUT_MS);
+    const deadline = Date.now() + timeoutMs;
+    const controller = new AbortController();
+    const abort = () => controller.abort(data.signal?.reason);
+    if (data.signal?.aborted) abort();
+    else data.signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => controller.abort(new DOMException("Pushary ask timed out", "TimeoutError")), timeoutMs || 65e3);
+    try {
+      const created = await request("POST", "/decisions", {
+        question: data.question,
+        type: data.type,
+        options: data.options,
+        externalId: data.externalId,
+        email: data.email,
+        agentName: data.agentName,
+        context: data.context,
+        placeholder: data.placeholder,
+        toolName: data.toolName,
+        toolTarget: data.toolTarget,
+        actor: data.actor,
+        environment: data.environment,
+        parameters: data.parameters,
+        // Its changes name parameters rather than carrying values, so what the
+        // person sees is read from the same numbers a rule compares.
+        presentation: data.presentation,
+        approvalUrl: data.approvalUrl,
+        expiresInSeconds: data.expiresInSeconds,
+        poweredBy: data.poweredBy,
+        callbackUrl: data.callbackUrl,
+        requireReachable: data.requireReachable,
+        // Read only by a key issued on your workspace's sandbox site, where the
+        // simulator answers instead of a person. Ignored in production.
+        sandboxOutcome: data.sandboxOutcome,
+        idempotencyKey,
+        wait: false
+      }, { signal: controller.signal });
+      const type = created.type ?? data.type ?? "confirm";
+      let status = created.status;
+      let answered = created.answered;
+      let value = created.value ?? null;
+      while (status === "pending" && Date.now() < deadline) {
+        const waitSeconds = Math.max(
+          1,
+          Math.min(POLL_WINDOW_SECONDS, Math.ceil((deadline - Date.now()) / 1e3))
+        );
+        try {
+          const polled = await request("GET", `/decisions/${created.decisionId}`, {
+            wait: waitSeconds
+          }, { signal: controller.signal });
+          status = polled.status;
+          answered = polled.answered;
+          value = polled.value;
+        } catch (error) {
+          if (controller.signal.aborted && !data.signal?.aborted) break;
+          throw error;
+        }
+      }
+      return {
+        decisionId: created.decisionId,
+        status,
+        answered,
+        value,
+        type,
+        approved: isApproved({ status, type, value }),
+        // Surfaced from the create response so a caller can tell an unanswered
+        // decision that reached nobody (reachable:false) apart from a real decline.
+        reachable: created.reachable,
+        reachableChannels: created.reachableChannels,
+        deviceCount: created.deviceCount
+      };
+    } finally {
+      clearTimeout(timer);
+      data.signal?.removeEventListener("abort", abort);
     }
-    return {
-      decisionId: created.decisionId,
-      status,
-      answered,
-      value,
-      type,
-      approved: isApproved({ status, type, value }),
-      // Surfaced from the create response so a caller can tell an unanswered
-      // decision that reached nobody (reachable:false) apart from a real decline.
-      reachable: created.reachable,
-      reachableChannels: created.reachableChannels,
-      deviceCount: created.deviceCount
-    };
   };
   return Object.freeze({
     create: (data) => request("POST", "/decisions", data),
@@ -366,6 +384,7 @@ var createContext = (config) => {
   validateApiKey(config.apiKey);
   return Object.freeze({
     baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+    timeoutMs: config.requestTimeoutMs ?? 65e3,
     headers: Object.freeze({
       "Content-Type": "application/json",
       "Authorization": `Bearer ${config.apiKey}`
@@ -424,9 +443,8 @@ var parseDecisionCallback = (rawBody) => {
 };
 
 // src/adapters.ts
-var DEFAULT_NODE = "ask-human";
 var defaultProtectQuestion = (action, target) => `Approve ${action}${target ? ` ${target}` : ""}?`;
-var idempotencyKeyFor = (input) => deterministicKey([input.externalId, input.node ?? DEFAULT_NODE, input.question]);
+var idempotencyKeyFor = (input) => input.idempotencyKey ?? (0, import_node_crypto.randomUUID)();
 var isAffirmative = (answer) => isApproved({ status: "answered", type: "confirm", value: answer ?? null });
 var describeAnswer = (type, result) => {
   if (!result.answered) {
@@ -633,6 +651,9 @@ var createAdapterKernel = (helpersLabel) => {
     idempotencyKey: idempotencyKeyFor(input)
   });
   const createDurableDecision = async (config, input) => {
+    if (!input.idempotencyKey?.trim()) {
+      throw new Error("Pushary: durable decisions require an idempotencyKey tied to the run and step.");
+    }
     const created = await client(config).decisions.create({
       question: input.question,
       type: input.type,