@nohead/sdk 0.0.0 → 0.2.0

package/dist/core.d.ts

@@ -0,0 +1,86 @@
+import { APIPromise, PagePromise } from "./api-promise.ts";
+import { NoheadError } from "./errors.ts";
+import { type OperationId, type Operations } from "./generated/operations.gen.ts";
+import type { ListMeta } from "./generated/types.gen.ts";
+export declare const DEFAULT_BASE_URL = "https://api.nohead.io";
+export interface ClientOptions {
+    /** A project API key (`sk_live_…`). Defaults to `NOHEAD_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `NOHEAD_API_URL`, else `https://api.nohead.io`. */
+    baseUrl?: string;
+    /** The key's project. Looked up once with `GET /v1/me` when omitted. */
+    projectId?: string;
+    /** Retries of failed requests (see README, "Retries"). Default 2. */
+    maxRetries?: number;
+    /** Milliseconds per attempt. Default 60 000. */
+    timeout?: number;
+    /** A `fetch` implementation, for proxies, instrumentation or tests. */
+    fetch?: typeof fetch;
+    /** Headers added to every request. */
+    headers?: Record<string, string>;
+    /** Log deprecation and plan usage warnings (once each). Default true. */
+    warnings?: boolean;
+    /** Called before each retry, for example to report it. */
+    onRetry?: (retry: RetryEvent) => void;
+}
+/** A retry about to happen (`onRetry`). */
+export interface RetryEvent {
+    /** 1 for the first retry of the request, 2 for the second… */
+    attempt: number;
+    /** Seconds the client waits before it. */
+    delay: number;
+    /** The URL being retried. */
+    url: string;
+    /** The status that failed, or undefined when the connection did. */
+    status?: number;
+    /** What failed: an `APIError` or a `ConnectionError` (none for storage). */
+    error?: NoheadError;
+}
+export interface RequestOptions {
+    /** Sent as `Idempotency-Key` on writes. Generated when omitted. */
+    idempotencyKey?: string;
+    /** A reason for the change, shown in history (`Nohead-Change-Note`). */
+    changeNote?: string;
+    signal?: AbortSignal;
+    /** Milliseconds per attempt, overriding the client's. */
+    timeout?: number;
+    /** Retries, overriding the client's. */
+    maxRetries?: number;
+    headers?: Record<string, string>;
+}
+/** Options of record writes that accept `If-Match`. */
+export interface ConditionalRequestOptions extends RequestOptions {
+    /**
+     * Only write if the record is still at this revision; otherwise the API
+     * answers `412` (`PreconditionFailedError`). A record works too.
+     */
+    ifMatch?: number | {
+        revision: number;
+    };
+}
+export interface RequestInput {
+    path?: Record<string, string | number | undefined>;
+    query?: object;
+    body?: unknown;
+}
+type AllOptions = ConditionalRequestOptions;
+export declare class Core {
+    #private;
+    constructor(options: ClientOptions);
+    /** The API key's project, from `GET /v1/me` the first time. */
+    projectId(): Promise<string>;
+    request<Op extends OperationId>(operation: Op, input?: RequestInput, options?: AllOptions): APIPromise<Operations[Op]["response"]>;
+    /** A list operation as pages of `Item`. */
+    paginate<Item, Meta extends ListMeta = ListMeta>(operation: OperationId, input: RequestInput, options?: RequestOptions): PagePromise<Item, Meta>;
+    /** `fetch` with this client's timeout and retries, for presigned URLs. */
+    fetchWithRetries(url: string, init: RequestInit, options: RequestOptions & {
+        retry: boolean;
+    }): Promise<Response>;
+}
+/**
+ * Query parameters as the API reads them: objects become `key[sub]=…`
+ * (`filter[status]=published`), arrays are comma-separated
+ * (`expand=author,tags`), dates are ISO 8601.
+ */
+export declare function appendQuery(params: URLSearchParams, value: unknown, key?: string): void;
+export {};

package/dist/core.js

@@ -0,0 +1,299 @@
+import { APIPromise, Page, PagePromise, } from "./api-promise.js";
+import { AbortError, ConnectionError, NoheadError, TimeoutError, apiError, retryAfterSeconds, } from "./errors.js";
+import { OPERATIONS, } from "./generated/operations.gen.js";
+import { VERSION } from "./version.js";
+export const DEFAULT_BASE_URL = "https://api.nohead.io";
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+const MAX_RETRY_AFTER_SECONDS = 60;
+const warnedDeprecations = new Set();
+let warnedUsage = false;
+export class Core {
+    #apiKey;
+    #baseUrl;
+    #fetch;
+    #headers;
+    #maxRetries;
+    #timeout;
+    #warnings;
+    #onRetry;
+    #projectId;
+    constructor(options) {
+        const env = environment();
+        // Empty environment variables count as unset.
+        const apiKey = options.apiKey ?? (env.NOHEAD_API_KEY || undefined);
+        if (!apiKey) {
+            throw new NoheadError("Missing API key: pass `apiKey` or set NOHEAD_API_KEY");
+        }
+        this.#apiKey = apiKey;
+        this.#baseUrl = (options.baseUrl ??
+            (env.NOHEAD_API_URL || DEFAULT_BASE_URL)).replace(/\/+$/, "");
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#headers = options.headers ?? {};
+        this.#maxRetries = options.maxRetries ?? 2;
+        this.#timeout = options.timeout ?? 60_000;
+        this.#warnings = options.warnings ?? true;
+        this.#onRetry = options.onRetry;
+        if (options.projectId)
+            this.#projectId = Promise.resolve(options.projectId);
+    }
+    /** The API key's project, from `GET /v1/me` the first time. */
+    projectId() {
+        this.#projectId ??= this.request("me_get", {}).then((me) => {
+            if (!me.api_key) {
+                throw new NoheadError("The credentials are not a project API key");
+            }
+            return me.api_key.project_id;
+        }, (error) => {
+            this.#projectId = undefined;
+            throw error;
+        });
+        return this.#projectId;
+    }
+    request(operation, input = {}, options = {}) {
+        return new APIPromise(this.#send(operation, input, options));
+    }
+    /** A list operation as pages of `Item`. */
+    paginate(operation, input, options = {}) {
+        const fetchPage = async (cursor) => {
+            const query = { ...input.query, ...(cursor ? { cursor } : {}) };
+            const result = await this.#send(operation, { ...input, query }, options);
+            const list = result.data;
+            const page = new Page(list.data, list.meta, (next) => fetchPage(next).then((r) => r.data));
+            return { ...result, data: page };
+        };
+        const first = input.query?.cursor;
+        return new PagePromise(fetchPage(first));
+    }
+    /** `fetch` with this client's timeout and retries, for presigned URLs. */
+    async fetchWithRetries(url, init, options) {
+        const maxRetries = options.retry
+            ? (options.maxRetries ?? this.#maxRetries)
+            : 0;
+        for (let attempt = 0;; attempt++) {
+            let failed;
+            try {
+                const { response } = await this.#attempt(url, init, options, false);
+                if (!RETRYABLE_STATUSES.has(response.status) || attempt >= maxRetries) {
+                    return response;
+                }
+                failed = { status: response.status };
+            }
+            catch (error) {
+                if (!(error instanceof ConnectionError) || attempt >= maxRetries) {
+                    throw error;
+                }
+                failed = { error };
+            }
+            await this.#retry(url, attempt, backoff(attempt), failed, options.signal);
+        }
+    }
+    async #send(operation, input, options) {
+        const { method, path } = OPERATIONS[operation];
+        const url = new URL(this.#baseUrl + (await this.#path(path, input.path)));
+        appendQuery(url.searchParams, input.query);
+        const headers = {
+            Accept: "application/json",
+            Authorization: `Bearer ${this.#apiKey}`,
+            "Nohead-Client": `sdk-typescript/${VERSION}`,
+            ...USER_AGENT,
+            ...this.#headers,
+        };
+        if (input.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (method !== "GET") {
+            headers["Idempotency-Key"] = options.idempotencyKey ?? crypto.randomUUID();
+        }
+        if (options.ifMatch !== undefined) {
+            const revision = typeof options.ifMatch === "object"
+                ? options.ifMatch.revision
+                : options.ifMatch;
+            headers["If-Match"] = `"${revision}"`;
+        }
+        if (options.changeNote)
+            headers["Nohead-Change-Note"] = options.changeNote;
+        Object.assign(headers, options.headers);
+        const init = {
+            method,
+            headers,
+            body: input.body === undefined ? undefined : JSON.stringify(input.body),
+        };
+        const maxRetries = options.maxRetries ?? this.#maxRetries;
+        for (let attempt = 0;; attempt++) {
+            let result;
+            try {
+                result = await this.#attempt(url.toString(), init, options, true);
+            }
+            catch (error) {
+                if (!(error instanceof ConnectionError) || attempt >= maxRetries) {
+                    throw error;
+                }
+                await this.#retry(url.toString(), attempt, backoff(attempt), { error }, options.signal);
+                continue;
+            }
+            const { response, body } = result;
+            this.#warn(operation, response);
+            const requestId = response.headers.get("x-request-id") ?? undefined;
+            if (response.ok)
+                return { data: body, response, requestId };
+            const error = apiError(response.status, body, response.headers);
+            const delay = retryDelay(error, attempt, maxRetries);
+            if (delay === undefined)
+                throw error;
+            await this.#retry(url.toString(), attempt, delay, { status: response.status, error }, options.signal);
+        }
+    }
+    #retry(url, attempt, delay, failed, signal) {
+        this.#onRetry?.({ attempt: attempt + 1, delay, url, ...failed });
+        return sleep(delay, signal);
+    }
+    async #attempt(url, init, options, readBody) {
+        const timeout = options.timeout ?? this.#timeout;
+        const timer = AbortSignal.timeout(timeout);
+        const signal = options.signal
+            ? AbortSignal.any([options.signal, timer])
+            : timer;
+        try {
+            const response = await this.#fetch(url, { ...init, signal });
+            const body = readBody ? await parseBody(response) : undefined;
+            return { response, body };
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                throw new AbortError("The request was aborted", {
+                    cause: options.signal.reason,
+                });
+            }
+            if (timer.aborted) {
+                throw new TimeoutError(`The request timed out after ${timeout} ms`);
+            }
+            throw new ConnectionError(`Could not reach ${new URL(url).host}: ${error.message}`, { cause: error });
+        }
+    }
+    async #path(template, values = {}) {
+        let path = template;
+        for (const [, name] of template.matchAll(/\{(\w+)\}/g)) {
+            let value = values[name];
+            if (value === undefined && name === "project_id") {
+                value = await this.projectId();
+            }
+            if (value === undefined || value === "") {
+                throw new NoheadError(`Missing ${name}`);
+            }
+            path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
+        }
+        return path;
+    }
+    #warn(operation, response) {
+        if (!this.#warnings)
+            return;
+        const deprecation = response.headers.get("deprecation");
+        if (deprecation && !warnedDeprecations.has(operation)) {
+            warnedDeprecations.add(operation);
+            const sunset = response.headers.get("sunset");
+            const link = response.headers.get("link")?.match(/<([^>]+)>/)?.[1];
+            console.warn(`[nohead] ${operation} is deprecated` +
+                (sunset ? ` and will be removed after ${sunset}` : "") +
+                (link ? `. See ${link}` : ""));
+        }
+        const usage = response.headers.get("nohead-usage-warning");
+        if (usage && !warnedUsage) {
+            warnedUsage = true;
+            console.warn(`[nohead] Over a plan limit: ${usage}`);
+        }
+    }
+}
+/** Seconds to wait before retrying `error`, or undefined to throw it. */
+function retryDelay(error, attempt, maxRetries) {
+    if (attempt >= maxRetries)
+        return undefined;
+    const inProgress = error.status === 409 && error.details.some((d) => d.code === "in_progress");
+    if (!inProgress && !RETRYABLE_STATUSES.has(error.status))
+        return undefined;
+    const retryAfter = retryAfterSeconds(error.headers);
+    if (retryAfter === undefined)
+        return backoff(attempt);
+    return retryAfter <= MAX_RETRY_AFTER_SECONDS ? retryAfter : undefined;
+}
+/** Exponential backoff with jitter: about 0.5 s, 1 s, 2 s… up to 8 s. */
+function backoff(attempt) {
+    const base = Math.min(0.5 * 2 ** attempt, 8);
+    return base * (1 - Math.random() * 0.25);
+}
+function sleep(seconds, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new AbortError("The request was aborted", { cause: signal.reason }));
+            return;
+        }
+        const timer = setTimeout(done, seconds * 1000);
+        function done() {
+            signal?.removeEventListener("abort", aborted);
+            resolve();
+        }
+        function aborted() {
+            clearTimeout(timer);
+            reject(new AbortError("The request was aborted", { cause: signal.reason }));
+        }
+        signal?.addEventListener("abort", aborted, { once: true });
+    });
+}
+async function parseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    if (!response.headers.get("content-type")?.includes("json"))
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Query parameters as the API reads them: objects become `key[sub]=…`
+ * (`filter[status]=published`), arrays are comma-separated
+ * (`expand=author,tags`), dates are ISO 8601.
+ */
+export function appendQuery(params, value, key) {
+    if (value === undefined || value === null)
+        return;
+    if (value instanceof Date) {
+        params.append(key, value.toISOString());
+    }
+    else if (Array.isArray(value)) {
+        if (value.length > 0)
+            params.append(key, value.map(scalar).join(","));
+    }
+    else if (typeof value === "object") {
+        for (const [name, inner] of Object.entries(value)) {
+            appendQuery(params, inner, key ? `${key}[${name}]` : name);
+        }
+    }
+    else {
+        params.append(key, scalar(value));
+    }
+}
+function scalar(value) {
+    return value instanceof Date ? value.toISOString() : String(value);
+}
+// `nohead-typescript/0.1.0 node/26.9.0`, or none in a browser, which sends its
+// own (Nohead-Client still names the SDK there).
+const RUNTIME = runtimeVersion();
+const USER_AGENT = {};
+if (RUNTIME)
+    USER_AGENT["User-Agent"] = `nohead-typescript/${VERSION} ${RUNTIME}`;
+function runtimeVersion() {
+    const g = globalThis;
+    if (g.Bun?.version)
+        return `bun/${g.Bun.version}`;
+    if (g.Deno?.version?.deno)
+        return `deno/${g.Deno.version.deno}`;
+    if (g.process?.versions?.node)
+        return `node/${g.process.versions.node}`;
+    return undefined;
+}
+function environment() {
+    const process = globalThis.process;
+    return process?.env ?? {};
+}

package/dist/errors.d.ts

@@ -0,0 +1,85 @@
+import type { ErrorDetail, ErrorType } from "./generated/types.gen.ts";
+/** The base class of every error this SDK throws. */
+export declare class NoheadError extends Error {
+    name: string;
+}
+/** The API answered with an error status. Subclasses follow the error `type`. */
+export declare class APIError extends NoheadError {
+    name: string;
+    /** The HTTP status. */
+    readonly status: number;
+    /** The error `type`, e.g. `validation_error`; undefined if the body had none. */
+    readonly type: ErrorType | undefined;
+    /** The request's ID (`req_…`), for support requests and logs. */
+    readonly requestId: string | undefined;
+    /** Field-level details, e.g. `[{ field: "title", code: "required", … }]`. */
+    readonly details: ErrorDetail[];
+    readonly headers: Headers;
+    /** The parsed response body, or its text when it was not JSON. */
+    readonly body: unknown;
+    constructor(status: number, body: unknown, headers: Headers);
+}
+export declare class InvalidRequestError extends APIError {
+    name: string;
+}
+export declare class AuthenticationError extends APIError {
+    name: string;
+}
+export declare class PlanLimitExceededError extends APIError {
+    name: string;
+}
+export declare class AuthorizationError extends APIError {
+    name: string;
+}
+export declare class NotFoundError extends APIError {
+    name: string;
+}
+export declare class ConflictError extends APIError {
+    name: string;
+}
+/** An `ifMatch` revision was not the current one: reload and try again. */
+export declare class PreconditionFailedError extends APIError {
+    name: string;
+    /** The resource's current revision, when the API reports it. */
+    get currentRevision(): number | undefined;
+}
+export declare class ValidationError extends APIError {
+    name: string;
+}
+export declare class RateLimitError extends APIError {
+    name: string;
+    /** Seconds to wait before retrying, from `Retry-After`. */
+    get retryAfter(): number | undefined;
+}
+export declare class InternalServerError extends APIError {
+    name: string;
+}
+export declare class ServiceUnavailableError extends APIError {
+    name: string;
+}
+/** The request never got a response: DNS, TLS, a reset connection. */
+export declare class ConnectionError extends NoheadError {
+    name: string;
+}
+/** An attempt took longer than the `timeout` option. */
+export declare class TimeoutError extends ConnectionError {
+    name: string;
+}
+/** The caller's `signal` aborted the request. */
+export declare class AbortError extends NoheadError {
+    name: string;
+}
+/** A presigned upload to storage failed (`assets.upload`). */
+export declare class UploadError extends NoheadError {
+    name: string;
+    /** Storage's HTTP status, when it answered. */
+    readonly status: number | undefined;
+    constructor(message: string, status?: number, options?: ErrorOptions);
+}
+/** A webhook request's signature or timestamp did not check out. */
+export declare class WebhookVerificationError extends NoheadError {
+    name: string;
+}
+/** The error for a response, by its `type`, or by status when it has none. */
+export declare function apiError(status: number, body: unknown, headers: Headers): APIError;
+export declare function retryAfterSeconds(headers: Headers): number | undefined;

package/dist/errors.js

@@ -0,0 +1,144 @@
+/** The base class of every error this SDK throws. */
+export class NoheadError extends Error {
+    name = "NoheadError";
+}
+/** The API answered with an error status. Subclasses follow the error `type`. */
+export class APIError extends NoheadError {
+    name = "APIError";
+    /** The HTTP status. */
+    status;
+    /** The error `type`, e.g. `validation_error`; undefined if the body had none. */
+    type;
+    /** The request's ID (`req_…`), for support requests and logs. */
+    requestId;
+    /** Field-level details, e.g. `[{ field: "title", code: "required", … }]`. */
+    details;
+    headers;
+    /** The parsed response body, or its text when it was not JSON. */
+    body;
+    constructor(status, body, headers) {
+        const error = errorEnvelope(body);
+        super(error?.message ?? `Request failed with status ${status}`);
+        this.status = status;
+        this.type = error?.type;
+        this.requestId =
+            error?.request_id ?? headers.get("x-request-id") ?? undefined;
+        this.details = error?.details ?? [];
+        this.headers = headers;
+        this.body = body;
+    }
+}
+export class InvalidRequestError extends APIError {
+    name = "InvalidRequestError";
+}
+export class AuthenticationError extends APIError {
+    name = "AuthenticationError";
+}
+export class PlanLimitExceededError extends APIError {
+    name = "PlanLimitExceededError";
+}
+export class AuthorizationError extends APIError {
+    name = "AuthorizationError";
+}
+export class NotFoundError extends APIError {
+    name = "NotFoundError";
+}
+export class ConflictError extends APIError {
+    name = "ConflictError";
+}
+/** An `ifMatch` revision was not the current one: reload and try again. */
+export class PreconditionFailedError extends APIError {
+    name = "PreconditionFailedError";
+    /** The resource's current revision, when the API reports it. */
+    get currentRevision() {
+        return this.details.find((d) => d.code === "revision_mismatch")
+            ?.current_revision;
+    }
+}
+export class ValidationError extends APIError {
+    name = "ValidationError";
+}
+export class RateLimitError extends APIError {
+    name = "RateLimitError";
+    /** Seconds to wait before retrying, from `Retry-After`. */
+    get retryAfter() {
+        return retryAfterSeconds(this.headers);
+    }
+}
+export class InternalServerError extends APIError {
+    name = "InternalServerError";
+}
+export class ServiceUnavailableError extends APIError {
+    name = "ServiceUnavailableError";
+}
+/** The request never got a response: DNS, TLS, a reset connection. */
+export class ConnectionError extends NoheadError {
+    name = "ConnectionError";
+}
+/** An attempt took longer than the `timeout` option. */
+export class TimeoutError extends ConnectionError {
+    name = "TimeoutError";
+}
+/** The caller's `signal` aborted the request. */
+export class AbortError extends NoheadError {
+    name = "AbortError";
+}
+/** A presigned upload to storage failed (`assets.upload`). */
+export class UploadError extends NoheadError {
+    name = "UploadError";
+    /** Storage's HTTP status, when it answered. */
+    status;
+    constructor(message, status, options) {
+        super(message, options);
+        this.status = status;
+    }
+}
+/** A webhook request's signature or timestamp did not check out. */
+export class WebhookVerificationError extends NoheadError {
+    name = "WebhookVerificationError";
+}
+const CLASSES = {
+    invalid_request: InvalidRequestError,
+    authentication_error: AuthenticationError,
+    plan_limit_exceeded: PlanLimitExceededError,
+    authorization_error: AuthorizationError,
+    not_found: NotFoundError,
+    conflict: ConflictError,
+    precondition_failed: PreconditionFailedError,
+    validation_error: ValidationError,
+    rate_limited: RateLimitError,
+    internal_error: InternalServerError,
+    service_unavailable: ServiceUnavailableError,
+};
+/** The error for a response, by its `type`, or by status when it has none. */
+export function apiError(status, body, headers) {
+    const type = errorEnvelope(body)?.type;
+    const Class = (type && CLASSES[type]) ||
+        (status === 503
+            ? ServiceUnavailableError
+            : status >= 500
+                ? InternalServerError
+                : APIError);
+    return new Class(status, body, headers);
+}
+export function retryAfterSeconds(headers) {
+    const value = headers.get("retry-after");
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds);
+    const date = Date.parse(value);
+    return Number.isNaN(date)
+        ? undefined
+        : Math.max(0, (date - Date.now()) / 1000);
+}
+function errorEnvelope(body) {
+    if (typeof body !== "object" || body === null || !("error" in body)) {
+        return undefined;
+    }
+    const error = body.error;
+    return typeof error === "object" && error !== null
+        ? error
+        : undefined;
+}