@axonflow/sdk 9.1.0 → 9.2.0

package/README.md

@@ -7,13 +7,13 @@
 
 > **Upgrade strongly recommended.** AxonFlow ships substantial monthly security and quality hardening; staying on the latest major is the security-supported release line. [Latest release](https://github.com/getaxonflow/axonflow-sdk-typescript/releases/latest) · [Security advisories](https://github.com/getaxonflow/axonflow-sdk-typescript/security/advisories)
 
-> **Evaluating AxonFlow for a real deployment?**
+> **Taking a sponsored workflow to production?**
 >
 > Choose the path that fits:
 > - **Self-serve:** free 90-day [Evaluation License](https://getaxonflow.com/evaluation-license?utm_source=readme_sdk_typescript_eval)
-> - **Hands-on:** [Design Partner Program](https://getaxonflow.com/design-partner?utm_source=readme_sdk_typescript) — Enterprise access for the scoped engagement, founder-led architecture and rollout support, and preferential pricing after successful rollout
+> - **Paid production program:** [Design Partner or Confidential Pilot](https://getaxonflow.com/design-partner?utm_source=readme_sdk_typescript)  -  one scoped workflow over 60 or 75 days, founder-led rollout support, upfront conversion pricing, and a fixed decision date; public track from $2,000 or confidential track from $4,000
 >
-> Priority support, architecture review, incident-readiness review, and roadmap input are included for selected partners. We reply within 48 hours.
+> The paid program requires a dated forcing event, written controls, an executive sponsor, and a technical owner. Prices are subject to eligibility and a signed agreement.
 
 > **Questions or feedback?**
 >
@@ -29,11 +29,11 @@ A deployed AxonFlow platform (self-hosted or cloud) is required for end-to-end A
 
 ### See AxonFlow in Action
 
-Three short videos covering different angles of the platform:
+Videos covering different angles of the platform:
 
-- **[Community Quickstart Demo (Code + Terminal, 2.5 min)](https://youtu.be/BSqU1z0xxCo)** — governed calls, PII block, Gateway Mode with LangChain/CrewAI, and MAP from YAML
-- **[Runtime Control Demo (Portal + Workflow, 2.5 min)](https://youtu.be/sRTv2uF0sxY)** — approvals, retry safety, execution state, and the audit viewer
-- **[Architecture Deep Dive (12 min)](https://youtu.be/Q2CZ1qnquhg)** — how the control plane works, policy enforcement flow, and multi-agent planning
+- **[Product demos: Platform + Fraud & Risk](https://getaxonflow.com/demo/?utm_source=github&utm_medium=readme&utm_campaign=product_demo&utm_content=axonflow-sdk-typescript)** - runtime enforcement, HITL approvals, audit evidence, cost visibility, and agentic payment controls
+- **[Community Quickstart walkthrough (2 min)](https://youtu.be/BSqU1z0xxCo)** - governed calls, PII blocking, Gateway Mode with LangChain/CrewAI, and MAP from YAML
+- **[Architecture deep dive (12 min)](https://youtu.be/Q2CZ1qnquhg)** - how the control plane works, policy enforcement flow, and multi-agent planning
 
 ## Installation
 
@@ -67,7 +67,7 @@ Concurrent executions applies to MAP and WCP executions per tenant. Pending exec
 
 > **Note:** Evidence export and policy simulation are licensed AxonFlow platform capabilities available alongside the SDK on your deployed platform — not language-specific SDK helpers. Access them via the platform API or customer portal. The SDK row is included to show what your licensed deployment unlocks at each tier.
 
-[Get a free Evaluation license](https://getaxonflow.com/evaluation-license?utm_source=readme_sdk_typescript_eval) · [Apply for Design Partner](https://getaxonflow.com/design-partner?utm_source=readme_sdk_typescript_eval) · [Full feature matrix](https://docs.getaxonflow.com/docs/features/community-vs-enterprise?utm_source=readme_sdk_typescript_eval)
+[Get a free Evaluation license](https://getaxonflow.com/evaluation-license?utm_source=readme_sdk_typescript_eval) · [Run a paid production program](https://getaxonflow.com/design-partner?utm_source=readme_sdk_typescript_eval) · [Full feature matrix](https://docs.getaxonflow.com/docs/features/community-vs-enterprise?utm_source=readme_sdk_typescript_eval)
 
 ## Try Without Installing
 
@@ -461,6 +461,85 @@ export default async function handler(req, res) {
 }
 ```
 
+## AuthZEN-Native Authorization
+
+`axonflow.evaluate` asks the gateway an AuthZEN question - may this subject perform this action on this resource? - over `POST /api/v1/access/evaluation`. It is the surface to write **new** integrations against: at v11 the engine behind it becomes AxonFlow's new Policy Decision Point with no wire change, so an integration written here migrates once rather than twice. Nothing is deprecated by it today; `decide` and the gateway/proxy methods are wire-stable through all of v11.
+
+```typescript
+import { AuthZENRefusal, AxonFlow } from '@axonflow/sdk';
+
+const decision = await axonflow.evaluate({
+  subject: { type: 'gateway', id: 'llm-gateway-01' },
+  action: { name: 'llm.completion' },
+  resource: { type: 'llm', id: 'llm' },
+  context: { args: { query: userPrompt } },
+});
+
+if (!decision.allowed) {
+  throw new Error(`blocked: ${decision.state} (${decision.reason})`);
+}
+for (const obligation of decision.mandatoryObligations) {
+  // an allow you cannot discharge is not an allow
+}
+```
+
+Several preconditions of **one** operation go in a bulk envelope, which returns **one** decision - a denied entry denies the operation, so a caller cannot act on the entry it liked:
+
+```typescript
+const decision = await axonflow.evaluateAll({
+  subject: { type: 'gateway', id: 'llm-gateway-01' },
+  action: { name: 'tool.call' },
+  context: { args: { query: userPrompt } },
+  evaluations: [
+    { resource: { type: 'tool', id: 'jira/move_issue' } },
+    { resource: { type: 'tool', id: 'jira/update_project' } },
+  ],
+});
+```
+
+### Known gotchas
+
+**A refusal is not a denial.** This surface refuses anything it cannot evaluate rather than evaluating around it - send a subject property or an unrecognised context member and you get an `AuthZENRefusal` naming the exact member, not a decision computed without it. Treating every error as a deny fails closed, which is safe, but blocks traffic that would be allowed once the request is corrected.
+
+```typescript
+try {
+  const decision = await axonflow.evaluate(request);
+} catch (err) {
+  if (err instanceof AuthZENRefusal) {
+    err.code; // e.g. 'unevaluable_attribute' - a closed, generated set
+    err.pointer; // '/evaluation/subject/properties' - the member to fix
+    err.refusedBy; // 'client' (this SDK) or 'gateway'
+    err.retryable; // only a gateway dependency failure is
+  }
+}
+```
+
+`AuthZENProtocolError` is separate and means something else: the gateway answered `200` with a body this build cannot safely act on - no profile context, a profile it cannot read, or a decision boolean that disagrees with its operational state. It is always fail-closed, and the fix is an upgrade or an operator, not a corrected request. A `401` surfaces as the SDK's ordinary `AuthenticationError`, because the gateway answers authentication before this route runs.
+
+**`decision.allowed`, never `decision.decision`.** The bare boolean is AuthZEN 1.0's collapsed rendering; `allowed` additionally requires the operational state to be `ALLOW`, so a `CHALLENGE` or an `ERROR` can never be read as permission.
+
+**Three states, not two.** `undefined` cannot express the difference between "the source established there is no value" and "the source could not be reached", and collapsing them is how an attribute nobody resolved gets recorded as one that was weighed. Attributes inside the `context` and `properties` bags may be explicit:
+
+```typescript
+import { AUTHZEN_UNKNOWN_RESOLUTION_FAILED, AuthZENAttribute } from '@axonflow/sdk';
+
+const context = {
+  args: { query: userPrompt },
+  correlation: {
+    session_id: AuthZENAttribute.absent(), // a fact: omitted, request sent
+    trace_id: AuthZENAttribute.unknown(AUTHZEN_UNKNOWN_RESOLUTION_FAILED), // refused locally
+  },
+};
+```
+
+The tri-state applies to attribute **data**, not to the structural members (`subject.id`, `action.name`, …): those are the identity of the question being asked, and an identity you cannot resolve is not an attribute whose absence a policy could evaluate - there is no request to make.
+
+**Wire member names are `snake_case`, not `camelCase`.** These interfaces ARE the wire documents - they are serialised verbatim - so `source_policy`, `decision_id` and `schema_version` keep the names the server uses. That is deliberate: a server refusal's JSON Pointer names a member, and the pointer is this surface's whole diagnosis, so it has to name a member the caller can find in their own code.
+
+**Today's mapping is deliberately narrow.** `subject.type` must be `'gateway'` (an end-user subject needs the identity plane, which activates at v11); an `llm` or `agent` resource id must be the stage name itself, not a provider/model pair, because nothing on the serving path reads a provider or a model; a `tool` resource id is `'server/tool'`, because both halves ARE read. Everything else is refused by name.
+
+The wire types AND their runtime validators are **generated** from the platform's canonical contract artifact (`scripts/gen-authzen-types/generate.js`); CI fails if the committed module is not what the artifact produces. A TypeScript interface is erased at runtime, so the validators are what actually refuses a body this build cannot interpret. Runnable example: [`examples/authzen/index.ts`](examples/authzen/index.ts). Migration notes: [`docs/AUTHZEN_MIGRATION_DRAFT.md`](docs/AUTHZEN_MIGRATION_DRAFT.md).
+
 ## Configuration Options
 
 ```typescript
@@ -716,16 +795,16 @@ connectors.forEach(conn => {
 
 ```typescript
 await axonflow.installConnector({
-  connector_id: 'amadeus-travel',
-  name: 'amadeus-prod',
+  connector_id: 'redis-cache',
+  name: 'redis-cache',
   tenant_id: 'your-tenant-id',
   options: {
-    environment: 'production'
+    // Host/port as seen from the platform (orchestrator), not from this
+    // process — 'redis' on the docker-compose stack.
+    host: 'redis',
+    port: 6379
   },
-  credentials: {
-    api_key: process.env.AMADEUS_API_KEY,
-    api_secret: process.env.AMADEUS_API_SECRET
-  }
+  credentials: {}
 });
 
 console.log('Connector installed successfully!');
@@ -734,19 +813,18 @@ console.log('Connector installed successfully!');
 ### Query a Connector
 
 ```typescript
-// Query the Amadeus connector for flight information
+// Query the Redis connector. Redis connector queries are command
+// statements (GET / EXISTS / TTL / KEYS) with the key in params.
 const resp = await axonflow.queryConnector(
-  'amadeus-prod',
-  'Find flights from Paris to Amsterdam on Dec 15',
+  'redis-cache',
+  'GET',
   {
-    origin: 'CDG',
-    destination: 'AMS',
-    date: '2025-12-15'
+    key: 'user:123:preferences'
   }
 );
 
 if (resp.success) {
-  console.log('Flight data:', resp.data);
+  console.log('Redis data:', resp.data);
 } else {
   console.error('Query failed:', resp.error);
 }
@@ -1028,6 +1106,23 @@ distinguishable from production heartbeat).
 
 `AXONFLOW_TELEMETRY=off` disables the anonymous SDK heartbeat (version, OS, architecture). On **self-hosted** and **in-VPC** deployments, that heartbeat is the only data the SDK sends to AxonFlow, so setting `=off` means we receive nothing. On **Community SaaS** (`try.getaxonflow.com`) the hosted service also processes operational data — registrations, audit logs, policy enforcement records, workflow state, plan data, and request-header metadata aggregated for usage analytics — as part of running the platform; that operational data flow is governed by the [Privacy Policy](https://getaxonflow.com/privacy/), not by `AXONFLOW_TELEMETRY`.
 
+### Platform licence tier (`license_tier`)
+
+Each heartbeat also reports the licence tier of the AxonFlow platform the SDK is configured to talk to — for example `community`, `evaluation`, `Enterprise`, or the transient `starting` while a platform is still booting. This lets us tell an enterprise-licensed deployment apart from an unlicensed community one in aggregate adoption figures, which the heartbeat previously could not distinguish.
+
+What is and is not collected:
+
+- **Collected:** the coarse tier string only.
+- **Not collected:** your licence key, its expiry, its seat or node count, your organisation's name, and any other licence detail. The SDK never reads your licence key.
+
+The value is read from the `tier` field of the platform's own `/health` response — the same response the heartbeat already fetches to report the platform version, and an endpoint that returns this field to any caller without authentication. **No additional network request is made, and the SDK gains no access to anything `/health` does not already return.**
+
+**This is an adoption-analytics signal, not an entitlement one.** The value is whatever the platform at your configured endpoint reported about itself, relayed unchanged: the SDK derives nothing and verifies nothing, and the receiver cannot verify the relay either. Whoever operates that endpoint controls the value completely, so it must never gate entitlement, unlock a feature, or enter any authorization or billing decision. It is used only for aggregate adoption figures.
+
+The field is **omitted entirely** whenever the tier could not be determined — the platform is unreachable, returns an error, returns an unparseable body, or returns no `tier` field. It is never defaulted to a guessed value, so an absent field means "not known", never "community".
+
+`AXONFLOW_TELEMETRY=off` suppresses this field along with the rest of the heartbeat.
+
 `DO_NOT_TRACK` is **not** honored as an opt-out for AxonFlow telemetry. It is commonly inherited from host tools and developer environments, which makes it an unreliable expression of user intent.
 
 See [Telemetry Documentation](https://docs.getaxonflow.com/docs/telemetry) for full details.

package/dist/cjs/authzen.d.ts

@@ -0,0 +1,328 @@
+/**
+ * AuthZEN-native authorization for the AxonFlow SDK.
+ *
+ * This is the surface the ADR-065 compatibility plan commits to in all five
+ * SDKs. It talks to `POST /api/v1/access/evaluation`, whose wire shape is
+ * generated from the platform's canonical contract (see
+ * `src/types/authzen.gen.ts`); nothing in this file re-states a field name or
+ * an enum value.
+ *
+ * ## What this replaces, and when
+ *
+ * Nothing yet. The existing decision surface (`decide`, `explainDecision` and
+ * the gateway/proxy methods) stays wire-stable through all of v11 and is not
+ * deprecated here. This is the surface to write NEW integrations against,
+ * because at v11 the engine behind it becomes the ADR-065 Policy Decision Point
+ * with no wire change — an integration written against it migrates once rather
+ * than twice. See `docs/AUTHZEN_MIGRATION_DRAFT.md`.
+ *
+ * ## The one thing worth knowing before you call it
+ *
+ * The server refuses anything it cannot evaluate rather than evaluating around
+ * it. Send a subject property, an unrecognised context member, or an argument
+ * beside the query, and you get an `AuthZENRefusal` naming the exact member —
+ * not a decision computed without it. That is deliberate: a decision that
+ * silently ignored an attribute would tell you the attribute was weighed when
+ * it was not, and every audit of that decision would inherit the claim.
+ *
+ * So treat an `AuthZENRefusal` as "fix the request", and retry only when
+ * `refusal.retryable` is true.
+ */
+import { AxonFlowError } from './errors';
+import { AuthZENApprovalRequirement, AuthZENBulk, AuthZENCategory, AuthZENEnvelope, AuthZENError, AuthZENErrorCode, AuthZENObligation, AuthZENOperationalState, AuthZENReasonCode, AuthZENRequest, AuthZENResponse, AuthZENResponseContext } from './types/authzen.gen';
+/**
+ * The marker every tri-state attribute carries. See {@link AuthZENAttribute}.
+ *
+ * Exported so a caller building attributes across a serialisation boundary can
+ * reconstruct one the SDK will still recognise.
+ */
+export declare const AUTHZEN_ATTRIBUTE_MARKER = "__axonflow_authzen_attribute__";
+/** The AuthZEN evaluation endpoint. */
+export declare const AUTHZEN_PATH = "/api/v1/access/evaluation";
+/**
+ * How a Policy Enforcement Point negotiates the AxonFlow profile.
+ *
+ * The SDK always sends it. AuthZEN 1.0's response is a bare boolean, and the
+ * four-valued state, the obligations and the approval challenge ride in the
+ * response context, which the server returns only to a caller that asked for it
+ * by version. This SDK understands the profile, so there is no reason to ask
+ * for less than it can read — and a response WITHOUT the context is therefore a
+ * protocol failure here rather than a decision with no obligations.
+ */
+export declare const AUTHZEN_PROFILE_HEADER = "X-Axonflow-AuthZEN-Profile";
+export declare const AUTHZEN_UNKNOWN_NOT_SUPPLIED = "attribute_not_supplied";
+export declare const AUTHZEN_UNKNOWN_RESOLUTION_FAILED = "resolution_failed";
+export declare const AUTHZEN_UNKNOWN_STALE = "stale";
+export declare const AUTHZEN_UNKNOWN_SCHEMA_MISMATCH = "schema_mismatch";
+export declare const AUTHZEN_UNKNOWN_CLOSURE_UNAVAILABLE = "closure_unavailable";
+export declare const AUTHZEN_UNKNOWN_CLOSURE_TRUNCATED = "closure_truncated";
+export declare const AUTHZEN_UNKNOWN_MALFORMED_VALUE = "malformed_value";
+export declare const AUTHZEN_UNKNOWN_REQUIRED_ABSENT = "required_attribute_absent";
+/** Who declined to produce a decision. */
+export type AuthZENRefusedBy = 'client' | 'gateway';
+/**
+ * The request was NOT evaluated, and here is the typed reason why.
+ *
+ * A refusal is not a denial. `decision: false` says the request WAS evaluated
+ * and the answer was no; a refusal says no decision exists. Code that treats
+ * every error as a deny fails closed — which is safe — but will block traffic
+ * that should have been allowed once the request is corrected.
+ *
+ * `refusedBy` says who made the call. `'gateway'` is a refusal document the
+ * server sent; `'client'` is this SDK declining to send a request it can
+ * already see will not be evaluated — an attribute the caller could not
+ * resolve, or an evaluation with no subject. The code vocabulary is shared
+ * because the REASONS are shared: an incomplete evaluation is an incomplete
+ * evaluation whoever notices it first.
+ */
+export declare class AuthZENRefusal extends AxonFlowError {
+    readonly code: AuthZENErrorCode;
+    readonly pointer?: string;
+    readonly supported?: string[];
+    readonly requestId?: string;
+    readonly refusedBy: AuthZENRefusedBy;
+    constructor(code: AuthZENErrorCode, message: string, options: {
+        refusedBy: AuthZENRefusedBy;
+        pointer?: string;
+        supported?: string[];
+        requestId?: string;
+    });
+    /** Build a refusal from the structured document the server sent. */
+    static fromBody(body: AuthZENError): AuthZENRefusal;
+    /**
+     * Whether sending the same request again could give a different answer.
+     *
+     * Only a dependency failure the GATEWAY reported is. Every other code names
+     * something about the request itself, which will not change on a retry — so
+     * a client that retries on any refusal burns its budget on requests that
+     * cannot succeed.
+     *
+     * A client-side refusal is never retryable, whatever its code: this SDK does
+     * not resolve the caller's attributes, so nothing it can do will change the
+     * answer. Reading retryability off the code alone would have told a caller to
+     * retry an attribute its own resolver failed to produce.
+     */
+    get retryable(): boolean;
+}
+/**
+ * A 200 whose body this build cannot safely interpret.
+ *
+ * Deliberately NOT an `AuthZENRefusal`. A refusal carries the server's own
+ * typed code from a closed vocabulary the server owns; a response this build
+ * cannot read is not something the server said, and dressing it in a server
+ * code would tell the caller the gateway refused when it did not. The two also
+ * demand different actions: a refusal means fix the request, a protocol error
+ * means upgrade the SDK or go and look at the deployment.
+ *
+ * It is always fail-closed: no decision is returned, so a caller that lets it
+ * propagate blocks the operation.
+ */
+export declare class AuthZENProtocolError extends AxonFlowError {
+    constructor(message: string);
+}
+/** The three states a policy-visible attribute can be in. */
+export type AuthZENAttributeState = 'known' | 'absent' | 'unknown';
+/**
+ * One policy-visible attribute in exactly one of three states.
+ *
+ * `undefined` and `null` cannot express this. ADR-065's model has three:
+ *
+ * - `known` — the authoritative source returned a value. It is sent.
+ * - `absent` — the source successfully established that there is NO value.
+ *   Absence is a FACT, not a failure, so the member is omitted and the request
+ *   is sent: a policy that handles absence gets to handle it.
+ * - `unknown` — the value could not be established. The request is NOT sent.
+ *   Sending it would have the gateway evaluate as though the attribute were
+ *   absent, and the resulting decision — and every audit of it — would record
+ *   that an attribute was weighed when nobody ever read it. That is the exact
+ *   failure the whole surface refuses to commit, one hop earlier.
+ *
+ * Collapsing absent into unknown is the defect this type exists to prevent, and
+ * it is not hypothetical: on the platform side an ABSENT `subject.type` was
+ * read as the one supported value, so omitting the field bypassed the
+ * impersonation refusal that naming it correctly triggered.
+ *
+ * Where it may be used: inside the ATTRIBUTE bags — `context` on a request or a
+ * bulk envelope, and the `properties` bag on a subject, action or resource — at
+ * any depth. Not on the structural members (`subject.id`, `action.name`,
+ * `resource.type` …): those are the identity of the question being asked, not
+ * data about it, and an identity the caller cannot resolve is not an attribute
+ * whose absence a policy could evaluate — there is simply no request to make.
+ *
+ * @example
+ * ```typescript
+ * AuthZENAttribute.known('acme-corp');
+ * AuthZENAttribute.absent();
+ * AuthZENAttribute.unknown(AUTHZEN_UNKNOWN_RESOLUTION_FAILED);
+ * ```
+ */
+export declare class AuthZENAttribute {
+    readonly state: AuthZENAttributeState;
+    readonly value: unknown;
+    readonly reason: string;
+    /**
+     * The marker, carried as an ordinary ENUMERABLE property.
+     *
+     * Recognising an attribute by `instanceof` alone has a silent failure in the
+     * dangerous direction: a bundler that duplicated this package gives two
+     * distinct classes. A non-enumerable Symbol brand fixes that and introduces
+     * the same failure by another route - every ordinary copy strips it, so
+     * `structuredClone`, a spread, a JSON round trip or a worker boundary turned
+     * an UNKNOWN attribute back into ordinary data and SENT it. Measured against
+     * a live gateway.
+     *
+     * Recognising it by SHAPE alone has the mirror failure: a caller's own bag
+     * carrying `state`/`value`/`reason` is read as an attribute, and a legitimate
+     * request is refused with a message asserting the caller could not establish
+     * a value it did establish.
+     *
+     * An enumerable marker closes both. It survives every ordinary copy, and no
+     * caller's data carries it by accident. The Python sibling uses the same key
+     * for the same reason.
+     */
+    readonly [AUTHZEN_ATTRIBUTE_MARKER] = true;
+    private constructor();
+    /** The source returned this value. */
+    static known(value: unknown): AuthZENAttribute;
+    /** The source established that there is no value. */
+    static absent(): AuthZENAttribute;
+    /**
+     * The value could not be established, for the named reason.
+     *
+     * The reason is mandatory. An unknown with no reason carries no more than
+     * `undefined` already did, and the whole point of the third state is that it
+     * says why.
+     */
+    static unknown(reason: string): AuthZENAttribute;
+    /**
+     * Whether `value` is a tri-state attribute, however it was copied.
+     *
+     * See the marker above for why this is neither a bare `instanceof` nor a
+     * structural shape check.
+     */
+    static is(value: unknown): value is AuthZENAttribute;
+}
+/**
+ * The decision, with the readings a Policy Enforcement Point acts on.
+ *
+ * It implements the generated wire type rather than replacing it, so `decision`
+ * and `context` remain exactly what the server sent while the readings below
+ * stay in hand-written code the generator never has to know about.
+ */
+export declare class AuthZENDecision implements AuthZENResponse {
+    readonly decision: boolean;
+    readonly context?: AuthZENResponseContext;
+    constructor(response: AuthZENResponse);
+    /**
+     * Whether the enforcement point may proceed.
+     *
+     * Read this rather than `decision`. `decision` is AuthZEN 1.0's collapsed
+     * boolean; the operational STATE is what the policy engine actually produced,
+     * and exactly one state permits execution. Requiring both means a response
+     * whose boolean and state disagree can never be read as an allow — and such a
+     * response is refused before it gets here anyway, so this is the second of
+     * two locks rather than the only one.
+     *
+     * An allow with an undischarged MANDATORY obligation is not an allow. See
+     * `mandatoryObligations`.
+     */
+    get allowed(): boolean;
+    /**
+     * The four-valued operational state.
+     *
+     * `ERROR` when there is no context. Unreachable via `evaluate`, which refuses
+     * a context-less 200 before constructing this — but the type is public and a
+     * caller can build one by hand, and the safe reading of an outcome that
+     * carries no state is not ALLOW.
+     */
+    get state(): AuthZENOperationalState;
+    /**
+     * The id of the evaluation that DETERMINED this outcome.
+     *
+     * For a bulk envelope this is the entry that decided the meet, not the last
+     * one evaluated: it is the id an operator looks up to explain the answer.
+     */
+    get decisionId(): string | undefined;
+    /** The safe machine-readable reason code, when the server sent one. */
+    get reason(): AuthZENReasonCode | undefined;
+    /** The coarse outcome category, when the server sent one. */
+    get category(): AuthZENCategory | undefined;
+    /** Instructions the enforcement point must discharge before proceeding. */
+    get obligations(): AuthZENObligation[];
+    /**
+     * The obligations that are not optional.
+     *
+     * A mandatory obligation that cannot be discharged means the operation must
+     * NOT proceed, even though `allowed` is true. This SDK cannot make that call
+     * for you — whether your enforcement point can discharge a redaction is a
+     * fact about your seam, not about the decision — so it gives you the list and
+     * stays out of the way.
+     */
+    get mandatoryObligations(): AuthZENObligation[];
+    /** The approval challenge, when the state is CHALLENGE. */
+    get approval(): AuthZENApprovalRequirement | undefined;
+}
+/**
+ * Return the envelope with every tri-state attribute resolved to the wire.
+ *
+ * Throws `AuthZENRefusal` with `refusedBy: 'client'` and the JSON Pointer of
+ * the offending member when an attribute is UNKNOWN.
+ *
+ * The pointers match the server's own vocabulary — `/evaluation/...` for a
+ * singular envelope, `/evaluations/evaluations/<i>/...` for a plural entry — so
+ * a client-side refusal and a gateway refusal name the same member the same
+ * way, and a caller does not have to learn two pointer dialects.
+ */
+export declare function resolveEnvelope(envelope: AuthZENEnvelope): AuthZENEnvelope;
+/** Refuse an envelope that cannot produce a decision, before the round trip. */
+export declare function checkEnvelopeComplete(envelope: AuthZENEnvelope): void;
+/** What `evaluateEnvelope` needs from the SDK's own HTTP path. */
+export type AuthZENTransport = (path: string, body: unknown, headers: Record<string, string>) => Promise<{
+    status: number;
+    body: string;
+}>;
+/**
+ * Build an envelope: RESOLVE, check completeness, then validate.
+ *
+ * The counterpart of the Python sibling's `build_envelope`, and it exists for
+ * the same reason: `evaluate` and `evaluateAll` must not each assemble an
+ * envelope inline, or the two entry points drift on the order these steps run
+ * in - and that order decides which of two problems a caller with two problems
+ * is told about.
+ */
+export declare function buildEnvelope(evaluation?: AuthZENRequest, evaluations?: AuthZENBulk): AuthZENEnvelope;
+/**
+ * Run one envelope through `send` and interpret the answer.
+ *
+ * `send` is the SDK's own transport — the same authenticated fetch wrapper,
+ * headers and heartbeat gate every other method uses. It is passed in rather
+ * than built here so this module owns the AuthZEN semantics and nothing else; a
+ * second transport would be a second place for credentials, timeouts and proxy
+ * configuration to drift out of step with the client the user configured.
+ */
+export declare function evaluateEnvelope(send: AuthZENTransport, envelope: AuthZENEnvelope): Promise<AuthZENDecision>;
+/**
+ * Guarantee no tri-state attribute reaches the wire.
+ *
+ * `resolveEnvelope` walks every bag the contract declares, so on today's
+ * contract this has nothing to catch. It exists for the case that does not
+ * announce itself: a container kind added to the artifact later, or an attribute
+ * reaching a member the resolver does not visit. Without it that attribute is
+ * not a crash - `JSON.stringify` turns the instance into an ordinary
+ * `{"state": …, "value": …, "reason": …}` object - so the request is SENT,
+ * carrying a resolver's internal shape where the gateway expects a value, and an
+ * UNKNOWN attribute reaches the network after all.
+ *
+ * The Python sibling carries the same control, and had exactly this defect:
+ * there the check ran after serialisation and could never fire.
+ */
+export declare function assertFullyResolved(value: unknown, path?: string, depth?: number): void;
+/**
+ * The exact document this SDK would send for `envelope`.
+ *
+ * Exported for tests and for support: "what did the SDK actually put on the
+ * wire" is the first question of every integration problem, and answering it by
+ * reading the client's source is how the answer ends up wrong.
+ */
+export declare function toWire(envelope: AuthZENEnvelope): AuthZENEnvelope;
+//# sourceMappingURL=authzen.d.ts.map

package/dist/cjs/authzen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authzen.d.ts","sourceRoot":"","sources":["../../src/authzen.ts"],"names":[],"mappings":"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"}