totemlayer 0.1.1 → 0.1.3

package/bin/sdk/transport.js

@@ -0,0 +1,197 @@
+import { apiError, TotemCanceledError, TotemError, TotemNetworkError, TotemTimeoutError, } from "./errors.js";
+export function idempotencyKey() {
+    return globalThis.crypto.randomUUID();
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const cancel = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", cancel);
+            reject(new TotemCanceledError("Totem request canceled.", { code: "CANCELED" }));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", cancel);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", cancel, { once: true });
+        if (signal?.aborted)
+            cancel();
+    });
+}
+export class Transport {
+    #apiKey;
+    #baseUrl;
+    #fetch;
+    #timeoutMs;
+    #maxRetries;
+    #retryDelayMs;
+    constructor(options) {
+        if (!options.apiKey?.trim())
+            throw new TotemError("An agent API key is required.", { code: "INVALID_CONFIG" });
+        const url = new URL(options.baseUrl ?? "https://totemlayer.com");
+        const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+        if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            url.pathname !== "/") {
+            throw new TotemError("baseUrl must be an HTTPS origin or a local HTTP origin.", {
+                code: "INVALID_CONFIG",
+            });
+        }
+        this.#apiKey = options.apiKey;
+        this.#baseUrl = `${url.origin}/api/v1/network`;
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#timeoutMs = options.timeoutMs ?? 15_000;
+        this.#maxRetries = options.maxRetries ?? 2;
+        this.#retryDelayMs = options.retryDelayMs ?? 250;
+        if (!Number.isFinite(this.#timeoutMs) ||
+            this.#timeoutMs < 1 ||
+            !Number.isInteger(this.#maxRetries) ||
+            this.#maxRetries < 0 ||
+            this.#maxRetries > 10 ||
+            !Number.isFinite(this.#retryDelayMs) ||
+            this.#retryDelayMs < 0) {
+            throw new TotemError("Invalid timeout or retry configuration.", { code: "INVALID_CONFIG" });
+        }
+    }
+    async request(method, path, options = {}) {
+        const url = new URL(`${this.#baseUrl}${path}`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== null)
+                url.searchParams.set(key, String(value));
+        }
+        const retrySafe = method === "GET" || options.retrySafe === true || Boolean(options.idempotencyKey);
+        const body = options.binaryBody ?? (options.body === undefined ? undefined : JSON.stringify(options.body));
+        const headers = {
+            Authorization: `Bearer ${this.#apiKey}`,
+            Accept: "application/json",
+            ...(body === undefined || options.binaryBody ? {} : { "Content-Type": "application/json" }),
+            ...(options.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : {}),
+            ...(options.headers ?? {}),
+        };
+        for (let attempt = 0;; attempt++) {
+            if (options.signal?.aborted)
+                throw new TotemCanceledError("Totem request canceled.", { code: "CANCELED" });
+            const controller = new AbortController();
+            let timer;
+            let cancel;
+            let retryAfter = null;
+            try {
+                const aborted = new Promise((_, reject) => {
+                    cancel = () => {
+                        controller.abort();
+                        reject(new TotemCanceledError("Totem request canceled.", { code: "CANCELED" }));
+                    };
+                    options.signal?.addEventListener("abort", cancel, { once: true });
+                    if (options.signal?.aborted)
+                        cancel();
+                    timer = setTimeout(() => {
+                        controller.abort();
+                        reject(new TotemTimeoutError("Totem request timed out.", { code: "TIMEOUT" }));
+                    }, this.#timeoutMs);
+                });
+                const response = (async () => {
+                    const result = await this.#fetch(url.toString(), {
+                        method,
+                        headers,
+                        body: body instanceof Uint8Array ? new Uint8Array(body) : body,
+                        signal: controller.signal,
+                        redirect: "error",
+                        cache: "no-store",
+                    });
+                    retryAfter = result.headers.get("Retry-After");
+                    const requestId = result.headers.get("X-Request-Id") ?? undefined;
+                    let payload;
+                    try {
+                        payload = await result.json();
+                    }
+                    catch {
+                        if (!result.ok)
+                            throw apiError(result.status, undefined, requestId);
+                        throw new TotemError("Totem returned invalid JSON.", {
+                            code: "INVALID_RESPONSE",
+                            requestId,
+                        });
+                    }
+                    if (!result.ok)
+                        throw apiError(result.status, payload, requestId);
+                    if (!payload || typeof payload !== "object" || !("data" in payload)) {
+                        throw new TotemError("Totem returned an invalid response envelope.", {
+                            code: "INVALID_RESPONSE",
+                            requestId,
+                        });
+                    }
+                    return payload;
+                })();
+                return await Promise.race([response, aborted]);
+            }
+            catch (cause) {
+                const error = cause instanceof TotemError
+                    ? cause
+                    : new TotemNetworkError("Unable to reach Totem.", { code: "NETWORK_ERROR", cause });
+                const transient = error instanceof TotemNetworkError ||
+                    error instanceof TotemTimeoutError ||
+                    (error.status !== undefined && [408, 429, 500, 502, 503, 504].includes(error.status));
+                if (!retrySafe || !transient || attempt >= this.#maxRetries)
+                    throw error;
+                // The request timer and caller listener must not survive into backoff.
+                clearTimeout(timer);
+                if (cancel)
+                    options.signal?.removeEventListener("abort", cancel);
+                const seconds = retryAfter === null ? NaN : Number(retryAfter);
+                const parsedDate = retryAfter === null ? NaN : Date.parse(retryAfter);
+                const requestedDelay = Number.isFinite(seconds) ? seconds * 1000 : parsedDate - Date.now();
+                const fallback = this.#retryDelayMs * 2 ** attempt * (0.75 + Math.random() * 0.5);
+                await sleep(Math.min(30_000, Math.max(0, Number.isFinite(requestedDelay) ? requestedDelay : fallback)), options.signal);
+            }
+            finally {
+                clearTimeout(timer);
+                if (cancel)
+                    options.signal?.removeEventListener("abort", cancel);
+            }
+        }
+    }
+    async download(path, options = {}) {
+        const signal = AbortSignal.any([options.signal, AbortSignal.timeout(this.#timeoutMs)].filter(Boolean));
+        let response;
+        try {
+            response = await this.#fetch(`${this.#baseUrl}${path}`, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${this.#apiKey}` },
+                signal,
+                redirect: "error",
+                cache: "no-store",
+            });
+        }
+        catch (cause) {
+            throw new TotemNetworkError("Unable to download the attachment.", {
+                code: "NETWORK_ERROR",
+                cause,
+            });
+        }
+        if (!response.ok) {
+            const payload = await response.json().catch(() => undefined);
+            throw apiError(response.status, payload, response.headers.get("x-request-id") ?? undefined);
+        }
+        const reported = Number(response.headers.get("content-length"));
+        if (reported > 2 * 1024 * 1024)
+            throw new TotemError("The attachment exceeds the 2 MiB limit.", {
+                code: "ATTACHMENT_TOO_LARGE",
+            });
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.byteLength > 2 * 1024 * 1024)
+            throw new TotemError("The attachment exceeds the 2 MiB limit.", {
+                code: "ATTACHMENT_TOO_LARGE",
+            });
+        const disposition = response.headers.get("content-disposition") ?? "";
+        const encoded = disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
+        return {
+            bytes,
+            mediaType: response.headers.get("content-type") ?? "application/octet-stream",
+            name: encoded ? decodeURIComponent(encoded) : "attachment",
+            sha256: response.headers.get("x-content-sha256"),
+        };
+    }
+}

package/bin/sdk/types.js

@@ -0,0 +1 @@
+export {};