@nohead/sdk 0.8.0 → 0.10.0

package/dist/core.js

@@ -1,16 +1,12 @@
 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 { AbortError, ConnectionError, NoheadError, TimeoutError, apiError, isObject, retryAfterSeconds, } from "./errors.js";
+import { OPERATIONS, RICH_TEXT_OPERATIONS, } from "./generated/operations.gen.js";
 import { VERSION } from "./version.js";
 export const DEFAULT_BASE_URL = "https://api.nohead.io";
-/**
- * The string with lone surrogates (half an emoji, from cutting a string)
- * replaced by U+FFFD, as `String.prototype.toWellFormed` does, so
- * `encodeURIComponent` can encode it.
- */
-const wellFormed = (text) => text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
 const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
 const MAX_RETRY_AFTER_SECONDS = 60;
+// Once per process, not per client: an app that makes a client per request
+// (as on Workers) would otherwise warn on every one.
 const warnedDeprecations = new Set();
 let warnedUsage = false;
 export class Core {
@@ -22,37 +18,54 @@ export class Core {
     #timeout;
     #warnings;
     #onRetry;
-    #projectId;
-    constructor(options) {
-        const env = environment();
-        // Empty environment variables count as unset.
-        const apiKey = options.apiKey ?? (env.NOHEAD_API_KEY || undefined);
+    #richText;
+    // The project lookup, shared with the client's copies (`withOptions`).
+    #project;
+    constructor(options, project = {}) {
+        // Empty options and environment variables count as unset.
+        const apiKey = options.apiKey || environment().NOHEAD_API_KEY;
         if (!apiKey) {
             throw new NoheadError("Missing API key: pass `apiKey` or set NOHEAD_API_KEY");
         }
         this.#apiKey = apiKey;
-        this.#baseUrl = withoutTrailingSlashes(options.baseUrl ?? (env.NOHEAD_API_URL || DEFAULT_BASE_URL));
+        this.#baseUrl = baseUrlOf(options.baseUrl || DEFAULT_BASE_URL);
         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;
+        this.#richText = options.richText;
+        this.#project = project;
         if (options.projectId)
-            this.#projectId = Promise.resolve(options.projectId);
+            project.id ??= Promise.resolve(options.projectId);
+    }
+    /** A copy with other settings, sharing the project lookup. */
+    withOptions(options) {
+        return new Core({
+            apiKey: this.#apiKey,
+            baseUrl: this.#baseUrl,
+            fetch: this.#fetch,
+            headers: { ...this.#headers, ...options.headers },
+            maxRetries: options.maxRetries ?? this.#maxRetries,
+            timeout: options.timeout ?? this.#timeout,
+            warnings: this.#warnings,
+            onRetry: options.onRetry ?? this.#onRetry,
+            richText: options.richText || this.#richText,
+        }, this.#project);
     }
     /** The API key's project, from `GET /v1/me` the first time. */
     projectId() {
-        this.#projectId ??= this.request("me_get", {}).then((me) => {
+        this.#project.id ??= 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;
+            this.#project.id = undefined;
             throw error;
         });
-        return this.#projectId;
+        return this.#project.id;
     }
     request(operation, input = {}, options = {}) {
         return new APIPromise(this.#send(operation, input, options));
@@ -63,21 +76,32 @@ export class Core {
             const query = { ...input.query, ...(cursor ? { cursor } : {}) };
             const result = await this.#send(operation, { ...input, query }, options);
             const list = result.data;
+            // A proxy's page, say, rather than the API's list.
+            if (!isObject(list) ||
+                !Array.isArray(list.data) ||
+                !isObject(list.meta)) {
+                throw new NoheadError(`The API's response could not be read (HTTP ${result.response.status})`);
+            }
             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. */
+    /**
+     * `fetch` with this client's retries, for an upload's presigned URL. fetch
+     * shows no upload progress, so each attempt may take as long as sending
+     * `byteSize` at 64 KiB/s, if that is longer than the timeout.
+     */
     async fetchWithRetries(url, init, options) {
         const maxRetries = options.retry
             ? (options.maxRetries ?? this.#maxRetries)
             : 0;
+        const timeout = Math.max(options.timeout ?? this.#timeout, (options.byteSize / 65_536) * 1000);
         for (let attempt = 0;; attempt++) {
             let failed;
             try {
-                const { response } = await this.#attempt(url, init, options, false);
+                const { response } = await this.#attempt(url, init, { ...options, timeout }, false);
                 if (!RETRYABLE_STATUSES.has(response.status) || attempt >= maxRetries) {
                     return response;
                 }
@@ -96,33 +120,44 @@ export class Core {
         const { method, path } = OPERATIONS[operation];
         const url = new URL(this.#baseUrl + (await this.#path(path, input.path)));
         appendQuery(url.searchParams, input.query);
-        const headers = {
+        // The call's, else the client's, and only where the operation takes it.
+        const richText = options.richText || this.#richText;
+        if (richText && RICH_TEXT_OPERATIONS.has(operation)) {
+            url.searchParams.set("rich_text", richText);
+        }
+        // Each name once, whatever its case: the defaults, then the client's
+        // headers, the call's, and those of the request options, which win.
+        const headers = {};
+        setHeaders(headers, {
             Accept: "application/json",
             Authorization: `Bearer ${this.#apiKey}`,
             "Nohead-Client": `sdk-typescript/${VERSION}`,
             ...USER_AGENT,
-            ...this.#headers,
-        };
+        });
+        setHeaders(headers, this.#headers);
+        setHeaders(headers, options.headers);
+        const own = {};
         if (input.body !== undefined)
-            headers["Content-Type"] = "application/json";
+            own["Content-Type"] = "application/json";
         if (method !== "GET") {
-            headers["Idempotency-Key"] = options.idempotencyKey ?? crypto.randomUUID();
+            own["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.ifMatch !== undefined && options.ifMatch !== null) {
+            own["If-Match"] = `"${revisionOf(options.ifMatch)}"`;
         }
         // Percent-encoded UTF-8: header values are bytes, and fetch refuses
-        // anything past Latin-1 (the API decodes it).
+        // anything past Latin-1 (the API decodes it). Lone surrogates (half an
+        // emoji, from cutting a string) become U+FFFD, so encodeURIComponent
+        // can encode them.
         if (options.changeNote)
-            headers["Nohead-Change-Note"] = encodeURIComponent(wellFormed(options.changeNote));
-        Object.assign(headers, options.headers);
+            own["Nohead-Change-Note"] = encodeURIComponent(options.changeNote.toWellFormed());
+        setHeaders(headers, own);
         const init = {
             method,
             headers,
-            body: input.body === undefined ? undefined : JSON.stringify(input.body),
+            body: input.body === undefined
+                ? undefined
+                : JSON.stringify(input.body, finiteNumbers),
         };
         const maxRetries = options.maxRetries ?? this.#maxRetries;
         for (let attempt = 0;; attempt++) {
@@ -154,14 +189,32 @@ export class Core {
         return sleep(delay, signal);
     }
     async #attempt(url, init, options, readBody) {
+        // The timeout is the longest wait for progress, so a response that
+        // keeps arriving never times out: the timer starts again when the
+        // response comes, and with each chunk of its body.
         const timeout = options.timeout ?? this.#timeout;
-        const timer = AbortSignal.timeout(timeout);
+        const timer = new AbortController();
+        let timeoutId;
+        const progress = () => {
+            clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => timer.abort(), timeout);
+        };
         const signal = options.signal
-            ? AbortSignal.any([options.signal, timer])
-            : timer;
+            ? AbortSignal.any([options.signal, timer.signal])
+            : timer.signal;
         try {
-            const response = await this.#fetch(url, { ...init, signal });
-            const body = readBody ? await parseBody(response) : undefined;
+            progress();
+            // Redirects aren't followed: one would send the API key to another
+            // host, or a write as a GET.
+            const response = await this.#fetch(url, {
+                ...init,
+                redirect: "manual",
+                signal,
+            });
+            progress();
+            const body = readBody
+                ? await parseBody(response, signal, progress)
+                : undefined;
             return { response, body };
         }
         catch (error) {
@@ -170,11 +223,14 @@ export class Core {
                     cause: options.signal.reason,
                 });
             }
-            if (timer.aborted) {
+            if (timer.signal.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 });
         }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     async #path(template, values = {}) {
         let path = template;
@@ -183,7 +239,7 @@ export class Core {
         for (const name of Object.keys(values))
             if (!names.includes(name))
                 throw new TypeError(`${name} is not a path parameter of ${template}`);
-        for (const [, name] of template.matchAll(/\{(\w+)\}/g)) {
+        for (const name of names) {
             let value = values[name];
             if (value === undefined && name === "project_id") {
                 value = await this.projectId();
@@ -191,6 +247,10 @@ export class Core {
             if (value === undefined || value === "") {
                 throw new NoheadError(`Missing ${name}`);
             }
+            // Encoding leaves these as they are, and URLs resolve them.
+            if (value === "." || value === "..") {
+                throw new NoheadError(`Invalid ${name}: "${value}"`);
+            }
             path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
         }
         return path;
@@ -249,8 +309,8 @@ function sleep(seconds, signal) {
         signal?.addEventListener("abort", aborted, { once: true });
     });
 }
-async function parseBody(response) {
-    const text = await response.text();
+async function parseBody(response, signal, progress) {
+    const text = await readText(response, signal, progress);
     if (!text)
         return undefined;
     if (!response.headers.get("content-type")?.includes("json"))
@@ -262,6 +322,31 @@ async function parseBody(response) {
         return text;
     }
 }
+/** The body's text, calling `progress` for each chunk that arrives. */
+async function readText(response, signal, progress) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    // A fetch ends the body when the signal aborts, but not every fetch is
+    // the platform's.
+    const cancel = () => void reader.cancel().catch(() => undefined);
+    signal.addEventListener("abort", cancel, { once: true });
+    const decoder = new TextDecoder();
+    let text = "";
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            signal.throwIfAborted();
+            if (done)
+                return text + decoder.decode();
+            progress();
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+    }
+}
 /**
  * Query parameters as the API reads them: objects become `key[sub]=…`
  * (`filter[price][lt]=50`), arrays are comma-separated (`expand=author,tags`)
@@ -308,12 +393,48 @@ function runtimeVersion() {
         return `node/${g.process.versions.node}`;
     return undefined;
 }
-/** `url` without trailing slashes; a loop, as a regex backtracks on long runs of them. */
-function withoutTrailingSlashes(url) {
+/** `url` without trailing slashes, if it is an http or https URL. */
+function baseUrlOf(url) {
+    // A loop, as a regex backtracks on long runs of slashes.
     let end = url.length;
     while (end > 0 && url[end - 1] === "/")
         end--;
-    return url.slice(0, end);
+    const base = url.slice(0, end);
+    let protocol;
+    try {
+        protocol = new URL(base).protocol;
+    }
+    catch {
+        // Not a URL at all.
+    }
+    if (protocol !== "http:" && protocol !== "https:") {
+        throw new NoheadError("baseUrl must be an http or https URL");
+    }
+    return base;
+}
+/** Sets each header, replacing one of the same name in any case. */
+function setHeaders(headers, values = {}) {
+    for (const [name, value] of Object.entries(values)) {
+        for (const key of Object.keys(headers))
+            if (key.toLowerCase() === name.toLowerCase())
+                delete headers[key];
+        headers[name] = value;
+    }
+}
+/** `ifMatch`'s revision: a number, or a record's or a draft's. */
+function revisionOf(ifMatch) {
+    const revision = isObject(ifMatch) ? ifMatch.revision : ifMatch;
+    if (!Number.isInteger(revision)) {
+        throw new TypeError("ifMatch takes a revision number, or a record, draft or object with a revision");
+    }
+    return revision;
+}
+// JSON has no NaN or Infinity, which JSON.stringify would send as null.
+function finiteNumbers(key, value) {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new TypeError(`JSON can't carry ${value}${key ? ` (in ${key})` : ""}`);
+    }
+    return value;
 }
 function environment() {
     const process = globalThis.process;

package/dist/errors.d.ts

@@ -3,7 +3,11 @@ import type { ErrorDetail, ErrorType } from "./generated/types.gen.ts";
 export declare class NoheadError extends Error {
     name: string;
 }
-/** The API answered with an error status. Subclasses follow the error `type`. */
+/**
+ * The API answered with an error status. Subclasses follow the error `type`.
+ * Its `message` names the status, the type and the request's ID along with
+ * the API's message: `422 validation_error: Title is required (request req_…)`.
+ */
 export declare class APIError extends NoheadError {
     name: string;
     /** The HTTP status. */
@@ -13,6 +17,8 @@ export declare class APIError extends NoheadError {
      * none. A type newer than this SDK is kept as its string.
      */
     readonly type: ErrorType | (string & {}) | undefined;
+    /** The API's own message, without the status, type and ID `message` adds. */
+    readonly apiMessage: string;
     /** The request's ID (`req_…`), for support requests and logs. */
     readonly requestId: string | undefined;
     /** Field-level details, e.g. `[{ field: "title", code: "required", … }]`. */
@@ -85,4 +91,10 @@ export declare class WebhookVerificationError extends NoheadError {
 }
 /** 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;
+/**
+ * `Retry-After` in seconds: a number of seconds (`120`, `1.5`), or an HTTP
+ * date. Anything else (`-1`, `1e3`, `0x10`, an ISO 8601 time) is undefined,
+ * as the Python and Ruby SDKs read it.
+ */
 export declare function retryAfterSeconds(headers: Headers): number | undefined;
+export declare const isObject: (value: unknown) => value is Record<string, unknown>;

package/dist/errors.js

@@ -2,7 +2,11 @@
 export class NoheadError extends Error {
     name = "NoheadError";
 }
-/** The API answered with an error status. Subclasses follow the error `type`. */
+/**
+ * The API answered with an error status. Subclasses follow the error `type`.
+ * Its `message` names the status, the type and the request's ID along with
+ * the API's message: `422 validation_error: Title is required (request req_…)`.
+ */
 export class APIError extends NoheadError {
     name = "APIError";
     /** The HTTP status. */
@@ -12,6 +16,8 @@ export class APIError extends NoheadError {
      * none. A type newer than this SDK is kept as its string.
      */
     type;
+    /** The API's own message, without the status, type and ID `message` adds. */
+    apiMessage;
     /** The request's ID (`req_…`), for support requests and logs. */
     requestId;
     /** Field-level details, e.g. `[{ field: "title", code: "required", … }]`. */
@@ -20,12 +26,17 @@ export class APIError extends NoheadError {
     /** 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}`);
+        // Below 400 (and not 2xx) is a redirect, which the SDK doesn't follow:
+        // `0` is a browser's, which shows nothing of it.
+        const error = status < 400 ? redirect(headers) : errorEnvelope(body);
+        const requestId = error?.request_id ?? headers.get("x-request-id") ?? undefined;
+        const apiMessage = error?.message || `Request failed with status ${status}`;
+        super(`${status} ${error?.type || "error"}: ${apiMessage}` +
+            (requestId ? ` (request ${requestId})` : ""));
         this.status = status;
+        this.apiMessage = apiMessage;
         this.type = error?.type;
-        this.requestId =
-            error?.request_id ?? headers.get("x-request-id") ?? undefined;
+        this.requestId = requestId;
         this.details = error?.details ?? [];
         this.headers = headers;
         this.body = body;
@@ -118,6 +129,8 @@ const CLASSES = new Map(Object.entries({
 }));
 /** The error for a response, by its `type`, or by status when it has none. */
 export function apiError(status, body, headers) {
+    if (status < 400)
+        return new APIError(status, body, headers);
     const type = errorEnvelope(body)?.type;
     const Class = (type && CLASSES.get(type)) ||
         (status === 503
@@ -127,18 +140,49 @@ export function apiError(status, body, headers) {
                 : APIError);
     return new Class(status, body, headers);
 }
+/**
+ * `Retry-After` in seconds: a number of seconds (`120`, `1.5`), or an HTTP
+ * date. Anything else (`-1`, `1e3`, `0x10`, an ISO 8601 time) is undefined,
+ * as the Python and Ruby SDKs read it.
+ */
 export function retryAfterSeconds(headers) {
-    const value = headers.get("retry-after");
+    const value = headers.get("retry-after")?.trim();
     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)
+    if (/^\d+(\.\d+)?$/.test(value))
+        return Number(value);
+    const date = httpDate(value);
+    return date === undefined
         ? undefined
         : Math.max(0, (date - Date.now()) / 1000);
 }
+// The three forms of an HTTP date (RFC 9110), all in GMT. Not Date.parse,
+// which takes more than these, and asctime's in the local time zone.
+const HTTP_DATES = [
+    // IMF-fixdate: Sun, 06 Nov 1994 08:49:37 GMT
+    /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (?<day>\d{2}) (?<month>\w{3}) (?<year>\d{4}) (?<time>\d{2}:\d{2}:\d{2}) GMT$/,
+    // RFC 850: Sunday, 06-Nov-94 08:49:37 GMT
+    /^(?:Mon|Tues|Wednes|Thurs|Fri|Satur|Sun)day, (?<day>\d{2})-(?<month>\w{3})-(?<year>\d{2}) (?<time>\d{2}:\d{2}:\d{2}) GMT$/,
+    // asctime: Sun Nov  6 08:49:37 1994
+    /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (?<month>\w{3}) (?<day>[ \d]\d) (?<time>\d{2}:\d{2}:\d{2}) (?<year>\d{4})$/,
+];
+const MONTHS = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
+/** An HTTP date in milliseconds, or undefined if `value` isn't one. */
+function httpDate(value) {
+    const date = HTTP_DATES.map((pattern) => pattern.exec(value)?.groups).find(Boolean);
+    const month = MONTHS.indexOf(date?.month ?? "");
+    if (!date || month < 0)
+        return undefined;
+    let year = Number(date.year);
+    // RFC 850's two digits: the latest such year not over 50 years ahead.
+    if (date.year.length === 2) {
+        year += 2000;
+        if (year > new Date().getUTCFullYear() + 50)
+            year -= 100;
+    }
+    const [hours, minutes, seconds] = date.time.split(":").map(Number);
+    return Date.UTC(year, month, Number(date.day), hours, minutes, seconds);
+}
 // The error envelope's fields that have the right type: a proxy or gateway
 // in front of the API may answer with any JSON.
 function errorEnvelope(body) {
@@ -149,10 +193,24 @@ function errorEnvelope(body) {
         type: typeof type === "string" ? type : undefined,
         message: typeof message === "string" ? message : undefined,
         request_id: typeof request_id === "string" ? request_id : undefined,
-        // Only objects: currentRevision reads each detail's fields.
-        details: Array.isArray(details)
-            ? details.filter(isObject)
-            : undefined,
+        details: Array.isArray(details) ? details.map(errorDetail) : undefined,
+    };
+}
+// A detail that isn't an object is kept as its text, so currentRevision can
+// read every detail's fields.
+function errorDetail(detail) {
+    if (isObject(detail) && !Array.isArray(detail))
+        return detail;
+    const message = typeof detail === "string" ? detail : JSON.stringify(detail);
+    return { code: "unknown", message: String(message) };
+}
+// A redirect's error: following one would send the API key elsewhere, or a
+// write as a GET.
+function redirect(headers) {
+    const location = headers.get("location");
+    return {
+        type: "redirect",
+        message: `The API answered with a redirect${location ? ` to ${location}` : ""}; check the base URL`,
     };
 }
-const isObject = (value) => typeof value === "object" && value !== null;
+export const isObject = (value) => typeof value === "object" && value !== null;

package/dist/generated/operations.gen.d.ts

@@ -326,6 +326,8 @@ export declare const OPERATIONS: {
     };
 };
 export type OperationId = keyof typeof OPERATIONS;
+/** The operations that take `rich_text`: those returning records or drafts. */
+export declare const RICH_TEXT_OPERATIONS: ReadonlySet<OperationId>;
 export interface Operations {
     assets_complete: {
         data: T.AssetsCompleteData;

package/dist/generated/operations.gen.js

@@ -81,3 +81,27 @@ export const OPERATIONS = {
     webhooks_test: { method: "POST", path: "/v1/webhooks/{webhook_id}/test" },
     webhooks_update: { method: "PATCH", path: "/v1/webhooks/{webhook_id}" },
 };
+/** The operations that take `rich_text`: those returning records or drafts. */
+export const RICH_TEXT_OPERATIONS = new Set([
+    "collections_search",
+    "drafts_create",
+    "drafts_discard",
+    "drafts_get",
+    "drafts_list",
+    "drafts_merge",
+    "drafts_schedule",
+    "drafts_unschedule",
+    "drafts_update",
+    "projects_search",
+    "record_drafts_list",
+    "record_revisions_revert",
+    "records_bulk",
+    "records_create",
+    "records_delete",
+    "records_get",
+    "records_list",
+    "records_publish",
+    "records_restore",
+    "records_unpublish",
+    "records_update",
+]);