@forumulate/sdk 0.5.0 → 0.7.0

package/dist/helpers.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.positionalHelpers = positionalHelpers;
+const webhooks_1 = require("./webhooks");
+function positionalHelpers(request) {
+    return {
+        // ── Identity ──────────────────────────────────────────────────────────────
+        auth: {
+            // `register` and `login` were removed in 0.6: the Atlas cutover removed `/auth/register`
+            // and `/auth/login`, so both failed for every caller. Sign-in is Atlas (a browser
+            // flow); an integration authenticates with a Personal Access Token.
+            me: () => request('GET', '/auth/me'),
+            /** Mint a Personal Access Token (requires an authenticated session). */
+            createToken: (input) => request('POST', '/pats', {
+                body: input,
+            }),
+        },
+        // ── Organizations ─────────────────────────────────────────────────────────
+        orgs: {
+            list: () => request('GET', '/orgs'),
+            create: (input) => request('POST', '/orgs', { body: input }),
+        },
+        // ── Spaces & content ───────────────────────────────────────────────────────
+        spaces: {
+            list: (orgId) => request('GET', `/orgs/${orgId}/spaces`),
+            create: (orgId, input) => request('POST', `/orgs/${orgId}/spaces`, { body: input }),
+            createCollection: (orgId, spaceId, input) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/collections`, { body: input }),
+            createPage: (orgId, spaceId, collectionId, input) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/collections/${collectionId}/pages`, { body: input }),
+            setPageContent: (orgId, spaceId, pageId, input) => request('PUT', `/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}/content`, {
+                body: input,
+            }),
+            publishPage: (orgId, spaceId, pageId) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}/publish`, { body: {} }),
+        },
+        /**
+         * Shapes and pieces — the surface an agent works through.
+         *
+         * `shape` says what one piece of a space is made of and hands back JSON
+         * Schema; `items` writes one, whatever a piece happens to be in that space:
+         * a documentation page, a blog post, a release, an incident. The reply says
+         * which required sections are still empty, so an agent can create a piece,
+         * ask what it forgot, and close the gap.
+         */
+        shapes: {
+            get: (orgId, spaceId) => request('GET', `/orgs/${orgId}/spaces/${spaceId}/shape`),
+            set: (orgId, spaceId, patch) => request('PUT', `/orgs/${orgId}/spaces/${spaceId}/shape`, {
+                body: patch,
+            }),
+            applyPreset: (orgId, spaceId, name) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/shape/presets/${name}`, {
+                body: {},
+            }),
+        },
+        items: {
+            create: (orgId, spaceId, input) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/items`, {
+                body: input,
+            }),
+            /**
+             * What is in a space: how something finds a piece it has no words for.
+             *
+             * Pass `include: ['body']` to get content. Asking for `sections` ALONE is
+             * the trap: it is populated only for pieces written against a shape, so a
+             * space of free-form pages answers with empty objects and a sync carries
+             * nothing while reporting success. Every row says which field holds its
+             * content in `contentIn`.
+             *
+             * Any option here puts the response in its paged form, so `page` and
+             * `sync` come back — `page.total` is what a walk should check its own
+             * count against, and `sync.checkpoint` is what an incremental sync stores.
+             */
+            list: (orgId, spaceId, opts = {}) => {
+                // A bare number used to be the whole signature; keep it working.
+                const o = typeof opts === 'number' ? { limit: opts } : opts;
+                const query = {};
+                if (o.limit)
+                    query.limit = o.limit;
+                if (o.include?.length)
+                    query.include = o.include.join(',');
+                if (o.cursor)
+                    query.cursor = o.cursor;
+                if (o.updatedSince)
+                    query.updated_since = o.updatedSince;
+                if (o.includeDeleted)
+                    query.include_deleted = 'true';
+                if (o.fields?.length)
+                    query.fields = o.fields.join(',');
+                return request('GET', `/orgs/${orgId}/spaces/${spaceId}/items`, { query });
+            },
+            get: (orgId, spaceId, itemId) => request('GET', `/orgs/${orgId}/spaces/${spaceId}/items/${itemId}`),
+            /**
+             * Make it readable. Kinds that are live on creation say so and change nothing.
+             *
+             * `conformance` describes the piece AFTER publishing — which declared slots
+             * are filled and which are still missing — so an agent that has just made
+             * its work readable can tell a complete piece from one with holes in it
+             * without fetching it again. The server has always sent it and this type
+             * omitted it, so a TypeScript caller could not see the field the docs
+             * promise (E-11).
+             */
+            publish: (orgId, spaceId, itemId) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/items/${itemId}/publish`, { body: {} }),
+            /**
+             * Replace a piece's whole body — as markdown, or as blocks.
+             *
+             * The create door has always taken markdown and this one took blocks only,
+             * so "make it from this file" worked and "update it from the same file" did
+             * not. Both now; blocks win if a caller sends both.
+             */
+            setContent: (orgId, spaceId, itemId, input) => request('PUT', `/orgs/${orgId}/spaces/${spaceId}/items/${itemId}/content`, { body: input }),
+            /** Replace one named section. Idempotent — sending it twice writes it once. */
+            setSection: (orgId, spaceId, itemId, key, markdown) => request('PUT', `/orgs/${orgId}/spaces/${spaceId}/items/${itemId}/sections/${key}`, { body: { markdown } }),
+        },
+        /**
+         * The addresses a space answers at.
+         *
+         * Published because the question a customer asks about a custom domain —
+         * "why is it not live yet" — is answerable only from `verified`, `active` and
+         * the setup records, and the SDK could not reach any of them (DX-2). A failed
+         * verification is a 200 with `verified: false`: read the body, not the status.
+         */
+        domains: {
+            list: (orgId, spaceId) => request('GET', `/orgs/${orgId}/spaces/${spaceId}/domains`),
+            add: (orgId, spaceId, input) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/domains`, {
+                body: input,
+            }),
+            /** Re-run the ownership check. `activate: false` proves it without switching traffic. */
+            verify: (orgId, spaceId, domainId, activate = true) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/domains/${domainId}/verify`, { body: { activate } }),
+            /** Switch traffic to an address whose ownership is already proven. */
+            activate: (orgId, spaceId, domainId) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/domains/${domainId}/activate`, { body: {} }),
+            /** What to configure, and what is still missing. */
+            setup: (orgId, spaceId, domainId) => request('GET', `/orgs/${orgId}/spaces/${spaceId}/domains/${domainId}/setup`),
+        },
+        // ── Webhooks ───────────────────────────────────────────────────────────────
+        webhooks: {
+            list: (orgId) => request('GET', `/orgs/${orgId}/webhooks`),
+            create: (orgId, input) => request('POST', `/orgs/${orgId}/webhooks`, { body: input }),
+            /** Check a delivery's `X-Forumulate-Signature`; see {@link verifyWebhookSignature}. */
+            verifySignature: webhooks_1.verifyWebhookSignature,
+            /** Verify a delivery and parse it; throws when the signature does not hold. */
+            constructEvent: webhooks_1.constructWebhookEvent,
+        },
+        // ── Space snapshots (version history) ───────────────────────────────────────
+        snapshots: {
+            list: (orgId, spaceId) => request('GET', `/orgs/${orgId}/spaces/${spaceId}/snapshots`),
+            create: (orgId, spaceId, label) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/snapshots`, {
+                body: { label },
+            }),
+            restore: (orgId, spaceId, id) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/snapshots/${id}/restore`, { body: {} }),
+        },
+        // ── Community (forum topics) ────────────────────────────────────────────────
+        forum: {
+            listTopics: (orgId, spaceId, query = {}) => request('GET', `/orgs/${orgId}/spaces/${spaceId}/forum`, { query }),
+            createTopic: (orgId, spaceId, input) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/forum`, {
+                body: input,
+            }),
+            reply: (orgId, spaceId, topicId, content) => request('POST', `/orgs/${orgId}/spaces/${spaceId}/forum/${topicId}/replies`, { body: { content } }),
+        },
+        // ── Search & analytics (org-level) ──────────────────────────────────────────
+        search: {
+            unified: (orgId, q, opts = {}) => request('GET', `/orgs/${orgId}/search`, {
+                query: { q, ...opts },
+            }),
+        },
+        analytics: {
+            orgEvents: (orgId, days) => request('GET', `/orgs/${orgId}/analytics/events`, {
+                query: days ? { days } : {},
+            }),
+        },
+        // ── Public reader (no auth required) ────────────────────────────────────────
+        public: {
+            getPage: (orgId, spaceId, pageId) => request('GET', `/public/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}`),
+            search: (orgId, spaceId, query) => request('GET', `/public/orgs/${orgId}/spaces/${spaceId}/search`, {
+                query: { q: query },
+            }),
+            listComments: (orgId, spaceId, pageId) => request('GET', `/public/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}/comments`),
+            postComment: (orgId, spaceId, pageId, input) => request('POST', `/public/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}/comments`, { body: input }),
+            reactToComment: (orgId, spaceId, commentId, emoji) => request('POST', `/public/orgs/${orgId}/spaces/${spaceId}/comments/${commentId}/react`, { body: { emoji } }),
+            /** Download the whole space as a PDF. Returns the raw `Response` (read `.blob()` / `.arrayBuffer()`). */
+            pdf: (orgId, spaceId) => request('GET', `/public/orgs/${orgId}/spaces/${spaceId}/pdf`, { raw: true }),
+        },
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/http.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The one place a request leaves the SDK: headers, body encoding, retries,
+ * response decoding and the error type. Every surface — the positional
+ * helpers, `typed()`, `request(operationId)` and the generated namespaces —
+ * goes through `send`, so a retry or a header rule cannot apply to one door
+ * and not another.
+ */
+/** Kept in step with package.json by `coverage.test.ts`. */
+export declare const SDK_VERSION = "0.7.0";
+/** The API's error envelope: `{ error: { code, message, details? }, requestId? }`. */
+export interface ForumulateErrorInit {
+    /** Field-level detail, e.g. `{ title: ['Required'] }` for `validation.failed`. */
+    details?: unknown;
+    /** The id to quote in a support request; the API puts it on every error. */
+    requestId?: string;
+    /** Seconds the API asked us to wait (`Retry-After`), when it said. */
+    retryAfter?: number;
+    /** The parsed body, whole, for anything the fields above do not carry. */
+    body?: unknown;
+    /** The response headers of the failed request. */
+    headers?: Headers;
+    cause?: unknown;
+}
+/**
+ * Thrown for any non-2xx API response, and for a network failure that
+ * outlived its retries (`status: 0`, `code: 'network.error'`). Mirrors the
+ * API's error envelope.
+ */
+export declare class ForumulateError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    readonly requestId?: string;
+    readonly retryAfter?: number;
+    readonly body?: unknown;
+    readonly headers?: Headers;
+    constructor(status: number, code: string, message: string, init?: ForumulateErrorInit);
+}
+export type Query = Record<string, string | number | boolean | readonly (string | number)[] | undefined | null>;
+/** Per-call options every surface accepts. */
+export interface CallOptions {
+    /** Extra headers for this request; they win over the client's. */
+    headers?: Record<string, string>;
+    /**
+     * Makes a write safe to repeat: the API runs the first request with a key
+     * and replays its answer to any repeat for 24 hours. POST and PATCH get a
+     * generated one by default (reused across this call's own retries); pass
+     * yours to dedupe across processes, e.g. a queue message id.
+     */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+    /** Overrides the client's `maxRetries` for this call. */
+    maxRetries?: number;
+}
+export interface SendInit extends CallOptions {
+    method: string;
+    path: string;
+    query?: Query;
+    body?: unknown;
+    /** Return the untouched `Response` (binary downloads, streams). */
+    raw?: boolean;
+    /** How to read a 2xx body when it is not JSON. */
+    kind?: 'json' | 'text' | 'binary';
+    /** `Forumulate-Version` to send unless the caller already set one. */
+    version?: string;
+}
+export interface Transport {
+    baseUrl: string;
+    token?: string;
+    credentials: boolean;
+    headers: Record<string, string>;
+    fetch: typeof fetch;
+    maxRetries: number;
+    autoIdempotencyKey: boolean;
+}
+/**
+ * How long to wait before retry number `attempt` (0-based), or `null` to stop.
+ *
+ * `Retry-After` wins when present — seconds or an HTTP date — because the
+ * API sends it on purpose (a 429's window, a 503's batch interruption). Without
+ * it: exponential from 0.5s, capped at 8s, with jitter so a fleet of clients
+ * that failed together does not retry together.
+ */
+export declare function retryDelayMs(attempt: number, retryAfter: string | null | undefined, now?: number): number | null;
+export declare function send<T>(t: Transport, init: SendInit): Promise<T>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * The one place a request leaves the SDK: headers, body encoding, retries,
+ * response decoding and the error type. Every surface — the positional
+ * helpers, `typed()`, `request(operationId)` and the generated namespaces —
+ * goes through `send`, so a retry or a header rule cannot apply to one door
+ * and not another.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForumulateError = exports.SDK_VERSION = void 0;
+exports.retryDelayMs = retryDelayMs;
+exports.send = send;
+/** Kept in step with package.json by `coverage.test.ts`. */
+exports.SDK_VERSION = '0.7.0';
+/**
+ * Thrown for any non-2xx API response, and for a network failure that
+ * outlived its retries (`status: 0`, `code: 'network.error'`). Mirrors the
+ * API's error envelope.
+ */
+class ForumulateError extends Error {
+    status;
+    code;
+    details;
+    requestId;
+    retryAfter;
+    body;
+    headers;
+    constructor(status, code, message, init = {}) {
+        super(message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.status = status;
+        this.code = code;
+        this.name = 'ForumulateError';
+        this.details = init.details;
+        this.requestId = init.requestId;
+        this.retryAfter = init.retryAfter;
+        this.body = init.body;
+        this.headers = init.headers;
+    }
+}
+exports.ForumulateError = ForumulateError;
+/** 408, 429 and the gateway family. A 500 is not here: the API means it ("retrying will not help"). */
+const RETRY_STATUS = new Set([408, 429, 502, 503, 504]);
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
+/** A Retry-After longer than this is a "come back later", not a retry; surface it. */
+const MAX_RETRY_AFTER_MS = 60_000;
+const hasHeader = (h, name) => Object.keys(h).some((k) => k.toLowerCase() === name.toLowerCase());
+const isRawBody = (b) => (typeof FormData !== 'undefined' && b instanceof FormData) ||
+    (typeof Blob !== 'undefined' && b instanceof Blob) ||
+    (typeof URLSearchParams !== 'undefined' && b instanceof URLSearchParams) ||
+    (typeof ReadableStream !== 'undefined' && b instanceof ReadableStream) ||
+    b instanceof ArrayBuffer ||
+    ArrayBuffer.isView(b);
+function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return 'sdk-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 12);
+}
+/**
+ * How long to wait before retry number `attempt` (0-based), or `null` to stop.
+ *
+ * `Retry-After` wins when present — seconds or an HTTP date — because the
+ * API sends it on purpose (a 429's window, a 503's batch interruption). Without
+ * it: exponential from 0.5s, capped at 8s, with jitter so a fleet of clients
+ * that failed together does not retry together.
+ */
+function retryDelayMs(attempt, retryAfter, now = Date.now()) {
+    if (retryAfter != null && retryAfter.trim() !== '') {
+        const secs = Number(retryAfter);
+        const ms = Number.isFinite(secs) ? secs * 1000 : Date.parse(retryAfter) - now;
+        if (Number.isFinite(ms))
+            return ms > MAX_RETRY_AFTER_MS ? null : Math.max(0, ms);
+    }
+    return Math.min(500 * 2 ** attempt, 8000) * (1 - Math.random() * 0.25);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener?.('abort', () => {
+            clearTimeout(t);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}
+function buildUrl(base, path, query) {
+    const url = new URL(base + path);
+    for (const [k, v] of Object.entries(query ?? {})) {
+        if (v === undefined || v === null)
+            continue;
+        // Lists are comma-joined: `include=sections,body` is how the API reads them.
+        url.searchParams.set(k, Array.isArray(v) ? v.join(',') : String(v));
+    }
+    return url.toString();
+}
+async function decode(res, init) {
+    if (init.raw || init.kind === 'binary')
+        return res;
+    const text = await res.text();
+    if (init.kind === 'text')
+        return text;
+    if (!text)
+        return undefined;
+    const type = res.headers?.get?.('content-type') ?? '';
+    // No content type (a test double, an odd proxy) is read as JSON, as it always was.
+    if (!type || /json/i.test(type))
+        return JSON.parse(text);
+    return text;
+}
+async function toError(res) {
+    let body;
+    try {
+        const text = await res.text();
+        body = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        /* non-JSON body (an edge block page) */
+    }
+    const env = (body ?? {});
+    const after = res.headers?.get?.('retry-after');
+    const retryAfter = after != null && Number.isFinite(Number(after)) ? Number(after) : undefined;
+    return new ForumulateError(res.status, env.error?.code ?? 'error', env.error?.message ?? res.statusText, {
+        details: env.error?.details,
+        requestId: env.requestId ?? res.headers?.get?.('x-request-id') ?? undefined,
+        retryAfter,
+        body,
+        headers: res.headers,
+    });
+}
+async function send(t, init) {
+    const method = init.method.toUpperCase();
+    const url = buildUrl(t.baseUrl, init.path, init.query);
+    /*
+     * Ours first, the caller's last, so a per-request header wins.
+     *
+     * `Idempotency-Key` has to be per-REQUEST (a key reused across two
+     * different writes is worse than none), and `Forumulate-Version` is
+     * naturally per-client — so both layers exist and the narrower one
+     * overrides. `Content-Type` is set before the caller's so a multipart or
+     * ndjson body can correct it rather than be forced to JSON.
+     */
+    const headers = { ...t.headers };
+    if (t.token)
+        headers.Authorization = `Bearer ${t.token}`;
+    const raw = init.body !== undefined && isRawBody(init.body);
+    if (init.body !== undefined && !raw)
+        headers['Content-Type'] = 'application/json';
+    if (init.version &&
+        !hasHeader(headers, 'forumulate-version') &&
+        !hasHeader(init.headers ?? {}, 'forumulate-version')) {
+        headers['Forumulate-Version'] = init.version;
+    }
+    Object.assign(headers, init.headers ?? {});
+    if (init.idempotencyKey)
+        headers['Idempotency-Key'] = init.idempotencyKey;
+    else if (t.autoIdempotencyKey &&
+        (method === 'POST' || method === 'PATCH') &&
+        !hasHeader(headers, 'idempotency-key')) {
+        // Generated ONCE per call, so every retry of this call carries the same key.
+        headers['Idempotency-Key'] = newIdempotencyKey();
+    }
+    const retryable = SAFE_METHODS.has(method) || hasHeader(headers, 'idempotency-key');
+    const maxRetries = retryable ? Math.max(0, init.maxRetries ?? t.maxRetries) : 0;
+    const body = init.body === undefined ? undefined : raw ? init.body : JSON.stringify(init.body);
+    for (let attempt = 0;; attempt++) {
+        let res;
+        try {
+            res = await t.fetch(url, {
+                method,
+                headers,
+                credentials: t.credentials ? 'include' : 'same-origin',
+                body,
+                signal: init.signal,
+            });
+        }
+        catch (err) {
+            if (err?.name === 'AbortError' || init.signal?.aborted)
+                throw err;
+            const wait = attempt < maxRetries ? retryDelayMs(attempt, null) : null;
+            if (wait === null) {
+                throw new ForumulateError(0, 'network.error', err?.message ?? 'Network request failed', { cause: err });
+            }
+            await sleep(wait, init.signal);
+            continue;
+        }
+        if (res.ok)
+            return (await decode(res, init));
+        if (attempt < maxRetries && RETRY_STATUS.has(res.status)) {
+            const wait = retryDelayMs(attempt, res.headers?.get?.('retry-after'));
+            if (wait !== null) {
+                await res.text?.().catch(() => undefined);
+                await sleep(wait, init.signal);
+                continue;
+            }
+        }
+        throw await toError(res);
+    }
+}
+//# sourceMappingURL=http.js.map