@plantops/iam-client 0.1.0

package/dist/endpoints/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/endpoints/roles.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,yBAAyB,EACzB,OAAO,EACP,uBAAuB,EACvB,yBAAyB,EACzB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,+EAA+E;IAC/E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC;;;OAGG;IACH,iBAAiB,IAAI,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACxD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC1D,cAAc,CACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACrC;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,GAAG,QAAQ,CAgB3D"}

package/dist/endpoints/roles.js

@@ -0,0 +1,21 @@
+/**
+ * `/iam/roles/*` — the WHAT dimension, Doc 06 §7.
+ *
+ * A role is a bag of permissions drawn from the tenant's *enabled* applications;
+ * `setPermissions` is a PUT because the screen behind it is a checklist, and a
+ * checklist submits a set, not a diff.
+ */
+import { IAM_ROUTE_PREFIX } from '@plantops/contracts';
+export function rolesEndpoints(request) {
+    const base = `${IAM_ROUTE_PREFIX}/roles`;
+    const at = (id, suffix = '') => `${base}/${encodeURIComponent(id)}${suffix}`;
+    return {
+        create: (body) => request({ method: 'POST', path: base, body }),
+        list: (query) => request({ method: 'GET', path: base, query: { ...query } }),
+        update: (id, body) => request({ method: 'PATCH', path: at(id), body }),
+        remove: (id) => request({ method: 'DELETE', path: at(id) }),
+        permissionCatalog: () => request({ method: 'GET', path: `${base}/permission-catalog` }),
+        permissions: (id) => request({ method: 'GET', path: at(id, '/permissions') }),
+        setPermissions: (id, body) => request({ method: 'PUT', path: at(id, '/permissions'), body }),
+    };
+}

package/dist/endpoints/scopes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `/iam/scopes/*` — the WHERE dimension, Doc 06 §6.
+ *
+ * The tree comes back whole rather than paginated: it is one tenant's org
+ * structure, it is drawn as a tree, and a page of nodes is not a tree
+ * (`ScopeTreeResponse`).
+ */
+import type { CreateScopeNodeRequest, ScopeNodeDTO, ScopeTreeResponse, UpdateScopeNodeRequest } from '@plantops/contracts';
+import type { Requester } from '../http.js';
+export interface ScopesApi {
+    create(body: CreateScopeNodeRequest): Promise<ScopeNodeDTO>;
+    tree(): Promise<ScopeTreeResponse>;
+    /** Rename, or move — a move rewrites the subtree's paths and invalidates. */
+    update(id: string, body: UpdateScopeNodeRequest): Promise<ScopeNodeDTO>;
+    /** Refused while bindings still hang off the node (Doc 06 §6). */
+    remove(id: string): Promise<void>;
+}
+export declare function scopesEndpoints(request: Requester): ScopesApi;
+//# sourceMappingURL=scopes.d.ts.map

package/dist/endpoints/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/endpoints/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5D,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACnC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACxE,kEAAkE;IAClE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAU7D"}

package/dist/endpoints/scopes.js

@@ -0,0 +1,18 @@
+/**
+ * `/iam/scopes/*` — the WHERE dimension, Doc 06 §6.
+ *
+ * The tree comes back whole rather than paginated: it is one tenant's org
+ * structure, it is drawn as a tree, and a page of nodes is not a tree
+ * (`ScopeTreeResponse`).
+ */
+import { IAM_ROUTE_PREFIX } from '@plantops/contracts';
+export function scopesEndpoints(request) {
+    const base = `${IAM_ROUTE_PREFIX}/scopes`;
+    const at = (id) => `${base}/${encodeURIComponent(id)}`;
+    return {
+        create: (body) => request({ method: 'POST', path: base, body }),
+        tree: () => request({ method: 'GET', path: base }),
+        update: (id, body) => request({ method: 'PATCH', path: at(id), body }),
+        remove: (id) => request({ method: 'DELETE', path: at(id) }),
+    };
+}

package/dist/endpoints/service-accounts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `/iam/service-accounts/*` — non-human subjects, Doc 06 §10.
+ *
+ * `create` and `rotate` are the only two calls in this library that return a
+ * secret, and they return it exactly once (`ServiceAccountSecretDTO`). A caller
+ * that discards it cannot ask for it again — only rotate, which invalidates the
+ * one it lost.
+ */
+import type { CreateServiceAccountRequest, Paginated, PaginationQuery, ServiceAccountDTO, ServiceAccountSecretDTO, UpdateServiceAccountRequest } from '@plantops/contracts';
+import type { Requester } from '../http.js';
+export interface ServiceAccountsApi {
+    create(body: CreateServiceAccountRequest): Promise<ServiceAccountSecretDTO>;
+    list(query?: PaginationQuery): Promise<Paginated<ServiceAccountDTO>>;
+    rotate(id: string): Promise<ServiceAccountSecretDTO>;
+    /** Revoke or reactivate. */
+    update(id: string, body: UpdateServiceAccountRequest): Promise<ServiceAccountDTO>;
+}
+export declare function serviceAccountsEndpoints(request: Requester): ServiceAccountsApi;
+//# sourceMappingURL=service-accounts.d.ts.map

package/dist/endpoints/service-accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-accounts.d.ts","sourceRoot":"","sources":["../../src/endpoints/service-accounts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,2BAA2B,EAC3B,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC5B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,IAAI,EAAE,2BAA2B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC5E,IAAI,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACrE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACrD,4BAA4B;IAC5B,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,2BAA2B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACnF;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,SAAS,GAAG,kBAAkB,CAW/E"}

package/dist/endpoints/service-accounts.js

@@ -0,0 +1,19 @@
+/**
+ * `/iam/service-accounts/*` — non-human subjects, Doc 06 §10.
+ *
+ * `create` and `rotate` are the only two calls in this library that return a
+ * secret, and they return it exactly once (`ServiceAccountSecretDTO`). A caller
+ * that discards it cannot ask for it again — only rotate, which invalidates the
+ * one it lost.
+ */
+import { IAM_ROUTE_PREFIX } from '@plantops/contracts';
+export function serviceAccountsEndpoints(request) {
+    const base = `${IAM_ROUTE_PREFIX}/service-accounts`;
+    const at = (id, suffix = '') => `${base}/${encodeURIComponent(id)}${suffix}`;
+    return {
+        create: (body) => request({ method: 'POST', path: base, body }),
+        list: (query) => request({ method: 'GET', path: base, query: { ...query } }),
+        rotate: (id) => request({ method: 'POST', path: at(id, '/rotate') }),
+        update: (id, body) => request({ method: 'PATCH', path: at(id), body }),
+    };
+}

package/dist/endpoints/users.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `/iam/users/*` — the WHO dimension, Doc 06 §8.
+ *
+ * Note what `bulk` returns: a `200` with a per-row report, not a `201` and not a
+ * `207`. Valid rows commit even when others do not, so the response is the only
+ * place a caller learns which addresses landed — see `BulkUserUploadResponse`.
+ */
+import type { BulkUserUploadRequest, BulkUserUploadResponse, CreateUserRequest, Paginated, PaginationQuery, UpdateUserRequest, UserByRoleDTO, UserDetailDTO, UserDTO, UserStatus } from '@plantops/contracts';
+import type { Requester } from '../http.js';
+/**
+ * `GET /iam/users`'s filters (Doc 06 §8, Doc 09 §3.3).
+ *
+ * Declared here rather than imported: `@plantops/contracts` types the bodies
+ * and the responses of this surface, not every query string, and the roadmap
+ * freezes `contracts` for this session. `q` is the free-text search over name
+ * and email; `status` is the "locked users" filter the console opens with.
+ */
+export interface UsersQuery extends PaginationQuery {
+    status?: UserStatus;
+    q?: string;
+}
+export interface UsersApi {
+    create(body: CreateUserRequest): Promise<UserDTO>;
+    list(query?: UsersQuery): Promise<Paginated<UserDTO>>;
+    /** Profile plus the bindings behind it. */
+    detail(id: string): Promise<UserDetailDTO>;
+    /** Update, lock, unlock or disable (Doc 03 §8). */
+    update(id: string, body: UpdateUserRequest): Promise<UserDetailDTO>;
+    /** The roster upload and its per-row report. At most 500 rows. */
+    bulk(body: BulkUserUploadRequest): Promise<BulkUserUploadResponse>;
+    /**
+     * "Users by Role" — a holder appears once, with every scope they hold the
+     * role at gathered into `scopes`, expired bindings flagged rather than
+     * dropped.
+     */
+    byRole(roleId: string, query?: PaginationQuery): Promise<Paginated<UserByRoleDTO>>;
+}
+export declare function usersEndpoints(request: Requester): UsersApi;
+//# sourceMappingURL=users.d.ts.map

package/dist/endpoints/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/endpoints/users.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,OAAO,EACP,UAAU,EACX,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,2CAA2C;IAC3C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,mDAAmD;IACnD,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACpE,kEAAkE;IAClE,IAAI,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnE;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;CACpF;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,GAAG,QAAQ,CAiB3D"}

package/dist/endpoints/users.js

@@ -0,0 +1,24 @@
+/**
+ * `/iam/users/*` — the WHO dimension, Doc 06 §8.
+ *
+ * Note what `bulk` returns: a `200` with a per-row report, not a `201` and not a
+ * `207`. Valid rows commit even when others do not, so the response is the only
+ * place a caller learns which addresses landed — see `BulkUserUploadResponse`.
+ */
+import { IAM_ROUTE_PREFIX } from '@plantops/contracts';
+export function usersEndpoints(request) {
+    const base = `${IAM_ROUTE_PREFIX}/users`;
+    const at = (id) => `${base}/${encodeURIComponent(id)}`;
+    return {
+        create: (body) => request({ method: 'POST', path: base, body }),
+        list: (query) => request({ method: 'GET', path: base, query: { ...query } }),
+        detail: (id) => request({ method: 'GET', path: at(id) }),
+        update: (id, body) => request({ method: 'PATCH', path: at(id), body }),
+        bulk: (body) => request({ method: 'POST', path: `${base}/bulk`, body }),
+        byRole: (roleId, query) => request({
+            method: 'GET',
+            path: `${base}/by-role/${encodeURIComponent(roleId)}`,
+            query: { ...query },
+        }),
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What a call through this client throws (Doc 06 §2).
+ *
+ * Two classes, because a caller has two genuinely different decisions to make.
+ * {@link IamApiError} means the IAM answered and refused: there is a status, a
+ * closed-table `code` to branch on, and a `requestId` that correlates the
+ * refusal with the server's logs and its audit trail. {@link IamTransportError}
+ * means no answer came back at all — DNS, TLS, a cut connection, a timeout, or
+ * a body that was not the JSON it claimed to be. The first is a decision the
+ * server made about the request; the second is not, and retrying it is
+ * sometimes right where retrying the first never is.
+ *
+ * Both extend {@link IamClientError} so that `catch (e) { if (e instanceof
+ * IamClientError) … }` covers everything this library throws, and nothing else.
+ */
+import { IamErrorCode, type IamErrorDetail } from '@plantops/contracts';
+/** Base of every error this library throws. */
+export declare class IamClientError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A response the IAM refused, in the terms Doc 06 §2 defines. */
+export declare class IamApiError extends IamClientError {
+    readonly status: number;
+    readonly code: IamErrorCode;
+    /**
+     * The correlation handle from the envelope, or the `X-Request-Id` header when
+     * the body was not an envelope. `null` when neither was present — which is
+     * itself a sign that the answer did not come from the IAM.
+     */
+    readonly requestId: string | null;
+    /** Field-level complaints; only `VALIDATION_FAILED` carries them. */
+    readonly details: readonly IamErrorDetail[];
+    /** True when {@link code} was inferred from the status, not read from a body. */
+    readonly inferred: boolean;
+    constructor(init: {
+        status: number;
+        code: IamErrorCode;
+        message: string;
+        requestId?: string | null;
+        details?: readonly IamErrorDetail[];
+        inferred?: boolean;
+    });
+    /**
+     * Builds the error from what a failed response actually carried.
+     *
+     * `body` is the already-parsed JSON, or `undefined` when the body was not
+     * JSON at all — an HTML error page from something in front of the API being
+     * the ordinary case.
+     */
+    static from(status: number, body: unknown, fallback?: {
+        requestId?: string | null;
+        text?: string;
+    }): IamApiError;
+    /** `if (error.is(IamErrorCode.NOT_FOUND))` — the common branch, spelled once. */
+    is(code: IamErrorCode): boolean;
+}
+/**
+ * The request never produced an answer to refuse it: a network fault, an abort,
+ * a timeout, or a success body that would not parse as JSON.
+ */
+export declare class IamTransportError extends IamClientError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function isIamApiError(value: unknown): value is IamApiError;
+export declare function isIamClientError(value: unknown): value is IamClientError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,YAAY,EAEZ,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAE7B,+CAA+C;AAC/C,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAyBD,kEAAkE;AAClE,qBAAa,WAAY,SAAQ,cAAc;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;gBAEf,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,YAAY,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;QACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB;IAUD;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CACT,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,QAAQ,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAC1D,WAAW;IAoBd,iFAAiF;IACjF,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO;CAGhC;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE"}

package/dist/errors.js

@@ -0,0 +1,113 @@
+/**
+ * What a call through this client throws (Doc 06 §2).
+ *
+ * Two classes, because a caller has two genuinely different decisions to make.
+ * {@link IamApiError} means the IAM answered and refused: there is a status, a
+ * closed-table `code` to branch on, and a `requestId` that correlates the
+ * refusal with the server's logs and its audit trail. {@link IamTransportError}
+ * means no answer came back at all — DNS, TLS, a cut connection, a timeout, or
+ * a body that was not the JSON it claimed to be. The first is a decision the
+ * server made about the request; the second is not, and retrying it is
+ * sometimes right where retrying the first never is.
+ *
+ * Both extend {@link IamClientError} so that `catch (e) { if (e instanceof
+ * IamClientError) … }` covers everything this library throws, and nothing else.
+ */
+import { IamErrorCode, isIamErrorResponse, } from '@plantops/contracts';
+/** Base of every error this library throws. */
+export class IamClientError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'IamClientError';
+    }
+}
+/**
+ * Status → code for a response that was *not* the Doc 06 §2 envelope.
+ *
+ * The IAM always sends the envelope — `INTERNAL_ERROR` was added to the table
+ * in Session 6 precisely so that an unhandled exception still parses. But a
+ * client does not only talk to the IAM: a reverse proxy's own 502, a load
+ * balancer's 504 or a captive portal's HTML all arrive on the same socket, and
+ * a consumer branching on `error.code` should not have to special-case the
+ * shape it gets when something in between answered first. So a non-envelope
+ * failure is still an {@link IamApiError}, with the nearest code the status
+ * justifies and {@link IamApiError.inferred} set to say the code was not the
+ * server's own word.
+ */
+const CODE_FOR_STATUS = Object.freeze({
+    400: IamErrorCode.VALIDATION_FAILED,
+    401: IamErrorCode.AUTH_REQUIRED,
+    403: IamErrorCode.PERMISSION_DENIED,
+    404: IamErrorCode.NOT_FOUND,
+    409: IamErrorCode.CONFLICT,
+    423: IamErrorCode.ACCOUNT_LOCKED,
+    429: IamErrorCode.RATE_LIMITED,
+});
+/** A response the IAM refused, in the terms Doc 06 §2 defines. */
+export class IamApiError extends IamClientError {
+    status;
+    code;
+    /**
+     * The correlation handle from the envelope, or the `X-Request-Id` header when
+     * the body was not an envelope. `null` when neither was present — which is
+     * itself a sign that the answer did not come from the IAM.
+     */
+    requestId;
+    /** Field-level complaints; only `VALIDATION_FAILED` carries them. */
+    details;
+    /** True when {@link code} was inferred from the status, not read from a body. */
+    inferred;
+    constructor(init) {
+        super(init.message);
+        this.name = 'IamApiError';
+        this.status = init.status;
+        this.code = init.code;
+        this.requestId = init.requestId ?? null;
+        this.details = init.details ?? [];
+        this.inferred = init.inferred ?? false;
+    }
+    /**
+     * Builds the error from what a failed response actually carried.
+     *
+     * `body` is the already-parsed JSON, or `undefined` when the body was not
+     * JSON at all — an HTML error page from something in front of the API being
+     * the ordinary case.
+     */
+    static from(status, body, fallback = {}) {
+        if (isIamErrorResponse(body)) {
+            const { code, message, requestId, details } = body.error;
+            return new IamApiError({ status, code, message, requestId, details });
+        }
+        const code = CODE_FOR_STATUS[status] ?? IamErrorCode.INTERNAL_ERROR;
+        const excerpt = (fallback.text ?? '').trim().slice(0, 200);
+        return new IamApiError({
+            status,
+            code,
+            message: excerpt === ''
+                ? `HTTP ${status} from the IAM, with no error envelope.`
+                : `HTTP ${status} from the IAM, with no error envelope: ${excerpt}`,
+            requestId: fallback.requestId ?? null,
+            inferred: true,
+        });
+    }
+    /** `if (error.is(IamErrorCode.NOT_FOUND))` — the common branch, spelled once. */
+    is(code) {
+        return this.code === code;
+    }
+}
+/**
+ * The request never produced an answer to refuse it: a network fault, an abort,
+ * a timeout, or a success body that would not parse as JSON.
+ */
+export class IamTransportError extends IamClientError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'IamTransportError';
+    }
+}
+export function isIamApiError(value) {
+    return value instanceof IamApiError;
+}
+export function isIamClientError(value) {
+    return value instanceof IamClientError;
+}

package/dist/http.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The one place this library touches the network.
+ *
+ * Everything above it — the `endpoints/` modules, the token lifecycle in
+ * `auth.ts`, the cache in `resolve-cache.ts` — is transport-free and therefore
+ * testable without a socket. What lives here is the small, unavoidable set of
+ * decisions about HTTP itself: how a query string is built, when a body is
+ * JSON, what an empty `204` deserialises to, how a failure becomes an
+ * {@link IamApiError}, and the single re-authentication retry that hides an
+ * expired access token from every caller.
+ *
+ * ## Why the fetch types are declared here rather than imported
+ *
+ * The library must run in Node and in a browser (Doc 08 §2 — `admin-web` and
+ * every future module), and those two disagree about where the types for
+ * `fetch` come from: `lib.dom` in one, the undici typings of `@types/node` in
+ * the other. Naming either would make this package unbuildable in the other
+ * context. The structural minimum both satisfy is four properties and one
+ * method, so that is what {@link FetchLike} asks for — and it is also exactly
+ * what a test double has to implement, which is why the mocked-server suite
+ * needs no HTTP library at all.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+/** A query-string value; `undefined` means "omit this parameter". */
+export type QueryValue = string | number | boolean | undefined;
+export type QueryParams = Readonly<Record<string, QueryValue>>;
+/** The structural subset of `RequestInit` this client ever sends. */
+export interface HttpRequestInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+/** The structural subset of `Response` this client ever reads. */
+export interface HttpResponseLike {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string, init: HttpRequestInit) => Promise<HttpResponseLike>;
+/** One call, described in the terms the endpoint modules think in. */
+export interface RequestSpec {
+    method: HttpMethod;
+    /** Absolute path from the API root, e.g. `/iam/users`. */
+    path: string;
+    query?: QueryParams;
+    /** Serialised as JSON when present. `undefined` sends no body at all. */
+    body?: unknown;
+    /**
+     * `'none'` for the routes that cannot carry a token — login, refresh, the
+     * service-account exchange, the JWKS document. Everything else defaults to
+     * `'bearer'` and takes part in the refresh-on-401 retry.
+     */
+    auth?: 'bearer' | 'none';
+    /**
+     * What the successful body is.
+     *
+     * `'json'` everywhere but one route: `GET /iam/audit/export` answers
+     * `text/csv` (Doc 06 §12), and a client that insisted on JSON would have to
+     * either special-case it outside the transport — losing the token handling and
+     * the error mapping — or hand callers a `Response` this library never exposes.
+     * Failures are unaffected: the Doc 06 §2 envelope is JSON on every route,
+     * including that one.
+     */
+    accept?: 'json' | 'text';
+    signal?: AbortSignal;
+}
+/** What every endpoint module is handed, and the only thing it may use. */
+export type Requester = <T>(spec: RequestSpec) => Promise<T>;
+export interface HttpTransportOptions {
+    /** API root — the origin, not the `/iam` prefix. */
+    baseUrl: string;
+    fetch?: FetchLike;
+    /** Sent on every request. */
+    headers?: Readonly<Record<string, string>>;
+    /** Abort a request that has taken this long. Omit for no client-side limit. */
+    timeoutMs?: number;
+    /** The current access token, or `null` when there is none. */
+    authorize?: () => Promise<string | null>;
+    /**
+     * Called once per request that came back `401`, with the token that failed.
+     * Resolving `true` means a usable token now exists and the request should be
+     * retried exactly once; `false` means the `401` stands.
+     */
+    reauthorize?: (usedToken: string | null) => Promise<boolean>;
+}
+/** Trailing slashes on the base would double up against a leading-slash path. */
+export declare const stripTrailingSlash: (url: string) => string;
+export declare function buildQuery(query: QueryParams | undefined): string;
+export declare class HttpTransport {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly authorize;
+    private readonly reauthorize;
+    constructor(options: HttpTransportOptions);
+    /** The {@link Requester} handed to every endpoint module. */
+    readonly request: Requester;
+    private attempt;
+    /**
+     * A timeout and a caller's own `AbortSignal`, combined without
+     * `AbortSignal.any` — which is newer than some runtimes this library has to
+     * work in, and which would be the only reason to require one.
+     */
+    private deadline;
+    /** Body to value, or to the error of Doc 06 §2. */
+    private interpret;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

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

package/dist/http.js

@@ -0,0 +1,164 @@
+/**
+ * The one place this library touches the network.
+ *
+ * Everything above it — the `endpoints/` modules, the token lifecycle in
+ * `auth.ts`, the cache in `resolve-cache.ts` — is transport-free and therefore
+ * testable without a socket. What lives here is the small, unavoidable set of
+ * decisions about HTTP itself: how a query string is built, when a body is
+ * JSON, what an empty `204` deserialises to, how a failure becomes an
+ * {@link IamApiError}, and the single re-authentication retry that hides an
+ * expired access token from every caller.
+ *
+ * ## Why the fetch types are declared here rather than imported
+ *
+ * The library must run in Node and in a browser (Doc 08 §2 — `admin-web` and
+ * every future module), and those two disagree about where the types for
+ * `fetch` come from: `lib.dom` in one, the undici typings of `@types/node` in
+ * the other. Naming either would make this package unbuildable in the other
+ * context. The structural minimum both satisfy is four properties and one
+ * method, so that is what {@link FetchLike} asks for — and it is also exactly
+ * what a test double has to implement, which is why the mocked-server suite
+ * needs no HTTP library at all.
+ */
+import { IamApiError, IamTransportError } from './errors.js';
+/** Trailing slashes on the base would double up against a leading-slash path. */
+export const stripTrailingSlash = (url) => url.replace(/\/+$/, '');
+export function buildQuery(query) {
+    if (query === undefined)
+        return '';
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined)
+            search.append(key, String(value));
+    }
+    const encoded = search.toString();
+    return encoded === '' ? '' : `?${encoded}`;
+}
+export class HttpTransport {
+    baseUrl;
+    fetchImpl;
+    headers;
+    timeoutMs;
+    authorize;
+    reauthorize;
+    constructor(options) {
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new TypeError('No fetch implementation. This runtime has no global fetch — pass one ' +
+                'as `fetch` in the client options.');
+        }
+        this.baseUrl = stripTrailingSlash(options.baseUrl);
+        // Wrapped rather than stored bare: an unbound global `fetch` throws
+        // "Illegal invocation" in a browser once it is detached from `window`.
+        this.fetchImpl = (url, init) => fetchImpl(url, init);
+        this.headers = options.headers ?? {};
+        this.timeoutMs = options.timeoutMs;
+        this.authorize = options.authorize;
+        this.reauthorize = options.reauthorize;
+    }
+    /** The {@link Requester} handed to every endpoint module. */
+    request = async (spec) => {
+        const bearer = spec.auth !== 'none';
+        const token = bearer && this.authorize ? await this.authorize() : null;
+        const first = await this.attempt(spec, token);
+        if (first.status !== 401 ||
+            !bearer ||
+            this.reauthorize === undefined ||
+            !(await this.reauthorize(token))) {
+            return this.interpret(first, spec.accept);
+        }
+        // The refused response is being thrown away, so drain it: an unread body
+        // holds its connection open until the socket is collected.
+        await first.text().catch(() => undefined);
+        // Exactly one retry. A second 401 after a successful refresh is the server
+        // saying this subject may not do this at all, and looping on it would turn
+        // a revoked session into an unbounded refresh storm.
+        const retryToken = this.authorize ? await this.authorize() : null;
+        return this.interpret(await this.attempt(spec, retryToken), spec.accept);
+    };
+    async attempt(spec, token) {
+        const headers = {
+            accept: 'application/json',
+            ...this.headers,
+        };
+        if (spec.body !== undefined)
+            headers['content-type'] = 'application/json';
+        if (token !== null)
+            headers['authorization'] = `Bearer ${token}`;
+        const url = `${this.baseUrl}${spec.path}${buildQuery(spec.query)}`;
+        const { signal, done } = this.deadline(spec.signal);
+        try {
+            return await this.fetchImpl(url, {
+                method: spec.method,
+                headers,
+                ...(spec.body === undefined ? {} : { body: JSON.stringify(spec.body) }),
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (cause) {
+            throw new IamTransportError(`${spec.method} ${spec.path} did not complete: ${describe(cause)}`, { cause });
+        }
+        finally {
+            done();
+        }
+    }
+    /**
+     * A timeout and a caller's own `AbortSignal`, combined without
+     * `AbortSignal.any` — which is newer than some runtimes this library has to
+     * work in, and which would be the only reason to require one.
+     */
+    deadline(caller) {
+        if (this.timeoutMs === undefined) {
+            return { signal: caller, done: () => undefined };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const forward = () => controller.abort();
+        caller?.addEventListener('abort', forward);
+        if (caller?.aborted === true)
+            forward();
+        return {
+            signal: controller.signal,
+            done: () => {
+                clearTimeout(timer);
+                caller?.removeEventListener('abort', forward);
+            },
+        };
+    }
+    /** Body to value, or to the error of Doc 06 §2. */
+    async interpret(response, accept = 'json') {
+        const text = await response.text();
+        const parsed = parseJson(text);
+        if (!response.ok) {
+            throw IamApiError.from(response.status, parsed, {
+                requestId: response.headers.get('x-request-id'),
+                text,
+            });
+        }
+        // A caller that asked for text gets the body as it arrived — including an
+        // empty one, which for a CSV export is a header row that matched nothing
+        // rather than a missing answer.
+        if (accept === 'text')
+            return text;
+        // The routes that answer 204 with nothing at all (Doc 06 §3, §6, §7, §9).
+        if (text.trim() === '')
+            return undefined;
+        if (parsed === undefined) {
+            throw new IamTransportError(`HTTP ${response.status} carried a body that is not JSON.`);
+        }
+        return parsed;
+    }
+}
+function parseJson(text) {
+    if (text.trim() === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}