@pushary/server 2.2.0 → 2.3.0

package/README.md

@@ -1,6 +1,14 @@
 # @pushary/server
 
-Server-side SDK for [Pushary](https://pushary.com): send push notifications, and add human-in-the-loop approvals to your AI agent (pause on a decision until a specific human answers).
+The decision layer for AI agents. Your agent asks, your user decides on their phone.
+
+This is the server SDK for [Pushary](https://pushary.com). It also sends push notifications.
+
+## What you need
+
+- A Pushary Partner plan, from $99 a month, to ask your own users. [Start the trial](https://pushary.com/sign-up?from=agent&plan=partner).
+- An API key from [Partner onboarding](https://pushary.com/onboarding/partner), set as `PUSHARY_API_KEY`.
+- Your users install the free Pushary app ([iPhone](https://apps.apple.com/us/app/pushary/id6785677563), [Android](https://play.google.com/store/apps/details?id=com.pushary.app)). They never sign up or pay.
 
 ## Installation
 
@@ -19,17 +27,25 @@ bun add @pushary/server
 ```typescript
 import { createPusharyServer } from '@pushary/server'
 
-const pushary = createPusharyServer({
-  apiKey: process.env.PUSHARY_API_KEY,
-})
+const pushary = createPusharyServer({ apiKey: process.env.PUSHARY_API_KEY })
 
-await pushary.notifications.send({
-  title: 'Hello!',
-  body: 'Your order has shipped',
-  subscriberIds: ['sub_123'],
+const { universalLink } = await pushary.enroll('user-123')
+// Once per user: show universalLink as a button or QR code.
+
+const { approved } = await pushary.decisions.ask({
+  externalId: 'user-123',
+  question: 'Issue a $50 refund?',
+  type: 'confirm', // confirm | select | input
 })
+if (approved) await issueRefund()
 ```
 
+That is the whole integration: connect a user's phone once, then ask them whenever
+your agent needs a yes. `ask()` creates a fresh decision per call and waits until the
+person answers or the deadline passes (55 seconds by default). `approved` is true only
+when the person said yes, so a declined, expired or unanswered decision blocks the
+action. For longer waits, see [Decisions (lower-level)](#decisions-lower-level).
+
 ## API Key
 
 The server SDK requires your full API key (`pk_xxx.sk_xxx`) which includes the secret portion. 
@@ -38,6 +54,22 @@ The server SDK requires your full API key (`pk_xxx.sk_xxx`) which includes the s
 
 Get your API key by following [Get your API key](https://pushary.com/docs/agents/api-key).
 
+## Push notifications quick start
+
+```typescript
+import { createPusharyServer } from '@pushary/server'
+
+const pushary = createPusharyServer({
+  apiKey: process.env.PUSHARY_API_KEY,
+})
+
+await pushary.notifications.send({
+  title: 'Hello!',
+  body: 'Your order has shipped',
+  subscriberIds: ['sub_123'],
+})
+```
+
 ## Resources
 
 ### Subscribers
@@ -121,30 +153,6 @@ await pushary.notifications.send({
 })
 ```
 
-### Human-in-the-loop for agents (the two-call contract)
-
-The whole integration is two calls. Connect an end-user's phone once, then ask them
-whenever your agent needs a human. Requires the [Partner plan](https://pushary.com/agent-notifications-integration).
-
-```typescript
-// 1. Connect an end-user's phone (keyless, no account for them). Show the link.
-const { universalLink } = await pushary.enroll('user-123')
-// Render universalLink as a button or QR. One tap turns on approvals.
-
-// 2. Ask that person and block until they answer. Fail-closed `approved` flag.
-const { approved, value, status } = await pushary.decisions.ask({
-  externalId: 'user-123',
-  question: 'Issue a $50 refund?',
-  type: 'confirm',                // confirm | select | input
-})
-if (approved) await issueRefund()
-```
-
-`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.
-
 ### Decisions (lower-level)
 
 For long waits or your own resume logic, use `create` + a webhook or `get`, and
@@ -248,7 +256,8 @@ For an explicit human gate, set `policy: false`. The gate keeps the full review
 **Upgrade handling:** version 2.1 changes human gate keys. Finish already-started operations on the SDK version that created them, or migrate their persisted bindings explicitly. Do not replay previously executed operations through the new key scheme. A fingerprint identifies the proposed action; the application's execution record and framework persistence still own recovery after an uncertain tool execution.
 
 Every official Pushary adapter (`@pushary/eve`, `@pushary/ai-sdk`,
-`@pushary/langgraph`, `@pushary/mastra`, `@pushary/openai-agents`) is a thin binding
+`@pushary/langgraph`, `@pushary/mastra`, `@pushary/openai-agents`,
+`@pushary/claude-agent-sdk`) is a thin binding
 over one shared kernel, and that kernel is public. If you run an in-house harness, or
 a framework we have not shipped for, this is the same surface they are built on.
 
@@ -316,15 +325,15 @@ names asks a person. `run` is called only after the action is authorized, and an
 error it throws is not caught: reporting it as `ok: false` would be
 indistinguishable from a refusal.
 
-`protect()` is **at most once**. The decision is idempotent — a replay of the same
-`runId` + `callId` + action lands on the same approval instead of asking twice — and
+`protect()` is **at most once**. The decision is idempotent: a replay of the same
+`runId` + `callId` + action lands on the same approval instead of asking twice: and
 the approval is then spent against a durable permit before `run` is called. A retry, a
 concurrent worker and a resumed run all reach the same permit and exactly one of them
 proceeds; the rest come back `ok: false` with a reason worded to stop the model rather
 than invite another attempt.
 
-The permit is bound to the exact subject that was authorized — the action, its target,
-the actor, the environment, the end-user and every fact you sent — so changing the
+The permit is bound to the exact subject that was authorized: the action, its target,
+the actor, the environment, the end-user and every fact you sent: so changing the
 amount between the approval and the execution leaves you with no permit for the action
 you now want to run. `protect()` then records `succeeded` or `failed` against it; a
 process that dies mid-action leaves the permit unresolved, which is visible and
@@ -425,3 +434,14 @@ A positive `timeoutMs` covers creation and polling. `timeoutMs: 0` retains creat
 ### 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.
+
+### Cancel decision HTTP work
+
+`decisions.create(data, { signal })`, `decisions.get(id, { wait, signal })`, and
+`decisions.cancel(id, { signal })` accept an optional `AbortSignal`. The HTTP
+`requestTimeoutMs` still applies when a caller signal is present, including while
+reading the response body. Caller cancellation preserves its abort reason;
+HTTP deadline expiry raises `TimeoutError`. These calls do not retry internally.
+Aborting HTTP work does not withdraw a server-side decision: cancel its known ID
+with a separate cleanup signal. A lost create response may leave a decision until
+its configured expiration.

package/dist/adapters.cjs

@@ -97,13 +97,28 @@ var handleResponse = async (response) => {
 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
-  });
-  return handleResponse(response);
+  options?.signal?.throwIfAborted();
+  const controller = new AbortController();
+  const abort = () => controller.abort(options?.signal?.reason);
+  options?.signal?.addEventListener("abort", abort, { once: true });
+  const timer = setTimeout(() => controller.abort(new DOMException("Pushary request timed out", "TimeoutError")), ctx.timeoutMs ?? 65e3);
+  try {
+    const response = await fetch(url, {
+      method,
+      signal: controller.signal,
+      headers: ctx.headers,
+      body: !isGet && body ? JSON.stringify(body) : void 0
+    });
+    const result = await handleResponse(response);
+    controller.signal.throwIfAborted();
+    return result;
+  } catch (error) {
+    controller.signal.throwIfAborted();
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    options?.signal?.removeEventListener("abort", abort);
+  }
 };
 
 // src/resources/subscribers.ts
@@ -277,12 +292,12 @@ var createDecisionsResource = (request) => {
     }
   };
   return Object.freeze({
-    create: (data) => request("POST", "/decisions", data),
-    get: (id, opts) => request("GET", `/decisions/${id}`, opts?.wait ? { wait: opts.wait } : void 0),
+    create: (data, options) => request("POST", "/decisions", data, options),
+    get: (id, opts) => request("GET", `/decisions/${id}`, opts?.wait ? { wait: opts.wait } : void 0, opts),
     list: (opts) => request("GET", "/decisions", opts ? { ...opts } : void 0),
     ask,
     answer: (id, answer) => request("POST", `/decisions/${id}`, { answer }),
-    cancel: (id) => request("DELETE", `/decisions/${id}`),
+    cancel: (id, options) => request("DELETE", `/decisions/${id}`, void 0, options),
     getWebhookSecret: () => request("GET", "/webhook-secret"),
     rotateWebhookSecret: () => request("POST", "/webhook-secret")
   });
@@ -395,10 +410,10 @@ var createRecordExecution = (request) => (receipt) => request("POST", `/authoriz
 var DEFAULT_BASE_URL = "https://pushary.com/api/v1/server";
 var validateApiKey = (apiKey) => {
   if (!apiKey) {
-    throw new Error("API key is required. Get your API key from https://pushary.com/dashboard/settings");
+    throw new Error("API key is required. Get your API key from https://pushary.com/dashboard/agent/settings");
   }
   if (!apiKey.includes(".")) {
-    throw new Error("Invalid API key format. Use the full API key (pk_xxx.sk_xxx)");
+    throw new Error("Invalid API key format. Use the full API key (pk_xxx.xxx)");
   }
 };
 var createContext = (config) => {