@pushary/server 1.3.3 → 1.4.0

package/dist/adapters.d.cts

@@ -0,0 +1,158 @@
+import { D as DecisionType, I as AskResult, P as PusharyServer, G as EnrollResult } from './util-Ihfh4f82.cjs';
+export { a0 as SIGNATURE_HEADER, a1 as deterministicKey, a2 as isApproved, $ as parseDecisionCallback, _ as verifyWebhookSignature } from './util-Ihfh4f82.cjs';
+
+/** Config every adapter accepts, whatever framework it binds. */
+interface PusharyAdapterConfig {
+    /** Pushary API key (pk_xxx.sk_xxx). Defaults to `process.env.PUSHARY_API_KEY`. */
+    readonly apiKey?: string;
+    /** Shown on the approval so the human knows which agent is asking. */
+    readonly agentName?: string;
+    /** How long a blocking ask waits before returning (default 55s, serverless-safe). */
+    readonly timeoutMs?: number;
+    /** Override the API base URL (tests / self-host). */
+    readonly baseUrl?: string;
+}
+/** One ask, as an adapter hands it to the kernel. */
+interface AskHumanInput {
+    readonly question: string;
+    /** Your own stable id for the end-user who decides. */
+    readonly externalId: string;
+    /** Stable node/step/tool name, used to build a re-run-safe idempotency key. */
+    readonly node?: string;
+    readonly type?: DecisionType;
+    readonly options?: readonly string[];
+    readonly context?: string;
+    /** Present on the durable path; Pushary POSTs the answer here. */
+    readonly callbackUrl?: string;
+}
+/** A decision opened durably, before the framework parks its run. */
+interface CreatedDecision {
+    readonly decisionId: string;
+    readonly correlationId: string;
+    readonly status: string;
+    readonly reachable?: boolean;
+    readonly reachableChannels?: number;
+    readonly deviceCount?: number;
+}
+/** A verified, parsed answer callback, keyed by `correlationId`. */
+interface PusharyCallback {
+    readonly correlationId: string;
+    readonly answer: string;
+    readonly value: string;
+    readonly approved: boolean;
+    readonly context?: string;
+    readonly answeredAt: string;
+}
+/**
+ * Re-run-safe idempotency key. A node, step, or tool call that replays on resume
+ * lands on the same decision instead of paging the human twice.
+ */
+declare const idempotencyKeyFor: (input: AskHumanInput) => string;
+/** Fail-closed yes/no check for a confirm answer. */
+declare const isAffirmative: (answer: string | null | undefined) => boolean;
+/** Turn a decision outcome into an unambiguous instruction for the model. */
+declare const describeAnswer: (type: DecisionType, result: AskResult) => string;
+/**
+ * Verify a callback signature and parse it, or return null. The `answer` is what
+ * you feed back into the framework's resume seam.
+ */
+declare const resolvePusharyCallback: (rawBody: string, signature: string | null | undefined, secret: string) => PusharyCallback | null;
+/**
+ * Connection-level options for a request-time approval gate. Everything that
+ * varies per tool call lives on {@link ApprovalAsk} instead, so a gate holds one
+ * client and no per-call state.
+ */
+interface PusharyGateConfig {
+    /** Pushary API key. Defaults to `process.env.PUSHARY_API_KEY`. */
+    readonly apiKey?: string;
+    /** Shown on the approval so the human knows which agent is asking. */
+    readonly agentName?: string;
+    /** How long the decision stays answerable. */
+    readonly expiresInSeconds?: number;
+    /** How long to block waiting for an answer before failing closed. */
+    readonly timeoutMs?: number;
+    /**
+     * Refuse to open a decision nobody can receive, so an end-user with no connected
+     * device is denied at request time instead of silently expiring.
+     */
+    readonly requireReachable?: boolean;
+    /** Override the API base URL (tests / self-host). */
+    readonly baseUrl?: string;
+}
+/**
+ * One gated tool call, resolved down to what Pushary needs. The adapter owns the
+ * mapping from its framework's context, so per-call resolvers stay typed against
+ * the framework's own shapes rather than a lowest common denominator.
+ */
+interface ApprovalAsk {
+    /** The tool the model wants to run. */
+    readonly toolName: string;
+    /** Unique per tool call. Keys the decision together with `sessionId`. */
+    readonly callId: string;
+    /** Stable per run, session, or thread. */
+    readonly sessionId: string;
+    /** What the human is shown. */
+    readonly question: string;
+    /** The enrolled end-user who decides. */
+    readonly externalId: string;
+}
+/** What a gate answers. Denials always carry a reason the model can read. */
+type ApprovalDecision = {
+    readonly approved: true;
+} | {
+    readonly approved: false;
+    readonly reason: string;
+};
+/** A request-time gate: ask a person, fail closed. */
+type ApprovalGate = (ask: ApprovalAsk) => Promise<ApprovalDecision>;
+declare const DENIED_UNANSWERED = "No answer from the approver, so this was denied. Do not retry the same action.";
+declare const DENIED_REFUSED = "The approver denied this action.";
+/**
+ * The default question: the tool name plus a truncated view of its input, so the
+ * human sees what they are approving without a wall of JSON on a lock screen.
+ */
+declare const renderApprovalQuestion: (toolName: string, toolInput: unknown) => string;
+/**
+ * The calls an adapter makes, bound to one framework's name so a missing key or a
+ * missing end-user says which helpers to configure. Build one per adapter module.
+ */
+interface AdapterKernel {
+    /** The underlying client, for anything the kernel does not cover. */
+    readonly client: (config: PusharyAdapterConfig) => PusharyServer;
+    /**
+     * Blocking ask: create a decision and poll durably until the human answers or
+     * the deadline passes. Idempotency keyed by externalId + node + question.
+     */
+    readonly askExternalUser: (config: PusharyAdapterConfig, input: AskHumanInput) => Promise<AskResult>;
+    /**
+     * Durable create: open a decision with a `callbackUrl` and return at once, for
+     * a framework that parks its run and resumes on the webhook.
+     */
+    readonly createDurableDecision: (config: PusharyAdapterConfig, input: AskHumanInput) => Promise<CreatedDecision>;
+    /** Connect one end-user's phone (keyless). Show them the returned link. */
+    readonly connect: (config: PusharyAdapterConfig, externalId: string) => Promise<EnrollResult>;
+    /**
+     * Build a request-time approval gate. The client is created here, so a missing
+     * key throws where the gate is defined rather than on the first tool call.
+     */
+    readonly createGate: (config: PusharyGateConfig) => ApprovalGate;
+    /**
+     * The end-user to ask, or a clear error naming these helpers. Adapters call this
+     * after applying their own resolver and the framework's own default.
+     */
+    readonly requireExternalId: (externalId: string | undefined) => string;
+}
+/**
+ * Build the kernel for one adapter.
+ *
+ * `helpersLabel` names the adapter in the missing-key error, so the message points
+ * at the helpers the caller is actually using ("the LangGraph helpers").
+ *
+ * ```ts
+ * const kernel = createAdapterKernel('the Acme helpers')
+ * export const askHuman = kernel.askExternalUser
+ * ```
+ */
+declare const createAdapterKernel: (helpersLabel: string) => AdapterKernel;
+
+export { type AdapterKernel, type ApprovalAsk, type ApprovalDecision, type ApprovalGate, type AskHumanInput, AskResult, type CreatedDecision, DENIED_REFUSED, DENIED_UNANSWERED, DecisionType, EnrollResult, type PusharyAdapterConfig, type PusharyCallback, type PusharyGateConfig, PusharyServer, createAdapterKernel, describeAnswer, idempotencyKeyFor, isAffirmative, renderApprovalQuestion, resolvePusharyCallback };

package/dist/adapters.d.ts

@@ -0,0 +1,158 @@
+import { D as DecisionType, I as AskResult, P as PusharyServer, G as EnrollResult } from './util-Ihfh4f82.js';
+export { a0 as SIGNATURE_HEADER, a1 as deterministicKey, a2 as isApproved, $ as parseDecisionCallback, _ as verifyWebhookSignature } from './util-Ihfh4f82.js';
+
+/** Config every adapter accepts, whatever framework it binds. */
+interface PusharyAdapterConfig {
+    /** Pushary API key (pk_xxx.sk_xxx). Defaults to `process.env.PUSHARY_API_KEY`. */
+    readonly apiKey?: string;
+    /** Shown on the approval so the human knows which agent is asking. */
+    readonly agentName?: string;
+    /** How long a blocking ask waits before returning (default 55s, serverless-safe). */
+    readonly timeoutMs?: number;
+    /** Override the API base URL (tests / self-host). */
+    readonly baseUrl?: string;
+}
+/** One ask, as an adapter hands it to the kernel. */
+interface AskHumanInput {
+    readonly question: string;
+    /** Your own stable id for the end-user who decides. */
+    readonly externalId: string;
+    /** Stable node/step/tool name, used to build a re-run-safe idempotency key. */
+    readonly node?: string;
+    readonly type?: DecisionType;
+    readonly options?: readonly string[];
+    readonly context?: string;
+    /** Present on the durable path; Pushary POSTs the answer here. */
+    readonly callbackUrl?: string;
+}
+/** A decision opened durably, before the framework parks its run. */
+interface CreatedDecision {
+    readonly decisionId: string;
+    readonly correlationId: string;
+    readonly status: string;
+    readonly reachable?: boolean;
+    readonly reachableChannels?: number;
+    readonly deviceCount?: number;
+}
+/** A verified, parsed answer callback, keyed by `correlationId`. */
+interface PusharyCallback {
+    readonly correlationId: string;
+    readonly answer: string;
+    readonly value: string;
+    readonly approved: boolean;
+    readonly context?: string;
+    readonly answeredAt: string;
+}
+/**
+ * Re-run-safe idempotency key. A node, step, or tool call that replays on resume
+ * lands on the same decision instead of paging the human twice.
+ */
+declare const idempotencyKeyFor: (input: AskHumanInput) => string;
+/** Fail-closed yes/no check for a confirm answer. */
+declare const isAffirmative: (answer: string | null | undefined) => boolean;
+/** Turn a decision outcome into an unambiguous instruction for the model. */
+declare const describeAnswer: (type: DecisionType, result: AskResult) => string;
+/**
+ * Verify a callback signature and parse it, or return null. The `answer` is what
+ * you feed back into the framework's resume seam.
+ */
+declare const resolvePusharyCallback: (rawBody: string, signature: string | null | undefined, secret: string) => PusharyCallback | null;
+/**
+ * Connection-level options for a request-time approval gate. Everything that
+ * varies per tool call lives on {@link ApprovalAsk} instead, so a gate holds one
+ * client and no per-call state.
+ */
+interface PusharyGateConfig {
+    /** Pushary API key. Defaults to `process.env.PUSHARY_API_KEY`. */
+    readonly apiKey?: string;
+    /** Shown on the approval so the human knows which agent is asking. */
+    readonly agentName?: string;
+    /** How long the decision stays answerable. */
+    readonly expiresInSeconds?: number;
+    /** How long to block waiting for an answer before failing closed. */
+    readonly timeoutMs?: number;
+    /**
+     * Refuse to open a decision nobody can receive, so an end-user with no connected
+     * device is denied at request time instead of silently expiring.
+     */
+    readonly requireReachable?: boolean;
+    /** Override the API base URL (tests / self-host). */
+    readonly baseUrl?: string;
+}
+/**
+ * One gated tool call, resolved down to what Pushary needs. The adapter owns the
+ * mapping from its framework's context, so per-call resolvers stay typed against
+ * the framework's own shapes rather than a lowest common denominator.
+ */
+interface ApprovalAsk {
+    /** The tool the model wants to run. */
+    readonly toolName: string;
+    /** Unique per tool call. Keys the decision together with `sessionId`. */
+    readonly callId: string;
+    /** Stable per run, session, or thread. */
+    readonly sessionId: string;
+    /** What the human is shown. */
+    readonly question: string;
+    /** The enrolled end-user who decides. */
+    readonly externalId: string;
+}
+/** What a gate answers. Denials always carry a reason the model can read. */
+type ApprovalDecision = {
+    readonly approved: true;
+} | {
+    readonly approved: false;
+    readonly reason: string;
+};
+/** A request-time gate: ask a person, fail closed. */
+type ApprovalGate = (ask: ApprovalAsk) => Promise<ApprovalDecision>;
+declare const DENIED_UNANSWERED = "No answer from the approver, so this was denied. Do not retry the same action.";
+declare const DENIED_REFUSED = "The approver denied this action.";
+/**
+ * The default question: the tool name plus a truncated view of its input, so the
+ * human sees what they are approving without a wall of JSON on a lock screen.
+ */
+declare const renderApprovalQuestion: (toolName: string, toolInput: unknown) => string;
+/**
+ * The calls an adapter makes, bound to one framework's name so a missing key or a
+ * missing end-user says which helpers to configure. Build one per adapter module.
+ */
+interface AdapterKernel {
+    /** The underlying client, for anything the kernel does not cover. */
+    readonly client: (config: PusharyAdapterConfig) => PusharyServer;
+    /**
+     * Blocking ask: create a decision and poll durably until the human answers or
+     * the deadline passes. Idempotency keyed by externalId + node + question.
+     */
+    readonly askExternalUser: (config: PusharyAdapterConfig, input: AskHumanInput) => Promise<AskResult>;
+    /**
+     * Durable create: open a decision with a `callbackUrl` and return at once, for
+     * a framework that parks its run and resumes on the webhook.
+     */
+    readonly createDurableDecision: (config: PusharyAdapterConfig, input: AskHumanInput) => Promise<CreatedDecision>;
+    /** Connect one end-user's phone (keyless). Show them the returned link. */
+    readonly connect: (config: PusharyAdapterConfig, externalId: string) => Promise<EnrollResult>;
+    /**
+     * Build a request-time approval gate. The client is created here, so a missing
+     * key throws where the gate is defined rather than on the first tool call.
+     */
+    readonly createGate: (config: PusharyGateConfig) => ApprovalGate;
+    /**
+     * The end-user to ask, or a clear error naming these helpers. Adapters call this
+     * after applying their own resolver and the framework's own default.
+     */
+    readonly requireExternalId: (externalId: string | undefined) => string;
+}
+/**
+ * Build the kernel for one adapter.
+ *
+ * `helpersLabel` names the adapter in the missing-key error, so the message points
+ * at the helpers the caller is actually using ("the LangGraph helpers").
+ *
+ * ```ts
+ * const kernel = createAdapterKernel('the Acme helpers')
+ * export const askHuman = kernel.askExternalUser
+ * ```
+ */
+declare const createAdapterKernel: (helpersLabel: string) => AdapterKernel;
+
+export { type AdapterKernel, type ApprovalAsk, type ApprovalDecision, type ApprovalGate, type AskHumanInput, AskResult, type CreatedDecision, DENIED_REFUSED, DENIED_UNANSWERED, DecisionType, EnrollResult, type PusharyAdapterConfig, type PusharyCallback, type PusharyGateConfig, PusharyServer, createAdapterKernel, describeAnswer, idempotencyKeyFor, isAffirmative, renderApprovalQuestion, resolvePusharyCallback };

package/dist/adapters.js

@@ -0,0 +1,156 @@
+import {
+  SIGNATURE_HEADER,
+  createPusharyServer,
+  deterministicKey,
+  isApproved,
+  parseDecisionCallback,
+  verifyWebhookSignature
+} from "./chunk-22FUZ6F5.js";
+
+// 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
+  });
+};
+export {
+  DENIED_REFUSED,
+  DENIED_UNANSWERED,
+  SIGNATURE_HEADER,
+  createAdapterKernel,
+  describeAnswer,
+  deterministicKey,
+  idempotencyKeyFor,
+  isAffirmative,
+  isApproved,
+  parseDecisionCallback,
+  renderApprovalQuestion,
+  resolvePusharyCallback,
+  verifyWebhookSignature
+};
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters.ts"],"sourcesContent":["// The shared kernel behind every Pushary framework adapter. Published as\n// `@pushary/server/adapters` so a new adapter is a thin binding — map the\n// framework's context onto these shapes, map the result back — instead of another\n// copy of the same ~150 lines. Nothing here imports a framework.\n\nimport { createPusharyServer, type PusharyServer } from './client'\nimport { deterministicKey, isApproved } from './util'\nimport { parseDecisionCallback, verifyWebhookSignature } from './webhook'\nimport type { AskResult, DecisionType, EnrollResult } from './types'\n\n/** Config every adapter accepts, whatever framework it binds. */\nexport interface PusharyAdapterConfig {\n  /** Pushary API key (pk_xxx.sk_xxx). Defaults to `process.env.PUSHARY_API_KEY`. */\n  readonly apiKey?: string\n  /** Shown on the approval so the human knows which agent is asking. */\n  readonly agentName?: string\n  /** How long a blocking ask waits before returning (default 55s, serverless-safe). */\n  readonly timeoutMs?: number\n  /** Override the API base URL (tests / self-host). */\n  readonly baseUrl?: string\n}\n\n/** One ask, as an adapter hands it to the kernel. */\nexport interface AskHumanInput {\n  readonly question: string\n  /** Your own stable id for the end-user who decides. */\n  readonly externalId: string\n  /** Stable node/step/tool name, used to build a re-run-safe idempotency key. */\n  readonly node?: string\n  readonly type?: DecisionType\n  readonly options?: readonly string[]\n  readonly context?: string\n  /** Present on the durable path; Pushary POSTs the answer here. */\n  readonly callbackUrl?: string\n}\n\n/** A decision opened durably, before the framework parks its run. */\nexport interface CreatedDecision {\n  readonly decisionId: string\n  readonly correlationId: string\n  readonly status: string\n  readonly reachable?: boolean\n  readonly reachableChannels?: number\n  readonly deviceCount?: number\n}\n\n/** A verified, parsed answer callback, keyed by `correlationId`. */\nexport interface PusharyCallback {\n  readonly correlationId: string\n  readonly answer: string\n  readonly value: string\n  readonly approved: boolean\n  readonly context?: string\n  readonly answeredAt: string\n}\n\nconst DEFAULT_NODE = 'ask-human'\n\n/**\n * Re-run-safe idempotency key. A node, step, or tool call that replays on resume\n * lands on the same decision instead of paging the human twice.\n */\nexport const idempotencyKeyFor = (input: AskHumanInput): string =>\n  deterministicKey([input.externalId, input.node ?? DEFAULT_NODE, input.question])\n\n/** Fail-closed yes/no check for a confirm answer. */\nexport const isAffirmative = (answer: string | null | undefined): boolean =>\n  isApproved({ status: 'answered', type: 'confirm', value: answer ?? null })\n\n/** Turn a decision outcome into an unambiguous instruction for the model. */\nexport const describeAnswer = (type: DecisionType, result: AskResult): string => {\n  if (!result.answered) {\n    return `No answer (status: ${result.status}). Treat this as NOT approved and do not proceed.`\n  }\n  if (type === 'confirm') {\n    return result.approved\n      ? 'The human approved. You may proceed.'\n      : 'The human declined. Do not proceed.'\n  }\n  return `The human answered: ${result.value ?? ''}`\n}\n\n/**\n * Verify a callback signature and parse it, or return null. The `answer` is what\n * you feed back into the framework's resume seam.\n */\nexport const resolvePusharyCallback = (\n  rawBody: string,\n  signature: string | null | undefined,\n  secret: string,\n): PusharyCallback | null => {\n  if (!verifyWebhookSignature(rawBody, signature, secret)) return null\n  const callback = parseDecisionCallback(rawBody)\n  if (!callback) return null\n  return {\n    correlationId: callback.correlationId,\n    answer: callback.answer,\n    value: callback.value,\n    approved: isAffirmative(callback.answer),\n    context: callback.context,\n    answeredAt: callback.answeredAt,\n  }\n}\n\n/**\n * Connection-level options for a request-time approval gate. Everything that\n * varies per tool call lives on {@link ApprovalAsk} instead, so a gate holds one\n * client and no per-call state.\n */\nexport interface PusharyGateConfig {\n  /** Pushary API key. Defaults to `process.env.PUSHARY_API_KEY`. */\n  readonly apiKey?: string\n  /** Shown on the approval so the human knows which agent is asking. */\n  readonly agentName?: string\n  /** How long the decision stays answerable. */\n  readonly expiresInSeconds?: number\n  /** How long to block waiting for an answer before failing closed. */\n  readonly timeoutMs?: number\n  /**\n   * Refuse to open a decision nobody can receive, so an end-user with no connected\n   * device is denied at request time instead of silently expiring.\n   */\n  readonly requireReachable?: boolean\n  /** Override the API base URL (tests / self-host). */\n  readonly baseUrl?: string\n}\n\n/**\n * One gated tool call, resolved down to what Pushary needs. The adapter owns the\n * mapping from its framework's context, so per-call resolvers stay typed against\n * the framework's own shapes rather than a lowest common denominator.\n */\nexport interface ApprovalAsk {\n  /** The tool the model wants to run. */\n  readonly toolName: string\n  /** Unique per tool call. Keys the decision together with `sessionId`. */\n  readonly callId: string\n  /** Stable per run, session, or thread. */\n  readonly sessionId: string\n  /** What the human is shown. */\n  readonly question: string\n  /** The enrolled end-user who decides. */\n  readonly externalId: string\n}\n\n/** What a gate answers. Denials always carry a reason the model can read. */\nexport type ApprovalDecision =\n  | { readonly approved: true }\n  | { readonly approved: false; readonly reason: string }\n\n/** A request-time gate: ask a person, fail closed. */\nexport type ApprovalGate = (ask: ApprovalAsk) => Promise<ApprovalDecision>\n\nconst MAX_INPUT_CHARS = 300\n\nexport const DENIED_UNANSWERED =\n  'No answer from the approver, so this was denied. Do not retry the same action.'\nexport const DENIED_REFUSED = 'The approver denied this action.'\n\n/**\n * The default question: the tool name plus a truncated view of its input, so the\n * human sees what they are approving without a wall of JSON on a lock screen.\n */\nexport const renderApprovalQuestion = (toolName: string, toolInput: unknown): string => {\n  if (toolInput === undefined || toolInput === null) return `Approve ${toolName}?`\n  const summary = summarise(toolInput)\n  return summary === undefined ? `Approve ${toolName}?` : `Approve ${toolName}? ${summary}`\n}\n\nconst summarise = (toolInput: unknown): string | undefined => {\n  let rendered: string | undefined\n  if (typeof toolInput === 'string') {\n    rendered = toolInput\n  } else {\n    try {\n      // Returns undefined for a function or a symbol, and throws on a cycle. Neither\n      // is a reason to fail the tool call: a gate that cannot render its input still\n      // has to ask, so fall back to the bare tool name.\n      rendered = JSON.stringify(toolInput)\n    } catch {\n      return undefined\n    }\n  }\n  if (rendered === undefined) return undefined\n  return rendered.length > MAX_INPUT_CHARS ? `${rendered.slice(0, MAX_INPUT_CHARS)}...` : rendered\n}\n\n/**\n * The calls an adapter makes, bound to one framework's name so a missing key or a\n * missing end-user says which helpers to configure. Build one per adapter module.\n */\nexport interface AdapterKernel {\n  /** The underlying client, for anything the kernel does not cover. */\n  readonly client: (config: PusharyAdapterConfig) => PusharyServer\n  /**\n   * Blocking ask: create a decision and poll durably until the human answers or\n   * the deadline passes. Idempotency keyed by externalId + node + question.\n   */\n  readonly askExternalUser: (\n    config: PusharyAdapterConfig,\n    input: AskHumanInput,\n  ) => Promise<AskResult>\n  /**\n   * Durable create: open a decision with a `callbackUrl` and return at once, for\n   * a framework that parks its run and resumes on the webhook.\n   */\n  readonly createDurableDecision: (\n    config: PusharyAdapterConfig,\n    input: AskHumanInput,\n  ) => Promise<CreatedDecision>\n  /** Connect one end-user's phone (keyless). Show them the returned link. */\n  readonly connect: (config: PusharyAdapterConfig, externalId: string) => Promise<EnrollResult>\n  /**\n   * Build a request-time approval gate. The client is created here, so a missing\n   * key throws where the gate is defined rather than on the first tool call.\n   */\n  readonly createGate: (config: PusharyGateConfig) => ApprovalGate\n  /**\n   * The end-user to ask, or a clear error naming these helpers. Adapters call this\n   * after applying their own resolver and the framework's own default.\n   */\n  readonly requireExternalId: (externalId: string | undefined) => string\n}\n\n/**\n * Build the kernel for one adapter.\n *\n * `helpersLabel` names the adapter in the missing-key error, so the message points\n * at the helpers the caller is actually using (\"the LangGraph helpers\").\n *\n * ```ts\n * const kernel = createAdapterKernel('the Acme helpers')\n * export const askHuman = kernel.askExternalUser\n * ```\n */\nexport const createAdapterKernel = (helpersLabel: string): AdapterKernel => {\n  const requireApiKey = (apiKey: string | undefined): string => {\n    const resolved = apiKey ?? process.env.PUSHARY_API_KEY\n    if (!resolved) {\n      throw new Error(`Pushary: set PUSHARY_API_KEY or pass { apiKey } to ${helpersLabel}.`)\n    }\n    return resolved\n  }\n\n  const client = (config: PusharyAdapterConfig): PusharyServer =>\n    createPusharyServer({\n      apiKey: requireApiKey(config.apiKey),\n      ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),\n    })\n\n  const requireExternalId = (externalId: string | undefined): string => {\n    if (!externalId) {\n      throw new Error(\n        `Pushary: no end-user to ask. Pass { externalId } to ${helpersLabel}, or run ` +\n          'user-scoped auth so the framework supplies one.',\n      )\n    }\n    return externalId\n  }\n\n  const createGate = (config: PusharyGateConfig): ApprovalGate => {\n    const gateClient = createPusharyServer({\n      apiKey: requireApiKey(config.apiKey),\n      ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),\n    })\n\n    return async (ask: ApprovalAsk): Promise<ApprovalDecision> => {\n      const result = await gateClient.decisions.ask({\n        question: ask.question,\n        type: 'confirm',\n        externalId: ask.externalId,\n        ...(config.agentName ? { agentName: config.agentName } : {}),\n        ...(config.expiresInSeconds ? { expiresInSeconds: config.expiresInSeconds } : {}),\n        ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),\n        ...(config.requireReachable ? { requireReachable: config.requireReachable } : {}),\n        // Stable across replays, so a re-run of this call resolves to the same\n        // decision instead of asking twice.\n        idempotencyKey: deterministicKey([ask.sessionId, ask.callId, ask.toolName]),\n      })\n\n      if (result.approved) return { approved: true }\n      return { approved: false, reason: result.answered ? DENIED_REFUSED : DENIED_UNANSWERED }\n    }\n  }\n\n  const askExternalUser = (\n    config: PusharyAdapterConfig,\n    input: AskHumanInput,\n  ): Promise<AskResult> =>\n    client(config).decisions.ask({\n      question: input.question,\n      type: input.type,\n      options: input.options,\n      externalId: input.externalId,\n      context: input.context,\n      agentName: config.agentName,\n      timeoutMs: config.timeoutMs,\n      idempotencyKey: idempotencyKeyFor(input),\n    })\n\n  const createDurableDecision = async (\n    config: PusharyAdapterConfig,\n    input: AskHumanInput,\n  ): Promise<CreatedDecision> => {\n    const created = await client(config).decisions.create({\n      question: input.question,\n      type: input.type,\n      options: input.options,\n      externalId: input.externalId,\n      context: input.context,\n      callbackUrl: input.callbackUrl,\n      agentName: config.agentName,\n      idempotencyKey: idempotencyKeyFor(input),\n      wait: false,\n    })\n    return {\n      decisionId: created.decisionId,\n      correlationId: created.decisionId,\n      status: created.status,\n      reachable: created.reachable,\n      reachableChannels: created.reachableChannels,\n      deviceCount: created.deviceCount,\n    }\n  }\n\n  const connect = (config: PusharyAdapterConfig, externalId: string): Promise<EnrollResult> =>\n    client(config).enroll(externalId)\n\n  return Object.freeze({\n    client,\n    askExternalUser,\n    createDurableDecision,\n    connect,\n    createGate,\n    requireExternalId,\n  })\n}\n\nexport { SIGNATURE_HEADER, verifyWebhookSignature, parseDecisionCallback } from './webhook'\nexport { deterministicKey, isApproved } from './util'\nexport type { AskResult, DecisionType, EnrollResult, PusharyServer }\n"],"mappings":"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","names":[]}