confluence.js 2.2.0-dev20260320072155 → 3.0.0

package/dist/core/apiObject.d.ts

@@ -0,0 +1,3 @@
+import { z, type ZodRawShape } from 'zod';
+export declare function apiObject<Shape extends ZodRawShape>(shape: Shape): z.ZodObject<{ -readonly [P in keyof Shape]: Shape[P]; }, z.core.$loose>;
+//# sourceMappingURL=apiObject.d.ts.map

package/dist/core/apiObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiObject.d.ts","sourceRoot":"","sources":["../../src/core/apiObject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAE1C,wBAAgB,SAAS,CAAC,KAAK,SAAS,WAAW,EAAE,KAAK,EAAE,KAAK,2EAEhE"}

package/dist/core/apiObject.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export function apiObject(shape) {
+    return z.object(shape).loose();
+}
+//# sourceMappingURL=apiObject.js.map

package/dist/core/apiObject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiObject.js","sourceRoot":"","sources":["../../src/core/apiObject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAoB,MAAM,KAAK,CAAC;AAE1C,MAAM,UAAU,SAAS,CAA4B,KAAY;IAC/D,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC;AACjC,CAAC"}

package/dist/core/bodyToFetchBody.d.ts

@@ -0,0 +1,12 @@
+export declare function bodyToFetchBody(body: unknown): BodyInit | AsyncIterable<unknown>;
+/**
+ * Whether to declare `application/json` for this request.
+ *
+ * Sent even when there is no body, for any method that could carry one. Some endpoints reject a bodyless `DELETE`
+ * with 415 unless the header is present — Jira's remote-link deletes do — and a `Content-Type` on an empty request is
+ * inert everywhere else. Binary and multipart bodies are excluded because they bring their own type, and `fetch` has
+ * to be left to set the multipart boundary itself.
+ */
+export declare function shouldSetJsonContentType(body: unknown, method?: string): boolean;
+export declare function requiresDuplex(body: unknown): boolean;
+//# sourceMappingURL=bodyToFetchBody.d.ts.map

package/dist/core/bodyToFetchBody.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyToFetchBody.d.ts","sourceRoot":"","sources":["../../src/core/bodyToFetchBody.ts"],"names":[],"mappings":"AAkCA,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAMhF;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAQhF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAIrD"}

package/dist/core/bodyToFetchBody.js

@@ -0,0 +1,60 @@
+function isAsyncIterable(value) {
+    if (value == null)
+        return false;
+    return typeof value[Symbol.asyncIterator] === 'function';
+}
+/**
+ * Whether the body carries its own encoding and must be handed to `fetch` untouched.
+ *
+ * A bare string is deliberately *not* one of these. These are JSON APIs, and the endpoints that take a lone string —
+ * an account id, a preference value — want it as a JSON string, quoted, under `application/json`. Treating it as a
+ * pre-encoded payload shipped it raw as `text/plain` and made those endpoints unreachable. Attachment content never
+ * arrives here as a string: the multipart builder normalizes it into `FormData` or a stream first.
+ */
+function isBinaryBody(body) {
+    if (typeof FormData !== 'undefined' && body instanceof FormData)
+        return true;
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams)
+        return true;
+    if (typeof Blob !== 'undefined' && body instanceof Blob)
+        return true;
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream)
+        return true;
+    if (typeof ArrayBuffer !== 'undefined' && body instanceof ArrayBuffer)
+        return true;
+    // Covers Node's Buffer too, which is a Uint8Array — naming it here would drag
+    // @types/node into the declaration and break browser consumers.
+    if (typeof ArrayBuffer !== 'undefined' && ArrayBuffer.isView(body))
+        return true;
+    if (isAsyncIterable(body))
+        return true;
+    return false;
+}
+export function bodyToFetchBody(body) {
+    if (isBinaryBody(body)) {
+        return body;
+    }
+    return JSON.stringify(body);
+}
+/**
+ * Whether to declare `application/json` for this request.
+ *
+ * Sent even when there is no body, for any method that could carry one. Some endpoints reject a bodyless `DELETE`
+ * with 415 unless the header is present — Jira's remote-link deletes do — and a `Content-Type` on an empty request is
+ * inert everywhere else. Binary and multipart bodies are excluded because they bring their own type, and `fetch` has
+ * to be left to set the multipart boundary itself.
+ */
+export function shouldSetJsonContentType(body, method) {
+    if (isBinaryBody(body))
+        return false;
+    if (body !== undefined && body !== null)
+        return true;
+    const verb = (method ?? 'GET').toUpperCase();
+    return verb !== 'GET' && verb !== 'HEAD';
+}
+export function requiresDuplex(body) {
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream)
+        return true;
+    return isAsyncIterable(body);
+}
+//# sourceMappingURL=bodyToFetchBody.js.map

package/dist/core/bodyToFetchBody.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyToFetchBody.js","sourceRoot":"","sources":["../../src/core/bodyToFetchBody.ts"],"names":[],"mappings":"AAAA,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IAEhC,OAAO,OAAQ,KAA8C,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,UAAU,CAAC;AACrG,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,IAAa;IACjC,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,IAAI,YAAY,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE7E,IAAI,OAAO,eAAe,KAAK,WAAW,IAAI,IAAI,YAAY,eAAe;QAAE,OAAO,IAAI,CAAC;IAE3F,IAAI,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,YAAY,IAAI;QAAE,OAAO,IAAI,CAAC;IAErE,IAAI,OAAO,cAAc,KAAK,WAAW,IAAI,IAAI,YAAY,cAAc;QAAE,OAAO,IAAI,CAAC;IAEzF,IAAI,OAAO,WAAW,KAAK,WAAW,IAAI,IAAI,YAAY,WAAW;QAAE,OAAO,IAAI,CAAC;IAEnF,8EAA8E;IAC9E,gEAAgE;IAChE,IAAI,OAAO,WAAW,KAAK,WAAW,IAAI,WAAW,CAAC,MAAM,CAAC,IAAuB,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnG,IAAI,eAAe,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,IAAyC,CAAC;IACnD,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAa,EAAE,MAAe;IACrE,IAAI,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAErC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAErD,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAE7C,OAAO,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,MAAM,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,IAAI,OAAO,cAAc,KAAK,WAAW,IAAI,IAAI,YAAY,cAAc;QAAE,OAAO,IAAI,CAAC;IAEzF,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}

package/dist/core/createClient.d.ts

@@ -0,0 +1,15 @@
+import type { ClientConfig } from './schemas/index.js';
+import type { Client } from './interfaces/index.js';
+/**
+ * Creates a low-level Confluence API client.
+ *
+ * The client carries only transport, auth and retry policy — it is version agnostic, so one instance drives both
+ * `confluence.js/v1` and `confluence.js/v2`.
+ *
+ * Prefer `createV1Client` / `createV2Client` from `confluence.js` unless you want the flat functions and a smaller
+ * bundle.
+ *
+ * @stable
+ */
+export declare function createClient(config: ClientConfig | Client): Client;
+//# sourceMappingURL=createClient.d.ts.map

package/dist/core/createClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createClient.d.ts","sourceRoot":"","sources":["../../src/core/createClient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAQ,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAuEpD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,MAAM,CAgNlE"}

package/dist/core/createClient.js

@@ -0,0 +1,235 @@
+import { bodyToFetchBody, requiresDuplex, shouldSetJsonContentType } from './bodyToFetchBody.js';
+import { createApiError, isNetworkError, SchemaMismatchError, toNetworkError, TRANSIENT_HTTP_STATUSES, } from './errors/index.js';
+import { BufferSchema } from './formData/index.js';
+import { buildUrlWithSearchParams } from './serializeSearchParams.js';
+import { clientConfigSchema } from './schemas/index.js';
+import { createOAuth2Manager } from './oauth/index.js';
+/**
+ * Whether this 401 means "missing scope" rather than "stale token".
+ *
+ * Reads a clone, so the body stays available for the error that gets thrown later.
+ */
+async function isScopeMismatchResponse(response) {
+    try {
+        return /scope does not match/i.test(await response.clone().text());
+    }
+    catch {
+        return false;
+    }
+}
+/** A `Client` is anything with `sendRequest`; a `ClientConfig` never has one. */
+function isClient(value) {
+    return typeof value.sendRequest === 'function';
+}
+/**
+ * Base64 for the Basic auth header, the same way in every runtime.
+ *
+ * `btoa` alone mangles anything outside Latin-1, so the string is encoded to UTF-8 bytes first — a credential may well
+ * hold non-ASCII. Verified byte-identical to `Buffer.from(…).toString('base64')`.
+ */
+function base64Encode(value) {
+    const bytes = new TextEncoder().encode(value);
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+async function getAuthHeaders(auth) {
+    if (auth.type === 'oauth2') {
+        // Handled by the manager, which owns refresh and expiry. Reaching here means
+        // the caller swapped in OAuth 2.0 through `getAuthOn401`, which cannot carry
+        // that state — so fall back to whatever static token was supplied.
+        return auth.accessToken ? { Authorization: `Bearer ${auth.accessToken}` } : {};
+    }
+    if (auth.type === 'basic') {
+        const encoded = base64Encode(`${auth.email}:${auth.apiToken}`);
+        return { Authorization: `Basic ${encoded}` };
+    }
+    if ('getToken' in auth) {
+        const token = await auth.getToken();
+        return { Authorization: `Bearer ${token}` };
+    }
+    return { Authorization: `Bearer ${auth.token}` };
+}
+/**
+ * Creates a low-level Confluence API client.
+ *
+ * The client carries only transport, auth and retry policy — it is version agnostic, so one instance drives both
+ * `confluence.js/v1` and `confluence.js/v2`.
+ *
+ * Prefer `createV1Client` / `createV2Client` from `confluence.js` unless you want the flat functions and a smaller
+ * bundle.
+ *
+ * @stable
+ */
+export function createClient(config) {
+    // Already a client: hand it straight back. This is what lets createV1Client and
+    // createV2Client share one instance — and with it one OAuth token. Building a
+    // client per factory would give each its own refresh cycle, and the first
+    // rotation would kill the other's refresh token.
+    if (isClient(config))
+        return config;
+    clientConfigSchema.parse(config);
+    const { host, auth, headers: configHeaders = {}, getAuthOn401, retry } = config;
+    const retryMaxAttempts = Math.max(1, retry?.maxAttempts ?? 1);
+    const retryInitialDelayMs = retry?.initialDelayMs ?? 500;
+    const retryBackoffFactor = retry?.backoffFactor ?? 2;
+    // One manager per client, so the refreshed token and the resolved cloud id are
+    // shared by every request instead of being rediscovered per call.
+    const oauth2Manager = auth?.type === 'oauth2' ? createOAuth2Manager(auth) : undefined;
+    return {
+        async sendRequest(requestConfig) {
+            const path = requestConfig.url.startsWith('/') ? requestConfig.url : `/${requestConfig.url}`;
+            // Under OAuth 2.0 the gateway URL wins over `host`: a 3LO token is rejected
+            // on the site's own domain, so honouring `host` there would only produce 401s.
+            const effectiveHost = oauth2Manager ? await oauth2Manager.getBaseUrl() : host;
+            const normalizedHost = effectiveHost && (effectiveHost.endsWith('/') ? effectiveHost.slice(0, -1) : effectiveHost);
+            const url = normalizedHost ? normalizedHost + path : requestConfig.url;
+            const fullUrl = buildUrlWithSearchParams(url, requestConfig.searchParams);
+            const rawBody = requestConfig.body;
+            const body = rawBody === undefined || rawBody === null ? undefined : bodyToFetchBody(rawBody);
+            const doRequest = async (authHeaders) => {
+                const headers = {
+                    Accept: 'application/json',
+                    ...(shouldSetJsonContentType(rawBody, requestConfig.method) ? { 'Content-Type': 'application/json' } : {}),
+                    ...authHeaders,
+                    ...configHeaders,
+                    ...requestConfig.headers,
+                };
+                const init = {
+                    method: requestConfig.method,
+                    headers: Object.keys(headers).length > 0 ? headers : undefined,
+                    body: body,
+                };
+                if (requiresDuplex(rawBody)) {
+                    init.duplex = 'half';
+                }
+                return fetch(fullUrl, init);
+            };
+            const currentAuthHeaders = async () => {
+                if (oauth2Manager)
+                    return { Authorization: await oauth2Manager.getAuthorizationHeader() };
+                return auth ? getAuthHeaders(auth) : {};
+            };
+            let derivedAuthHeaders = await currentAuthHeaders();
+            let response;
+            let delayMs = retryInitialDelayMs;
+            let networkAttempt = 0;
+            let reauthenticated = false;
+            // Retry loop: covers transport-layer failures (TLS/socket/DNS) and
+            // 502/503/504 upstream failures. Auth re-derivation on 401 happens once
+            // per response cycle, inside the loop, so a refreshed token survives
+            // subsequent transient retries.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional retry loop
+            while (true) {
+                try {
+                    response = await doRequest(derivedAuthHeaders);
+                }
+                catch (err) {
+                    // A bad URL also rejects here, as a TypeError with no code — wrapping it
+                    // keeps one catch surface, and `transient: false` keeps it out of retries.
+                    const networkError = isNetworkError(err) ? err : toNetworkError(err, fullUrl);
+                    if (networkAttempt + 1 < retryMaxAttempts && networkError.transient) {
+                        networkAttempt += 1;
+                        await new Promise(resolve => setTimeout(resolve, delayMs));
+                        delayMs = Math.round(delayMs * retryBackoffFactor);
+                        continue;
+                    }
+                    throw networkError;
+                }
+                // Re-authentication is attempted at most once per request: a second 401
+                // means the fresh credentials are themselves rejected, and retrying that
+                // forever would turn a bad token into an infinite loop.
+                //
+                // A missing scope also answers 401, and refreshing cannot mint a scope the
+                // app never asked for. Worse, each pointless refresh rotates the refresh
+                // token, so a loop of scope errors would churn credentials for nothing.
+                if (response.status === 401 && !reauthenticated && !(await isScopeMismatchResponse(response))) {
+                    if (oauth2Manager?.canRefresh()) {
+                        reauthenticated = true;
+                        await oauth2Manager.forceRefresh();
+                        derivedAuthHeaders = await currentAuthHeaders();
+                        continue;
+                    }
+                    if (getAuthOn401) {
+                        reauthenticated = true;
+                        derivedAuthHeaders = await getAuthHeaders(await getAuthOn401());
+                        continue;
+                    }
+                }
+                if (TRANSIENT_HTTP_STATUSES.has(response.status) && networkAttempt + 1 < retryMaxAttempts) {
+                    networkAttempt += 1;
+                    await new Promise(resolve => setTimeout(resolve, delayMs));
+                    delayMs = Math.round(delayMs * retryBackoffFactor);
+                    continue;
+                }
+                break;
+            }
+            if (!response.ok) {
+                const text = await response.text();
+                let detail = text;
+                try {
+                    detail = JSON.parse(text);
+                }
+                catch {
+                    //
+                }
+                throw createApiError(`Request failed: ${response.status} ${response.statusText}${text ? ` - ${text}` : ''}`, response.status, response.statusText, detail, response.headers);
+            }
+            const contentType = response.headers.get('content-type');
+            if (response.status === 204)
+                return undefined;
+            // A download endpoint says so with `BufferSchema`, and it is the only
+            // reliable signal: the response carries the *file's* content type, so
+            // `text/plain` is as legitimate for a download as `application/pdf` and
+            // sniffing the header cannot tell the two intents apart. Without this the
+            // body was dropped on the floor and every download resolved to `undefined`.
+            if (requestConfig.schema === BufferSchema) {
+                return BufferSchema.parse(new Uint8Array(await response.arrayBuffer()));
+            }
+            if (contentType && !contentType.includes('application/json')) {
+                // An endpoint that declares a schema and answers with something that is
+                // not JSON has broken its contract. Returning `undefined` here would
+                // hand back a value the caller's types say cannot occur, and the
+                // failure would surface far from the call that caused it.
+                if (requestConfig.schema) {
+                    throw new SchemaMismatchError(`Expected a JSON response to validate against the schema, got ${contentType}`, await response.text());
+                }
+                return undefined;
+            }
+            let data;
+            if (contentType?.includes('application/json')) {
+                const text = await response.text();
+                try {
+                    data = JSON.parse(text);
+                }
+                catch (e) {
+                    if (e instanceof SyntaxError) {
+                        // Confluence sometimes sends application/json Content-Type with a plain-text body
+                        data = text || undefined;
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+            else {
+                const text = await response.text();
+                data = text || undefined;
+            }
+            if (requestConfig.schema && data !== undefined) {
+                const parsed = requestConfig.schema.safeParse(data);
+                if (!parsed.success) {
+                    // The response parsed as JSON but is not the shape the endpoint
+                    // promises. Callers should not have to know zod is the validator to
+                    // catch this, so it arrives as the library's own error with the
+                    // validation issues preserved on `cause`.
+                    throw new SchemaMismatchError(`Response did not match the schema for ${requestConfig.method ?? 'GET'} ${requestConfig.url}`, JSON.stringify(data), { cause: parsed.error });
+                }
+                return parsed.data;
+            }
+            return data;
+        },
+    };
+}
+//# sourceMappingURL=createClient.js.map

package/dist/core/createClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createClient.js","sourceRoot":"","sources":["../../src/core/createClient.ts"],"names":[],"mappings":"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"}

package/dist/core/errors/apiError.d.ts

@@ -0,0 +1,104 @@
+import { ERROR_KINDS, type ErrorKind } from './kinds.js';
+export interface ApiErrorOptions {
+    /** The error that caused this one — a transport failure, a parse failure. */
+    cause?: unknown;
+}
+/**
+ * Thrown when Confluence returns a non-2xx HTTP response.
+ *
+ * The subclasses below cover the statuses worth branching on. Catch this one to catch them all, or a subclass — or use
+ * the predicates, which survive a duplicated install of this package.
+ *
+ * @stable
+ */
+export declare class ApiError extends Error {
+    readonly [ERROR_KINDS]: readonly ErrorKind[];
+    /** HTTP status. */
+    readonly status: number;
+    readonly statusText: string;
+    /** Atlassian's error payload, parsed when it was JSON and the raw text when it was not. */
+    readonly body: unknown;
+    constructor(message: string, status: number, statusText: string, body: unknown, options?: ApiErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * 401 — the credentials are missing, expired or rejected.
+ *
+ * @stable
+ */
+export declare class AuthError extends ApiError {
+    readonly [ERROR_KINDS]: readonly ErrorKind[];
+    constructor(message: string, statusText: string, body: unknown, options?: ApiErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * 401 with `Unauthorized; scope does not match` — the token is valid, but the app never asked for a scope this endpoint
+ * needs.
+ *
+ * A subclass of {@link AuthError} because it is still a 401, but worth its own type: refreshing the token cannot fix
+ * it, so the client does not try. The app needs the scope added in the developer console and the user has to consent
+ * again.
+ *
+ * Under 3LO this is also how the two API versions bite: v2 endpoints want granular scopes (`read:page:confluence`),
+ * v1 endpoints want classic ones (`read:confluence-content.all`). An app that holds only one family gets this error
+ * from the other.
+ *
+ * @stable
+ */
+export declare class ScopeError extends AuthError {
+    readonly [ERROR_KINDS]: readonly ErrorKind[];
+    constructor(message: string, statusText: string, body: unknown, options?: ApiErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * 403 — authenticated, but not allowed. Usually a Confluence permission rather than a scope.
+ *
+ * @stable
+ */
+export declare class ForbiddenError extends ApiError {
+    readonly [ERROR_KINDS]: readonly ErrorKind[];
+    constructor(message: string, statusText: string, body: unknown, options?: ApiErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * 404 — no such thing, or no permission to know it exists.
+ *
+ * Confluence returns 404 for both, deliberately: telling the two apart would leak the existence of restricted content.
+ *
+ * @stable
+ */
+export declare class NotFoundError extends ApiError {
+    readonly [ERROR_KINDS]: readonly ErrorKind[];
+    constructor(message: string, statusText: string, body: unknown, options?: ApiErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+export interface RateLimitErrorOptions extends ApiErrorOptions {
+    /** How long to wait before retrying, in ms, when Confluence said so. */
+    retryAfterMs?: number;
+}
+/**
+ * 429 — you are being rate limited.
+ *
+ * `retryAfterMs` carries Atlassian's own advice when the response included `Retry-After`. It is not retried for you:
+ * the right response to a rate limit is to slow the whole client down, which only your code can decide.
+ *
+ * @stable
+ */
+export declare class RateLimitError extends ApiError {
+    readonly [ERROR_KINDS]: readonly ErrorKind[];
+    /** Milliseconds to wait, from the `Retry-After` header. Undefined when the response did not say. */
+    readonly retryAfterMs?: number;
+    constructor(message: string, statusText: string, body: unknown, options?: RateLimitErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * 5xx — Confluence failed on its own side.
+ *
+ * @stable
+ */
+export declare class ServerError extends ApiError {
+    readonly [ERROR_KINDS]: readonly ErrorKind[];
+    constructor(message: string, status: number, statusText: string, body: unknown, options?: ApiErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+//# sourceMappingURL=apiError.d.ts.map

package/dist/core/errors/apiError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiError.d.ts","sourceRoot":"","sources":["../../../src/core/errors/apiError.ts"],"names":[],"mappings":"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"}

package/dist/core/errors/apiError.js

@@ -0,0 +1,136 @@
+import { ERROR_KINDS, hasErrorKind } from './kinds.js';
+/**
+ * Thrown when Confluence returns a non-2xx HTTP response.
+ *
+ * The subclasses below cover the statuses worth branching on. Catch this one to catch them all, or a subclass — or use
+ * the predicates, which survive a duplicated install of this package.
+ *
+ * @stable
+ */
+export class ApiError extends Error {
+    [ERROR_KINDS] = ['api'];
+    /** HTTP status. */
+    status;
+    statusText;
+    /** Atlassian's error payload, parsed when it was JSON and the raw text when it was not. */
+    body;
+    constructor(message, status, statusText, body, options) {
+        super(message, options);
+        this.name = 'ApiError';
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    static [Symbol.hasInstance](value) {
+        return hasErrorKind(value, 'api');
+    }
+}
+/**
+ * 401 — the credentials are missing, expired or rejected.
+ *
+ * @stable
+ */
+export class AuthError extends ApiError {
+    [ERROR_KINDS] = ['api', 'auth'];
+    constructor(message, statusText, body, options) {
+        super(message, 401, statusText, body, options);
+        this.name = 'AuthError';
+    }
+    static [Symbol.hasInstance](value) {
+        return hasErrorKind(value, 'auth');
+    }
+}
+/**
+ * 401 with `Unauthorized; scope does not match` — the token is valid, but the app never asked for a scope this endpoint
+ * needs.
+ *
+ * A subclass of {@link AuthError} because it is still a 401, but worth its own type: refreshing the token cannot fix
+ * it, so the client does not try. The app needs the scope added in the developer console and the user has to consent
+ * again.
+ *
+ * Under 3LO this is also how the two API versions bite: v2 endpoints want granular scopes (`read:page:confluence`),
+ * v1 endpoints want classic ones (`read:confluence-content.all`). An app that holds only one family gets this error
+ * from the other.
+ *
+ * @stable
+ */
+export class ScopeError extends AuthError {
+    [ERROR_KINDS] = ['api', 'auth', 'scope'];
+    constructor(message, statusText, body, options) {
+        super(message, statusText, body, options);
+        this.name = 'ScopeError';
+    }
+    static [Symbol.hasInstance](value) {
+        return hasErrorKind(value, 'scope');
+    }
+}
+/**
+ * 403 — authenticated, but not allowed. Usually a Confluence permission rather than a scope.
+ *
+ * @stable
+ */
+export class ForbiddenError extends ApiError {
+    [ERROR_KINDS] = ['api', 'forbidden'];
+    constructor(message, statusText, body, options) {
+        super(message, 403, statusText, body, options);
+        this.name = 'ForbiddenError';
+    }
+    static [Symbol.hasInstance](value) {
+        return hasErrorKind(value, 'forbidden');
+    }
+}
+/**
+ * 404 — no such thing, or no permission to know it exists.
+ *
+ * Confluence returns 404 for both, deliberately: telling the two apart would leak the existence of restricted content.
+ *
+ * @stable
+ */
+export class NotFoundError extends ApiError {
+    [ERROR_KINDS] = ['api', 'notFound'];
+    constructor(message, statusText, body, options) {
+        super(message, 404, statusText, body, options);
+        this.name = 'NotFoundError';
+    }
+    static [Symbol.hasInstance](value) {
+        return hasErrorKind(value, 'notFound');
+    }
+}
+/**
+ * 429 — you are being rate limited.
+ *
+ * `retryAfterMs` carries Atlassian's own advice when the response included `Retry-After`. It is not retried for you:
+ * the right response to a rate limit is to slow the whole client down, which only your code can decide.
+ *
+ * @stable
+ */
+export class RateLimitError extends ApiError {
+    [ERROR_KINDS] = ['api', 'rateLimit'];
+    /** Milliseconds to wait, from the `Retry-After` header. Undefined when the response did not say. */
+    retryAfterMs;
+    constructor(message, statusText, body, options) {
+        super(message, 429, statusText, body, options);
+        this.name = 'RateLimitError';
+        this.retryAfterMs = options?.retryAfterMs;
+    }
+    static [Symbol.hasInstance](value) {
+        return hasErrorKind(value, 'rateLimit');
+    }
+}
+/**
+ * 5xx — Confluence failed on its own side.
+ *
+ * @stable
+ */
+export class ServerError extends ApiError {
+    [ERROR_KINDS] = ['api', 'server'];
+    constructor(message, status, statusText, body, options) {
+        super(message, status, statusText, body, options);
+        this.name = 'ServerError';
+    }
+    static [Symbol.hasInstance](value) {
+        return hasErrorKind(value, 'server');
+    }
+}
+//# sourceMappingURL=apiError.js.map

package/dist/core/errors/apiError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiError.js","sourceRoot":"","sources":["../../../src/core/errors/apiError.ts"],"names":[],"mappings":"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"}

package/dist/core/errors/fromResponse.d.ts

@@ -0,0 +1,16 @@
+import { ApiError, type ApiErrorOptions } from './apiError.js';
+import { NetworkError } from './networkError.js';
+/** HTTP statuses that signal a recoverable upstream failure. The single source of truth for both retry paths. */
+export declare const TRANSIENT_HTTP_STATUSES: Set<number>;
+/** Whether a transport failure is worth retrying. Broken TLS sessions (`ERR_SSL_*`) count. */
+export declare function isTransientCode(code: string | undefined): boolean;
+/** Wrap whatever `fetch` rejected with into a `NetworkError`, preserving the original as `cause`. */
+export declare function toNetworkError(err: unknown, url: string): NetworkError;
+/**
+ * `Retry-After` in milliseconds. The header is either delta-seconds or an HTTP date; both are accepted, and anything
+ * else is ignored rather than guessed at.
+ */
+export declare function parseRetryAfter(header: string | null, now?: number): number | undefined;
+/** Build the error class that matches the status, so callers can branch on the type instead of the number. */
+export declare function createApiError(message: string, status: number, statusText: string, body: unknown, headers?: Headers, options?: ApiErrorOptions): ApiError;
+//# sourceMappingURL=fromResponse.d.ts.map

package/dist/core/errors/fromResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fromResponse.d.ts","sourceRoot":"","sources":["../../../src/core/errors/fromResponse.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EAOR,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAiBjD,iHAAiH;AACjH,eAAO,MAAM,uBAAuB,aAA2B,CAAC;AAsBhE,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAIjE;AAED,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAStE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CAY3F;AAeD,8GAA8G;AAC9G,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE,eAAe,GACxB,QAAQ,CA2BV"}