@atlasent/sdk 1.5.0 → 2.10.0

package/dist/protect-BKxcoR_2.d.ts

@@ -1,159 +0,0 @@
-/**
- * Error types for the AtlaSent TypeScript SDK.
- *
- * The SDK follows a fail-closed design: a clean policy DENY is
- * returned as `EvaluateResponse.decision === "DENY"` (not thrown),
- * but any failure to confirm authorization — network, timeout,
- * bad response, invalid key, rate limit — throws an
- * {@link AtlaSentError}.
- */
-/** Discriminator for {@link AtlaSentError.code}. */
-type AtlaSentErrorCode = "invalid_api_key" | "forbidden" | "rate_limited" | "timeout" | "network" | "bad_response" | "bad_request" | "server_error";
-/** Initialization options for {@link AtlaSentError}. */
-interface AtlaSentErrorInit {
-    status?: number;
-    code?: AtlaSentErrorCode;
-    requestId?: string;
-    retryAfterMs?: number;
-    cause?: unknown;
-}
-/**
- * The only error type this SDK throws.
- *
- * Flat top-level properties mirror the convention used by Stripe,
- * Octokit, and Supabase. `cause` is forwarded to the standard
- * ES2022 `Error` constructor.
- */
-declare class AtlaSentError extends Error {
-    name: string;
-    /** HTTP status code, when the error originated from an API response. */
-    readonly status: number | undefined;
-    /** Coarse category — useful for `switch` statements at call sites. */
-    readonly code: AtlaSentErrorCode | undefined;
-    /** Correlation ID echoed from the `X-Request-ID` header the SDK sent. */
-    readonly requestId: string | undefined;
-    /** Parsed `Retry-After` header value, in milliseconds. Only set for 429. */
-    readonly retryAfterMs: number | undefined;
-    constructor(message: string, init?: AtlaSentErrorInit);
-}
-/**
- * Outcome of a denied decision.
- *
- * `"deny"` is what the current `/v1-evaluate` API returns. `"hold"`
- * and `"escalate"` are reserved for forthcoming API decisions that
- * put a permit into a pending state requiring human review; the
- * union is declared now so call sites can `switch` exhaustively
- * from the start and adopt new decisions without a breaking change.
- */
-type AtlaSentDecision = "deny" | "hold" | "escalate";
-/** Initialization options for {@link AtlaSentDeniedError}. */
-interface AtlaSentDeniedErrorInit {
-    decision: AtlaSentDecision;
-    evaluationId: string;
-    reason?: string;
-    requestId?: string;
-    auditHash?: string;
-}
-/**
- * Thrown by {@link atlasent.protect} when the policy engine refuses
- * the action, or when a permit fails end-to-end verification.
- *
- * This is the **fail-closed boundary** of the SDK: every code path
- * that short-circuits an action because authorization was not
- * confirmed raises an `AtlaSentDeniedError`. Callers cannot silently
- * proceed on a denial by forgetting to branch on a return value.
- *
- * Extends {@link AtlaSentError} so `instanceof AtlaSentError`
- * catches denials as part of the SDK's single exception family;
- * use `instanceof AtlaSentDeniedError` to distinguish a policy
- * denial from a transport/auth error.
- */
-declare class AtlaSentDeniedError extends AtlaSentError {
-    name: string;
-    /** Policy decision — `"deny"` today; `"hold"` / `"escalate"` reserved. */
-    readonly decision: AtlaSentDecision;
-    /** Opaque permit/decision id from `/v1-evaluate`. */
-    readonly evaluationId: string;
-    /** Human-readable explanation from the policy engine, if provided. */
-    readonly reason: string | undefined;
-    /** Hash-chained audit-trail entry associated with the decision. */
-    readonly auditHash: string | undefined;
-    constructor(init: AtlaSentDeniedErrorInit);
-}
-
-/**
- * `atlasent.protect(...)` — the one-call, fail-closed execution-time
- * authorization boundary.
- *
- * ```ts
- * import atlasent from "@atlasent/sdk";
- *
- * const permit = await atlasent.protect({
- *   agent: "deploy-bot",
- *   action: "deploy_to_production",
- *   context: { commit, approver },
- * });
- * // …run the action. If we got here, AtlaSent authorized it
- * // end-to-end (evaluate + verifyPermit).
- * ```
- *
- * Unlike {@link AtlaSentClient.evaluate}, `protect` never returns a
- * denied decision. On deny, it throws {@link AtlaSentDeniedError};
- * on transport / auth / server failure it throws
- * {@link AtlaSentError}. The action cannot execute unless a valid
- * {@link Permit} is returned — this is the SDK's category boundary,
- * not a helper.
- */
-/** Input to {@link protect}. Same shape as `EvaluateRequest`. */
-interface ProtectRequest {
-    agent: string;
-    action: string;
-    context?: Record<string, unknown>;
-}
-/**
- * Success return from {@link protect}. The action is authorized
- * end-to-end — evaluation allowed AND the resulting permit verified.
- */
-interface Permit {
-    /** Opaque permit / decision identifier. */
-    permitId: string;
-    /** Verification hash bound to the permit. */
-    permitHash: string;
-    /** Audit-trail entry associated with the decision (hash-chained). */
-    auditHash: string;
-    /** Human-readable reason from the policy engine. */
-    reason: string;
-    /** ISO 8601 timestamp of the verification. */
-    timestamp: string;
-}
-/** Configuration for the process-wide singleton used by {@link protect}. */
-interface ConfigureOptions {
-    /** Overrides `ATLASENT_API_KEY` env var. */
-    apiKey?: string;
-    /** Overrides the default `https://api.atlasent.io`. */
-    baseUrl?: string;
-    /** Per-request timeout in ms. */
-    timeoutMs?: number;
-    /** Inject a custom fetch (primarily for tests). */
-    fetch?: typeof fetch;
-}
-/**
- * Configure the singleton client used by {@link protect}. Optional —
- * if `ATLASENT_API_KEY` is set in the environment, `protect` works
- * without any configuration. Calling `configure` again replaces the
- * singleton; subsequent `protect` calls use the new settings.
- */
-declare function configure(options: ConfigureOptions): void;
-/**
- * Authorize an action end-to-end. On allow, returns a verified
- * {@link Permit}. On anything else, throws:
- *
- * - {@link AtlaSentDeniedError} — policy denied, or the permit
- *   failed verification. Fail-closed: if this throws, the action
- *   MUST NOT proceed.
- * - {@link AtlaSentError} — transport, timeout, auth, rate-limit,
- *   or server error. Same fail-closed contract: do not proceed.
- */
-declare function protect(request: ProtectRequest): Promise<Permit>;
-
-export { AtlaSentDeniedError as A, type ConfigureOptions as C, type Permit as P, AtlaSentError as a, type ProtectRequest as b, configure as c, type AtlaSentDecision as d, type AtlaSentDeniedErrorInit as e, type AtlaSentErrorCode as f, type AtlaSentErrorInit as g, protect as p };