kaafil-js 0.1.0-beta.0

package/dist/client-entry.d.cts

@@ -0,0 +1,187 @@
+import { E as Environment, R as Resolvable, M as ManagerRefreshResult, A as AgencyAdminRefreshResult, V as VendorsResource, J as JourneyResource } from './paginator-CE9JhsLi.cjs';
+export { B as BookingStatus, C as ClaimStatusIngest, a as CursorPageMeta, b as ERROR_CODE_TABLE, c as ErrorCodeTableEntry, d as EventType, F as FetchPage, G as Gender, K as KaafilAbortError, e as KaafilApiError, f as KaafilCapabilityUnavailableError, g as KaafilEntitlementError, h as KaafilError, i as KaafilErrorCode, j as KaafilErrorKind, k as KaafilInvalidRequestError, l as KaafilLockedError, m as KaafilNetworkError, n as KaafilNotFoundError, o as KaafilNotImplementedError, p as KaafilPagedResponse, q as KaafilPaginationError, r as KaafilPaginationExhaustedError, s as KaafilPaginationInFlightError, t as KaafilPaginator, u as KaafilRateLimitedError, v as KaafilReadOnlyRoleError, w as KaafilResponse, x as KaafilShareTokenExpiredError, y as KaafilShareTokenRevokedError, z as KaafilTimeoutError, D as KaafilTransportError, H as KaafilUnauthenticatedError, I as KaafilValidationError, L as KaafilVersionConflictError, N as ManagerRole, O as ManifestMode, P as OutboxClass, Q as PagedResponseMeta, S as PaginatorPage, T as PartyKind, U as PlanRefusalReason, W as ResponseMeta, X as Retryability, Y as TriggerAnchor, Z as TripMode, _ as TripStatus, $ as UnsatisfiableSchemeError, a0 as WaitUntilJourneyReadyOptions, a1 as isKaafilError, a2 as isRetryable } from './paginator-CE9JhsLi.cjs';
+
+/**
+ * `KaafilClient` — the browser entry (`kaafil-js/client`).
+ * `architecture/08-sdk.md §2, §3.2, §3.3`.
+ *
+ * Kept as a separate module graph from `./client.ts`/`./index.ts` so it
+ * structurally CANNOT reach the API-key credential path — not by
+ * convention, by the shape of the import graph:
+ *
+ * - This file never imports `./client.ts` (the only place a
+ *   `{ kind: 'apiKey', apiKey }` config is ever assembled) or `./index.ts`.
+ * - It never imports `./config.ts`'s API-key-specific exports —
+ *   `assertApiKeyMatchesEnvironment`, `guardApiKeyEnvironment`,
+ *   `ApiKeyEnvironmentMismatchError` — only `resolveBaseUrl`/
+ *   `assertValidTimeout`/`assertValidMaxAttempts`, which every client needs,
+ *   API key or not.
+ * - It builds `ManagerSessionCredentialConfig`/`ShareTokenCredentialConfig`/
+ *   `AgencyAdminCredentialConfig` objects using the literal string kinds
+ *   (`'managerSession'`/`'shareToken'`/`'agencyAdmin'`) rather than
+ *   importing the shared `CredentialKind` value export from
+ *   `./auth/credentials.ts` — that constant's own object literal carries the
+ *   `'apiKey'` kind alongside the other three (one generated-adjacent table,
+ *   not four separable ones), so importing it at all would pull that value
+ *   into this bundle for no reason this file has.
+ *
+ * A bundler following only this file's import graph has no path to the code
+ * that turns an API-key string into a working credential. (`./auth/credentials.ts`'s
+ * `SECURITY_SCHEME_CARRIERS` table — shared infrastructure `CredentialResolver`
+ * needs to resolve a `managerAuth`/`shareAuth`/`agencyAdminAuth` *bearer*
+ * header just as much as an `apiKeyAuth` one — still carries the literal
+ * header name `X-API-Key` as inert data for the scheme this file never
+ * selects; that table is generated, single, and un-split, so its presence in
+ * this bundle is not evidence of a reachable API-key path. What this file
+ * cannot do, from its own code or anything it imports, is construct or
+ * validate an API-key credential, or reach the `Kaafil` class.)
+ */
+
+interface KaafilClientOptions {
+    readonly environment: Environment;
+    /** Overrides the environment's default base URL outright — see
+     * `./config.ts`'s `resolveBaseUrl` for why the two are never merged. */
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly maxAttempts?: number;
+    readonly userAgent?: string;
+    readonly random?: () => number;
+}
+/**
+ * `session.open(...)`'s options — just the tokens a manager-token mint (or a
+ * prior refresh) already handed the host; never a URL, never a header.
+ * Rotation from here on is automatic (`./auth/credentials.ts`'s
+ * `CredentialResolver`, exchanging directly with the engine).
+ */
+interface OpenManagerSessionOptions {
+    readonly accessToken: Resolvable<string>;
+    readonly refreshToken: Resolvable<string>;
+    readonly expiresAt?: Resolvable<string>;
+    /** Persists the rotated pair after a successful refresh — the SDK keeps
+     * no state across a reload, so this is the host's one hook to survive one. */
+    readonly onRefresh?: (result: ManagerRefreshResult) => void | Promise<void>;
+    /** Overrides the direct engine exchange with an integrator-supplied one —
+     * see `./auth/credentials.ts`'s `ManagerSessionCredentialConfig.refresh`. */
+    readonly refresh?: (refreshToken: string) => Promise<ManagerRefreshResult>;
+}
+/**
+ * `admin.open(...)`'s options — the agency-admin analogue of
+ * `OpenManagerSessionOptions` above: the access/refresh pair a server-side
+ * `kaafil.auth.mintAgencyAdminToken(...)` call (or a prior refresh) already
+ * handed the host. Rotation from here on is automatic, the same way a
+ * manager session's is (`./auth/credentials.ts`'s `CredentialResolver`,
+ * exchanging directly with the engine).
+ */
+interface OpenAgencyAdminSessionOptions {
+    readonly accessToken: Resolvable<string>;
+    readonly refreshToken: Resolvable<string>;
+    readonly expiresAt?: Resolvable<string>;
+    readonly onRefresh?: (result: AgencyAdminRefreshResult) => void | Promise<void>;
+    /** Overrides the direct engine exchange with an integrator-supplied one —
+     * see `./auth/credentials.ts`'s `AgencyAdminCredentialConfig.refresh`. */
+    readonly refresh?: (refreshToken: string) => Promise<AgencyAdminRefreshResult>;
+}
+/** `share.open(...)`'s options. */
+interface OpenShareTokenOptions {
+    readonly token: Resolvable<string>;
+}
+/**
+ * Thrown by `.vendors`/`.journey` before `session.open()`/`share.open()` has
+ * run, or after `close()`. There is no resource surface without a credential
+ * to resolve headers with, so this fails at the point of use rather than
+ * letting a call fall through to an unauthenticated request.
+ */
+declare class KaafilClientNotOpenError extends Error {
+    constructor();
+}
+/**
+ * Thrown by `session.open()`/`share.open()` while a session is already open.
+ * `close()` first — silently replacing a live session out from under
+ * whatever the caller thought was still open is exactly the kind of
+ * ambiguity this SDK does not leave implicit.
+ */
+declare class KaafilClientAlreadyOpenError extends Error {
+    constructor();
+}
+/**
+ * The browser client. Constructed with only an `environment` — no
+ * credential yet, because none exists until a manager session, an
+ * agency-admin session, or a share token is minted server-side and handed
+ * to `session.open`/`admin.open`/`share.open`.
+ *
+ * Only `vendors` and `journey` are reachable from here: every other
+ * resource group built in this wave (`trips`, `auth`, `shareTokens`,
+ * `webhooks`, `events`) declares `apiKeyAuth` as its only accepted scheme in
+ * the vendored spec (`../generated/security.ts`'s `OPERATION_SECURITY`) —
+ * a scheme none of a manager session, an agency-admin session, or a share
+ * token can ever satisfy — so exposing them here would just be a way to
+ * reach `UnsatisfiableSchemeError` a resource-group at a time. `vendors`
+ * (`listTripVendors`) and `journey` (`readJourney`/`readJourneyCapabilities`/
+ * `listJourneyTriggers`/`patchJourneyTrigger`) both accept `apiKeyAuth` OR
+ * `managerAuth` OR `agencyAdminAuth` — genuinely reachable from either
+ * rotating session this file can open. Both are exposed uniformly for a
+ * `shareToken`-opened client too, rather than hand-branching per credential
+ * kind here: no operation in the current spec accepts `shareAuth` at all
+ * (verified — `grep shareAuth src/generated/security.ts` matches only the
+ * scheme's own declaration, never an operation's accepted-schemes list), so
+ * a share-opened client calling either today gets `UnsatisfiableSchemeError`
+ * from `CredentialResolver` itself; the moment a future spec revision adds a
+ * `shareAuth`-accepting operation to either group, it becomes reachable here
+ * with no change to this file, which is the entire point of leaving that
+ * decision to the resolver rather than duplicating the spec's scheme table
+ * as a second, hand-maintained gate here.
+ */
+declare class KaafilClient {
+    #private;
+    constructor(options: KaafilClientOptions);
+    readonly session: {
+        /**
+         * Opens a manager session with the access/refresh pair a server-side
+         * `kaafil.auth.mintManagerToken(...)` call already minted. Rotation
+         * after this point — pre-emptive, and on a `401` — is entirely
+         * automatic: `CredentialResolver` exchanges directly with the engine
+         * (`../auth/credentials.ts`, `../http/client.ts`'s
+         * `createManagerSessionRefreshExchange`). Nothing else is required —
+         * `refresh`/`onRefresh` above are optional hooks, not obligations.
+         */
+        open: (options: OpenManagerSessionOptions) => void;
+    };
+    readonly admin: {
+        /**
+         * Opens an agency-admin session with the access/refresh pair a
+         * server-side `kaafil.auth.mintAgencyAdminToken(...)` call already
+         * minted. Rotation after this point — pre-emptive, and on a `401` — is
+         * entirely automatic, the same way `session.open`'s is:
+         * `CredentialResolver` exchanges directly with the engine
+         * (`../auth/credentials.ts`, `../http/client.ts`'s
+         * `createAgencyAdminSessionRefreshExchange`). Nothing else is required
+         * — `refresh`/`onRefresh` above are optional hooks, not obligations.
+         */
+        open: (options: OpenAgencyAdminSessionOptions) => void;
+    };
+    readonly share: {
+        /** Opens a read-only session with a share token minted server-side by
+         * `kaafil.shareTokens.create(...)`. */
+        open: (options: OpenShareTokenOptions) => void;
+    };
+    get vendors(): VendorsResource;
+    get journey(): JourneyResource;
+    /**
+     * Total teardown. One assignment, no field to forget — see
+     * `KaafilClientState` above. Safe to call whether or not a session is
+     * open; calling any resource method afterward throws
+     * `KaafilClientNotOpenError`, and `session.open`/`share.open` can be
+     * called again immediately after.
+     */
+    close(): void;
+    /**
+     * Mints an idempotency key outside the normal per-call flow. Every
+     * mutating method already mints and reuses one automatically
+     * (`../http/client.ts`) — this exists for the rare case of pinning a key
+     * ahead of time, to replay the exact same logical operation across a
+     * process restart.
+     */
+    static newIdempotencyKey(): string;
+}
+
+export { AgencyAdminRefreshResult, Environment, JourneyResource, KaafilClient, KaafilClientAlreadyOpenError, KaafilClientNotOpenError, type KaafilClientOptions, ManagerRefreshResult, type OpenAgencyAdminSessionOptions, type OpenManagerSessionOptions, type OpenShareTokenOptions, Resolvable, VendorsResource };

package/dist/client-entry.d.ts

@@ -0,0 +1,187 @@
+import { E as Environment, R as Resolvable, M as ManagerRefreshResult, A as AgencyAdminRefreshResult, V as VendorsResource, J as JourneyResource } from './paginator-CE9JhsLi.js';
+export { B as BookingStatus, C as ClaimStatusIngest, a as CursorPageMeta, b as ERROR_CODE_TABLE, c as ErrorCodeTableEntry, d as EventType, F as FetchPage, G as Gender, K as KaafilAbortError, e as KaafilApiError, f as KaafilCapabilityUnavailableError, g as KaafilEntitlementError, h as KaafilError, i as KaafilErrorCode, j as KaafilErrorKind, k as KaafilInvalidRequestError, l as KaafilLockedError, m as KaafilNetworkError, n as KaafilNotFoundError, o as KaafilNotImplementedError, p as KaafilPagedResponse, q as KaafilPaginationError, r as KaafilPaginationExhaustedError, s as KaafilPaginationInFlightError, t as KaafilPaginator, u as KaafilRateLimitedError, v as KaafilReadOnlyRoleError, w as KaafilResponse, x as KaafilShareTokenExpiredError, y as KaafilShareTokenRevokedError, z as KaafilTimeoutError, D as KaafilTransportError, H as KaafilUnauthenticatedError, I as KaafilValidationError, L as KaafilVersionConflictError, N as ManagerRole, O as ManifestMode, P as OutboxClass, Q as PagedResponseMeta, S as PaginatorPage, T as PartyKind, U as PlanRefusalReason, W as ResponseMeta, X as Retryability, Y as TriggerAnchor, Z as TripMode, _ as TripStatus, $ as UnsatisfiableSchemeError, a0 as WaitUntilJourneyReadyOptions, a1 as isKaafilError, a2 as isRetryable } from './paginator-CE9JhsLi.js';
+
+/**
+ * `KaafilClient` — the browser entry (`kaafil-js/client`).
+ * `architecture/08-sdk.md §2, §3.2, §3.3`.
+ *
+ * Kept as a separate module graph from `./client.ts`/`./index.ts` so it
+ * structurally CANNOT reach the API-key credential path — not by
+ * convention, by the shape of the import graph:
+ *
+ * - This file never imports `./client.ts` (the only place a
+ *   `{ kind: 'apiKey', apiKey }` config is ever assembled) or `./index.ts`.
+ * - It never imports `./config.ts`'s API-key-specific exports —
+ *   `assertApiKeyMatchesEnvironment`, `guardApiKeyEnvironment`,
+ *   `ApiKeyEnvironmentMismatchError` — only `resolveBaseUrl`/
+ *   `assertValidTimeout`/`assertValidMaxAttempts`, which every client needs,
+ *   API key or not.
+ * - It builds `ManagerSessionCredentialConfig`/`ShareTokenCredentialConfig`/
+ *   `AgencyAdminCredentialConfig` objects using the literal string kinds
+ *   (`'managerSession'`/`'shareToken'`/`'agencyAdmin'`) rather than
+ *   importing the shared `CredentialKind` value export from
+ *   `./auth/credentials.ts` — that constant's own object literal carries the
+ *   `'apiKey'` kind alongside the other three (one generated-adjacent table,
+ *   not four separable ones), so importing it at all would pull that value
+ *   into this bundle for no reason this file has.
+ *
+ * A bundler following only this file's import graph has no path to the code
+ * that turns an API-key string into a working credential. (`./auth/credentials.ts`'s
+ * `SECURITY_SCHEME_CARRIERS` table — shared infrastructure `CredentialResolver`
+ * needs to resolve a `managerAuth`/`shareAuth`/`agencyAdminAuth` *bearer*
+ * header just as much as an `apiKeyAuth` one — still carries the literal
+ * header name `X-API-Key` as inert data for the scheme this file never
+ * selects; that table is generated, single, and un-split, so its presence in
+ * this bundle is not evidence of a reachable API-key path. What this file
+ * cannot do, from its own code or anything it imports, is construct or
+ * validate an API-key credential, or reach the `Kaafil` class.)
+ */
+
+interface KaafilClientOptions {
+    readonly environment: Environment;
+    /** Overrides the environment's default base URL outright — see
+     * `./config.ts`'s `resolveBaseUrl` for why the two are never merged. */
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly maxAttempts?: number;
+    readonly userAgent?: string;
+    readonly random?: () => number;
+}
+/**
+ * `session.open(...)`'s options — just the tokens a manager-token mint (or a
+ * prior refresh) already handed the host; never a URL, never a header.
+ * Rotation from here on is automatic (`./auth/credentials.ts`'s
+ * `CredentialResolver`, exchanging directly with the engine).
+ */
+interface OpenManagerSessionOptions {
+    readonly accessToken: Resolvable<string>;
+    readonly refreshToken: Resolvable<string>;
+    readonly expiresAt?: Resolvable<string>;
+    /** Persists the rotated pair after a successful refresh — the SDK keeps
+     * no state across a reload, so this is the host's one hook to survive one. */
+    readonly onRefresh?: (result: ManagerRefreshResult) => void | Promise<void>;
+    /** Overrides the direct engine exchange with an integrator-supplied one —
+     * see `./auth/credentials.ts`'s `ManagerSessionCredentialConfig.refresh`. */
+    readonly refresh?: (refreshToken: string) => Promise<ManagerRefreshResult>;
+}
+/**
+ * `admin.open(...)`'s options — the agency-admin analogue of
+ * `OpenManagerSessionOptions` above: the access/refresh pair a server-side
+ * `kaafil.auth.mintAgencyAdminToken(...)` call (or a prior refresh) already
+ * handed the host. Rotation from here on is automatic, the same way a
+ * manager session's is (`./auth/credentials.ts`'s `CredentialResolver`,
+ * exchanging directly with the engine).
+ */
+interface OpenAgencyAdminSessionOptions {
+    readonly accessToken: Resolvable<string>;
+    readonly refreshToken: Resolvable<string>;
+    readonly expiresAt?: Resolvable<string>;
+    readonly onRefresh?: (result: AgencyAdminRefreshResult) => void | Promise<void>;
+    /** Overrides the direct engine exchange with an integrator-supplied one —
+     * see `./auth/credentials.ts`'s `AgencyAdminCredentialConfig.refresh`. */
+    readonly refresh?: (refreshToken: string) => Promise<AgencyAdminRefreshResult>;
+}
+/** `share.open(...)`'s options. */
+interface OpenShareTokenOptions {
+    readonly token: Resolvable<string>;
+}
+/**
+ * Thrown by `.vendors`/`.journey` before `session.open()`/`share.open()` has
+ * run, or after `close()`. There is no resource surface without a credential
+ * to resolve headers with, so this fails at the point of use rather than
+ * letting a call fall through to an unauthenticated request.
+ */
+declare class KaafilClientNotOpenError extends Error {
+    constructor();
+}
+/**
+ * Thrown by `session.open()`/`share.open()` while a session is already open.
+ * `close()` first — silently replacing a live session out from under
+ * whatever the caller thought was still open is exactly the kind of
+ * ambiguity this SDK does not leave implicit.
+ */
+declare class KaafilClientAlreadyOpenError extends Error {
+    constructor();
+}
+/**
+ * The browser client. Constructed with only an `environment` — no
+ * credential yet, because none exists until a manager session, an
+ * agency-admin session, or a share token is minted server-side and handed
+ * to `session.open`/`admin.open`/`share.open`.
+ *
+ * Only `vendors` and `journey` are reachable from here: every other
+ * resource group built in this wave (`trips`, `auth`, `shareTokens`,
+ * `webhooks`, `events`) declares `apiKeyAuth` as its only accepted scheme in
+ * the vendored spec (`../generated/security.ts`'s `OPERATION_SECURITY`) —
+ * a scheme none of a manager session, an agency-admin session, or a share
+ * token can ever satisfy — so exposing them here would just be a way to
+ * reach `UnsatisfiableSchemeError` a resource-group at a time. `vendors`
+ * (`listTripVendors`) and `journey` (`readJourney`/`readJourneyCapabilities`/
+ * `listJourneyTriggers`/`patchJourneyTrigger`) both accept `apiKeyAuth` OR
+ * `managerAuth` OR `agencyAdminAuth` — genuinely reachable from either
+ * rotating session this file can open. Both are exposed uniformly for a
+ * `shareToken`-opened client too, rather than hand-branching per credential
+ * kind here: no operation in the current spec accepts `shareAuth` at all
+ * (verified — `grep shareAuth src/generated/security.ts` matches only the
+ * scheme's own declaration, never an operation's accepted-schemes list), so
+ * a share-opened client calling either today gets `UnsatisfiableSchemeError`
+ * from `CredentialResolver` itself; the moment a future spec revision adds a
+ * `shareAuth`-accepting operation to either group, it becomes reachable here
+ * with no change to this file, which is the entire point of leaving that
+ * decision to the resolver rather than duplicating the spec's scheme table
+ * as a second, hand-maintained gate here.
+ */
+declare class KaafilClient {
+    #private;
+    constructor(options: KaafilClientOptions);
+    readonly session: {
+        /**
+         * Opens a manager session with the access/refresh pair a server-side
+         * `kaafil.auth.mintManagerToken(...)` call already minted. Rotation
+         * after this point — pre-emptive, and on a `401` — is entirely
+         * automatic: `CredentialResolver` exchanges directly with the engine
+         * (`../auth/credentials.ts`, `../http/client.ts`'s
+         * `createManagerSessionRefreshExchange`). Nothing else is required —
+         * `refresh`/`onRefresh` above are optional hooks, not obligations.
+         */
+        open: (options: OpenManagerSessionOptions) => void;
+    };
+    readonly admin: {
+        /**
+         * Opens an agency-admin session with the access/refresh pair a
+         * server-side `kaafil.auth.mintAgencyAdminToken(...)` call already
+         * minted. Rotation after this point — pre-emptive, and on a `401` — is
+         * entirely automatic, the same way `session.open`'s is:
+         * `CredentialResolver` exchanges directly with the engine
+         * (`../auth/credentials.ts`, `../http/client.ts`'s
+         * `createAgencyAdminSessionRefreshExchange`). Nothing else is required
+         * — `refresh`/`onRefresh` above are optional hooks, not obligations.
+         */
+        open: (options: OpenAgencyAdminSessionOptions) => void;
+    };
+    readonly share: {
+        /** Opens a read-only session with a share token minted server-side by
+         * `kaafil.shareTokens.create(...)`. */
+        open: (options: OpenShareTokenOptions) => void;
+    };
+    get vendors(): VendorsResource;
+    get journey(): JourneyResource;
+    /**
+     * Total teardown. One assignment, no field to forget — see
+     * `KaafilClientState` above. Safe to call whether or not a session is
+     * open; calling any resource method afterward throws
+     * `KaafilClientNotOpenError`, and `session.open`/`share.open` can be
+     * called again immediately after.
+     */
+    close(): void;
+    /**
+     * Mints an idempotency key outside the normal per-call flow. Every
+     * mutating method already mints and reuses one automatically
+     * (`../http/client.ts`) — this exists for the rare case of pinning a key
+     * ahead of time, to replay the exact same logical operation across a
+     * process restart.
+     */
+    static newIdempotencyKey(): string;
+}
+
+export { AgencyAdminRefreshResult, Environment, JourneyResource, KaafilClient, KaafilClientAlreadyOpenError, KaafilClientNotOpenError, type KaafilClientOptions, ManagerRefreshResult, type OpenAgencyAdminSessionOptions, type OpenManagerSessionOptions, type OpenShareTokenOptions, Resolvable, VendorsResource };