wellmarked 1.1.0

package/dist/cjs/models.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Typed response objects returned by the WellMarked SDK.
+ *
+ * These mirror the JSON shapes documented at https://api.wellmarked.io/docs.
+ *
+ * Response objects carry only the body fields documented in the API
+ * reference — they do not surface HTTP headers. Quota state lives on the
+ * account, so use `WellMarked.getUsage()` to read it.
+ */
+/**
+ * Per-article metadata returned with each extraction.
+ *
+ * `date` is the article's published date as a string (often `null` — not
+ * every page publishes one). `retrievedAt` is the timestamp at which
+ * WellMarked actually fetched the page, populated on every successful
+ * extraction. The two fields are independent.
+ */
+export interface ExtractionMeta {
+    url: string;
+    title: string | null;
+    author: string | null;
+    date: string | null;
+    retrievedAt: Date | null;
+}
+export declare function extractionMetaFromDict(data: Record<string, unknown>): ExtractionMeta;
+/** Result of `POST /extract`. */
+export interface ExtractResult {
+    markdown: string;
+    metadata: ExtractionMeta;
+    requestId: string;
+}
+export declare function extractResultFromResponse(body: Record<string, unknown>): ExtractResult;
+/**
+ * One entry in a bulk job's `results` list.
+ *
+ * On success, `markdown` and `metadata` are populated and `error` is null.
+ * On a per-URL failure, `markdown`/`metadata` are null and `error` carries
+ * an API error code (e.g. `target_timeout`).
+ */
+export interface BulkItem {
+    url: string;
+    markdown: string | null;
+    metadata: ExtractionMeta | null;
+    error: string | null;
+    /** True when the item completed successfully (no error + has markdown). */
+    readonly ok: boolean;
+}
+export declare function bulkItemFromDict(data: Record<string, unknown>): BulkItem;
+/** "queued" | "processing" | "done" */
+export type JobStatus = "queued" | "processing" | "done";
+/**
+ * Status of a bulk extraction job.
+ *
+ * Returned from both `POST /bulk` and `GET /bulk/{jobId}`. Also one of the
+ * two possible return types from the polymorphic `WellMarked.getJob` and
+ * `WellMarked.waitForJob` — use the `kind` discriminator (or a type guard)
+ * to distinguish from `CrawlJob` if you need to read crawl-specific fields.
+ */
+export interface BulkJob {
+    readonly kind: "bulk";
+    jobId: string;
+    status: JobStatus;
+    total: number;
+    completed: number;
+    results: BulkItem[];
+    createdAt: Date | null;
+    finishedAt: Date | null;
+    /** True when `status === "done"`. */
+    readonly done: boolean;
+}
+export declare function bulkJobFromResponse(body: Record<string, unknown>): BulkJob;
+/**
+ * One page in a crawl job's `results` list.
+ *
+ * Shape mirrors `BulkItem` with an added `depth` field showing how far
+ * from the root URL this page sits in the BFS.
+ */
+export interface CrawlItem {
+    url: string;
+    depth: number;
+    markdown: string | null;
+    metadata: ExtractionMeta | null;
+    error: string | null;
+    /** True when the page completed successfully (no error + has markdown). */
+    readonly ok: boolean;
+}
+export declare function crawlItemFromDict(data: Record<string, unknown>): CrawlItem;
+export type TruncatedReason = "page_cap_reached" | "quota_exhausted";
+/**
+ * Status of a crawl job. Returned from `POST /crawl` and `GET /crawl/{jobId}`.
+ *
+ * Two crawl-only fields:
+ *   - `truncated`        — true when the crawl stopped before exhausting
+ *                          the frontier (depth/page cap or quota).
+ *   - `truncatedReason`  — `"page_cap_reached"` | `"quota_exhausted"` |
+ *                          `null`.
+ */
+export interface CrawlJob {
+    readonly kind: "crawl";
+    jobId: string;
+    status: JobStatus;
+    total: number;
+    completed: number;
+    results: CrawlItem[];
+    truncated: boolean;
+    truncatedReason: TruncatedReason | null;
+    createdAt: Date | null;
+    finishedAt: Date | null;
+    /** True when `status === "done"`. */
+    readonly done: boolean;
+}
+export declare function crawlJobFromResponse(body: Record<string, unknown>): CrawlJob;
+/**
+ * Result of `GET /usage` — current-period quota state.
+ *
+ * This is the source of truth for rate-limit / quota information. The SDK
+ * does not surface `X-RateLimit-*` headers on extract/bulk responses;
+ * call `WellMarked.getUsage()` instead.
+ */
+export interface Usage {
+    plan: string;
+    period: string;
+    used: number;
+    limit: number;
+    remaining: number;
+}
+export declare function usageFromResponse(body: Record<string, unknown>): Usage;
+/**
+ * Result of `POST /keys/rotate`.
+ *
+ * `apiKey` is the new raw key — store it before discarding this object,
+ * there is no recovery flow. The previous key is invalidated the moment
+ * the rotation call returns 200.
+ */
+export interface RotatedKey {
+    apiKey: string;
+    rotatedAt: Date | null;
+}
+export declare function rotatedKeyFromResponse(body: Record<string, unknown>): RotatedKey;
+export declare function isBulkJob(job: BulkJob | CrawlJob): job is BulkJob;
+export declare function isCrawlJob(job: BulkJob | CrawlJob): job is CrawlJob;

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/version.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+exports.VERSION = "1.0.0";

package/dist/cjs/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "1.0.0";

package/dist/esm/client.d.ts

@@ -0,0 +1,173 @@
+/**
+ * WellMarked client.
+ *
+ * The client is a thin, typed wrapper around the HTTP API. All endpoint
+ * methods are async — there is no separate sync/async split as in the
+ * Python SDK because JavaScript I/O is async by default.
+ *
+ *     import { WellMarked } from "wellmarked";
+ *
+ *     const wm = new WellMarked({ apiKey: "wm_..." });
+ *     const result = await wm.extract("https://example.com/article");
+ *     console.log(result.markdown);
+ *
+ * The API key can also be passed via the `WELLMARKED_API_KEY` environment
+ * variable (Node.js), in which case `new WellMarked()` is enough.
+ */
+import { APIStatusError } from "./errors.js";
+import { type BulkJob, type CrawlJob, type ExtractResult, type RotatedKey, type Usage } from "./models.js";
+export interface WellMarkedOptions {
+    /**
+     * Your WellMarked API key (`wm_...`). Falls back to the
+     * `WELLMARKED_API_KEY` environment variable (Node.js only).
+     */
+    apiKey?: string;
+    /** API base URL. Override for testing. */
+    baseUrl?: string;
+    /** Per-request timeout, milliseconds. Defaults to 30000 (30s). */
+    timeoutMs?: number;
+    /**
+     * Bring your own `fetch`. Defaults to the global `fetch`. Useful for
+     * polyfills, custom agents/proxies, or test mocking.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Extra headers sent on every request — useful for adding an internal
+     * correlation id, a custom user agent suffix, etc.
+     *
+     * Authorization / Content-Type / Accept are reserved and silently
+     * ignored if passed (the SDK manages those itself).
+     */
+    headers?: Record<string, string>;
+}
+export interface ExtractOptions {
+    /**
+     * Use Playwright to render JS-heavy pages. Requires a Pro/Enterprise
+     * plan AND `ENABLE_JS_RENDERING=true` on the API instance.
+     */
+    renderJs?: boolean;
+}
+export interface BulkOptions {
+    renderJs?: boolean;
+}
+export interface CrawlOptions {
+    /** Max BFS depth from the root. Defaults to 1. Must be >= 0. */
+    depth?: number;
+    renderJs?: boolean;
+}
+export interface WaitForJobOptions {
+    /** Milliseconds to sleep between polls. Defaults to 2000. */
+    pollIntervalMs?: number;
+    /** Total ms to wait before timing out. `null` waits forever. Defaults to 300000 (5 min). */
+    timeoutMs?: number | null;
+}
+export declare class WellMarked {
+    private apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly extraHeaders;
+    constructor(options?: WellMarkedOptions);
+    /**
+     * Extract clean Markdown from a single URL.
+     *
+     * Throws:
+     *   - `RateLimitError`            — monthly plan limit reached.
+     *   - `UnprocessableEntityError`  — `no_content`, `target_timeout`, or
+     *                                   `js_rendering_disabled`.
+     *   - `AuthenticationError`       — missing or invalid API key.
+     */
+    extract(url: string, options?: ExtractOptions): Promise<ExtractResult>;
+    /**
+     * Submit a batch of URLs for concurrent extraction.
+     *
+     * Returns immediately with `status="queued"`. Poll with `getJob` or
+     * block with `waitForJob` to collect results.
+     *
+     * Throws:
+     *   - `PermissionDeniedError`     — `plan_not_supported` (Free tier).
+     *   - `UnprocessableEntityError`  — `bulk_cap_exceeded` (50 on Pro).
+     *   - `RateLimitError`            — would exceed remaining monthly quota.
+     */
+    bulk(urls: Iterable<string>, options?: BulkOptions): Promise<BulkJob>;
+    /**
+     * Polymorphic job lookup — works for both bulk and crawl jobs.
+     *
+     * Calls `GET /bulk/{jobId}` first, then inspects the response's `kind`
+     * discriminator field. If the job is actually a crawl, a second request
+     * to `GET /crawl/{jobId}` fetches the full crawl shape (with per-item
+     * depth and the truncated flags). Returns `BulkJob` or `CrawlJob`
+     * accordingly.
+     *
+     * Use `isCrawlJob(job)` (or check `job.kind === "crawl"`) to branch on
+     * crawl-specific behavior. The shared interface (`status`, `completed`,
+     * `total`, `results`, `done`) works on either type.
+     *
+     * Jobs are retained for 6 hours after completion.
+     */
+    getJob(jobId: string): Promise<BulkJob | CrawlJob>;
+    /**
+     * Block until a job reaches `status="done"` (or timeout). Works for both
+     * bulk and crawl jobs.
+     *
+     * The first call uses the polymorphic `getJob` to discover the job's
+     * kind. Subsequent polls go directly to the typed endpoint, so a crawl
+     * job only pays the dispatch round-trip once.
+     *
+     * Throws:
+     *   - `Error` with message "did not finish within ..." — the job didn't
+     *     finish before `timeoutMs` elapsed.
+     */
+    waitForJob(jobId: string, options?: WaitForJobOptions): Promise<BulkJob | CrawlJob>;
+    /**
+     * Crawl a site starting from `url`, BFS to `depth`.
+     *
+     * Returns immediately with `status="queued"`. Use `getJob` to poll, or
+     * `waitForJob` to block until done — both handle crawl and bulk jobIds
+     * transparently.
+     *
+     * Plan caps:
+     *   - Free        → `PermissionDeniedError` (`plan_not_supported`)
+     *   - Pro         → max depth 5, up to 1,000 pages per crawl
+     *   - Enterprise  → unlimited depth and pages
+     *
+     * Throws:
+     *   - `PermissionDeniedError`     — `plan_not_supported` (Free tier).
+     *   - `UnprocessableEntityError`  — `crawl_depth_exceeded`.
+     */
+    crawl(url: string, options?: CrawlOptions): Promise<CrawlJob>;
+    /**
+     * Add or replace a per-request header for the rest of this client's life.
+     *
+     * Authorization / Content-Type / Accept are reserved — calls that try
+     * to set those are silently ignored. To rotate the bearer token, use
+     * `rotateKey()`.
+     */
+    setHeader(name: string, value: string): void;
+    /** Remove a header previously added via `headers:` or `setHeader()`. */
+    removeHeader(name: string): void;
+    /**
+     * Return your usage for the current billing period.
+     *
+     * Does not count toward your monthly quota.
+     */
+    getUsage(): Promise<Usage>;
+    /**
+     * Mint a new API key. The current key is invalidated immediately.
+     *
+     * The new raw key is in the returned `apiKey` field — store it before
+     * discarding the result. There is no recovery flow.
+     *
+     * The client auto-swaps to the new key for subsequent requests.
+     *
+     * Does not count toward your monthly quota.
+     */
+    rotateKey(): Promise<RotatedKey>;
+    /**
+     * Internal: read the current API key. Exposed for tests.
+     * Not part of the public, semver-stable surface.
+     */
+    _getApiKey(): string;
+    private request;
+}
+export { APIStatusError };

package/dist/esm/client.js

@@ -0,0 +1,330 @@
+/**
+ * WellMarked client.
+ *
+ * The client is a thin, typed wrapper around the HTTP API. All endpoint
+ * methods are async — there is no separate sync/async split as in the
+ * Python SDK because JavaScript I/O is async by default.
+ *
+ *     import { WellMarked } from "wellmarked";
+ *
+ *     const wm = new WellMarked({ apiKey: "wm_..." });
+ *     const result = await wm.extract("https://example.com/article");
+ *     console.log(result.markdown);
+ *
+ * The API key can also be passed via the `WELLMARKED_API_KEY` environment
+ * variable (Node.js), in which case `new WellMarked()` is enough.
+ */
+import { APIConnectionError, APIStatusError, WellMarkedError, fromResponse, } from "./errors.js";
+import { bulkJobFromResponse, crawlJobFromResponse, extractResultFromResponse, rotatedKeyFromResponse, usageFromResponse, } from "./models.js";
+import { VERSION } from "./version.js";
+const DEFAULT_BASE_URL = "https://api.wellmarked.io";
+const DEFAULT_TIMEOUT_MS = 30000;
+const RESERVED_HEADERS = new Set([
+    "authorization",
+    "content-type",
+    "accept",
+]);
+function resolveApiKey(apiKey) {
+    if (apiKey)
+        return apiKey;
+    const env = typeof process !== "undefined" && process.env
+        ? process.env.WELLMARKED_API_KEY
+        : undefined;
+    if (env)
+        return env;
+    throw new Error("No API key provided. Pass apiKey: ... to the client or set the " +
+        "WELLMARKED_API_KEY environment variable. Generate a key at " +
+        "https://wellmarked.io.");
+}
+function defaultHeaders(apiKey) {
+    return {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": `wellmarked-js/${VERSION}`,
+    };
+}
+function mergeHeaders(apiKey, extra) {
+    const out = defaultHeaders(apiKey);
+    if (!extra)
+        return out;
+    for (const [k, v] of Object.entries(extra)) {
+        if (RESERVED_HEADERS.has(k.toLowerCase()))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class WellMarked {
+    constructor(options = {}) {
+        this.apiKey = resolveApiKey(options.apiKey);
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const f = options.fetch ?? (typeof fetch !== "undefined" ? fetch : undefined);
+        if (!f) {
+            throw new Error("No fetch implementation available. Pass `fetch:` to the client " +
+                "(undici, node-fetch, etc.) or upgrade to Node 18+.");
+        }
+        // Bind so `this` isn't lost when calling globalThis.fetch.
+        this.fetchImpl = f.bind(globalThis);
+        this.extraHeaders = {};
+        if (options.headers) {
+            for (const [k, v] of Object.entries(options.headers)) {
+                if (RESERVED_HEADERS.has(k.toLowerCase()))
+                    continue;
+                this.extraHeaders[k] = v;
+            }
+        }
+    }
+    // ── Endpoints ──────────────────────────────────────────────────────────────
+    /**
+     * Extract clean Markdown from a single URL.
+     *
+     * Throws:
+     *   - `RateLimitError`            — monthly plan limit reached.
+     *   - `UnprocessableEntityError`  — `no_content`, `target_timeout`, or
+     *                                   `js_rendering_disabled`.
+     *   - `AuthenticationError`       — missing or invalid API key.
+     */
+    async extract(url, options = {}) {
+        const body = await this.request("POST", "/extract", {
+            url,
+            render_js: options.renderJs === true,
+        });
+        return extractResultFromResponse(body);
+    }
+    /**
+     * Submit a batch of URLs for concurrent extraction.
+     *
+     * Returns immediately with `status="queued"`. Poll with `getJob` or
+     * block with `waitForJob` to collect results.
+     *
+     * Throws:
+     *   - `PermissionDeniedError`     — `plan_not_supported` (Free tier).
+     *   - `UnprocessableEntityError`  — `bulk_cap_exceeded` (50 on Pro).
+     *   - `RateLimitError`            — would exceed remaining monthly quota.
+     */
+    async bulk(urls, options = {}) {
+        const urlList = Array.from(urls);
+        if (urlList.length === 0) {
+            throw new Error("bulk() requires at least one URL.");
+        }
+        const body = await this.request("POST", "/bulk", {
+            urls: urlList,
+            render_js: options.renderJs === true,
+        });
+        return bulkJobFromResponse(body);
+    }
+    /**
+     * Polymorphic job lookup — works for both bulk and crawl jobs.
+     *
+     * Calls `GET /bulk/{jobId}` first, then inspects the response's `kind`
+     * discriminator field. If the job is actually a crawl, a second request
+     * to `GET /crawl/{jobId}` fetches the full crawl shape (with per-item
+     * depth and the truncated flags). Returns `BulkJob` or `CrawlJob`
+     * accordingly.
+     *
+     * Use `isCrawlJob(job)` (or check `job.kind === "crawl"`) to branch on
+     * crawl-specific behavior. The shared interface (`status`, `completed`,
+     * `total`, `results`, `done`) works on either type.
+     *
+     * Jobs are retained for 6 hours after completion.
+     */
+    async getJob(jobId) {
+        const body = (await this.request("GET", `/bulk/${jobId}`));
+        // /bulk/{id} answers for any jobId today (the endpoint just serializes
+        // results in the bulk shape regardless of stored job_type). The `kind`
+        // field tells us whether we got a bulk-shaped response of a crawl
+        // job; if so, re-fetch via /crawl/{id} for the proper shape.
+        if (body.kind === "crawl") {
+            const crawlBody = (await this.request("GET", `/crawl/${jobId}`));
+            return crawlJobFromResponse(crawlBody);
+        }
+        return bulkJobFromResponse(body);
+    }
+    /**
+     * Block until a job reaches `status="done"` (or timeout). Works for both
+     * bulk and crawl jobs.
+     *
+     * The first call uses the polymorphic `getJob` to discover the job's
+     * kind. Subsequent polls go directly to the typed endpoint, so a crawl
+     * job only pays the dispatch round-trip once.
+     *
+     * Throws:
+     *   - `Error` with message "did not finish within ..." — the job didn't
+     *     finish before `timeoutMs` elapsed.
+     */
+    async waitForJob(jobId, options = {}) {
+        const pollIntervalMs = options.pollIntervalMs ?? 2000;
+        const timeoutMs = options.timeoutMs === undefined ? 300000 : options.timeoutMs;
+        const deadline = timeoutMs === null ? null : Date.now() + timeoutMs;
+        let job = await this.getJob(jobId);
+        const isCrawl = job.kind === "crawl";
+        while (!job.done) {
+            if (deadline !== null && Date.now() >= deadline) {
+                throw new Error(`Job ${jobId} did not finish within ${timeoutMs}ms ` +
+                    `(last status: ${job.status}, ${job.completed}/${job.total})`);
+            }
+            await sleep(pollIntervalMs);
+            const path = isCrawl ? `/crawl/${jobId}` : `/bulk/${jobId}`;
+            const body = (await this.request("GET", path));
+            job = isCrawl ? crawlJobFromResponse(body) : bulkJobFromResponse(body);
+        }
+        return job;
+    }
+    /**
+     * Crawl a site starting from `url`, BFS to `depth`.
+     *
+     * Returns immediately with `status="queued"`. Use `getJob` to poll, or
+     * `waitForJob` to block until done — both handle crawl and bulk jobIds
+     * transparently.
+     *
+     * Plan caps:
+     *   - Free        → `PermissionDeniedError` (`plan_not_supported`)
+     *   - Pro         → max depth 5, up to 1,000 pages per crawl
+     *   - Enterprise  → unlimited depth and pages
+     *
+     * Throws:
+     *   - `PermissionDeniedError`     — `plan_not_supported` (Free tier).
+     *   - `UnprocessableEntityError`  — `crawl_depth_exceeded`.
+     */
+    async crawl(url, options = {}) {
+        const depth = options.depth ?? 1;
+        if (depth < 0) {
+            throw new Error("depth must be >= 0.");
+        }
+        const body = await this.request("POST", "/crawl", {
+            url,
+            depth,
+            render_js: options.renderJs === true,
+        });
+        return crawlJobFromResponse(body);
+    }
+    // ── Custom headers ─────────────────────────────────────────────────────────
+    /**
+     * Add or replace a per-request header for the rest of this client's life.
+     *
+     * Authorization / Content-Type / Accept are reserved — calls that try
+     * to set those are silently ignored. To rotate the bearer token, use
+     * `rotateKey()`.
+     */
+    setHeader(name, value) {
+        if (RESERVED_HEADERS.has(name.toLowerCase()))
+            return;
+        this.extraHeaders[name] = value;
+    }
+    /** Remove a header previously added via `headers:` or `setHeader()`. */
+    removeHeader(name) {
+        delete this.extraHeaders[name];
+    }
+    /**
+     * Return your usage for the current billing period.
+     *
+     * Does not count toward your monthly quota.
+     */
+    async getUsage() {
+        const body = await this.request("GET", "/usage");
+        return usageFromResponse(body);
+    }
+    /**
+     * Mint a new API key. The current key is invalidated immediately.
+     *
+     * The new raw key is in the returned `apiKey` field — store it before
+     * discarding the result. There is no recovery flow.
+     *
+     * The client auto-swaps to the new key for subsequent requests.
+     *
+     * Does not count toward your monthly quota.
+     */
+    async rotateKey() {
+        const body = await this.request("POST", "/keys/rotate");
+        const rotated = rotatedKeyFromResponse(body);
+        if (rotated.apiKey) {
+            this.apiKey = rotated.apiKey;
+        }
+        return rotated;
+    }
+    /**
+     * Internal: read the current API key. Exposed for tests.
+     * Not part of the public, semver-stable surface.
+     */
+    _getApiKey() {
+        return this.apiKey;
+    }
+    // ── Transport ──────────────────────────────────────────────────────────────
+    async request(method, path, json) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = mergeHeaders(this.apiKey, this.extraHeaders);
+        const init = { method, headers };
+        if (json !== undefined) {
+            init.body = JSON.stringify(json);
+        }
+        let controller = null;
+        let timer = null;
+        if (this.timeoutMs > 0 && typeof AbortController !== "undefined") {
+            controller = new AbortController();
+            init.signal = controller.signal;
+            timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(url, init);
+        }
+        catch (err) {
+            throw new APIConnectionError(`Could not reach the WellMarked API: ${stringifyError(err)}`, { cause: err });
+        }
+        finally {
+            if (timer !== null)
+                clearTimeout(timer);
+        }
+        let bodyText = "";
+        try {
+            bodyText = await response.text();
+        }
+        catch (err) {
+            throw new APIConnectionError(`Could not read API response body: ${stringifyError(err)}`, { cause: err });
+        }
+        let body = null;
+        if (bodyText.length > 0) {
+            try {
+                body = JSON.parse(bodyText);
+            }
+            catch {
+                body = null;
+            }
+        }
+        return parseResponse(response.status, body);
+    }
+}
+function parseResponse(statusCode, body) {
+    let requestId;
+    if (body && typeof body === "object") {
+        const rid = body.request_id;
+        if (typeof rid === "string")
+            requestId = rid;
+    }
+    if (statusCode >= 200 && statusCode < 300) {
+        if (body === null) {
+            // The API contract says every documented endpoint returns a JSON
+            // body on 2xx. A null body means the server broke that contract
+            // (or a middlebox stripped it); fail loudly rather than letting
+            // downstream parsing crash on `body.foo` of null.
+            throw new WellMarkedError(`API returned HTTP ${statusCode} with no JSON body. ` +
+                "This is a contract violation — please report it.", { statusCode });
+        }
+        return body;
+    }
+    throw fromResponse(statusCode, body, requestId);
+}
+function stringifyError(err) {
+    if (err instanceof Error) {
+        return `${err.name}: ${err.message}`;
+    }
+    return String(err);
+}
+// Re-export the APIStatusError type so consumers can narrow without
+// pulling from "./errors" directly.
+export { APIStatusError };