@whooshbang/sdk 1.0.0-rc.14

package/dist/client.js

@@ -0,0 +1,924 @@
+import { contractValidationErrors, validateAccountProjection, validateApiCredential, validateApiCredentialCollection, validateApiCredentialRotation, validateApiCredentialSecretReveal, validateCreateApiCredentialRequest, validateCreateCustomerEndpointRequest, validateCreateMachineClientRequest, validateCreateMessageRequest, validateCreateProjectRequest, validateCreateSubscriptionLinkRequest, validateCustomerEndpoint, validateCustomerEndpointAttemptCollection, validateCustomerEndpointCollection, validateCustomerEndpointMutationResult, validateInteractionSummary, validateMachineClient, validateMachineCredential, validateMachineEventAckRequest, validateMachineEventAckResponse, validateMachineEventPollResponse, validateMessage, validateProblem, validateProject, validateProjectCollection, validateProviderCapabilitiesCollection, validateRegisterMachineCredentialRequest, validateRotateApiCredentialRequest, validateRotateCustomerEndpointRequest, validateSubscriptionLink, } from "@whooshbang/contracts";
+import { validateAdditiveCompatible } from "./additive-compatibility.js";
+import { WhooshBangAbortError, WhooshBangContractError, WhooshBangProblemError, WhooshBangProtocolError, WhooshBangTimeoutError, WhooshBangTransportError, validationError, } from "./errors.js";
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const MAX_PROBLEM_BYTES = 64 * 1024;
+const MAX_TIMEOUT_MS = 300_000;
+const MAX_INSPECTION_WAIT_SECONDS = 30;
+const MAX_MACHINE_POLL_LIMIT = 50;
+const MAX_PAGE_LIMIT = 100;
+const DIAGNOSTIC_HEADER = "whooshbang-diagnostic-id";
+const visibleAscii = /^[!-~]+$/u;
+function monotonicNow() {
+    return typeof performance === "object" &&
+        typeof performance.now === "function"
+        ? performance.now()
+        : Date.now();
+}
+function normalizeBaseUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new TypeError("baseUrl must use http or https.");
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new TypeError("baseUrl must not contain credentials.");
+    }
+    url.pathname = `${url.pathname.replace(/\/+$/u, "")}/`;
+    url.search = "";
+    url.hash = "";
+    return url;
+}
+function validateCredential(value) {
+    if (value.length === 0 || value.length > 4096 || !visibleAscii.test(value)) {
+        throw new TypeError("credential must be a bounded visible-ASCII bearer token.");
+    }
+}
+function codePointLength(value) {
+    return Array.from(value).length;
+}
+function containsAsciiControl(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint !== undefined && (codePoint <= 0x1f || codePoint === 0x7f)) {
+            return true;
+        }
+    }
+    return false;
+}
+function pathSegment(operation, value, label) {
+    if (codePointLength(value) === 0 ||
+        codePointLength(value) > 128 ||
+        value === "." ||
+        value === ".." ||
+        containsAsciiControl(value)) {
+        throw validationError(operation, label, "invalid_identifier", `${label} must be a bounded opaque identifier.`);
+    }
+    return encodeURIComponent(value);
+}
+function assertInput(operation, value, validator) {
+    if (!validator(value)) {
+        throw new WhooshBangContractError(operation, contractValidationErrors(validator), "The request does not match the WhooshBang contract.");
+    }
+}
+async function readBoundedJson(response, operation, limit) {
+    const declaredLength = response.headers.get("content-length");
+    if (declaredLength !== null &&
+        (!/^(?:0|[1-9]\d*)$/u.test(declaredLength) ||
+            !Number.isSafeInteger(Number(declaredLength)) ||
+            Number(declaredLength) > limit)) {
+        throw new WhooshBangProtocolError(operation, "The WhooshBang response exceeded the client safety limit.", response.status);
+    }
+    const chunks = [];
+    let byteLength = 0;
+    const reader = response.body?.getReader();
+    if (reader !== undefined) {
+        try {
+            for (;;) {
+                let result;
+                try {
+                    result = await reader.read();
+                }
+                catch {
+                    throw new WhooshBangProtocolError(operation, "The WhooshBang response body could not be read safely.", response.status);
+                }
+                if (result.done) {
+                    break;
+                }
+                byteLength += result.value.byteLength;
+                if (byteLength > limit) {
+                    try {
+                        await reader.cancel();
+                    }
+                    catch {
+                        // The bounded protocol error below intentionally redacts stream
+                        // cancellation failures from an untrusted Fetch implementation.
+                    }
+                    throw new WhooshBangProtocolError(operation, "The WhooshBang response exceeded the client safety limit.", response.status);
+                }
+                chunks.push(result.value);
+            }
+        }
+        finally {
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                // Releasing a hostile or already-failed reader must not replace the
+                // bounded public protocol error with an implementation detail.
+            }
+        }
+    }
+    const bytes = new Uint8Array(byteLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new WhooshBangProtocolError(operation, "The WhooshBang response was not valid UTF-8 JSON.", response.status);
+    }
+}
+function assertIdempotencyKey(operation, value) {
+    if (value.length < 8 || value.length > 255 || !visibleAscii.test(value)) {
+        throw validationError(operation, "idempotencyKey", "invalid_key", "idempotencyKey must contain 8 to 255 visible ASCII characters.");
+    }
+}
+function assertMachineCursor(operation, value) {
+    if (value.length < 8 ||
+        value.length > 128 ||
+        !/^mcur_[A-Za-z0-9_-]+$/u.test(value)) {
+        throw validationError(operation, "after", "invalid_cursor", "after must be a bounded machine cursor from a prior response.");
+    }
+}
+function assertOpaqueCursor(operation, value, subject) {
+    if (value.length === 0 ||
+        value.length > 256 ||
+        !/^[A-Za-z0-9_-]+$/u.test(value)) {
+        throw validationError(operation, "after", "invalid_cursor", `after must be a bounded ${subject} cursor from a prior response.`);
+    }
+}
+function boundedLimit(operation, limit, maximum) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > maximum) {
+        throw validationError(operation, "limit", "out_of_range", `limit must be an integer from 1 through ${maximum}.`);
+    }
+    return String(limit);
+}
+function boundedWait(operation, wait) {
+    if (!Number.isInteger(wait) ||
+        wait < 0 ||
+        wait > MAX_INSPECTION_WAIT_SECONDS) {
+        throw validationError(operation, "wait", "out_of_range", "wait must be an integer from 0 through 30.");
+    }
+    return String(wait);
+}
+/**
+ * Renders the shared bounded-wait query for a response-inspection read.
+ *
+ * The service owns the default. Omitting `wait` therefore sends no parameter
+ * at all rather than a client-invented value, which keeps the documented
+ * 30-second default exactly where the contract puts it.
+ */
+function inspectionWait(operation, wait) {
+    return wait === undefined ? "" : `?wait=${boundedWait(operation, wait)}`;
+}
+function responseMediaType(response) {
+    return (response.headers
+        .get("content-type")
+        ?.split(";", 1)[0]
+        ?.trim()
+        .toLowerCase() ?? "");
+}
+/**
+ * Combines the caller's signal with an optional local deadline.
+ *
+ * When only one of the two exists it is passed through by identity, so a
+ * caller inspecting the outgoing request sees exactly the signal they gave.
+ */
+function resolveSignal(operation, options) {
+    const caller = options.signal;
+    const timeoutMs = options.timeoutMs;
+    if (timeoutMs === undefined) {
+        return {
+            caller,
+            signal: caller,
+            timeoutMs: undefined,
+            timeoutSignal: undefined,
+        };
+    }
+    if (!Number.isInteger(timeoutMs) ||
+        timeoutMs < 1 ||
+        timeoutMs > MAX_TIMEOUT_MS) {
+        throw validationError(operation, "timeoutMs", "out_of_range", "timeoutMs must be an integer from 1 through 300000.");
+    }
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    return {
+        caller,
+        signal: caller === undefined
+            ? timeoutSignal
+            : AbortSignal.any([caller, timeoutSignal]),
+        timeoutMs,
+        timeoutSignal,
+    };
+}
+/**
+ * Classifies a rejected fetch without inventing a server outcome.
+ *
+ * A cancelled side effect may already have been applied, so the resulting
+ * error carries `outcomeUnknown` exactly as an ordinary transport failure
+ * does. The client still sends the request exactly once either way.
+ */
+function cancellationOrTransport(operation, sideEffect, resolved) {
+    if (resolved.caller?.aborted === true) {
+        return new WhooshBangAbortError(operation, sideEffect);
+    }
+    if (resolved.timeoutSignal?.aborted === true &&
+        resolved.timeoutMs !== undefined) {
+        return new WhooshBangTimeoutError(operation, sideEffect, resolved.timeoutMs);
+    }
+    return new WhooshBangTransportError(operation, sideEffect);
+}
+function describeFailure(error) {
+    if (error instanceof WhooshBangProblemError) {
+        return {
+            diagnosticId: error.diagnosticId,
+            outcome: "problem",
+            problemCode: error.code,
+            ...(error.retryAt === undefined ? {} : { retryAt: error.retryAt }),
+            retryable: error.retryable,
+            status: error.status,
+        };
+    }
+    if (error instanceof WhooshBangProtocolError) {
+        return {
+            outcome: "protocol",
+            ...(error.status === undefined ? {} : { status: error.status }),
+        };
+    }
+    if (error instanceof WhooshBangContractError) {
+        return { outcome: "contract" };
+    }
+    if (error instanceof WhooshBangTimeoutError) {
+        return { outcome: "timeout" };
+    }
+    if (error instanceof WhooshBangAbortError) {
+        return { outcome: "abort" };
+    }
+    return { outcome: "transport" };
+}
+export class WhooshBangClient {
+    #baseUrl;
+    #credential;
+    #fetch;
+    #logger;
+    constructor(options) {
+        this.#baseUrl = normalizeBaseUrl(options.baseUrl);
+        validateCredential(options.credential);
+        this.#credential = options.credential;
+        const runtimeFetch = options.fetch ?? globalThis.fetch;
+        if (typeof runtimeFetch !== "function") {
+            throw new TypeError("A Fetch-compatible implementation is required.");
+        }
+        this.#fetch = runtimeFetch.bind(globalThis);
+        this.#logger = options.logger;
+    }
+    async getAccount(options = {}) {
+        return this.#request({
+            method: "GET",
+            operation: "getAccount",
+            options,
+            path: "v1/account",
+            sideEffect: false,
+            validator: validateAccountProjection,
+        });
+    }
+    async listProjects(options = {}) {
+        const search = new URLSearchParams();
+        if (options.after !== undefined) {
+            assertOpaqueCursor("listProjects", options.after, "project");
+            search.set("after", options.after);
+        }
+        if (options.limit !== undefined) {
+            search.set("limit", boundedLimit("listProjects", options.limit, MAX_PAGE_LIMIT));
+        }
+        const suffix = search.size === 0 ? "" : `?${search.toString()}`;
+        return this.#request({
+            method: "GET",
+            operation: "listProjects",
+            options,
+            path: `v1/projects${suffix}`,
+            sideEffect: false,
+            validator: validateProjectCollection,
+        });
+    }
+    async createProject(request, options) {
+        assertInput("createProject", request, validateCreateProjectRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation: "createProject",
+            options,
+            path: "v1/projects",
+            sideEffect: true,
+            validator: validateProject,
+        });
+    }
+    async getProject(projectId, options = {}) {
+        return this.#request({
+            method: "GET",
+            operation: "getProject",
+            options,
+            path: `v1/projects/${pathSegment("getProject", projectId, "projectId")}`,
+            sideEffect: false,
+            validator: validateProject,
+        });
+    }
+    async listApiCredentials(projectId, environmentId, options = {}) {
+        const operation = "listApiCredentials";
+        const search = new URLSearchParams();
+        if (options.after !== undefined) {
+            assertOpaqueCursor(operation, options.after, "API credential");
+            search.set("after", options.after);
+        }
+        if (options.limit !== undefined) {
+            search.set("limit", boundedLimit(operation, options.limit, MAX_PAGE_LIMIT));
+        }
+        const suffix = search.size === 0 ? "" : `?${search.toString()}`;
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/credentials` +
+                suffix,
+            sideEffect: false,
+            validator: validateApiCredentialCollection,
+        });
+    }
+    async createApiCredential(projectId, environmentId, request, options = {}) {
+        const operation = "createApiCredential";
+        assertInput(operation, request, validateCreateApiCredentialRequest);
+        return this.#request({
+            body: request,
+            method: "POST",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/credentials`,
+            sideEffect: true,
+            validator: validateApiCredentialSecretReveal,
+        });
+    }
+    async rotateApiCredential(projectId, environmentId, credentialId, request, options = {}) {
+        const operation = "rotateApiCredential";
+        assertInput(operation, request, validateRotateApiCredentialRequest);
+        return this.#request({
+            body: request,
+            method: "POST",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/credentials/` +
+                `${pathSegment(operation, credentialId, "credentialId")}/rotate`,
+            sideEffect: true,
+            validator: validateApiCredentialRotation,
+        });
+    }
+    async revokeApiCredential(projectId, environmentId, credentialId, options = {}) {
+        const operation = "revokeApiCredential";
+        return this.#request({
+            method: "POST",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/credentials/` +
+                `${pathSegment(operation, credentialId, "credentialId")}/revoke`,
+            sideEffect: true,
+            validator: validateApiCredential,
+        });
+    }
+    async createSubscriptionLink(request, options) {
+        assertInput("createSubscriptionLink", request, validateCreateSubscriptionLinkRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation: "createSubscriptionLink",
+            options,
+            path: "v1/subscription-links",
+            sideEffect: true,
+            validator: validateSubscriptionLink,
+        });
+    }
+    async getSubscriptionLink(subscriptionLinkId, options = {}) {
+        const operation = "getSubscriptionLink";
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `v1/subscription-links/${pathSegment(operation, subscriptionLinkId, "subscriptionLinkId")}`,
+            sideEffect: false,
+            validator: validateSubscriptionLink,
+        });
+    }
+    async cancelSubscriptionLink(subscriptionLinkId, options) {
+        const operation = "cancelSubscriptionLink";
+        return this.#request({
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `v1/subscription-links/${pathSegment(operation, subscriptionLinkId, "subscriptionLinkId")}/cancel`,
+            sideEffect: true,
+            validator: validateSubscriptionLink,
+        });
+    }
+    async createMessage(request, options) {
+        assertInput("createMessage", request, validateCreateMessageRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation: "createMessage",
+            options,
+            path: "v1/messages",
+            sideEffect: true,
+            validator: validateMessage,
+        });
+    }
+    /**
+     * Reads the canonical message state, optionally holding for an open
+     * interaction's terminal state.
+     *
+     * A `wait` that expires still resolves with the current message. Inspection
+     * never acknowledges, consumes, retries, or replays anything.
+     */
+    async getMessage(messageId, options = {}) {
+        const operation = "getMessage";
+        const suffix = inspectionWait(operation, options.wait);
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `v1/messages/${pathSegment(operation, messageId, "messageId")}${suffix}`,
+            sideEffect: false,
+            validator: validateMessage,
+        });
+    }
+    /**
+     * Reads the canonical interaction summary, optionally holding for its
+     * terminal state.
+     *
+     * Expiry without resolution returns the current `open` summary successfully
+     * and can be re-polled immediately.
+     */
+    async getInteraction(interactionId, options = {}) {
+        const operation = "getInteraction";
+        const suffix = inspectionWait(operation, options.wait);
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `v1/interactions/${pathSegment(operation, interactionId, "interactionId")}${suffix}`,
+            sideEffect: false,
+            validator: validateInteractionSummary,
+        });
+    }
+    async cancelMessage(messageId, options) {
+        const operation = "cancelMessage";
+        return this.#request({
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `v1/messages/${pathSegment(operation, messageId, "messageId")}/cancel`,
+            sideEffect: true,
+            validator: validateMessage,
+        });
+    }
+    async getCapabilities(options = {}) {
+        return this.#request({
+            method: "GET",
+            operation: "getCapabilities",
+            options,
+            path: "v1/capabilities",
+            sideEffect: false,
+            validator: validateProviderCapabilitiesCollection,
+        });
+    }
+    async listCustomerEndpoints(projectId, environmentId, options = {}) {
+        const operation = "listCustomerEndpoints";
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: customerEndpointRoot(operation, projectId, environmentId),
+            sideEffect: false,
+            validator: validateCustomerEndpointCollection,
+        });
+    }
+    /**
+     * Creates one signing endpoint.
+     *
+     * The signing secret is revealed exactly once, in this result. An equivalent
+     * idempotent replay returns the same logical endpoint without it, so a caller
+     * that loses the value must rotate rather than re-read.
+     */
+    async createCustomerEndpoint(projectId, environmentId, request, options) {
+        const operation = "createCustomerEndpoint";
+        assertInput(operation, request, validateCreateCustomerEndpointRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: customerEndpointRoot(operation, projectId, environmentId),
+            sideEffect: true,
+            validator: validateCustomerEndpointMutationResult,
+        });
+    }
+    async getCustomerEndpoint(projectId, environmentId, endpointId, options = {}) {
+        const operation = "getCustomerEndpoint";
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: customerEndpointPath(operation, projectId, environmentId, endpointId),
+            sideEffect: false,
+            validator: validateCustomerEndpoint,
+        });
+    }
+    async verifyCustomerEndpoint(projectId, environmentId, endpointId, options = {}) {
+        const operation = "verifyCustomerEndpoint";
+        return this.#request({
+            method: "POST",
+            operation,
+            options,
+            path: `${customerEndpointPath(operation, projectId, environmentId, endpointId)}/verify`,
+            sideEffect: true,
+            validator: validateCustomerEndpoint,
+        });
+    }
+    /**
+     * Starts a rotation with a bounded overlap window.
+     *
+     * Both secrets verify for `overlap_seconds`, so a receiver that accepts the
+     * previous and the new secret together has no verification gap.
+     */
+    async rotateCustomerEndpoint(projectId, environmentId, endpointId, request, options) {
+        const operation = "rotateCustomerEndpoint";
+        assertInput(operation, request, validateRotateCustomerEndpointRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `${customerEndpointPath(operation, projectId, environmentId, endpointId)}/rotate`,
+            sideEffect: true,
+            validator: validateCustomerEndpointMutationResult,
+        });
+    }
+    async pauseCustomerEndpoint(projectId, environmentId, endpointId, options = {}) {
+        return this.#transitionCustomerEndpoint("pauseCustomerEndpoint", "pause", projectId, environmentId, endpointId, options);
+    }
+    async resumeCustomerEndpoint(projectId, environmentId, endpointId, options = {}) {
+        return this.#transitionCustomerEndpoint("resumeCustomerEndpoint", "resume", projectId, environmentId, endpointId, options);
+    }
+    async disableCustomerEndpoint(projectId, environmentId, endpointId, options = {}) {
+        return this.#transitionCustomerEndpoint("disableCustomerEndpoint", "disable", projectId, environmentId, endpointId, options);
+    }
+    async listCustomerEndpointAttempts(projectId, environmentId, endpointId, options = {}) {
+        const operation = "listCustomerEndpointAttempts";
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `${customerEndpointPath(operation, projectId, environmentId, endpointId)}/attempts`,
+            sideEffect: false,
+            validator: validateCustomerEndpointAttemptCollection,
+        });
+    }
+    /**
+     * The environment-scoped forms of the product operations.
+     *
+     * They exist for a caller whose authority selects an account rather than a
+     * project — a person's OAuth grant — and name the project and environment in
+     * the path that the flat forms take from a credential. Request, response,
+     * and semantics are otherwise identical, so a caller that changes authority
+     * changes which method it calls and nothing else.
+     */
+    async createSubscriptionLinkInEnvironment(projectId, environmentId, request, options) {
+        const operation = "createSubscriptionLinkInEnvironment";
+        assertInput(operation, request, validateCreateSubscriptionLinkRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/subscription-links`,
+            sideEffect: true,
+            validator: validateSubscriptionLink,
+        });
+    }
+    async getSubscriptionLinkInEnvironment(projectId, environmentId, subscriptionLinkId, options = {}) {
+        const operation = "getSubscriptionLinkInEnvironment";
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/subscription-links/` +
+                pathSegment(operation, subscriptionLinkId, "subscriptionLinkId"),
+            sideEffect: false,
+            validator: validateSubscriptionLink,
+        });
+    }
+    async createMessageInEnvironment(projectId, environmentId, request, options) {
+        const operation = "createMessageInEnvironment";
+        assertInput(operation, request, validateCreateMessageRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/messages`,
+            sideEffect: true,
+            validator: validateMessage,
+        });
+    }
+    async getMessageInEnvironment(projectId, environmentId, messageId, options = {}) {
+        const operation = "getMessageInEnvironment";
+        const suffix = inspectionWait(operation, options.wait);
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/messages/` +
+                `${pathSegment(operation, messageId, "messageId")}${suffix}`,
+            sideEffect: false,
+            validator: validateMessage,
+        });
+    }
+    async getInteractionInEnvironment(projectId, environmentId, interactionId, options = {}) {
+        const operation = "getInteractionInEnvironment";
+        const suffix = inspectionWait(operation, options.wait);
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/interactions/` +
+                `${pathSegment(operation, interactionId, "interactionId")}${suffix}`,
+            sideEffect: false,
+            validator: validateInteractionSummary,
+        });
+    }
+    async createMachineClientInEnvironment(projectId, environmentId, request, options) {
+        const operation = "createMachineClientInEnvironment";
+        assertInput(operation, request, validateCreateMachineClientRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/machine-clients`,
+            sideEffect: true,
+            validator: validateMachineClient,
+        });
+    }
+    async getCapabilitiesInEnvironment(projectId, environmentId, options = {}) {
+        const operation = "getCapabilitiesInEnvironment";
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `${environmentRoot(operation, projectId, environmentId)}/capabilities`,
+            sideEffect: false,
+            validator: validateProviderCapabilitiesCollection,
+        });
+    }
+    async createMachineClient(request, options) {
+        assertInput("createMachineClient", request, validateCreateMachineClientRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation: "createMachineClient",
+            options,
+            path: "v1/machine-clients",
+            sideEffect: true,
+            validator: validateMachineClient,
+        });
+    }
+    async getMachineClient(machineClientId, options = {}) {
+        const operation = "getMachineClient";
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `v1/machine-clients/${pathSegment(operation, machineClientId, "machineClientId")}`,
+            sideEffect: false,
+            validator: validateMachineClient,
+        });
+    }
+    /**
+     * Registers a locally generated credential by digest only.
+     *
+     * The readable secret never leaves the caller's process. See
+     * `createMachineCredential` for the generator that produces the pair.
+     */
+    async registerMachineCredential(machineClientId, request, options) {
+        const operation = "registerMachineCredential";
+        assertInput(operation, request, validateRegisterMachineCredentialRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `v1/machine-clients/${pathSegment(operation, machineClientId, "machineClientId")}/credentials`,
+            sideEffect: true,
+            validator: validateMachineCredential,
+        });
+    }
+    async revokeMachineCredential(machineClientId, credentialId, options) {
+        const operation = "revokeMachineCredential";
+        return this.#request({
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `v1/machine-clients/${pathSegment(operation, machineClientId, "machineClientId")}/credentials/` +
+                `${pathSegment(operation, credentialId, "credentialId")}/revoke`,
+            sideEffect: true,
+            validator: validateMachineCredential,
+        });
+    }
+    async revokeMachineClient(machineClientId, options) {
+        const operation = "revokeMachineClient";
+        return this.#request({
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `v1/machine-clients/${pathSegment(operation, machineClientId, "machineClientId")}/revoke`,
+            sideEffect: true,
+            validator: validateMachineClient,
+        });
+    }
+    async pollMachineEvents(options = {}) {
+        const operation = "pollMachineEvents";
+        const search = new URLSearchParams();
+        if (options.after !== undefined) {
+            assertMachineCursor(operation, options.after);
+            search.set("after", options.after);
+        }
+        if (options.wait !== undefined) {
+            search.set("wait", boundedWait(operation, options.wait));
+        }
+        if (options.limit !== undefined) {
+            search.set("limit", boundedLimit(operation, options.limit, MAX_MACHINE_POLL_LIMIT));
+        }
+        const suffix = search.size === 0 ? "" : `?${search.toString()}`;
+        return this.#request({
+            method: "GET",
+            operation,
+            options,
+            path: `v1/machine-events${suffix}`,
+            sideEffect: false,
+            validator: validateMachineEventPollResponse,
+        });
+    }
+    async acknowledgeMachineEvent(eventId, request, options) {
+        const operation = "acknowledgeMachineEvent";
+        assertInput(operation, request, validateMachineEventAckRequest);
+        return this.#request({
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            method: "POST",
+            operation,
+            options,
+            path: `v1/machine-events/${pathSegment(operation, eventId, "eventId")}/ack`,
+            sideEffect: true,
+            validator: validateMachineEventAckResponse,
+        });
+    }
+    async #transitionCustomerEndpoint(operation, action, projectId, environmentId, endpointId, options) {
+        return this.#request({
+            method: "POST",
+            operation,
+            options,
+            path: `${customerEndpointPath(operation, projectId, environmentId, endpointId)}/${action}`,
+            sideEffect: true,
+            validator: validateCustomerEndpoint,
+        });
+    }
+    #log(record) {
+        const logger = this.#logger;
+        if (logger === undefined) {
+            return;
+        }
+        try {
+            logger(record);
+        }
+        catch {
+            // A caller's logging hook must never change the operation's outcome.
+        }
+    }
+    /**
+     * Runs one attempt and reports exactly one log record for it.
+     *
+     * Caller input is validated first, outside the logged region, so the hook
+     * describes attempted requests only. A local refusal throws at the caller's
+     * own call site, where it is already unmissable.
+     */
+    async #request(descriptor) {
+        if (descriptor.idempotencyKey !== undefined) {
+            assertIdempotencyKey(descriptor.operation, descriptor.idempotencyKey);
+        }
+        const resolved = resolveSignal(descriptor.operation, descriptor.options);
+        const startedAt = monotonicNow();
+        try {
+            const result = await this.#send(descriptor, resolved);
+            this.#log({
+                ...(result.diagnosticId === undefined
+                    ? {}
+                    : { diagnosticId: result.diagnosticId }),
+                durationMs: Math.max(0, monotonicNow() - startedAt),
+                operation: descriptor.operation,
+                outcome: "success",
+                status: result.status,
+            });
+            return result.body;
+        }
+        catch (error) {
+            this.#log({
+                durationMs: Math.max(0, monotonicNow() - startedAt),
+                operation: descriptor.operation,
+                ...describeFailure(error),
+            });
+            throw error;
+        }
+    }
+    async #send(descriptor, resolved) {
+        const headers = new Headers({
+            accept: "application/json, application/problem+json",
+            authorization: `Bearer ${this.#credential}`,
+        });
+        if (descriptor.idempotencyKey !== undefined) {
+            headers.set("idempotency-key", descriptor.idempotencyKey);
+        }
+        let body;
+        if (descriptor.body !== undefined) {
+            headers.set("content-type", "application/json");
+            body = JSON.stringify(descriptor.body);
+        }
+        const url = new URL(descriptor.path, this.#baseUrl);
+        let response;
+        try {
+            response = await this.#fetch(url, {
+                ...(body === undefined ? {} : { body }),
+                headers,
+                method: descriptor.method,
+                ...(resolved.signal === undefined ? {} : { signal: resolved.signal }),
+            });
+        }
+        catch {
+            throw cancellationOrTransport(descriptor.operation, descriptor.sideEffect, resolved);
+        }
+        /**
+         * Reads the body, keeping a cancelled read a cancellation.
+         *
+         * A signal that fires after the response headers arrive rejects the
+         * stream read. Reporting that as a protocol error would blame the server
+         * and drop `outcomeUnknown`, when in fact the side effect may already
+         * have been applied.
+         */
+        const readBody = async (limit) => {
+            try {
+                return await readBoundedJson(response, descriptor.operation, limit);
+            }
+            catch (error) {
+                if (resolved.caller?.aborted === true ||
+                    resolved.timeoutSignal?.aborted === true) {
+                    throw cancellationOrTransport(descriptor.operation, descriptor.sideEffect, resolved);
+                }
+                throw error;
+            }
+        };
+        const diagnosticId = response.headers.get(DIAGNOSTIC_HEADER) ?? undefined;
+        const mediaType = responseMediaType(response);
+        if (!response.ok) {
+            if (mediaType !== "application/problem+json") {
+                throw new WhooshBangProtocolError(descriptor.operation, "The WhooshBang error response had an unexpected media type.", response.status);
+            }
+            const value = await readBody(MAX_PROBLEM_BYTES);
+            if (!validateProblem(value) || value.status !== response.status) {
+                throw new WhooshBangProtocolError(descriptor.operation, "The WhooshBang error response did not match Problem Details.", response.status);
+            }
+            throw new WhooshBangProblemError(value);
+        }
+        if (mediaType !== "application/json") {
+            throw new WhooshBangProtocolError(descriptor.operation, "The WhooshBang success response had an unexpected media type.", response.status);
+        }
+        const value = await readBody(MAX_RESPONSE_BYTES);
+        if (!validateAdditiveCompatible(value, descriptor.validator)) {
+            throw new WhooshBangContractError(descriptor.operation, contractValidationErrors(descriptor.validator), "The WhooshBang response did not match the pinned contract.");
+        }
+        return { body: value, diagnosticId, status: response.status };
+    }
+}
+function environmentRoot(operation, projectId, environmentId) {
+    const project = pathSegment(operation, projectId, "projectId");
+    const environment = pathSegment(operation, environmentId, "environmentId");
+    return `v1/projects/${project}/environments/${environment}`;
+}
+function customerEndpointRoot(operation, projectId, environmentId) {
+    return `${environmentRoot(operation, projectId, environmentId)}/customer-endpoints`;
+}
+function customerEndpointPath(operation, projectId, environmentId, endpointId) {
+    return `${customerEndpointRoot(operation, projectId, environmentId)}/${pathSegment(operation, endpointId, "endpointId")}`;
+}
+//# sourceMappingURL=client.js.map