@dreadkn1ght123/provisioning-client 1.0.0

package/README.md

@@ -0,0 +1,8 @@
+# `@dreadkn1ght123/provisioning-client`
+
+Backend-only typed `/v1` client. Supply a short-lived machine token through
+`getAccessToken`; never import this package from browser code. Every call needs a
+correlation ID and every mutation also needs a meaningful reason and an opaque
+idempotency key. Preserve the same key and body when a result is
+`operation_in_progress` or `ambiguous`. `reconciliation_required` must be handed
+to an IAM operator; do not call Keycloak or create a duplicate identity.

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC"}

package/dist/browser.js

@@ -0,0 +1,3 @@
+throw new Error("@dreadkn1ght123/provisioning-client is backend-only and cannot run in a browser");
+export {};
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAC;AACnG,OAAO,EAAE,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import type { BackendTokenProvider } from "./token.js";
+import type { Actor, InviteActor, LifecycleReason, MutationRequestOptions, MutationResponse, UpdateActorAccess } from "./types.js";
+export interface ProvisioningClientOptions {
+    baseUrl: string;
+    tokenProvider: BackendTokenProvider;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+export declare class ProvisioningClient {
+    private readonly options;
+    private readonly fetch;
+    private readonly timeoutMs;
+    private readonly baseUrl;
+    constructor(options: ProvisioningClientOptions);
+    invite(input: InviteActor, options: MutationRequestOptions): Promise<MutationResponse<Actor>>;
+    updateAccess(vvpActorId: string, input: UpdateActorAccess, options: MutationRequestOptions): Promise<MutationResponse<Actor>>;
+    disable(vvpActorId: string, input: LifecycleReason, options: MutationRequestOptions): Promise<MutationResponse<Actor>>;
+    restore(vvpActorId: string, input: LifecycleReason, options: MutationRequestOptions): Promise<MutationResponse<Actor>>;
+    getActor(vvpActorId: string, correlationId?: `${string}-${string}-${string}-${string}-${string}`): Promise<Actor>;
+    private mutate;
+    private request;
+    private actorId;
+    private jsonOrUndefined;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnI,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,oBAAoB,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAgBD,qBAAa,kBAAkB;IAKjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEJ,OAAO,EAAE,yBAAyB;IAM/D,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB;IAG1D,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,sBAAsB;IAG1F,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,sBAAsB;IAGnF,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,sBAAsB;IAI7E,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,sDAAe,GAAG,OAAO,CAAC,KAAK,CAAC;YAQlE,MAAM;YAgDN,OAAO;IAcrB,OAAO,CAAC,OAAO;YAKD,eAAe;CAI9B"}

package/dist/client.js

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+import { AmbiguousProvisioningResultError, errorFromResponse, ReconciliationRequiredError } from "./errors.js";
+const safeId = /^[A-Za-z0-9._:-]{1,128}$/;
+const keyPattern = /^[A-Za-z0-9._:-]{16,128}$/;
+function validateBackendUrl(value, label) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${label} must be a valid absolute URL`);
+    }
+    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new Error(`${label} must use HTTPS (HTTP is permitted only for exact loopback hosts)`);
+    }
+    if (url.username || url.password)
+        throw new Error(`${label} must not include URL credentials`);
+    return url;
+}
+export class ProvisioningClient {
+    options;
+    fetch;
+    timeoutMs;
+    baseUrl;
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = validateBackendUrl(options.baseUrl, "Provisioning API URL").toString().replace(/\/+$/, "");
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.timeoutMs = Math.min(Math.max(options.timeoutMs ?? 10_000, 100), 30_000);
+    }
+    invite(input, options) {
+        return this.mutate("POST", "/v1/actors", input, options);
+    }
+    updateAccess(vvpActorId, input, options) {
+        return this.mutate("PUT", `/v1/actors/${this.actorId(vvpActorId)}/access`, input, options);
+    }
+    disable(vvpActorId, input, options) {
+        return this.mutate("POST", `/v1/actors/${this.actorId(vvpActorId)}/disable`, input, options);
+    }
+    restore(vvpActorId, input, options) {
+        return this.mutate("POST", `/v1/actors/${this.actorId(vvpActorId)}/restore`, input, options);
+    }
+    async getActor(vvpActorId, correlationId = randomUUID()) {
+        if (!safeId.test(correlationId))
+            throw new Error("Invalid correlation ID");
+        const token = await this.options.tokenProvider.getAccessToken();
+        const response = await this.request("GET", `/v1/actors/${this.actorId(vvpActorId)}`, correlationId, token);
+        if (!response.ok)
+            throw errorFromResponse(response.status, await this.jsonOrUndefined(response), correlationId);
+        return await response.json();
+    }
+    async mutate(method, path, body, options) {
+        if (typeof body.reason !== "string" || body.reason.trim().length < 3 || body.reason.trim().length > 500) {
+            throw new Error("A 3-500 character operator-meaningful reason is required");
+        }
+        const { idempotencyKey, correlationId } = options;
+        if (!keyPattern.test(idempotencyKey))
+            throw new Error("Invalid idempotency key");
+        if (!safeId.test(correlationId))
+            throw new Error("Invalid correlation ID");
+        // Acquiring a token precedes any request to the Provisioning API, so an
+        // acquisition failure is conclusively pre-effect and must not be treated
+        // as an ambiguous lifecycle mutation.
+        const token = await this.options.tokenProvider.getAccessToken();
+        let response;
+        try {
+            response = await this.request(method, path, correlationId, token, idempotencyKey, body);
+        }
+        catch (cause) {
+            throw new AmbiguousProvisioningResultError("Provisioning request did not produce an unambiguous response; retry only the exact request with the same idempotency key", idempotencyKey, correlationId, { cause });
+        }
+        if (!response.ok) {
+            const error = errorFromResponse(response.status, await this.jsonOrUndefined(response), response.headers.get("x-correlation-id") ?? correlationId);
+            if (response.status >= 500 && !(error instanceof ReconciliationRequiredError)) {
+                throw new AmbiguousProvisioningResultError("Provisioning API returned an ambiguous server failure; retry only the exact request with the same idempotency key", idempotencyKey, correlationId, { cause: error });
+            }
+            throw error;
+        }
+        let value;
+        try {
+            value = await response.json();
+            if (typeof value !== "object" || value === null || Array.isArray(value))
+                throw new Error("successful response body is not an object");
+        }
+        catch (cause) {
+            throw new AmbiguousProvisioningResultError("Provisioning API acknowledged a mutation but returned an unreadable response; retry only the exact request with the same idempotency key", idempotencyKey, correlationId, { cause });
+        }
+        return {
+            data: value,
+            replayed: response.headers.get("idempotency-replayed")?.toLowerCase() === "true",
+            correlationId: response.headers.get("x-correlation-id") ?? correlationId,
+            idempotencyKey,
+        };
+    }
+    async request(method, path, correlationId, token, idempotencyKey, body) {
+        return this.fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                "x-correlation-id": correlationId,
+                ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
+                ...(body ? { "content-type": "application/json" } : {}),
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+    }
+    actorId(value) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value))
+            throw new Error("Invalid VVP actor ID");
+        return encodeURIComponent(value);
+    }
+    async jsonOrUndefined(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+export interface ProvisioningErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        details?: Readonly<Record<string, string>>;
+    };
+    correlationId: string;
+}
+export declare class ProvisioningApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly correlationId?: string | undefined;
+    readonly details?: Readonly<Record<string, string>> | undefined;
+    constructor(code: string, status: number, message: string, correlationId?: string | undefined, details?: Readonly<Record<string, string>> | undefined);
+}
+export declare class IdempotencyConflictError extends ProvisioningApiError {
+    readonly name = "IdempotencyConflictError";
+}
+export declare class OperationInProgressError extends ProvisioningApiError {
+    readonly name = "OperationInProgressError";
+}
+export declare class ReconciliationRequiredError extends ProvisioningApiError {
+    readonly name = "ReconciliationRequiredError";
+}
+/** A transport failure has an unknown server outcome. Retry only with the same key and body. */
+export declare class AmbiguousProvisioningResultError extends Error {
+    readonly idempotencyKey: string;
+    readonly correlationId: string;
+    readonly name = "AmbiguousProvisioningResultError";
+    constructor(message: string, idempotencyKey: string, correlationId: string, options?: ErrorOptions);
+}
+export declare function errorFromResponse(status: number, body: unknown, fallbackCorrelationId?: string): ProvisioningApiError;
+//# 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,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;KAAE,CAAC;IACrF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAEvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAJ1C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACN,aAAa,CAAC,EAAE,MAAM,YAAA,EACtB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,YAAA;CAKtD;AAED,qBAAa,wBAAyB,SAAQ,oBAAoB;IAChE,SAAkB,IAAI,8BAA8B;CACrD;AACD,qBAAa,wBAAyB,SAAQ,oBAAoB;IAChE,SAAkB,IAAI,8BAA8B;CACrD;AACD,qBAAa,2BAA4B,SAAQ,oBAAoB;IACnE,SAAkB,IAAI,iCAAiC;CACxD;AAED,gGAAgG;AAChG,qBAAa,gCAAiC,SAAQ,KAAK;IAIvD,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM;IAJhC,SAAkB,IAAI,sCAAsC;gBAE1D,OAAO,EAAE,MAAM,EACN,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EAC9B,OAAO,CAAC,EAAE,YAAY;CAIzB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,qBAAqB,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAYrH"}

package/dist/errors.js

@@ -0,0 +1,51 @@
+export class ProvisioningApiError extends Error {
+    code;
+    status;
+    correlationId;
+    details;
+    constructor(code, status, message, correlationId, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.correlationId = correlationId;
+        this.details = details;
+        this.name = "ProvisioningApiError";
+    }
+}
+export class IdempotencyConflictError extends ProvisioningApiError {
+    name = "IdempotencyConflictError";
+}
+export class OperationInProgressError extends ProvisioningApiError {
+    name = "OperationInProgressError";
+}
+export class ReconciliationRequiredError extends ProvisioningApiError {
+    name = "ReconciliationRequiredError";
+}
+/** A transport failure has an unknown server outcome. Retry only with the same key and body. */
+export class AmbiguousProvisioningResultError extends Error {
+    idempotencyKey;
+    correlationId;
+    name = "AmbiguousProvisioningResultError";
+    constructor(message, idempotencyKey, correlationId, options) {
+        super(message, options);
+        this.idempotencyKey = idempotencyKey;
+        this.correlationId = correlationId;
+    }
+}
+export function errorFromResponse(status, body, fallbackCorrelationId) {
+    const value = body;
+    const error = value?.error;
+    const code = typeof error?.code === "string" ? error.code : "HTTP_ERROR";
+    const message = typeof error?.message === "string" ? error.message : `Provisioning API returned HTTP ${status}`;
+    const correlationId = typeof value?.correlationId === "string" ? value.correlationId : fallbackCorrelationId;
+    const details = error?.details && typeof error.details === "object" ? error.details : undefined;
+    const args = [code, status, message, correlationId, details];
+    if (code === "IDEMPOTENCY_CONFLICT")
+        return new IdempotencyConflictError(...args);
+    if (code === "OPERATION_IN_PROGRESS")
+        return new OperationInProgressError(...args);
+    if (code === "RECONCILIATION_REQUIRED")
+        return new ReconciliationRequiredError(...args);
+    return new ProvisioningApiError(...args);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAElC;IACA;IAEA;IACA;IALX,YACW,IAAY,EACZ,MAAc,EACvB,OAAe,EACN,aAAsB,EACtB,OAA0C;QAEnD,KAAK,CAAC,OAAO,CAAC,CAAC;QANN,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;QAEd,kBAAa,GAAb,aAAa,CAAS;QACtB,YAAO,GAAP,OAAO,CAAmC;QAGnD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,oBAAoB;IAC9C,IAAI,GAAG,0BAA0B,CAAC;CACrD;AACD,MAAM,OAAO,wBAAyB,SAAQ,oBAAoB;IAC9C,IAAI,GAAG,0BAA0B,CAAC;CACrD;AACD,MAAM,OAAO,2BAA4B,SAAQ,oBAAoB;IACjD,IAAI,GAAG,6BAA6B,CAAC;CACxD;AAED,gGAAgG;AAChG,MAAM,OAAO,gCAAiC,SAAQ,KAAK;IAI9C;IACA;IAJO,IAAI,GAAG,kCAAkC,CAAC;IAC5D,YACE,OAAe,EACN,cAAsB,EACtB,aAAqB,EAC9B,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAJf,mBAAc,GAAd,cAAc,CAAQ;QACtB,kBAAa,GAAb,aAAa,CAAQ;IAIhC,CAAC;CACF;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,IAAa,EAAE,qBAA8B;IAC7F,MAAM,KAAK,GAAG,IAAiD,CAAC;IAChE,MAAM,KAAK,GAAG,KAAK,EAAE,KAAK,CAAC;IAC3B,MAAM,IAAI,GAAG,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC;IACzE,MAAM,OAAO,GAAG,OAAO,KAAK,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,kCAAkC,MAAM,EAAE,CAAC;IAChH,MAAM,aAAa,GAAG,OAAO,KAAK,EAAE,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,qBAAqB,CAAC;IAC7G,MAAM,OAAO,GAAG,KAAK,EAAE,OAAO,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAChG,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,CAAU,CAAC;IACtE,IAAI,IAAI,KAAK,sBAAsB;QAAE,OAAO,IAAI,wBAAwB,CAAC,GAAG,IAAI,CAAC,CAAC;IAClF,IAAI,IAAI,KAAK,uBAAuB;QAAE,OAAO,IAAI,wBAAwB,CAAC,GAAG,IAAI,CAAC,CAAC;IACnF,IAAI,IAAI,KAAK,yBAAyB;QAAE,OAAO,IAAI,2BAA2B,CAAC,GAAG,IAAI,CAAC,CAAC;IACxF,OAAO,IAAI,oBAAoB,CAAC,GAAG,IAAI,CAAC,CAAC;AAC3C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./token.js";
+export * from "./types.js";
+/**
+ * Backend-only VVP Provisioning API client. This package deliberately has no
+ * Keycloak administration surface and must never be bundled for a browser.
+ */
+export declare const PROVISIONING_CLIENT_VERSION = "1.0.0";
+export interface InviteActor {
+    email: string;
+    externalId?: string;
+    actorType: string;
+    displayName?: string;
+    groups: readonly string[];
+    clientRoles: Readonly<Record<string, readonly string[]>>;
+    reason: string;
+}
+export interface ProvisioningClientOptions {
+    baseUrl: string;
+    /** Supplies a short-lived machine token. It is never retained or included in errors. */
+    getAccessToken: () => Promise<string>;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+export type ActorState = "INVITED" | "ACTIVE" | "DISABLED" | "RECONCILIATION_REQUIRED";
+export interface Actor {
+    vvpActorId: string;
+    keycloakSub?: string;
+    externalId?: string;
+    email: string;
+    actorType: string;
+    displayName?: string;
+    state: ActorState;
+    groups: readonly string[];
+    clientRoles: Readonly<Record<string, readonly string[]>>;
+    createdAt: string;
+    updatedAt: string;
+    disabledAt?: string;
+    reconciliation?: {
+        errorCode: string;
+    };
+}
+export interface ReadContext {
+    correlationId: string;
+}
+export declare function createProvisioningClient(options: ProvisioningClientOptions): {
+    invite: (body: InviteActor, ctx: MutationContext) => Promise<ProvisioningResult<Actor>>;
+    list: (query: ListActors, ctx: ReadContext) => Promise<ProvisioningResult<ActorPage>>;
+    get: (id: string, ctx: ReadContext) => Promise<ProvisioningResult<Actor>>;
+    updateAccess: (id: string, body: UpdateAccess, ctx: MutationContext) => Promise<ProvisioningResult<Actor>>;
+    access: (id: string, body: UpdateAccess, ctx: MutationContext) => Promise<ProvisioningResult<Actor>>;
+    disable: (id: string, reason: string, ctx: MutationContext) => Promise<ProvisioningResult<Actor>>;
+    restore: (id: string, reason: string, ctx: MutationContext) => Promise<ProvisioningResult<Actor>>;
+    resendInvitation: (id: string, reason: string, ctx: MutationContext) => Promise<ProvisioningResult<Actor>>;
+    resend: (id: string, reason: string, ctx: MutationContext) => Promise<ProvisioningResult<Actor>>;
+};
+export declare class ProvisioningClientError extends Error {
+    readonly code: ProvisioningErrorCode | "INVALID_CLIENT_CONFIGURATION" | "UNEXPECTED_RESPONSE";
+    readonly status: number | undefined;
+    readonly correlationId: string;
+    readonly details?: Readonly<Record<string, string>> | undefined;
+    constructor(code: ProvisioningErrorCode | "INVALID_CLIENT_CONFIGURATION" | "UNEXPECTED_RESPONSE", status: number | undefined, correlationId: string, message: string, details?: Readonly<Record<string, string>> | undefined);
+}
+export interface ListActors {
+    state?: ActorState;
+    email?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface ActorPage {
+    items: readonly Actor[];
+    nextCursor?: string;
+}
+export interface MutationContext {
+    idempotencyKey: string;
+    correlationId: string;
+}
+export declare const PROVISIONING_ERROR_CODES: readonly ["INVALID_REQUEST", "AUTHENTICATION_REQUIRED", "PROVISIONING_FORBIDDEN", "ACTOR_NOT_FOUND", "EMAIL_CONFLICT", "EXTERNAL_ID_CONFLICT", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_CONFLICT", "OPERATION_IN_PROGRESS", "ROLE_NOT_ALLOWED", "GROUP_NOT_ALLOWED", "INVALID_STATE", "KEYCLOAK_UNAVAILABLE", "KEYCLOAK_REJECTED", "REGISTRY_UNAVAILABLE", "RECONCILIATION_REQUIRED", "REQUEST_TOO_LARGE", "BROWSER_REQUEST_FORBIDDEN", "INTERNAL_ERROR"];
+export type ProvisioningErrorCode = typeof PROVISIONING_ERROR_CODES[number];
+export interface UpdateAccess {
+    groups: readonly string[];
+    clientRoles: Readonly<Record<string, readonly string[]>>;
+    reason: string;
+}
+export type ProvisioningResult<T> = {
+    status: "succeeded";
+    value: T;
+    correlationId: string;
+} | {
+    status: "operation_in_progress";
+    correlationId: string;
+    retryable: true;
+} | {
+    status: "reconciliation_required";
+    correlationId: string;
+    actor?: T;
+    retryable: false;
+} | {
+    status: "ambiguous";
+    correlationId: string;
+    retryable: false;
+    instruction: "RETRY_SAME_REQUEST";
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,181 @@
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./token.js";
+export * from "./types.js";
+/**
+ * Backend-only VVP Provisioning API client. This package deliberately has no
+ * Keycloak administration surface and must never be bundled for a browser.
+ */
+export const PROVISIONING_CLIENT_VERSION = "1.0.0";
+function meaningfulReason(body) {
+    if (typeof body.reason !== "string" || body.reason.trim().length < 3 || body.reason.length > 500)
+        throw new ProvisioningClientError("INVALID_CLIENT_CONFIGURATION", undefined, "", "A meaningful reason is required");
+}
+export function createProvisioningClient(options) {
+    let base;
+    try {
+        base = new URL(options.baseUrl);
+    }
+    catch {
+        throw new ProvisioningClientError("INVALID_CLIENT_CONFIGURATION", undefined, "", "Invalid Provisioning API URL");
+    }
+    if ((base.protocol !== "https:" && !["localhost", "127.0.0.1", "::1"].includes(base.hostname)) ||
+        !!base.username || !!base.password || !!base.search || !!base.hash || (base.pathname !== "/" && base.pathname !== ""))
+        throw new ProvisioningClientError("INVALID_CLIENT_CONFIGURATION", undefined, "", "Provisioning API must use HTTPS");
+    if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 120_000))
+        throw new ProvisioningClientError("INVALID_CLIENT_CONFIGURATION", undefined, "", "Timeout must be between 1 and 120000 milliseconds");
+    const request = async (method, path, ctx, shape, body) => {
+        const mutation = method !== "GET";
+        context(ctx, mutation);
+        const controller = new AbortController();
+        let rejectDeadline;
+        const deadline = new Promise((_, reject) => {
+            rejectDeadline = () => {
+                controller.abort();
+                reject(new Error("provisioning deadline exceeded"));
+            };
+        });
+        const timeout = setTimeout(rejectDeadline, options.timeoutMs ?? 10_000);
+        let response;
+        try {
+            // The same deadline races both token acquisition and the HTTP exchange.
+            // AbortSignal alone cannot settle a misbehaving token provider.
+            const token = await Promise.race([options.getAccessToken(), deadline]);
+            if (!token)
+                throw new Error("empty token");
+            const exchange = (options.fetch ?? globalThis.fetch)(new URL(path, base), {
+                method,
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    "x-correlation-id": ctx.correlationId,
+                    ...(mutation ? { "idempotency-key": ctx.idempotencyKey } : {}),
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: controller.signal,
+            });
+            response = await Promise.race([exchange, deadline]);
+        }
+        catch {
+            return { status: "ambiguous", correlationId: ctx.correlationId, retryable: false, instruction: "RETRY_SAME_REQUEST" };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        let data;
+        try {
+            data = await response.json();
+        }
+        catch {
+            data = undefined;
+        }
+        const responseCorrelation = response.headers.get("x-correlation-id") ?? ctx.correlationId;
+        if (response.ok) {
+            const parsed = shape === "actor" ? parseActor(data) : parsePage(data);
+            if (!parsed)
+                throw new ProvisioningClientError("UNEXPECTED_RESPONSE", response.status, responseCorrelation, "Provisioning API returned an invalid success payload");
+            return shape === "actor"
+                ? actorOutcome(parsed, responseCorrelation)
+                : { status: "succeeded", value: parsed, correlationId: responseCorrelation };
+        }
+        const envelope = data;
+        const code = envelope?.error?.code;
+        const correlationId = envelope?.correlationId ?? responseCorrelation;
+        if (code === "OPERATION_IN_PROGRESS")
+            return { status: "operation_in_progress", correlationId, retryable: true };
+        if (code === "RECONCILIATION_REQUIRED")
+            return { status: "reconciliation_required", correlationId, retryable: false };
+        if (response.status >= 500)
+            return { status: "ambiguous", correlationId, retryable: false, instruction: "RETRY_SAME_REQUEST" };
+        const stable = PROVISIONING_ERROR_CODES.includes(code)
+            ? code : "UNEXPECTED_RESPONSE";
+        throw new ProvisioningClientError(stable, response.status, correlationId, envelope?.error?.message ?? "Provisioning request failed", envelope?.error?.details);
+    };
+    const mutate = (method, path, body, ctx) => {
+        meaningfulReason(body);
+        return request(method, path, ctx, "actor", body);
+    };
+    const updateAccess = (id, body, ctx) => mutate("PUT", `/v1/actors/${encodeURIComponent(id)}/access`, body, ctx);
+    const resendInvitation = (id, reason, ctx) => mutate("POST", `/v1/actors/${encodeURIComponent(id)}/resend-invitation`, { reason }, ctx);
+    return {
+        invite: (body, ctx) => mutate("POST", "/v1/actors", body, ctx),
+        list: (query, ctx) => {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query))
+                if (value !== undefined)
+                    params.set(key, String(value));
+            return request("GET", `/v1/actors${params.size ? `?${params}` : ""}`, ctx, "page");
+        },
+        get: (id, ctx) => request("GET", `/v1/actors/${encodeURIComponent(id)}`, ctx, "actor"),
+        updateAccess,
+        access: updateAccess,
+        disable: (id, reason, ctx) => mutate("POST", `/v1/actors/${encodeURIComponent(id)}/disable`, { reason }, ctx),
+        restore: (id, reason, ctx) => mutate("POST", `/v1/actors/${encodeURIComponent(id)}/restore`, { reason }, ctx),
+        resendInvitation,
+        resend: resendInvitation,
+    };
+}
+const opaque = /^[A-Za-z0-9._:-]+$/;
+function parsePage(value) {
+    if (!object(value) || !Array.isArray(value["items"]))
+        return undefined;
+    const items = value["items"].map(parseActor);
+    if (items.some((item) => !item) || (value["nextCursor"] !== undefined && typeof value["nextCursor"] !== "string"))
+        return undefined;
+    return { items: items, ...(typeof value["nextCursor"] === "string" ? { nextCursor: value["nextCursor"] } : {}) };
+}
+export class ProvisioningClientError extends Error {
+    code;
+    status;
+    correlationId;
+    details;
+    constructor(code, status, correlationId, message, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.correlationId = correlationId;
+        this.details = details;
+        this.name = "ProvisioningClientError";
+    }
+}
+export const PROVISIONING_ERROR_CODES = [
+    "INVALID_REQUEST", "AUTHENTICATION_REQUIRED", "PROVISIONING_FORBIDDEN", "ACTOR_NOT_FOUND",
+    "EMAIL_CONFLICT", "EXTERNAL_ID_CONFLICT", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_CONFLICT",
+    "OPERATION_IN_PROGRESS", "ROLE_NOT_ALLOWED", "GROUP_NOT_ALLOWED", "INVALID_STATE",
+    "KEYCLOAK_UNAVAILABLE", "KEYCLOAK_REJECTED", "REGISTRY_UNAVAILABLE", "RECONCILIATION_REQUIRED",
+    "REQUEST_TOO_LARGE", "BROWSER_REQUEST_FORBIDDEN", "INTERNAL_ERROR",
+];
+function context(value, mutation) {
+    if (!value.correlationId || value.correlationId.length > 128 || !opaque.test(value.correlationId))
+        throw new ProvisioningClientError("INVALID_CLIENT_CONFIGURATION", undefined, "", "Invalid correlation ID");
+    if (mutation && (!("idempotencyKey" in value) || value.idempotencyKey.length < 16 ||
+        value.idempotencyKey.length > 128 || !opaque.test(value.idempotencyKey)))
+        throw new ProvisioningClientError("INVALID_CLIENT_CONFIGURATION", undefined, value.correlationId, "Invalid idempotency key");
+}
+const object = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function actorOutcome(actor, correlationId) {
+    return actor.state === "RECONCILIATION_REQUIRED"
+        ? { status: "reconciliation_required", correlationId, actor, retryable: false }
+        : { status: "succeeded", value: actor, correlationId };
+}
+function parseActor(value) {
+    const optionalString = (name) => value && object(value) &&
+        (value[name] === undefined || typeof value[name] === "string");
+    if (!object(value) || typeof value["vvpActorId"] !== "string" ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value["vvpActorId"]) ||
+        typeof value["email"] !== "string" || typeof value["actorType"] !== "string" ||
+        !optionalString("keycloakSub") || !optionalString("externalId") || !optionalString("displayName") ||
+        !optionalString("disabledAt") ||
+        !["INVITED", "ACTIVE", "DISABLED", "RECONCILIATION_REQUIRED"].includes(String(value["state"])) ||
+        !Array.isArray(value["groups"]) || !value["groups"].every((item) => typeof item === "string") ||
+        !object(value["clientRoles"]) ||
+        !Object.values(value["clientRoles"]).every((roles) => Array.isArray(roles) && roles.every((role) => typeof role === "string")) ||
+        typeof value["createdAt"] !== "string" || !Number.isFinite(Date.parse(value["createdAt"])) ||
+        typeof value["updatedAt"] !== "string" || !Number.isFinite(Date.parse(value["updatedAt"])) ||
+        (value["disabledAt"] !== undefined && !Number.isFinite(Date.parse(value["disabledAt"]))) ||
+        (value["reconciliation"] !== undefined &&
+            (!object(value["reconciliation"]) || typeof value["reconciliation"]["errorCode"] !== "string")))
+        return undefined;
+    return value;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/token.d.ts

@@ -0,0 +1,27 @@
+export interface BackendTokenProvider {
+    getAccessToken(): Promise<string>;
+}
+export interface ClientCredentialsTokenProviderOptions {
+    tokenEndpoint: string;
+    clientId: string;
+    clientSecret: string;
+    /** Defaults to and may only be provisioning-api. */
+    audience?: "provisioning-api";
+    timeoutMs?: number;
+    maxCacheMs?: number;
+    fetch?: typeof globalThis.fetch;
+    now?: () => number;
+}
+export declare class ClientCredentialsTokenProvider implements BackendTokenProvider {
+    private readonly options;
+    private cached?;
+    private pending;
+    private readonly fetch;
+    private readonly timeoutMs;
+    private readonly maxCacheMs;
+    private readonly now;
+    constructor(options: ClientCredentialsTokenProviderOptions);
+    getAccessToken(): Promise<string>;
+    private acquire;
+}
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,qCAAqC;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,8BAA+B,YAAW,oBAAoB;IAQ7D,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,MAAM,CAAC,CAAuC;IACtD,OAAO,CAAC,OAAO,CAA4D;IAC3E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEN,OAAO,EAAE,qCAAqC;IAerE,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;YAOzB,OAAO;CA2BtB"}

package/dist/token.js

@@ -0,0 +1,66 @@
+export class ClientCredentialsTokenProvider {
+    options;
+    cached;
+    pending;
+    fetch;
+    timeoutMs;
+    maxCacheMs;
+    now;
+    constructor(options) {
+        this.options = options;
+        let endpoint;
+        try {
+            endpoint = new URL(options.tokenEndpoint);
+        }
+        catch {
+            throw new Error("Token endpoint must be a valid absolute URL");
+        }
+        const loopback = endpoint.hostname === "localhost" || endpoint.hostname === "127.0.0.1" || endpoint.hostname === "::1" || endpoint.hostname === "[::1]";
+        if (endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && loopback)) {
+            throw new Error("Token endpoint must use HTTPS (HTTP is permitted only for exact loopback hosts)");
+        }
+        if (endpoint.username || endpoint.password)
+            throw new Error("Token endpoint must not include URL credentials");
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.timeoutMs = Math.min(Math.max(options.timeoutMs ?? 5_000, 100), 30_000);
+        this.maxCacheMs = Math.min(Math.max(options.maxCacheMs ?? 300_000, 1_000), 600_000);
+        this.now = options.now ?? Date.now;
+    }
+    async getAccessToken() {
+        if (this.cached && this.cached.expiresAt > this.now())
+            return this.cached.token;
+        this.pending ??= this.acquire().finally(() => { this.pending = undefined; });
+        this.cached = await this.pending;
+        return this.cached.token;
+    }
+    async acquire() {
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.options.clientId,
+            client_secret: this.options.clientSecret,
+            audience: this.options.audience ?? "provisioning-api",
+        });
+        let response;
+        try {
+            response = await this.fetch(this.options.tokenEndpoint, {
+                method: "POST",
+                headers: { "content-type": "application/x-www-form-urlencoded" },
+                body,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (cause) {
+            throw new Error("Machine token acquisition failed", { cause });
+        }
+        if (!response.ok)
+            throw new Error(`Machine token acquisition failed with HTTP ${response.status}`);
+        const value = await response.json();
+        if (typeof value.access_token !== "string" || (value.token_type !== undefined && String(value.token_type).toLowerCase() !== "bearer")) {
+            throw new Error("Machine token response is invalid");
+        }
+        const expiresIn = typeof value.expires_in === "number" && Number.isFinite(value.expires_in) ? value.expires_in * 1_000 : 60_000;
+        const ttl = Math.max(1_000, Math.min(this.maxCacheMs, expiresIn - 30_000));
+        return { token: value.access_token, expiresAt: this.now() + ttl };
+    }
+}
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export type ActorState = "INVITED" | "ACTIVE" | "DISABLED" | "RECONCILIATION_REQUIRED";
+export interface Actor {
+    vvpActorId: string;
+    keycloakSub?: string;
+    externalId?: string;
+    email: string;
+    actorType: string;
+    displayName?: string;
+    state: ActorState;
+    groups: readonly string[];
+    clientRoles: Readonly<Record<string, readonly string[]>>;
+    createdAt: string;
+    updatedAt: string;
+    disabledAt?: string;
+    reconciliation?: {
+        errorCode: string;
+    };
+}
+export interface InviteActor {
+    email: string;
+    externalId?: string;
+    actorType: string;
+    displayName?: string;
+    groups: readonly string[];
+    clientRoles: Readonly<Record<string, readonly string[]>>;
+    /** Human-readable operator or business justification; 3-500 characters. */
+    reason: string;
+}
+export interface UpdateActorAccess {
+    groups: readonly string[];
+    clientRoles: Readonly<Record<string, readonly string[]>>;
+    /** Human-readable operator or business justification; 3-500 characters. */
+    reason: string;
+}
+export interface LifecycleReason {
+    /** Human-readable operator or business justification; 3-500 characters. */
+    reason: string;
+}
+export interface MutationRequestOptions {
+    /** Persist before sending. Reuse only to retry the exact same logical request and body. */
+    idempotencyKey: string;
+    /** Persist before sending. Stable safe identifier useful for tracing an exact retry. */
+    correlationId: string;
+}
+export interface MutationResponse<T> {
+    data: T;
+    replayed: boolean;
+    correlationId: string;
+    idempotencyKey: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,yBAAyB,CAAC;AAEvF,MAAM,WAAW,KAAK;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACzD,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACzD,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,2FAA2F;IAC3F,cAAc,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@dreadkn1ght123/provisioning-client",
+  "version": "1.0.0",
+  "description": "Backend-only typed client for the VVP Provisioning API",
+  "browser": {
+    "./dist/index.js": "./dist/browser.js"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty false && tsc -p tsconfig.test.json --noEmit --pretty false",
+    "test": "vitest run --config vitest.config.ts"
+  }
+}