@pushary/server 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { H as AskDecision, I as AskResult, K as BoundKeyResult, M as BoundKeySummary, C as Campaign, g as CampaignStats, O as CampaignsResource, B as CancelDecisionResult, e as CreateCampaign, w as CreateDecision, l as CreateFlow, h as CreateTemplate, z as Decision, A as DecisionAnswerResult, E as DecisionCallback, x as DecisionReachability, y as DecisionResult, v as DecisionStatus, D as DecisionType, Y as DecisionsResource, G as EnrollResult, F as Flow, n as FlowListParams, q as FlowStatus, r as FlowStep, s as FlowStepConfig, t as FlowStepInput, p as FlowStepType, o as FlowTriggerType, X as FlowsResource, J as IssueBoundKey, Z as KeysResource, L as ListParams, V as NotificationsResource, u as PaginatedResponse, a as PusharyConfig, P as PusharyServer, R as RevokeKeyResult, a0 as SIGNATURE_HEADER, j as SendNotification, k as SendResult, S as Subscriber, d as SubscriberCount, b as SubscriberListParams, N as SubscribersResource, T as Template, Q as TemplatesResource, f as UpdateCampaign, m as UpdateFlow, U as UpdateSubscriber, i as UpdateTemplate, W as WebhookSecret, c as createPusharyServer, a1 as deterministicKey, a2 as isApproved, $ as parseDecisionCallback, _ as verifyWebhookSignature } from './util-Ihfh4f82.js';
+export { A as ActionPresentation, a6 as AskDecision, a7 as AskResult, O as AuthorizationAuthority, N as AuthorizationBinding, M as AuthorizationEvaluation, I as AuthorizationQuery, H as AuthorizationVerdict, J as AuthorizeRequest, K as AuthorizeResult, a9 as BoundKeyResult, aa as BoundKeySummary, C as Campaign, g as CampaignStats, ad as CampaignsResource, a2 as CancelDecisionResult, R as ConsumeAuthorizationResult, Q as ConsumedAuthorization, e as CreateCampaign, Z as CreateDecision, l as CreateFlow, h as CreateTemplate, a0 as Decision, a1 as DecisionAnswerResult, a3 as DecisionCallback, x as DecisionDeliverability, z as DecisionParameters, y as DecisionReach, _ as DecisionReachability, $ as DecisionResult, v as DecisionStatus, w as DecisionSubject, D as DecisionType, ah as DecisionsResource, a5 as EnrollResult, V as ExecutionOutcome, W as ExecutionReceipt, F as Flow, n as FlowListParams, q as FlowStatus, r as FlowStep, s as FlowStepConfig, t as FlowStepInput, p as FlowStepType, o as FlowTriggerType, ag as FlowsResource, a8 as IssueBoundKey, ai as KeysResource, L as ListParams, af as NotificationsResource, u as PaginatedResponse, Y as PermitExecutionState, X as PermitRefusal, B as PresentedChange, E as PresentedFormat, a as PusharyConfig, P as PusharyServer, ab as RevokeKeyResult, al as SIGNATURE_HEADER, G as SandboxOutcome, j as SendNotification, k as SendResult, S as Subscriber, d as SubscriberCount, b as SubscriberListParams, ac as SubscribersResource, T as Template, ae as TemplatesResource, f as UpdateCampaign, m as UpdateFlow, U as UpdateSubscriber, i as UpdateTemplate, a4 as WebhookSecret, c as createPusharyServer, am as deterministicKey, an as isApproved, ak as parseDecisionCallback, aj as verifyWebhookSignature } from './util-DeGBh5at.js';
 
 /**
  * Thrown for any non-2xx response from the API.

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   isApproved,
   parseDecisionCallback,
   verifyWebhookSignature
-} from "./chunk-22FUZ6F5.js";
+} from "./chunk-E6DWMKLZ.js";
 export {
   PusharyApiError,
   SIGNATURE_HEADER,

package/dist/{util-Ihfh4f82.d.cts → util-DeGBh5at.d.cts}

@@ -206,7 +206,128 @@ interface FlowListParams extends ListParams {
 }
 type DecisionType = 'confirm' | 'select' | 'input';
 type DecisionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
-interface CreateDecision {
+/**
+ * Typed arguments of an action. Scalars only: a rule reads these, and a nested
+ * object has no comparable value to read.
+ */
+type DecisionParameters = Readonly<Record<string, string | number | boolean>>;
+/**
+ * How to render one parameter to the person deciding.
+ *
+ * Declared here rather than imported, for the same reason AuthorizationVerdict
+ * is: this package is MIT and must not depend on Pushary's private core, so the
+ * wire values are the contract between them.
+ *
+ * A currency parameter holds MINOR units — 4800 is EUR 48.00. A float cannot
+ * hold money exactly and a pre-formatted string cannot be compared by a rule.
+ */
+type PresentedFormat = {
+    readonly kind: 'text';
+} | {
+    readonly kind: 'currency';
+    readonly currency: string;
+} | {
+    readonly kind: 'quantity';
+    readonly unit?: string;
+} | {
+    readonly kind: 'timestamp';
+} | {
+    readonly kind: 'boolean';
+};
+interface PresentedChange {
+    /**
+     * A key of `parameters`. The value is read from there and never carried here,
+     * so what the person sees and what a rule reads cannot be different numbers.
+     */
+    readonly parameter: string;
+    /** What to call it to a person: "Refund amount", not "amount_minor". */
+    readonly label: string;
+    readonly format: PresentedFormat;
+}
+/**
+ * The action in business language, for the surfaces a person actually reads.
+ *
+ * Optional. A caller that sends none keeps the free-text `question` it has
+ * always sent; only a caller that claims a presentation is held to it, and an
+ * invalid one is refused rather than half-rendered.
+ */
+interface ActionPresentation {
+    /** The action as a person would name it. "Refund order #4471". */
+    readonly label: string;
+    /** What actually happens. "Returns EUR 48.00 to the customer's card." */
+    readonly effect: string;
+    readonly changes?: readonly PresentedChange[];
+    /** Optional. Why this one is worth stopping for. */
+    readonly risk?: string;
+}
+interface DecisionSubject {
+    readonly toolName?: string;
+    readonly toolTarget?: string;
+    /**
+     * Who the action runs on behalf of, e.g. `user:u_44` or `team:billing`. This is
+     * the principal, which is not necessarily the person who approves: `externalId`
+     * names the recipient of the question, `actor` names whose authority the action
+     * claims. Max 120 characters.
+     */
+    readonly actor?: string;
+    /** Which deployment the action runs against, e.g. `production`. Max 40 characters. */
+    readonly environment?: string;
+    /**
+     * Typed arguments of the action, e.g. `{ amount: 4800, currency: 'EUR' }`.
+     * Scalars only, at most 32 keys. Recorded on the audit row so an approval can be
+     * read back against what it approved.
+     *
+     * Rejected as a whole (400) if any value is not a string, a finite number or a
+     * boolean, rather than being partly dropped: a rule that reads a missing
+     * parameter can only ever decide more permissively than one that reads it.
+     */
+    readonly parameters?: DecisionParameters;
+    /**
+     * What the person deciding sees, in business language. Its `changes` name
+     * parameters rather than carrying values, so display and policy read the same
+     * numbers. Refused (400) if it names a parameter you did not send, names one
+     * whose name marks it secret, or gives a value a format cannot render.
+     */
+    readonly presentation?: ActionPresentation;
+    /**
+     * Return a short-lived `approvalUrl` you can deliver yourself, over the email,
+     * SMS or in-app inbox you already have for this end-user.
+     *
+     * Off by default: a capability URL returned on every create is a capability URL
+     * in every log, for the majority of decisions that never needed one. The link
+     * is bound to this decision, this site and this recipient, and expires.
+     */
+    readonly approvalUrl?: boolean;
+}
+/** Whether a decision can reach this person, and by whose hands. */
+type DecisionDeliverability = 'push' | 'fallback' | 'unreachable';
+interface DecisionReach {
+    readonly externalId: string;
+    /**
+     * `push` — Pushary delivers it. `fallback` — nobody is enrolled, but you know
+     * this end-user: open the decision with `approvalUrl: true` and deliver the
+     * link yourself. `unreachable` — no end-user was named, so there is nobody to
+     * reach and no link to mint.
+     */
+    readonly deliverability: DecisionDeliverability;
+    readonly reachable: boolean;
+    readonly reachableChannels: number;
+    readonly deviceCount: number;
+    readonly webEndpoints: number;
+    readonly hint: string;
+}
+/**
+ * What the sandbox's simulated approver does.
+ *
+ * `approve` is the default. `no_answer` leaves the decision open, which is how
+ * you exercise your own fail-closed path without waiting on a real phone.
+ *
+ * Read only by a key issued on your workspace's sandbox site, where nothing is
+ * delivered and nobody is asked. Ignored in production, where the approver is a
+ * person.
+ */
+type SandboxOutcome = 'approve' | 'deny' | 'no_answer';
+interface CreateDecision extends DecisionSubject {
     readonly question: string;
     readonly type?: DecisionType;
     readonly options?: readonly string[];
@@ -222,6 +343,108 @@ interface CreateDecision {
     readonly idempotencyKey?: string;
     readonly poweredBy?: boolean;
     readonly requireReachable?: boolean;
+    readonly sandboxOutcome?: SandboxOutcome;
+}
+type AuthorizationVerdict = 'allow' | 'deny' | 'requires_human';
+interface AuthorizationQuery extends DecisionSubject {
+    /** The action being authorized. Required: a rule has to name it. */
+    readonly toolName: string;
+    /** Your own id for the end-user this action belongs to. */
+    readonly externalId?: string;
+    /**
+     * Shown to the person, if policy defers to one. Defaults to the action and its
+     * target, so a caller that only names the action still asks a readable question.
+     */
+    readonly question?: string;
+    readonly agentName?: string;
+}
+interface AuthorizeRequest extends AuthorizationQuery {
+    /** Forwarded to the ask, and used only when policy defers to a person. */
+    readonly timeoutMs?: number;
+    readonly expiresInSeconds?: number;
+    readonly idempotencyKey?: string;
+    readonly requireReachable?: boolean;
+}
+interface AuthorizeResult {
+    /** Fail-closed. False for a denial, and false when nobody answered. */
+    readonly approved: boolean;
+    /** What settled it: a rule, or a person. */
+    readonly resolvedBy: 'policy' | 'human';
+    /** The rule that decided, or null when no rule named the action. */
+    readonly policy: string | null;
+    readonly reason: string;
+    /** The decision opened when policy deferred to a person, else null. */
+    readonly decisionId: string | null;
+    /** The audit row a policy-settled authorization produced, else null. */
+    readonly authorizationId: string | null;
+}
+interface AuthorizationEvaluation {
+    readonly verdict: AuthorizationVerdict;
+    readonly policy: string | null;
+    readonly reason: string;
+    readonly authorizationId: string | null;
+}
+/**
+ * The exact subject an authorization was recorded against.
+ *
+ * Carried from the gate to the consume rather than rebuilt, because the two have
+ * to name the same action and rebuilding it is a second chance for them not to.
+ * The server digests this and what it recorded, and refuses unless they match.
+ */
+interface AuthorizationBinding {
+    /** The settled authorization: a policy verdict's id, or an approved decision's id. */
+    readonly authorizationId: string;
+    readonly toolName: string;
+    readonly toolTarget?: string;
+    readonly actor?: string;
+    readonly environment?: string;
+    readonly externalId?: string;
+    readonly parameters?: DecisionParameters;
+}
+/**
+ * Who allowed it, frozen when it was allowed.
+ *
+ * A rule can be edited and a member can lose their seat. An authorization that
+ * can only say "something allowed this" is not an audit trail, so the deciding
+ * authority is copied onto the permit and never updated.
+ */
+type AuthorizationAuthority = {
+    readonly kind: 'policy';
+    readonly rulePattern?: string;
+    readonly authorizationRuleId?: string;
+    readonly policyId?: string;
+} | {
+    readonly kind: 'human';
+    readonly answeredAt: string;
+    readonly answerSource?: string;
+    readonly approverUserId?: string;
+    readonly approverExternalId?: string;
+};
+/** Why a consume was refused. Every branch is a refusal; none of them means allowed. */
+type PermitRefusal = 'not_authorized' | 'action_mismatch' | 'expired' | 'already_consumed';
+type PermitExecutionState = 'running' | 'succeeded' | 'failed';
+interface ConsumedAuthorization {
+    readonly permitId: string;
+    readonly authority: AuthorizationAuthority;
+    /** ISO-8601. The permit is spent already; this is when it would have stopped being spendable. */
+    readonly expiresAt: string;
+}
+type ConsumeAuthorizationResult = {
+    readonly consumed: true;
+    readonly permit: ConsumedAuthorization;
+} | {
+    readonly consumed: false;
+    readonly refusal: PermitRefusal;
+    readonly reason: string;
+    /** On `already_consumed`, what the winning execution did. */
+    readonly executionState?: PermitExecutionState;
+};
+type ExecutionOutcome = 'succeeded' | 'failed';
+interface ExecutionReceipt {
+    readonly permitId: string;
+    readonly outcome: ExecutionOutcome;
+    /** Bounded and redacted server-side. What the action did, or why it did not. */
+    readonly summary?: string;
 }
 interface DecisionReachability {
     readonly reachable?: boolean;
@@ -283,7 +506,7 @@ interface EnrollResult {
     readonly universalLink: string;
     readonly expiresInSeconds: number;
 }
-interface AskDecision {
+interface AskDecision extends DecisionSubject {
     readonly question: string;
     readonly type?: DecisionType;
     readonly options?: readonly string[];
@@ -297,6 +520,9 @@ interface AskDecision {
     readonly poweredBy?: boolean;
     readonly callbackUrl?: string;
     readonly requireReachable?: boolean;
+    readonly sandboxOutcome?: SandboxOutcome;
+    readonly presentation?: ActionPresentation;
+    readonly approvalUrl?: boolean;
     readonly timeoutMs?: number;
 }
 interface AskResult extends DecisionReachability {
@@ -401,7 +627,14 @@ interface PusharyServer {
     readonly flows: FlowsResource;
     readonly decisions: DecisionsResource;
     readonly keys: KeysResource;
+    readonly authorize: (input: AuthorizeRequest) => Promise<AuthorizeResult>;
+    readonly evaluateAuthorization: (input: AuthorizationQuery) => Promise<AuthorizationEvaluation>;
+    readonly consumeAuthorization: (binding: AuthorizationBinding) => Promise<ConsumeAuthorizationResult>;
+    readonly recordExecution: (receipt: ExecutionReceipt) => Promise<{
+        readonly executionState: PermitExecutionState;
+    }>;
     readonly enroll: (externalId: string) => Promise<EnrollResult>;
+    readonly reachability: (externalId: string) => Promise<DecisionReach>;
 }
 declare const createPusharyServer: (config: PusharyConfig) => PusharyServer;
 
@@ -416,4 +649,4 @@ declare const isApproved: (decision: {
     readonly value: string | null;
 }) => boolean;
 
-export { parseDecisionCallback as $, type DecisionAnswerResult as A, type CancelDecisionResult as B, type Campaign as C, type DecisionType as D, type DecisionCallback as E, type Flow as F, type EnrollResult as G, type AskDecision as H, type AskResult as I, type IssueBoundKey as J, type BoundKeyResult as K, type ListParams as L, type BoundKeySummary as M, type SubscribersResource as N, type CampaignsResource as O, type PusharyServer as P, type TemplatesResource as Q, type RevokeKeyResult as R, type Subscriber as S, type Template as T, type UpdateSubscriber as U, type NotificationsResource as V, type WebhookSecret as W, type FlowsResource as X, type DecisionsResource as Y, type KeysResource as Z, verifyWebhookSignature as _, type PusharyConfig as a, SIGNATURE_HEADER as a0, deterministicKey as a1, isApproved as a2, type SubscriberListParams as b, createPusharyServer as c, type SubscriberCount as d, type CreateCampaign as e, type UpdateCampaign as f, type CampaignStats as g, type CreateTemplate as h, type UpdateTemplate as i, type SendNotification as j, type SendResult as k, type CreateFlow as l, type UpdateFlow as m, type FlowListParams as n, type FlowTriggerType as o, type FlowStepType as p, type FlowStatus as q, type FlowStep as r, type FlowStepConfig as s, type FlowStepInput as t, type PaginatedResponse as u, type DecisionStatus as v, type CreateDecision as w, type DecisionReachability as x, type DecisionResult as y, type Decision as z };
+export { type DecisionResult as $, type ActionPresentation as A, type PresentedChange as B, type Campaign as C, type DecisionType as D, type PresentedFormat as E, type Flow as F, type SandboxOutcome as G, type AuthorizationVerdict as H, type AuthorizationQuery as I, type AuthorizeRequest as J, type AuthorizeResult as K, type ListParams as L, type AuthorizationEvaluation as M, type AuthorizationBinding as N, type AuthorizationAuthority as O, type PusharyServer as P, type ConsumedAuthorization as Q, type ConsumeAuthorizationResult as R, type Subscriber as S, type Template as T, type UpdateSubscriber as U, type ExecutionOutcome as V, type ExecutionReceipt as W, type PermitRefusal as X, type PermitExecutionState as Y, type CreateDecision as Z, type DecisionReachability as _, type PusharyConfig as a, type Decision as a0, type DecisionAnswerResult as a1, type CancelDecisionResult as a2, type DecisionCallback as a3, type WebhookSecret as a4, type EnrollResult as a5, type AskDecision as a6, type AskResult as a7, type IssueBoundKey as a8, type BoundKeyResult as a9, type BoundKeySummary as aa, type RevokeKeyResult as ab, type SubscribersResource as ac, type CampaignsResource as ad, type TemplatesResource as ae, type NotificationsResource as af, type FlowsResource as ag, type DecisionsResource as ah, type KeysResource as ai, verifyWebhookSignature as aj, parseDecisionCallback as ak, SIGNATURE_HEADER as al, deterministicKey as am, isApproved as an, type SubscriberListParams as b, createPusharyServer as c, type SubscriberCount as d, type CreateCampaign as e, type UpdateCampaign as f, type CampaignStats as g, type CreateTemplate as h, type UpdateTemplate as i, type SendNotification as j, type SendResult as k, type CreateFlow as l, type UpdateFlow as m, type FlowListParams as n, type FlowTriggerType as o, type FlowStepType as p, type FlowStatus as q, type FlowStep as r, type FlowStepConfig as s, type FlowStepInput as t, type PaginatedResponse as u, type DecisionStatus as v, type DecisionSubject as w, type DecisionDeliverability as x, type DecisionReach as y, type DecisionParameters as z };

package/dist/{util-Ihfh4f82.d.ts → util-DeGBh5at.d.ts}

@@ -206,7 +206,128 @@ interface FlowListParams extends ListParams {
 }
 type DecisionType = 'confirm' | 'select' | 'input';
 type DecisionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
-interface CreateDecision {
+/**
+ * Typed arguments of an action. Scalars only: a rule reads these, and a nested
+ * object has no comparable value to read.
+ */
+type DecisionParameters = Readonly<Record<string, string | number | boolean>>;
+/**
+ * How to render one parameter to the person deciding.
+ *
+ * Declared here rather than imported, for the same reason AuthorizationVerdict
+ * is: this package is MIT and must not depend on Pushary's private core, so the
+ * wire values are the contract between them.
+ *
+ * A currency parameter holds MINOR units — 4800 is EUR 48.00. A float cannot
+ * hold money exactly and a pre-formatted string cannot be compared by a rule.
+ */
+type PresentedFormat = {
+    readonly kind: 'text';
+} | {
+    readonly kind: 'currency';
+    readonly currency: string;
+} | {
+    readonly kind: 'quantity';
+    readonly unit?: string;
+} | {
+    readonly kind: 'timestamp';
+} | {
+    readonly kind: 'boolean';
+};
+interface PresentedChange {
+    /**
+     * A key of `parameters`. The value is read from there and never carried here,
+     * so what the person sees and what a rule reads cannot be different numbers.
+     */
+    readonly parameter: string;
+    /** What to call it to a person: "Refund amount", not "amount_minor". */
+    readonly label: string;
+    readonly format: PresentedFormat;
+}
+/**
+ * The action in business language, for the surfaces a person actually reads.
+ *
+ * Optional. A caller that sends none keeps the free-text `question` it has
+ * always sent; only a caller that claims a presentation is held to it, and an
+ * invalid one is refused rather than half-rendered.
+ */
+interface ActionPresentation {
+    /** The action as a person would name it. "Refund order #4471". */
+    readonly label: string;
+    /** What actually happens. "Returns EUR 48.00 to the customer's card." */
+    readonly effect: string;
+    readonly changes?: readonly PresentedChange[];
+    /** Optional. Why this one is worth stopping for. */
+    readonly risk?: string;
+}
+interface DecisionSubject {
+    readonly toolName?: string;
+    readonly toolTarget?: string;
+    /**
+     * Who the action runs on behalf of, e.g. `user:u_44` or `team:billing`. This is
+     * the principal, which is not necessarily the person who approves: `externalId`
+     * names the recipient of the question, `actor` names whose authority the action
+     * claims. Max 120 characters.
+     */
+    readonly actor?: string;
+    /** Which deployment the action runs against, e.g. `production`. Max 40 characters. */
+    readonly environment?: string;
+    /**
+     * Typed arguments of the action, e.g. `{ amount: 4800, currency: 'EUR' }`.
+     * Scalars only, at most 32 keys. Recorded on the audit row so an approval can be
+     * read back against what it approved.
+     *
+     * Rejected as a whole (400) if any value is not a string, a finite number or a
+     * boolean, rather than being partly dropped: a rule that reads a missing
+     * parameter can only ever decide more permissively than one that reads it.
+     */
+    readonly parameters?: DecisionParameters;
+    /**
+     * What the person deciding sees, in business language. Its `changes` name
+     * parameters rather than carrying values, so display and policy read the same
+     * numbers. Refused (400) if it names a parameter you did not send, names one
+     * whose name marks it secret, or gives a value a format cannot render.
+     */
+    readonly presentation?: ActionPresentation;
+    /**
+     * Return a short-lived `approvalUrl` you can deliver yourself, over the email,
+     * SMS or in-app inbox you already have for this end-user.
+     *
+     * Off by default: a capability URL returned on every create is a capability URL
+     * in every log, for the majority of decisions that never needed one. The link
+     * is bound to this decision, this site and this recipient, and expires.
+     */
+    readonly approvalUrl?: boolean;
+}
+/** Whether a decision can reach this person, and by whose hands. */
+type DecisionDeliverability = 'push' | 'fallback' | 'unreachable';
+interface DecisionReach {
+    readonly externalId: string;
+    /**
+     * `push` — Pushary delivers it. `fallback` — nobody is enrolled, but you know
+     * this end-user: open the decision with `approvalUrl: true` and deliver the
+     * link yourself. `unreachable` — no end-user was named, so there is nobody to
+     * reach and no link to mint.
+     */
+    readonly deliverability: DecisionDeliverability;
+    readonly reachable: boolean;
+    readonly reachableChannels: number;
+    readonly deviceCount: number;
+    readonly webEndpoints: number;
+    readonly hint: string;
+}
+/**
+ * What the sandbox's simulated approver does.
+ *
+ * `approve` is the default. `no_answer` leaves the decision open, which is how
+ * you exercise your own fail-closed path without waiting on a real phone.
+ *
+ * Read only by a key issued on your workspace's sandbox site, where nothing is
+ * delivered and nobody is asked. Ignored in production, where the approver is a
+ * person.
+ */
+type SandboxOutcome = 'approve' | 'deny' | 'no_answer';
+interface CreateDecision extends DecisionSubject {
     readonly question: string;
     readonly type?: DecisionType;
     readonly options?: readonly string[];
@@ -222,6 +343,108 @@ interface CreateDecision {
     readonly idempotencyKey?: string;
     readonly poweredBy?: boolean;
     readonly requireReachable?: boolean;
+    readonly sandboxOutcome?: SandboxOutcome;
+}
+type AuthorizationVerdict = 'allow' | 'deny' | 'requires_human';
+interface AuthorizationQuery extends DecisionSubject {
+    /** The action being authorized. Required: a rule has to name it. */
+    readonly toolName: string;
+    /** Your own id for the end-user this action belongs to. */
+    readonly externalId?: string;
+    /**
+     * Shown to the person, if policy defers to one. Defaults to the action and its
+     * target, so a caller that only names the action still asks a readable question.
+     */
+    readonly question?: string;
+    readonly agentName?: string;
+}
+interface AuthorizeRequest extends AuthorizationQuery {
+    /** Forwarded to the ask, and used only when policy defers to a person. */
+    readonly timeoutMs?: number;
+    readonly expiresInSeconds?: number;
+    readonly idempotencyKey?: string;
+    readonly requireReachable?: boolean;
+}
+interface AuthorizeResult {
+    /** Fail-closed. False for a denial, and false when nobody answered. */
+    readonly approved: boolean;
+    /** What settled it: a rule, or a person. */
+    readonly resolvedBy: 'policy' | 'human';
+    /** The rule that decided, or null when no rule named the action. */
+    readonly policy: string | null;
+    readonly reason: string;
+    /** The decision opened when policy deferred to a person, else null. */
+    readonly decisionId: string | null;
+    /** The audit row a policy-settled authorization produced, else null. */
+    readonly authorizationId: string | null;
+}
+interface AuthorizationEvaluation {
+    readonly verdict: AuthorizationVerdict;
+    readonly policy: string | null;
+    readonly reason: string;
+    readonly authorizationId: string | null;
+}
+/**
+ * The exact subject an authorization was recorded against.
+ *
+ * Carried from the gate to the consume rather than rebuilt, because the two have
+ * to name the same action and rebuilding it is a second chance for them not to.
+ * The server digests this and what it recorded, and refuses unless they match.
+ */
+interface AuthorizationBinding {
+    /** The settled authorization: a policy verdict's id, or an approved decision's id. */
+    readonly authorizationId: string;
+    readonly toolName: string;
+    readonly toolTarget?: string;
+    readonly actor?: string;
+    readonly environment?: string;
+    readonly externalId?: string;
+    readonly parameters?: DecisionParameters;
+}
+/**
+ * Who allowed it, frozen when it was allowed.
+ *
+ * A rule can be edited and a member can lose their seat. An authorization that
+ * can only say "something allowed this" is not an audit trail, so the deciding
+ * authority is copied onto the permit and never updated.
+ */
+type AuthorizationAuthority = {
+    readonly kind: 'policy';
+    readonly rulePattern?: string;
+    readonly authorizationRuleId?: string;
+    readonly policyId?: string;
+} | {
+    readonly kind: 'human';
+    readonly answeredAt: string;
+    readonly answerSource?: string;
+    readonly approverUserId?: string;
+    readonly approverExternalId?: string;
+};
+/** Why a consume was refused. Every branch is a refusal; none of them means allowed. */
+type PermitRefusal = 'not_authorized' | 'action_mismatch' | 'expired' | 'already_consumed';
+type PermitExecutionState = 'running' | 'succeeded' | 'failed';
+interface ConsumedAuthorization {
+    readonly permitId: string;
+    readonly authority: AuthorizationAuthority;
+    /** ISO-8601. The permit is spent already; this is when it would have stopped being spendable. */
+    readonly expiresAt: string;
+}
+type ConsumeAuthorizationResult = {
+    readonly consumed: true;
+    readonly permit: ConsumedAuthorization;
+} | {
+    readonly consumed: false;
+    readonly refusal: PermitRefusal;
+    readonly reason: string;
+    /** On `already_consumed`, what the winning execution did. */
+    readonly executionState?: PermitExecutionState;
+};
+type ExecutionOutcome = 'succeeded' | 'failed';
+interface ExecutionReceipt {
+    readonly permitId: string;
+    readonly outcome: ExecutionOutcome;
+    /** Bounded and redacted server-side. What the action did, or why it did not. */
+    readonly summary?: string;
 }
 interface DecisionReachability {
     readonly reachable?: boolean;
@@ -283,7 +506,7 @@ interface EnrollResult {
     readonly universalLink: string;
     readonly expiresInSeconds: number;
 }
-interface AskDecision {
+interface AskDecision extends DecisionSubject {
     readonly question: string;
     readonly type?: DecisionType;
     readonly options?: readonly string[];
@@ -297,6 +520,9 @@ interface AskDecision {
     readonly poweredBy?: boolean;
     readonly callbackUrl?: string;
     readonly requireReachable?: boolean;
+    readonly sandboxOutcome?: SandboxOutcome;
+    readonly presentation?: ActionPresentation;
+    readonly approvalUrl?: boolean;
     readonly timeoutMs?: number;
 }
 interface AskResult extends DecisionReachability {
@@ -401,7 +627,14 @@ interface PusharyServer {
     readonly flows: FlowsResource;
     readonly decisions: DecisionsResource;
     readonly keys: KeysResource;
+    readonly authorize: (input: AuthorizeRequest) => Promise<AuthorizeResult>;
+    readonly evaluateAuthorization: (input: AuthorizationQuery) => Promise<AuthorizationEvaluation>;
+    readonly consumeAuthorization: (binding: AuthorizationBinding) => Promise<ConsumeAuthorizationResult>;
+    readonly recordExecution: (receipt: ExecutionReceipt) => Promise<{
+        readonly executionState: PermitExecutionState;
+    }>;
     readonly enroll: (externalId: string) => Promise<EnrollResult>;
+    readonly reachability: (externalId: string) => Promise<DecisionReach>;
 }
 declare const createPusharyServer: (config: PusharyConfig) => PusharyServer;
 
@@ -416,4 +649,4 @@ declare const isApproved: (decision: {
     readonly value: string | null;
 }) => boolean;
 
-export { parseDecisionCallback as $, type DecisionAnswerResult as A, type CancelDecisionResult as B, type Campaign as C, type DecisionType as D, type DecisionCallback as E, type Flow as F, type EnrollResult as G, type AskDecision as H, type AskResult as I, type IssueBoundKey as J, type BoundKeyResult as K, type ListParams as L, type BoundKeySummary as M, type SubscribersResource as N, type CampaignsResource as O, type PusharyServer as P, type TemplatesResource as Q, type RevokeKeyResult as R, type Subscriber as S, type Template as T, type UpdateSubscriber as U, type NotificationsResource as V, type WebhookSecret as W, type FlowsResource as X, type DecisionsResource as Y, type KeysResource as Z, verifyWebhookSignature as _, type PusharyConfig as a, SIGNATURE_HEADER as a0, deterministicKey as a1, isApproved as a2, type SubscriberListParams as b, createPusharyServer as c, type SubscriberCount as d, type CreateCampaign as e, type UpdateCampaign as f, type CampaignStats as g, type CreateTemplate as h, type UpdateTemplate as i, type SendNotification as j, type SendResult as k, type CreateFlow as l, type UpdateFlow as m, type FlowListParams as n, type FlowTriggerType as o, type FlowStepType as p, type FlowStatus as q, type FlowStep as r, type FlowStepConfig as s, type FlowStepInput as t, type PaginatedResponse as u, type DecisionStatus as v, type CreateDecision as w, type DecisionReachability as x, type DecisionResult as y, type Decision as z };
+export { type DecisionResult as $, type ActionPresentation as A, type PresentedChange as B, type Campaign as C, type DecisionType as D, type PresentedFormat as E, type Flow as F, type SandboxOutcome as G, type AuthorizationVerdict as H, type AuthorizationQuery as I, type AuthorizeRequest as J, type AuthorizeResult as K, type ListParams as L, type AuthorizationEvaluation as M, type AuthorizationBinding as N, type AuthorizationAuthority as O, type PusharyServer as P, type ConsumedAuthorization as Q, type ConsumeAuthorizationResult as R, type Subscriber as S, type Template as T, type UpdateSubscriber as U, type ExecutionOutcome as V, type ExecutionReceipt as W, type PermitRefusal as X, type PermitExecutionState as Y, type CreateDecision as Z, type DecisionReachability as _, type PusharyConfig as a, type Decision as a0, type DecisionAnswerResult as a1, type CancelDecisionResult as a2, type DecisionCallback as a3, type WebhookSecret as a4, type EnrollResult as a5, type AskDecision as a6, type AskResult as a7, type IssueBoundKey as a8, type BoundKeyResult as a9, type BoundKeySummary as aa, type RevokeKeyResult as ab, type SubscribersResource as ac, type CampaignsResource as ad, type TemplatesResource as ae, type NotificationsResource as af, type FlowsResource as ag, type DecisionsResource as ah, type KeysResource as ai, verifyWebhookSignature as aj, parseDecisionCallback as ak, SIGNATURE_HEADER as al, deterministicKey as am, isApproved as an, type SubscriberListParams as b, createPusharyServer as c, type SubscriberCount as d, type CreateCampaign as e, type UpdateCampaign as f, type CampaignStats as g, type CreateTemplate as h, type UpdateTemplate as i, type SendNotification as j, type SendResult as k, type CreateFlow as l, type UpdateFlow as m, type FlowListParams as n, type FlowTriggerType as o, type FlowStepType as p, type FlowStatus as q, type FlowStep as r, type FlowStepConfig as s, type FlowStepInput as t, type PaginatedResponse as u, type DecisionStatus as v, type DecisionSubject as w, type DecisionDeliverability as x, type DecisionReach as y, type DecisionParameters as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushary/server",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Pushary Server SDK: send push notifications and add human-in-the-loop approvals to your AI agent (pause on a decision until a specific human answers).",
   "author": "Pushary <business@pushary.com>",
   "homepage": "https://pushary.com",