@forumulate/sdk 0.5.0 → 0.7.0

package/dist/index.js

@@ -14,50 +14,66 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ForumulateClient = exports.ForumulateError = exports.verifyWebhookSignature = void 0;
+exports.ForumulateClient = exports.API_VERSION = exports.rowsOf = exports.retryDelayMs = exports.SDK_VERSION = exports.ForumulateError = exports.constructWebhookEvent = exports.verifyWebhookSignature = void 0;
 __exportStar(require("./types"), exports);
 var webhooks_1 = require("./webhooks");
 Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhooks_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "constructWebhookEvent", { enumerable: true, get: function () { return webhooks_1.constructWebhookEvent; } });
 __exportStar(require("./content"), exports);
+__exportStar(require("./translations"), exports);
+var http_1 = require("./http");
+Object.defineProperty(exports, "ForumulateError", { enumerable: true, get: function () { return http_1.ForumulateError; } });
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return http_1.SDK_VERSION; } });
+Object.defineProperty(exports, "retryDelayMs", { enumerable: true, get: function () { return http_1.retryDelayMs; } });
+var pagination_1 = require("./pagination");
+Object.defineProperty(exports, "rowsOf", { enumerable: true, get: function () { return pagination_1.rowsOf; } });
+var operations_gen_1 = require("./operations.gen");
+Object.defineProperty(exports, "API_VERSION", { enumerable: true, get: function () { return operations_gen_1.API_VERSION; } });
 const content_1 = require("./content");
-/** Thrown for any non-2xx API response. Mirrors the API's error envelope. */
-class ForumulateError extends Error {
-    status;
-    code;
-    constructor(status, code, message) {
-        super(message);
-        this.status = status;
-        this.code = code;
-        this.name = 'ForumulateError';
-    }
-}
-exports.ForumulateError = ForumulateError;
-/**
- * Typed client for the Forumulate REST API.
- *
- * ```ts
- * const forumulate = new ForumulateClient({ baseUrl: 'https://forumulate.com/api', token: pat });
- * const { orgs } = await forumulate.orgs.list();
- *
- * // or, from FORUMULATE_TOKEN / FORUMULATE_URL:
- * const fromEnv = ForumulateClient.fromEnv();
- * ```
- */
+const translations_1 = require("./translations");
+const http_2 = require("./http");
+const pagination_2 = require("./pagination");
+const helpers_1 = require("./helpers");
+const operations_gen_2 = require("./operations.gen");
+const resources_1 = require("./resources");
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 class ForumulateClient {
-    baseUrl;
-    token;
-    credentials;
-    defaultHeaders;
-    _fetch;
+    transport;
+    apiVersion;
     constructor(opts) {
-        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
-        this.token = opts.token;
-        this.credentials = opts.credentials ?? false;
-        this.defaultHeaders = { ...(opts.headers ?? {}) };
         const f = opts.fetch ?? globalThis.fetch;
         if (!f)
             throw new Error('No fetch implementation available — pass one via options.fetch.');
-        this._fetch = f;
+        const headers = { ...(opts.headers ?? {}) };
+        const inBrowser = typeof globalThis.document !== 'undefined';
+        if (!inBrowser && !Object.keys(headers).some((k) => k.toLowerCase() === 'user-agent')) {
+            headers['User-Agent'] = opts.userAgent ?? `forumulate-sdk-js/${http_2.SDK_VERSION}`;
+        }
+        this.transport = {
+            baseUrl: opts.baseUrl.replace(/\/$/, ''),
+            token: opts.token,
+            credentials: opts.credentials ?? false,
+            headers,
+            fetch: f,
+            maxRetries: opts.maxRetries ?? 2,
+            autoIdempotencyKey: opts.autoIdempotencyKey ?? true,
+        };
+        this.apiVersion = opts.apiVersion;
+        // Generated namespaces are built on first touch: a client that only ever
+        // calls `blog` never allocates the other 1,800 closures.
+        for (const name of (0, resources_1.namespaceNames)()) {
+            if (Object.prototype.hasOwnProperty.call(this, name))
+                continue;
+            Object.defineProperty(this, name, {
+                configurable: true,
+                enumerable: true,
+                get: () => {
+                    const value = (0, resources_1.buildNamespace)(name, this.invoke);
+                    Object.defineProperty(this, name, { value, enumerable: true });
+                    return value;
+                },
+            });
+        }
     }
     /**
      * A client configured from the environment, by the same names the CLI and
@@ -85,74 +101,34 @@ class ForumulateClient {
             ...opts,
         });
     }
-    /** Low-level request. Exposed so callers can reach endpoints the typed helpers don't cover yet. */
-    async request(method, path, opts = {}) {
-        const url = new URL(this.baseUrl + path);
-        for (const [k, v] of Object.entries(opts.query ?? {})) {
-            if (v !== undefined)
-                url.searchParams.set(k, String(v));
-        }
-        /*
-         * 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 = { ...this.defaultHeaders };
-        if (this.token)
-            headers.Authorization = `Bearer ${this.token}`;
-        if (opts.body !== undefined)
-            headers['Content-Type'] = 'application/json';
-        Object.assign(headers, opts.headers ?? {});
-        const res = await this._fetch(url.toString(), {
-            method,
-            headers,
-            credentials: this.credentials ? 'include' : 'same-origin',
-            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-        });
-        if (opts.raw) {
-            if (!res.ok)
-                throw await this.toError(res);
-            return res;
-        }
-        const text = await res.text();
-        const json = text ? JSON.parse(text) : undefined;
-        if (!res.ok) {
-            const err = (json?.error ?? {});
-            throw new ForumulateError(res.status, err.code ?? 'error', err.message ?? res.statusText);
+    request(a, b, c) {
+        if (typeof b === 'string') {
+            return this.http(a, b, (c ?? {}));
         }
-        return json;
+        const route = (0, resources_1.routeTable)().byId.get(a);
+        if (!route)
+            return Promise.reject(new TypeError(`Unknown operationId "${a}"`));
+        return this.invoke(route, b);
+    }
+    paginate(operationId, args) {
+        const route = (0, resources_1.routeTable)().byId.get(operationId);
+        if (!route?.flags.includes('p'))
+            throw new TypeError(`"${operationId}" is not a paged operation`);
+        return this.invoke(route, args);
     }
     /**
-     * Fully-typed request against ANY endpoint in the OpenAPI spec.
+     * Fully-typed request against ANY endpoint in the OpenAPI spec, by path.
      *
-     * Where the ~30 hand-written helpers above cover the stable, ergonomic
-     * surface, `typed` covers the *whole* API: the generated `paths` interface
-     * (`src/schema.ts`, produced from `openapi.json`) infers the path params,
-     * query params, JSON body and success response for the `(method, path)` you
-     * pass, so every one of the 600+ routes gets types and autocomplete without a
-     * bespoke wrapper. Path templates like `/orgs/{orgId}/spaces` are filled from
-     * `init.params`.
+     * The generated `paths` interface (`src/schema.ts`, produced from
+     * `openapi.json`) infers the path params, query params, JSON body and success
+     * response for the `(method, path)` you pass. Path templates like
+     * `/orgs/{orgId}/spaces` are filled from `init.params`.
      *
      * ```ts
-     * // GET a list — path param is required and checked; response is typed.
      * const { spaces } = await forumulate.typed('get', '/orgs/{orgId}/spaces', {
-     *   params: { orgId }, query: { deleted: 'false', limit: '50', cursor: '' },
-     * });
-     *
-     * // POST with a body the spec knows the shape of.
-     * await forumulate.typed('post', '/orgs/{orgId}/spaces', {
-     *   params: { orgId },
-     *   body: { name: 'Docs', slug: 'docs', type: 'DOCS', visibility: 'PUBLIC' },
+     *   params: { orgId }, query: { limit: 50 },
      * });
      * ```
-     *
-     * Regenerate the types after an API change with
-     * `pnpm --filter @forumulate/sdk dump-spec` then
-     * `npx openapi-typescript packages/sdk/openapi.json -o src/schema.ts`.
      */
     typed(method, path, init) {
         const opts = (init ?? {});
@@ -162,7 +138,7 @@ class ForumulateClient {
                 concrete = concrete.replace(`{${k}}`, encodeURIComponent(String(v)));
             }
         }
-        return this.request(String(method).toUpperCase(), concrete, {
+        return this.http(String(method).toUpperCase(), concrete, {
             body: opts.body,
             query: opts.query,
             raw: opts.raw,
@@ -171,187 +147,52 @@ class ForumulateClient {
             headers: opts.headers,
         });
     }
-    async toError(res) {
-        let code = 'error';
-        let message = res.statusText;
+    /** The 0.5 door: no version stated unless the client pins one. */
+    http(method, path, opts = {}) {
+        return (0, http_2.send)(this.transport, { method, path, ...opts, version: this.apiVersion });
+    }
+    /** The generated door: path filled from the args, version always stated, lists iterable. */
+    invoke = (route, args) => {
+        let resolved;
         try {
-            const j = await res.json();
-            code = j?.error?.code ?? code;
-            message = j?.error?.message ?? message;
+            resolved = (0, resources_1.resolveArgs)(route, args);
         }
-        catch {
-            /* non-JSON body */
+        catch (err) {
+            return Promise.reject(err);
         }
-        return new ForumulateError(res.status, code, message);
-    }
-    // ── Identity ──────────────────────────────────────────────────────────────
-    auth = {
-        register: (input) => this.request('POST', '/auth/register', {
-            body: input,
-        }),
-        login: (input) => this.request('POST', '/auth/login', { body: input }),
-        me: () => this.request('GET', '/auth/me'),
-        /** Mint a Personal Access Token (requires an authenticated session). */
-        createToken: (input) => this.request('POST', '/pats', {
-            body: input,
-        }),
-    };
-    // ── Content libraries (headless CMS) — see ./content ───────────────────────
-    content = (0, content_1.contentApi)((method, path, opts) => this.request(method, path, opts));
-    // ── Organizations ─────────────────────────────────────────────────────────
-    orgs = {
-        list: () => this.request('GET', '/orgs'),
-        create: (input) => this.request('POST', '/orgs', { body: input }),
-    };
-    // ── Spaces & content ───────────────────────────────────────────────────────
-    spaces = {
-        list: (orgId) => this.request('GET', `/orgs/${orgId}/spaces`),
-        create: (orgId, input) => this.request('POST', `/orgs/${orgId}/spaces`, { body: input }),
-        createCollection: (orgId, spaceId, input) => this.request('POST', `/orgs/${orgId}/spaces/${spaceId}/collections`, { body: input }),
-        createPage: (orgId, spaceId, collectionId, input) => this.request('POST', `/orgs/${orgId}/spaces/${spaceId}/collections/${collectionId}/pages`, { body: input }),
-        setPageContent: (orgId, spaceId, pageId, input) => this.request('PUT', `/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}/content`, { body: input }),
-        publishPage: (orgId, spaceId, pageId) => this.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) => this.request('GET', `/orgs/${orgId}/spaces/${spaceId}/shape`),
-        set: (orgId, spaceId, patch) => this.request('PUT', `/orgs/${orgId}/spaces/${spaceId}/shape`, {
-            body: patch,
-        }),
-        applyPreset: (orgId, spaceId, name) => this.request('POST', `/orgs/${orgId}/spaces/${spaceId}/shape/presets/${name}`, {
-            body: {},
-        }),
-    };
-    items = {
-        create: (orgId, spaceId, input) => this.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 this.request('GET', `/orgs/${orgId}/spaces/${spaceId}/items`, { query });
-        },
-        get: (orgId, spaceId, itemId) => this.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) => this.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) => this.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) => this.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) => this.request('GET', `/orgs/${orgId}/spaces/${spaceId}/domains`),
-        add: (orgId, spaceId, input) => this.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) => this.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) => this.request('POST', `/orgs/${orgId}/spaces/${spaceId}/domains/${domainId}/activate`, { body: {} }),
-        /** What to configure, and what is still missing. */
-        setup: (orgId, spaceId, domainId) => this.request('GET', `/orgs/${orgId}/spaces/${spaceId}/domains/${domainId}/setup`),
-    };
-    // ── Webhooks ───────────────────────────────────────────────────────────────
-    webhooks = {
-        list: (orgId) => this.request('GET', `/orgs/${orgId}/webhooks`),
-        create: (orgId, input) => this.request('POST', `/orgs/${orgId}/webhooks`, { body: input }),
-    };
-    // ── Space snapshots (version history) ───────────────────────────────────────
-    snapshots = {
-        list: (orgId, spaceId) => this.request('GET', `/orgs/${orgId}/spaces/${spaceId}/snapshots`),
-        create: (orgId, spaceId, label) => this.request('POST', `/orgs/${orgId}/spaces/${spaceId}/snapshots`, {
-            body: { label },
-        }),
-        restore: (orgId, spaceId, id) => this.request('POST', `/orgs/${orgId}/spaces/${spaceId}/snapshots/${id}/restore`, { body: {} }),
-    };
-    // ── Community (forum topics) ────────────────────────────────────────────────
-    forum = {
-        listTopics: (orgId, spaceId, query = {}) => this.request('GET', `/orgs/${orgId}/spaces/${spaceId}/forum`, { query }),
-        createTopic: (orgId, spaceId, input) => this.request('POST', `/orgs/${orgId}/spaces/${spaceId}/forum`, {
-            body: input,
-        }),
-        reply: (orgId, spaceId, topicId, content) => this.request('POST', `/orgs/${orgId}/spaces/${spaceId}/forum/${topicId}/replies`, { body: { content } }),
-    };
-    // ── Search & analytics (org-level) ──────────────────────────────────────────
-    search = {
-        unified: (orgId, q, opts = {}) => this.request('GET', `/orgs/${orgId}/search`, {
-            query: { q, ...opts },
-        }),
-    };
-    analytics = {
-        orgEvents: (orgId, days) => this.request('GET', `/orgs/${orgId}/analytics/events`, {
-            query: days ? { days } : {},
-        }),
-    };
-    // ── Public reader (no auth required) ────────────────────────────────────────
-    public = {
-        getPage: (orgId, spaceId, pageId) => this.request('GET', `/public/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}`),
-        search: (orgId, spaceId, query) => this.request('GET', `/public/orgs/${orgId}/spaces/${spaceId}/search`, {
-            query: { q: query },
-        }),
-        listComments: (orgId, spaceId, pageId) => this.request('GET', `/public/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}/comments`),
-        postComment: (orgId, spaceId, pageId, input) => this.request('POST', `/public/orgs/${orgId}/spaces/${spaceId}/pages/${pageId}/comments`, { body: input }),
-        reactToComment: (orgId, spaceId, commentId, emoji) => this.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) => this.request('GET', `/public/orgs/${orgId}/spaces/${spaceId}/pdf`, { raw: true }),
+        const { query, ...rest } = resolved;
+        const kind = route.flags.includes('b') ? 'binary' : route.flags.includes('t') ? 'text' : 'json';
+        const fetchPage = (q) => (0, http_2.send)(this.transport, {
+            ...rest,
+            method: route.method,
+            query: q,
+            kind,
+            version: this.apiVersion ?? operations_gen_2.API_VERSION,
+        });
+        if (route.flags.includes('p'))
+            return (0, pagination_2.pagePromise)(fetchPage, query ?? {});
+        return fetchPage(query ?? {});
     };
+    ns(name, hw) {
+        return (0, resources_1.mergeNamespace)((0, resources_1.buildNamespace)(name, this.invoke), hw);
+    }
+    helpers = (0, helpers_1.positionalHelpers)((method, path, opts) => this.http(method, path, opts));
+    // ── Namespaces with 0.5 helpers laid over the generated methods ─────────────
+    auth = this.ns('auth', this.helpers.auth);
+    content = this.ns('content', (0, content_1.contentApi)((method, path, opts) => this.http(method, path, opts)));
+    /** Translations of every kind of piece, routed by space type — see ./translations. */
+    translations = (0, translations_1.translationsApi)((method, path, opts) => this.http(method, path, opts));
+    orgs = this.ns('orgs', this.helpers.orgs);
+    spaces = this.ns('spaces', this.helpers.spaces);
+    shapes = this.ns('shapes', this.helpers.shapes);
+    items = this.ns('items', this.helpers.items);
+    domains = this.ns('domains', this.helpers.domains);
+    webhooks = this.ns('webhooks', this.helpers.webhooks);
+    snapshots = this.ns('snapshots', this.helpers.snapshots);
+    forum = this.ns('forum', this.helpers.forum);
+    search = this.ns('search', this.helpers.search);
+    analytics = this.ns('analytics', this.helpers.analytics);
+    public = this.ns('public', this.helpers.public);
 }
 exports.ForumulateClient = ForumulateClient;
 //# sourceMappingURL=index.js.map