@forumulate/sdk 0.4.0 → 0.7.0

package/dist/helpers.d.ts

@@ -0,0 +1,303 @@
+/**
+ * The positional helpers from 0.5 — `forumulate.spaces.create(orgId, input)`.
+ *
+ * They predate the generated namespaces and keep their signatures because
+ * code in the wild calls them. Each one wins its name inside its namespace
+ * (see `Merged` in resources.ts); every operation they do not cover is
+ * generated beside them. `coverage.test.ts` records which operation each one
+ * calls, so a helper cannot silently hide a different route.
+ */
+import type { Query } from './http';
+import { constructWebhookEvent, verifyWebhookSignature } from './webhooks';
+import type { Organization, Space, SpaceType, SpaceVisibility, Collection, Page, BlockDoc, SearchHit, UnifiedHit, Comment, Webhook, WebhookFormat, PublicPage, Conformance, DomainSetup, DomainSummary, Item, PageInfo, EffectiveShape, ShapeOverride } from './types';
+export type HelperRequest = <T>(method: string, path: string, opts?: {
+    body?: unknown;
+    query?: Query;
+    raw?: boolean;
+    headers?: Record<string, string>;
+}) => Promise<T>;
+export declare function positionalHelpers(request: HelperRequest): {
+    auth: {
+        me: () => Promise<{
+            user: {
+                id: string;
+                email: string;
+                name: string;
+            };
+        }>;
+        /** Mint a Personal Access Token (requires an authenticated session). */
+        createToken: (input: {
+            name: string;
+            scopes?: string[];
+        }) => Promise<{
+            token: string;
+            pat: {
+                id: string;
+                name: string;
+            };
+        }>;
+    };
+    orgs: {
+        list: () => Promise<{
+            orgs: Organization[];
+        }>;
+        create: (input: {
+            name: string;
+            slug: string;
+        }) => Promise<{
+            organization: Organization;
+        }>;
+    };
+    spaces: {
+        list: (orgId: string) => Promise<{
+            spaces: Space[];
+        }>;
+        create: (orgId: string, input: {
+            name: string;
+            slug: string;
+            type: SpaceType;
+            visibility: SpaceVisibility;
+        }) => Promise<{
+            space: Space;
+        }>;
+        createCollection: (orgId: string, spaceId: string, input: {
+            name: string;
+            slug: string;
+        }) => Promise<{
+            collection: Collection;
+        }>;
+        createPage: (orgId: string, spaceId: string, collectionId: string, input: {
+            title: string;
+            slug: string;
+        }) => Promise<{
+            page: Page;
+        }>;
+        setPageContent: (orgId: string, spaceId: string, pageId: string, input: {
+            title: string;
+            content: BlockDoc;
+        }) => Promise<{
+            page: Page;
+        }>;
+        publishPage: (orgId: string, spaceId: string, pageId: string) => Promise<{
+            page: Page;
+        }>;
+    };
+    /**
+     * 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: string, spaceId: string) => Promise<{
+            shape: EffectiveShape;
+            base: EffectiveShape;
+            presets: {
+                name: string;
+                label: string;
+                description: string;
+            }[];
+            jsonSchema: Record<string, unknown>;
+        }>;
+        set: (orgId: string, spaceId: string, patch: ShapeOverride) => Promise<{
+            shape: EffectiveShape;
+        }>;
+        applyPreset: (orgId: string, spaceId: string, name: string) => Promise<{
+            shape: EffectiveShape;
+        }>;
+    };
+    items: {
+        create: (orgId: string, spaceId: string, input: {
+            title: string;
+            slug?: string;
+            /** Which kind of piece, where the space holds more than one. */
+            preset?: string | null;
+            sections?: Record<string, string>;
+            body?: string;
+            params?: Record<string, unknown>;
+        }) => Promise<{
+            item: Item;
+        }>;
+        /**
+         * 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: string, spaceId: string, opts?: number | {
+            limit?: number;
+            include?: ("sections" | "body")[];
+            cursor?: string;
+            /** A `sync.checkpoint` from a previous walk, not a timestamp you made. */
+            updatedSince?: string;
+            includeDeleted?: boolean;
+            fields?: string[];
+        }) => Promise<{
+            items: Item[];
+            page?: PageInfo;
+            sync?: {
+                checkpoint: string;
+            };
+        }>;
+        get: (orgId: string, spaceId: string, itemId: string) => Promise<{
+            item: Item & {
+                sections: Record<string, string>;
+            };
+        }>;
+        /**
+         * 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: string, spaceId: string, itemId: string) => Promise<{
+            published: boolean;
+            note?: string;
+            conformance: Conformance;
+        }>;
+        /**
+         * 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: string, spaceId: string, itemId: string, input: {
+            body?: string;
+            content?: BlockDoc;
+        }) => Promise<{
+            conformance: Conformance;
+        }>;
+        /** Replace one named section. Idempotent — sending it twice writes it once. */
+        setSection: (orgId: string, spaceId: string, itemId: string, key: string, markdown: string) => Promise<{
+            conformance: Conformance;
+        }>;
+    };
+    /**
+     * 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: string, spaceId: string) => Promise<{
+            domains: DomainSummary[];
+        }>;
+        add: (orgId: string, spaceId: string, input: {
+            hostname: string;
+            basePath?: string;
+        }) => Promise<{
+            domain: DomainSummary;
+        }>;
+        /** Re-run the ownership check. `activate: false` proves it without switching traffic. */
+        verify: (orgId: string, spaceId: string, domainId: string, activate?: boolean) => Promise<{
+            domain: DomainSummary;
+        }>;
+        /** Switch traffic to an address whose ownership is already proven. */
+        activate: (orgId: string, spaceId: string, domainId: string) => Promise<{
+            domain: DomainSummary;
+        }>;
+        /** What to configure, and what is still missing. */
+        setup: (orgId: string, spaceId: string, domainId: string) => Promise<DomainSetup>;
+    };
+    webhooks: {
+        list: (orgId: string) => Promise<{
+            webhooks: Webhook[];
+        }>;
+        create: (orgId: string, input: {
+            url: string;
+            events: string[];
+            format?: WebhookFormat;
+        }) => Promise<{
+            webhook: Webhook;
+        }>;
+        /** Check a delivery's `X-Forumulate-Signature`; see {@link verifyWebhookSignature}. */
+        verifySignature: typeof verifyWebhookSignature;
+        /** Verify a delivery and parse it; throws when the signature does not hold. */
+        constructEvent: typeof constructWebhookEvent;
+    };
+    snapshots: {
+        list: (orgId: string, spaceId: string) => Promise<{
+            snapshots: unknown[];
+        }>;
+        create: (orgId: string, spaceId: string, label: string) => Promise<{
+            snapshot: unknown;
+        }>;
+        restore: (orgId: string, spaceId: string, id: string) => Promise<{
+            restored: number;
+            skipped: number;
+        }>;
+    };
+    forum: {
+        listTopics: (orgId: string, spaceId: string, query?: {
+            sort?: string;
+            category?: string;
+            page?: number;
+        }) => Promise<{
+            topics: unknown[];
+            hasMore?: boolean;
+        }>;
+        createTopic: (orgId: string, spaceId: string, input: {
+            title: string;
+            content: BlockDoc;
+            kind?: string;
+            tags?: string[];
+            categoryId?: string | null;
+        }) => Promise<{
+            topic: unknown;
+        }>;
+        reply: (orgId: string, spaceId: string, topicId: string, content: BlockDoc) => Promise<{
+            post: unknown;
+        }>;
+    };
+    search: {
+        unified: (orgId: string, q: string, opts?: {
+            type?: string;
+            limit?: number;
+        }) => Promise<{
+            hits: UnifiedHit[];
+        }>;
+    };
+    analytics: {
+        orgEvents: (orgId: string, days?: number) => Promise<unknown>;
+    };
+    public: {
+        getPage: (orgId: string, spaceId: string, pageId: string) => Promise<PublicPage>;
+        search: (orgId: string, spaceId: string, query: string) => Promise<{
+            hits: SearchHit[];
+        }>;
+        listComments: (orgId: string, spaceId: string, pageId: string) => Promise<{
+            comments: Comment[];
+        }>;
+        postComment: (orgId: string, spaceId: string, pageId: string, input: {
+            authorName: string;
+            body: string;
+            parentId?: string | null;
+        }) => Promise<{
+            comment: Comment;
+        }>;
+        reactToComment: (orgId: string, spaceId: string, commentId: string, emoji: string) => Promise<{
+            comment: Comment;
+        }>;
+        /** Download the whole space as a PDF. Returns the raw `Response` (read `.blob()` / `.arrayBuffer()`). */
+        pdf: (orgId: string, spaceId: string) => Promise<Response>;
+    };
+};
+export type PositionalHelpers = ReturnType<typeof positionalHelpers>;
+//# sourceMappingURL=helpers.d.ts.map

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