@pushary/server 1.3.2 → 1.4.0

package/README.md

@@ -36,7 +36,7 @@ The server SDK requires your full API key (`pk_xxx.sk_xxx`) which includes the s
 
 **Never expose this in client-side code.**
 
-Get your API key from your [Pushary Dashboard](https://pushary.com/dashboard/settings).
+Get your API key by following [Get your API key](https://pushary.com/docs/agents/api-key).
 
 ## Resources
 
@@ -174,6 +174,136 @@ const { webhookSecret } = await pushary.decisions.getWebhookSecret()
 const ok = verifyWebhookSignature(rawBody, signatureHeader, webhookSecret)
 ```
 
+### Helpers
+
+Four exports that the flows above rely on. Signatures are given because guessing
+them is easy to get wrong: `deterministicKey` takes an **array**, and `isApproved`
+reads a decision's `status`/`value`, not an `answer` field.
+
+```typescript
+import {
+  deterministicKey,
+  isApproved,
+  parseDecisionCallback,
+  SIGNATURE_HEADER,
+} from '@pushary/server'
+
+// deterministicKey(parts: readonly string[]): string
+// A stable idempotency key from the parts that identify one logical step. Same
+// parts in, same key out, so a retried run reuses its decision instead of asking
+// the human twice.
+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.
+isApproved({ status: 'answered', type: 'confirm', value: 'yes' })  // true
+isApproved({ status: 'answered', type: 'confirm', value: 'no' })   // false
+isApproved({ status: 'pending', type: 'confirm', value: null })    // false
+
+// SIGNATURE_HEADER: 'x-pushary-signature', the header carrying the signature.
+// parseDecisionCallback(rawBody: string): DecisionCallback | null
+//   Takes the RAW body string, not a parsed object, and returns null if the
+//   payload is not a well-formed callback. Verify the signature first.
+app.post('/webhooks/pushary', async (req, res) => {
+  const rawBody = req.rawBody.toString('utf8')
+  if (!verifyWebhookSignature(rawBody, req.header(SIGNATURE_HEADER), webhookSecret)) {
+    return res.sendStatus(401)
+  }
+
+  const callback = parseDecisionCallback(rawBody)
+  if (!callback) return res.sendStatus(400)
+
+  // A callback carries { correlationId, answer, value, answeredAt }. It has no
+  // `status` field, so it is not an isApproved() argument. Reaching this point
+  // already means the decision was answered, so judge the value directly, or
+  // re-read the decision if you want isApproved to do it for you.
+  if (callback.value === 'yes') await issueRefund()
+
+  res.sendStatus(200)
+})
+```
+
+## Writing a framework adapter: `@pushary/server/adapters`
+
+Every official Pushary adapter (`@pushary/eve`, `@pushary/ai-sdk`,
+`@pushary/langgraph`, `@pushary/mastra`, `@pushary/openai-agents`) 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.
+
+```typescript
+import { createAdapterKernel, renderApprovalQuestion } from '@pushary/server/adapters'
+
+const kernel = createAdapterKernel('the Acme helpers')
+
+// blocking ask; idempotency and the fail-closed result are already handled
+export const askHuman = kernel.askExternalUser
+
+// durable create, for a framework that parks its own run and resumes on a webhook
+export const openDecision = kernel.createDurableDecision
+
+// an enforced gate: build it once, call it per tool call
+const gate = kernel.createGate({ apiKey: process.env.PUSHARY_API_KEY! })
+
+export const approve = async (toolName: string, callId: string, input: unknown) => {
+  const decision = await gate({
+    toolName,
+    callId,
+    sessionId: currentRunId,
+    question: renderApprovalQuestion(toolName, input),
+    externalId: kernel.requireExternalId(currentUserId),
+  })
+  return decision // { approved: true } | { approved: false, reason }
+}
+```
+
+The label passed to `createAdapterKernel` is what appears in the error when a key or
+an end-user is missing, so it names your helpers rather than ours.
+
+Also exported: `describeAnswer` (turn an outcome into an instruction the model cannot
+misread), `resolvePusharyCallback` (verify and parse a webhook in one call),
+`idempotencyKeyFor`, and `isAffirmative`.
+
+Python has the same surface as `pushary.adapters`:
+
+```python
+from pushary.adapters import AdapterKernel, render_approval_question
+
+kernel = AdapterKernel("the Acme helpers")
+ask_human = kernel.ask_human
+gate = kernel.create_gate()
+```
+
+Both give you what the shipped adapters have: idempotency keyed on the call so a
+replay never asks twice, a denial reason the model can read, and silence treated as a
+no.
+
+## Handling errors
+
+Every non-2xx response throws a `PusharyApiError`. It extends `Error`, so existing
+`catch (e) { e.message }` code is unaffected, and it carries the status so you can
+tell "stop and re-authenticate" from "back off and retry" without matching on
+message text.
+
+```typescript
+import { PusharyApiError } from '@pushary/server'
+
+try {
+  await pushary.notifications.send({ title: 'Deploy finished' })
+} catch (err) {
+  if (err instanceof PusharyApiError) {
+    if (err.isAuthError) throw err          // 401/403: key is bad or revoked, do not retry
+    if (err.isRateLimited) return backOff() // 429
+    if (err.isServerError) return retry()   // 5xx
+    console.error(err.status, err.code, err.message) // 4xx: your request, fix the call
+  }
+  throw err
+}
+```
+
+`status`, `statusText`, `code` and `body` are all readable; `code` and `body` are
+present only when the API sent them.
+
 ## TypeScript
 
 Full TypeScript support with exported types:

package/dist/adapters.cjs

@@ -0,0 +1,452 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters.ts
+var adapters_exports = {};
+__export(adapters_exports, {
+  DENIED_REFUSED: () => DENIED_REFUSED,
+  DENIED_UNANSWERED: () => DENIED_UNANSWERED,
+  SIGNATURE_HEADER: () => SIGNATURE_HEADER,
+  createAdapterKernel: () => createAdapterKernel,
+  describeAnswer: () => describeAnswer,
+  deterministicKey: () => deterministicKey,
+  idempotencyKeyFor: () => idempotencyKeyFor,
+  isAffirmative: () => isAffirmative,
+  isApproved: () => isApproved,
+  parseDecisionCallback: () => parseDecisionCallback,
+  renderApprovalQuestion: () => renderApprovalQuestion,
+  resolvePusharyCallback: () => resolvePusharyCallback,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(adapters_exports);
+
+// src/error.ts
+var PusharyApiError = class _PusharyApiError extends Error {
+  constructor(message, init) {
+    super(message);
+    this.name = "PusharyApiError";
+    this.status = init.status;
+    this.statusText = init.statusText ?? "";
+    this.code = init.code;
+    this.body = init.body;
+    Object.setPrototypeOf(this, _PusharyApiError.prototype);
+  }
+  /** The key is missing, malformed, or revoked. Re-authenticate; do not retry. */
+  get isAuthError() {
+    return this.status === 401 || this.status === 403;
+  }
+  /** Rate limited. Back off and retry. */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+  /** Server-side fault. Safe to retry an idempotent call. */
+  get isServerError() {
+    return this.status >= 500;
+  }
+};
+
+// src/request.ts
+var buildUrl = (baseUrl, path, params) => {
+  const url = new URL(`${baseUrl}${path}`);
+  if (params) {
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== void 0 && value !== null) {
+        url.searchParams.set(key, String(value));
+      }
+    });
+  }
+  return url.toString();
+};
+var handleResponse = async (response) => {
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    throw new PusharyApiError(body.message || body.error || `HTTP ${response.status}`, {
+      status: response.status,
+      statusText: response.statusText,
+      code: body.code,
+      body
+    });
+  }
+  return response.json();
+};
+var createRequest = (ctx) => async (method, path, body) => {
+  const isGet = method === "GET";
+  const url = isGet && body ? buildUrl(ctx.baseUrl, path, body) : `${ctx.baseUrl}${path}`;
+  const response = await fetch(url, {
+    method,
+    headers: ctx.headers,
+    body: !isGet && body ? JSON.stringify(body) : void 0
+  });
+  return handleResponse(response);
+};
+
+// src/resources/subscribers.ts
+var createSubscribersResource = (request) => Object.freeze({
+  list: (params) => request("GET", "/subscribers", params),
+  get: (id) => request("GET", `/subscribers/${id}`),
+  update: (id, data) => request("PATCH", `/subscribers/${id}`, data),
+  delete: (id) => request("DELETE", `/subscribers/${id}`),
+  count: () => request("GET", "/subscribers/count")
+});
+
+// src/resources/campaigns.ts
+var createCampaignsResource = (request) => Object.freeze({
+  list: (params) => request("GET", "/campaigns", params),
+  create: (data) => request("POST", "/campaigns", data),
+  get: (id) => request("GET", `/campaigns/${id}`),
+  update: (id, data) => request("PATCH", `/campaigns/${id}`, data),
+  delete: (id) => request("DELETE", `/campaigns/${id}`),
+  send: (id) => request("POST", `/campaigns/${id}/send`),
+  pause: (id) => request("POST", `/campaigns/${id}/pause`),
+  resume: (id) => request("POST", `/campaigns/${id}/resume`),
+  stats: (id) => request("GET", `/campaigns/${id}/stats`)
+});
+
+// src/resources/templates.ts
+var createTemplatesResource = (request) => Object.freeze({
+  list: (params) => request("GET", "/templates", params),
+  create: (data) => request("POST", "/templates", data),
+  get: (id) => request("GET", `/templates/${id}`),
+  update: (id, data) => request("PATCH", `/templates/${id}`, data),
+  delete: (id) => request("DELETE", `/templates/${id}`)
+});
+
+// src/resources/notifications.ts
+var createNotificationsResource = (request) => Object.freeze({
+  send: (data) => request("POST", "/send", data)
+});
+
+// src/resources/flows.ts
+var createFlowsResource = (request) => Object.freeze({
+  list: (params) => request("GET", "/flows", params),
+  create: (data) => request("POST", "/flows", data),
+  get: (id) => request("GET", `/flows/${id}`),
+  update: (id, data) => request("PATCH", `/flows/${id}`, data),
+  delete: (id) => request("DELETE", `/flows/${id}`),
+  activate: (id) => request("POST", `/flows/${id}/activate`),
+  pause: (id) => request("POST", `/flows/${id}/pause`)
+});
+
+// src/resources/decisions.ts
+var import_crypto2 = require("crypto");
+
+// src/util.ts
+var import_crypto = require("crypto");
+var deterministicKey = (parts) => (0, import_crypto.createHash)("sha256").update(parts.join("\0")).digest("hex").slice(0, 40);
+var AFFIRMATIVE = /* @__PURE__ */ new Set([
+  "yes",
+  "y",
+  "approve",
+  "approved",
+  "ok",
+  "okay",
+  "confirm",
+  "accept",
+  "true"
+]);
+var isApproved = (decision) => {
+  if (decision.status !== "answered") return false;
+  if (decision.type && decision.type !== "confirm") return true;
+  return decision.value != null && AFFIRMATIVE.has(decision.value.trim().toLowerCase());
+};
+
+// src/resources/decisions.ts
+var POLL_WINDOW_SECONDS = 50;
+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,
+      expiresInSeconds: data.expiresInSeconds,
+      poweredBy: data.poweredBy,
+      callbackUrl: data.callbackUrl,
+      requireReachable: data.requireReachable,
+      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;
+    }
+    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),
+    get: (id, opts) => request("GET", `/decisions/${id}`, opts?.wait ? { wait: opts.wait } : void 0),
+    ask,
+    answer: (id, answer) => request("POST", `/decisions/${id}`, { answer }),
+    cancel: (id) => request("DELETE", `/decisions/${id}`),
+    getWebhookSecret: () => request("GET", "/webhook-secret"),
+    rotateWebhookSecret: () => request("POST", "/webhook-secret")
+  });
+};
+
+// src/resources/keys.ts
+var createKeysResource = (request) => Object.freeze({
+  issue: (data) => request("POST", "/keys", data),
+  list: () => request("GET", "/keys").then((r) => r.keys),
+  revoke: (keyPrefix) => request("DELETE", `/keys/${encodeURIComponent(keyPrefix)}`)
+});
+
+// src/client.ts
+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");
+  }
+  if (!apiKey.includes(".")) {
+    throw new Error("Invalid API key format. Use the full API key (pk_xxx.sk_xxx)");
+  }
+};
+var createContext = (config) => {
+  validateApiKey(config.apiKey);
+  return Object.freeze({
+    baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+    headers: Object.freeze({
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${config.apiKey}`
+    })
+  });
+};
+var createPusharyServer = (config) => {
+  const ctx = createContext(config);
+  const request = createRequest(ctx);
+  return Object.freeze({
+    subscribers: createSubscribersResource(request),
+    campaigns: createCampaignsResource(request),
+    templates: createTemplatesResource(request),
+    notifications: createNotificationsResource(request),
+    flows: createFlowsResource(request),
+    decisions: createDecisionsResource(request),
+    keys: createKeysResource(request),
+    enroll: (externalId) => request("POST", "/enroll", { externalId })
+  });
+};
+
+// src/webhook.ts
+var import_crypto3 = require("crypto");
+var SIGNATURE_HEADER = "x-pushary-signature";
+var verifyWebhookSignature = (rawBody, signature, secret) => {
+  if (!signature || !secret) return false;
+  const expected = (0, import_crypto3.createHmac)("sha256", secret).update(rawBody).digest("hex");
+  const a = Buffer.from(expected);
+  const b = Buffer.from(signature);
+  if (a.length !== b.length) return false;
+  return (0, import_crypto3.timingSafeEqual)(a, b);
+};
+var parseDecisionCallback = (rawBody) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const p = parsed;
+  if (typeof p.correlationId !== "string" || typeof p.answer !== "string") return null;
+  return {
+    correlationId: p.correlationId,
+    answer: p.answer,
+    value: typeof p.value === "string" ? p.value : p.answer,
+    answeredAt: typeof p.answeredAt === "string" ? p.answeredAt : "",
+    ...typeof p.context === "string" ? { context: p.context } : {}
+  };
+};
+
+// src/adapters.ts
+var DEFAULT_NODE = "ask-human";
+var idempotencyKeyFor = (input) => deterministicKey([input.externalId, input.node ?? DEFAULT_NODE, input.question]);
+var isAffirmative = (answer) => isApproved({ status: "answered", type: "confirm", value: answer ?? null });
+var describeAnswer = (type, result) => {
+  if (!result.answered) {
+    return `No answer (status: ${result.status}). Treat this as NOT approved and do not proceed.`;
+  }
+  if (type === "confirm") {
+    return result.approved ? "The human approved. You may proceed." : "The human declined. Do not proceed.";
+  }
+  return `The human answered: ${result.value ?? ""}`;
+};
+var resolvePusharyCallback = (rawBody, signature, secret) => {
+  if (!verifyWebhookSignature(rawBody, signature, secret)) return null;
+  const callback = parseDecisionCallback(rawBody);
+  if (!callback) return null;
+  return {
+    correlationId: callback.correlationId,
+    answer: callback.answer,
+    value: callback.value,
+    approved: isAffirmative(callback.answer),
+    context: callback.context,
+    answeredAt: callback.answeredAt
+  };
+};
+var MAX_INPUT_CHARS = 300;
+var DENIED_UNANSWERED = "No answer from the approver, so this was denied. Do not retry the same action.";
+var DENIED_REFUSED = "The approver denied this action.";
+var renderApprovalQuestion = (toolName, toolInput) => {
+  if (toolInput === void 0 || toolInput === null) return `Approve ${toolName}?`;
+  const summary = summarise(toolInput);
+  return summary === void 0 ? `Approve ${toolName}?` : `Approve ${toolName}? ${summary}`;
+};
+var summarise = (toolInput) => {
+  let rendered;
+  if (typeof toolInput === "string") {
+    rendered = toolInput;
+  } else {
+    try {
+      rendered = JSON.stringify(toolInput);
+    } catch {
+      return void 0;
+    }
+  }
+  if (rendered === void 0) return void 0;
+  return rendered.length > MAX_INPUT_CHARS ? `${rendered.slice(0, MAX_INPUT_CHARS)}...` : rendered;
+};
+var createAdapterKernel = (helpersLabel) => {
+  const requireApiKey = (apiKey) => {
+    const resolved = apiKey ?? process.env.PUSHARY_API_KEY;
+    if (!resolved) {
+      throw new Error(`Pushary: set PUSHARY_API_KEY or pass { apiKey } to ${helpersLabel}.`);
+    }
+    return resolved;
+  };
+  const client = (config) => createPusharyServer({
+    apiKey: requireApiKey(config.apiKey),
+    ...config.baseUrl ? { baseUrl: config.baseUrl } : {}
+  });
+  const requireExternalId = (externalId) => {
+    if (!externalId) {
+      throw new Error(
+        `Pushary: no end-user to ask. Pass { externalId } to ${helpersLabel}, or run user-scoped auth so the framework supplies one.`
+      );
+    }
+    return externalId;
+  };
+  const createGate = (config) => {
+    const gateClient = createPusharyServer({
+      apiKey: requireApiKey(config.apiKey),
+      ...config.baseUrl ? { baseUrl: config.baseUrl } : {}
+    });
+    return async (ask) => {
+      const result = await gateClient.decisions.ask({
+        question: ask.question,
+        type: "confirm",
+        externalId: ask.externalId,
+        ...config.agentName ? { agentName: config.agentName } : {},
+        ...config.expiresInSeconds ? { expiresInSeconds: config.expiresInSeconds } : {},
+        ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {},
+        ...config.requireReachable ? { requireReachable: config.requireReachable } : {},
+        // Stable across replays, so a re-run of this call resolves to the same
+        // decision instead of asking twice.
+        idempotencyKey: deterministicKey([ask.sessionId, ask.callId, ask.toolName])
+      });
+      if (result.approved) return { approved: true };
+      return { approved: false, reason: result.answered ? DENIED_REFUSED : DENIED_UNANSWERED };
+    };
+  };
+  const askExternalUser = (config, input) => client(config).decisions.ask({
+    question: input.question,
+    type: input.type,
+    options: input.options,
+    externalId: input.externalId,
+    context: input.context,
+    agentName: config.agentName,
+    timeoutMs: config.timeoutMs,
+    idempotencyKey: idempotencyKeyFor(input)
+  });
+  const createDurableDecision = async (config, input) => {
+    const created = await client(config).decisions.create({
+      question: input.question,
+      type: input.type,
+      options: input.options,
+      externalId: input.externalId,
+      context: input.context,
+      callbackUrl: input.callbackUrl,
+      agentName: config.agentName,
+      idempotencyKey: idempotencyKeyFor(input),
+      wait: false
+    });
+    return {
+      decisionId: created.decisionId,
+      correlationId: created.decisionId,
+      status: created.status,
+      reachable: created.reachable,
+      reachableChannels: created.reachableChannels,
+      deviceCount: created.deviceCount
+    };
+  };
+  const connect = (config, externalId) => client(config).enroll(externalId);
+  return Object.freeze({
+    client,
+    askExternalUser,
+    createDurableDecision,
+    connect,
+    createGate,
+    requireExternalId
+  });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DENIED_REFUSED,
+  DENIED_UNANSWERED,
+  SIGNATURE_HEADER,
+  createAdapterKernel,
+  describeAnswer,
+  deterministicKey,
+  idempotencyKeyFor,
+  isAffirmative,
+  isApproved,
+  parseDecisionCallback,
+  renderApprovalQuestion,
+  resolvePusharyCallback,
+  verifyWebhookSignature
+});
+//# sourceMappingURL=adapters.cjs.map