@forumulate/sdk 0.5.0 → 0.7.0

package/dist/translations.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Translations, across every kind of piece: `client.translations`.
+ *
+ * Each kind grew its own doors — a docs page's language twin, a post's or a
+ * release's `…/translations/{locale}`, an incident's — and a script that
+ * translated a release had to learn a second vocabulary for a page. These
+ * helpers say it once and route by the space's type, exactly as the CLI's
+ * `forumulate translations` and the MCP translation tools do:
+ *
+ *   locales   declare / relabel / remove a space's or a library's languages
+ *   status    one space's coverage: every piece × language → missing / draft /
+ *             published / outdated (`GET …/spaces/{spaceId}/translations`)
+ *   get/put/remove/auto   one piece's translation, whatever the piece is
+ *   labels    the site/space chrome dictionary (`…/i18n/labels`, `…/i18n/strings`)
+ *   overrides the org's UI string overrides and the public catalog
+ *
+ * Machine translation always uses the organization's OWN provider (its DeepL
+ * key; its AI provider for a library entry). There is no platform key, so a
+ * call without one is a 409 `ai.unavailable` — connect one with `deepl.connect`.
+ *
+ * Hand-written over `request`, like `./content`, because the generated
+ * `schema.ts` is refreshed from the DEPLOYED spec.
+ */
+type Request = <T>(method: string, path: string, opts?: {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}) => Promise<T>;
+/** A space or a content library — the two things that declare languages. */
+export type LocaleTarget = {
+    spaceId: string;
+} | {
+    libraryId: string;
+};
+export interface TranslationLocale {
+    code: string;
+    label: string;
+    /** The original language (`default` in a space; the library's `sourceLocale`). */
+    isSource: boolean;
+}
+export type TranslationState = 'missing' | 'draft' | 'published' | 'outdated';
+export type TranslationKind = 'page' | 'topic' | 'incident';
+/** Which door a piece's translation is behind (from the space's type). */
+export type TranslationDoor = 'page' | 'blog' | 'forum' | 'changelog' | 'incident';
+export interface TranslationCell {
+    state: TranslationState;
+    /** A docs page's language twin id (an item of its own); null for topics and incidents. */
+    id: string | null;
+    origin: 'human' | 'machine' | null;
+    updatedAt: string | null;
+}
+export interface TranslationCoverage {
+    spaceId: string;
+    spaceType: string;
+    kind: TranslationKind;
+    locales: {
+        code: string;
+        label: string;
+    }[];
+    items: {
+        id: string;
+        title: string;
+        slug: string | null;
+        kind: TranslationKind;
+        locales: Record<string, TranslationCell>;
+    }[];
+    totals: Record<string, Record<TranslationState, number>>;
+    truncated: boolean;
+}
+/** One piece's translation in one language, the same shape for every kind. */
+export interface PieceTranslation {
+    door: TranslationDoor;
+    locale: string;
+    state: TranslationState;
+    /** A page twin's own id; null otherwise. */
+    id: string | null;
+    title: string | null;
+    markdown: string | null;
+    /** A post's / release's summary line. */
+    excerpt?: string | null;
+    /** An incident's update texts, by update id. */
+    updates?: Record<string, string>;
+    origin: 'human' | 'machine' | null;
+}
+export interface PieceTranslationInput {
+    title?: string;
+    markdown?: string;
+    excerpt?: string;
+    updates?: Record<string, string>;
+    /** Serve it to readers. A page twin is published; a post's translation flagged. */
+    published?: boolean;
+}
+export interface AutoTranslateOptions {
+    /** Replace a translation a person wrote. Unset = 409. */
+    force?: boolean;
+    /** Publish what the machine wrote at once. Unset = a draft a person reads first. */
+    published?: boolean;
+}
+export type LabelScope = {
+    siteId: string;
+} | {
+    spaceId: string;
+};
+/** locale → original text → that language's words (plus `href` per link where set). */
+export type LabelDictionary = Record<string, Record<string, unknown>>;
+export type NamedTranslations = Record<string, {
+    name?: string;
+    description?: string;
+}>;
+export interface TranslationOverride {
+    locale: string;
+    key: string;
+    value: string;
+    updatedAt: string;
+}
+/** The door a space type keeps its pieces' translations behind. */
+export declare function translationDoorOf(spaceType: string): TranslationDoor;
+export declare function translationsApi(request: Request): {
+    locales: {
+        list: (orgId: string, target: LocaleTarget) => Promise<TranslationLocale[]>;
+        add: (orgId: string, target: LocaleTarget, input: {
+            code: string;
+            label: string;
+        }) => Promise<{
+            code: string;
+            label: string;
+            isSource: boolean;
+        }[]>;
+        /** Rename a language as the reader's switcher shows it. */
+        relabel: (orgId: string, target: LocaleTarget, code: string, label: string) => Promise<{
+            code: string;
+            label: string;
+            isSource: boolean;
+        }[]>;
+        remove: (orgId: string, target: LocaleTarget, code: string) => Promise<{
+            code: string;
+            label: string;
+            isSource: boolean;
+        }[]>;
+        /**
+         * Make the declared languages exactly `want` (the source excluded):
+         * adds what is missing, relabels what changed, removes what is not
+         * listed only when `prune` — removing a language trashes its
+         * translations, so it is never a side effect. Idempotent.
+         */
+        set: (orgId: string, target: LocaleTarget, want: {
+            code: string;
+            label: string;
+        }[], opts?: {
+            prune?: boolean;
+        }) => Promise<{
+            locales: TranslationLocale[];
+            added: string[];
+            relabeled: string[];
+            removed: string[];
+        }>;
+    };
+    /** Every piece × declared language of a space, in the four states. */
+    status: (orgId: string, spaceId: string) => Promise<TranslationCoverage>;
+    /** Each declared language and one piece's state in it (any kind). */
+    list: (orgId: string, spaceId: string, pieceId: string, opts?: {
+        door?: TranslationDoor;
+    }) => Promise<{
+        translations: unknown[];
+    }>;
+    /** One piece's translation, as Markdown, whatever the piece is. */
+    get: (orgId: string, spaceId: string, pieceId: string, locale: string, opts?: {
+        door?: TranslationDoor;
+    }) => Promise<PieceTranslation>;
+    /** Write or correct one piece's translation by hand (it becomes a person's). */
+    put: (orgId: string, spaceId: string, pieceId: string, locale: string, input: PieceTranslationInput, opts?: {
+        door?: TranslationDoor;
+    }) => Promise<PieceTranslation>;
+    /** Remove one piece's translation (a page twin goes to the trash). */
+    remove: (orgId: string, spaceId: string, pieceId: string, locale: string, opts?: {
+        door?: TranslationDoor;
+    }) => Promise<void>;
+    /** Machine-translate one piece with the org's own provider: `…/translations/{locale}/auto`. */
+    auto: (orgId: string, spaceId: string, pieceId: string, locale: string, opts?: AutoTranslateOptions & {
+        door?: TranslationDoor;
+    }) => Promise<{
+        translation: unknown;
+    }>;
+    /** A content library entry's machine translation (always a draft twin). */
+    autoEntry: (orgId: string, libraryId: string, entryId: string, locale: string, opts?: {
+        force?: boolean;
+    }) => Promise<{
+        locale: string;
+        results: {
+            entryId: string;
+            ok: boolean;
+            translationEntryId: string | null;
+            error: string | null;
+        }[];
+    }>;
+    /** Correct the language a piece is DECLARED to be written in (`PATCH …/items/{id}`). */
+    setItemLocale: (orgId: string, spaceId: string, itemId: string, locale: string | null) => Promise<{
+        item: {
+            id: string;
+            locale?: string | null;
+        };
+    }>;
+    /**
+     * Name translations: a space's (`settings.translations`) and a
+     * collection's. The API replaces the whole map on write, so `set` reads
+     * it first and changes one language — the other languages survive.
+     */
+    names: {
+        get: (orgId: string, spaceId: string, opts?: {
+            collectionId?: string;
+        }) => Promise<NamedTranslations>;
+        /** One language's name (and description); `null` removes that language. */
+        set: (orgId: string, spaceId: string, locale: string, words: {
+            name?: string;
+            description?: string;
+        } | null, opts?: {
+            collectionId?: string;
+        }) => Promise<NamedTranslations>;
+    };
+    /** A library entry's locale twin: its localized fields in one language. */
+    entryLocale: {
+        get: (orgId: string, libraryId: string, entryId: string, locale: string) => Promise<{
+            entryId: string;
+            locale: string;
+            fields: Record<string, unknown>;
+        }>;
+        /** Write the twin's DRAFT (made from the source when missing). */
+        put: (orgId: string, libraryId: string, entryId: string, locale: string, fields: Record<string, unknown>) => Promise<{
+            locale: string;
+            sourceEntryId: string;
+            entryId: string;
+            created: boolean;
+        }>;
+    };
+    /** The site/space chrome dictionary: every owner-written word, per language. */
+    labels: {
+        strings: (orgId: string, scope: LabelScope) => Promise<{
+            languages: string[];
+            labels: LabelDictionary;
+            strings: unknown[];
+            coverage: Record<string, {
+                translated: number;
+                total: number;
+            }>;
+        }>;
+        /** Replace the whole dictionary. */
+        replace: (orgId: string, scope: LabelScope, labels: LabelDictionary) => Promise<{
+            labels: LabelDictionary;
+        }>;
+        /** Merge word by word; `null` removes a word or a language. */
+        merge: (orgId: string, scope: LabelScope, labels: Record<string, Record<string, unknown> | null>) => Promise<{
+            labels: LabelDictionary;
+        }>;
+    };
+    /** The organization's own wording for our interface strings, per locale. */
+    overrides: {
+        list: (orgId: string, locale?: string) => Promise<{
+            overrides: TranslationOverride[];
+        }>;
+        set: (orgId: string, input: {
+            locale: string;
+            key: string;
+            value: string;
+        }) => Promise<{
+            override: TranslationOverride;
+        }>;
+        remove: (orgId: string, input: {
+            locale: string;
+            key: string;
+        }) => Promise<{
+            ok: true;
+        }>;
+        /** Every key a reader page can show and the English it replaces (public). */
+        catalog: (orgId: string) => Promise<{
+            catalog: Record<string, string>;
+        }>;
+        /** The overrides readers in one locale are served (public). */
+        forLocale: (orgId: string, locale: string) => Promise<{
+            overrides: Record<string, string>;
+        }>;
+    };
+    /** The org-wide default for the reader's language switcher. */
+    switcher: {
+        get: (orgId: string) => Promise<Record<string, unknown>>;
+        set: (orgId: string, config: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    };
+    /** The org's own DeepL key — what every `auto` uses. */
+    deepl: {
+        status: (orgId: string) => Promise<{
+            configured: boolean;
+        }>;
+        connect: (orgId: string, apiKey: string) => Promise<{
+            ok: true;
+        }>;
+        disconnect: (orgId: string) => Promise<{
+            ok: true;
+        }>;
+    };
+};
+export type TranslationsApi = ReturnType<typeof translationsApi>;
+export {};
+//# sourceMappingURL=translations.d.ts.map

package/dist/translations.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * Translations, across every kind of piece: `client.translations`.
+ *
+ * Each kind grew its own doors — a docs page's language twin, a post's or a
+ * release's `…/translations/{locale}`, an incident's — and a script that
+ * translated a release had to learn a second vocabulary for a page. These
+ * helpers say it once and route by the space's type, exactly as the CLI's
+ * `forumulate translations` and the MCP translation tools do:
+ *
+ *   locales   declare / relabel / remove a space's or a library's languages
+ *   status    one space's coverage: every piece × language → missing / draft /
+ *             published / outdated (`GET …/spaces/{spaceId}/translations`)
+ *   get/put/remove/auto   one piece's translation, whatever the piece is
+ *   labels    the site/space chrome dictionary (`…/i18n/labels`, `…/i18n/strings`)
+ *   overrides the org's UI string overrides and the public catalog
+ *
+ * Machine translation always uses the organization's OWN provider (its DeepL
+ * key; its AI provider for a library entry). There is no platform key, so a
+ * call without one is a 409 `ai.unavailable` — connect one with `deepl.connect`.
+ *
+ * Hand-written over `request`, like `./content`, because the generated
+ * `schema.ts` is refreshed from the DEPLOYED spec.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translationDoorOf = translationDoorOf;
+exports.translationsApi = translationsApi;
+const enc = encodeURIComponent;
+/** The door a space type keeps its pieces' translations behind. */
+function translationDoorOf(spaceType) {
+    switch (spaceType) {
+        case 'BLOG':
+            return 'blog';
+        case 'FORUM':
+            return 'forum';
+        case 'CHANGELOG':
+            return 'changelog';
+        case 'STATUS':
+            return 'incident';
+        default:
+            return 'page';
+    }
+}
+function translationsApi(request) {
+    const space = (orgId, spaceId) => `/orgs/${orgId}/spaces/${spaceId}`;
+    const library = (orgId, libraryId) => `/orgs/${orgId}/content/libraries/${libraryId}`;
+    const localesAt = (orgId, t) => 'libraryId' in t ? `${library(orgId, t.libraryId)}/locales` : `${space(orgId, t.spaceId)}/docs/locales`;
+    const labelsAt = (orgId, s) => 'siteId' in s ? `/orgs/${orgId}/sites/${s.siteId}/i18n` : `${space(orgId, s.spaceId)}/i18n`;
+    /** Both answers as one list: a space's has `default`, a library's `source`. */
+    const normalize = (r) => r.locales.map((l) => ({ code: l.code, label: l.label, isSource: Boolean(l.isDefault ?? l.source) }));
+    const doorOf = async (orgId, spaceId, door) => {
+        if (door)
+            return door;
+        const { space: s } = await request('GET', space(orgId, spaceId));
+        return translationDoorOf(s.type);
+    };
+    const collection = (orgId, spaceId, door, pieceId) => door === 'incident'
+        ? `${space(orgId, spaceId)}/status/incidents/${pieceId}/translations`
+        : door === 'page'
+            ? `${space(orgId, spaceId)}/pages/${pieceId}/translations`
+            : `${space(orgId, spaceId)}/${door}/${pieceId}/translations`;
+    const pageRow = async (orgId, spaceId, pageId, locale) => {
+        const { translations } = await request('GET', collection(orgId, spaceId, 'page', pageId));
+        const row = translations.find((r) => r.code.toLowerCase() === locale.toLowerCase());
+        if (!row)
+            throw Object.assign(new Error(`"${locale}" is not a language of this space.`), { status: 404 });
+        return row;
+    };
+    const topicState = (t) => !t.exists ? 'missing' : t.stale ? 'outdated' : t.published ? 'published' : 'draft';
+    const api = {
+        locales: {
+            list: async (orgId, target) => normalize(await request('GET', localesAt(orgId, target))),
+            add: async (orgId, target, input) => normalize(await request('POST', localesAt(orgId, target), { body: input })),
+            /** Rename a language as the reader's switcher shows it. */
+            relabel: async (orgId, target, code, label) => normalize(await request('PATCH', `${localesAt(orgId, target)}/${enc(code)}`, { body: { label } })),
+            remove: async (orgId, target, code) => normalize(await request('DELETE', `${localesAt(orgId, target)}/${enc(code)}`)),
+            /**
+             * Make the declared languages exactly `want` (the source excluded):
+             * adds what is missing, relabels what changed, removes what is not
+             * listed only when `prune` — removing a language trashes its
+             * translations, so it is never a side effect. Idempotent.
+             */
+            set: async (orgId, target, want, opts = {}) => {
+                let current = await api.locales.list(orgId, target);
+                const added = [];
+                const relabeled = [];
+                const removed = [];
+                for (const w of want) {
+                    const have = current.find((l) => !l.isSource && l.code.toLowerCase() === w.code.toLowerCase());
+                    if (!have) {
+                        current = await api.locales.add(orgId, target, w);
+                        added.push(w.code);
+                    }
+                    else if (have.label !== w.label) {
+                        current = await api.locales.relabel(orgId, target, have.code, w.label);
+                        relabeled.push(have.code);
+                    }
+                }
+                if (opts.prune)
+                    for (const l of current.filter((c) => !c.isSource && !want.some((w) => w.code.toLowerCase() === c.code.toLowerCase()))) {
+                        current = await api.locales.remove(orgId, target, l.code);
+                        removed.push(l.code);
+                    }
+                return { locales: current, added, relabeled, removed };
+            },
+        },
+        /** Every piece × declared language of a space, in the four states. */
+        status: (orgId, spaceId) => request('GET', `${space(orgId, spaceId)}/translations`),
+        /** Each declared language and one piece's state in it (any kind). */
+        list: async (orgId, spaceId, pieceId, opts = {}) => {
+            const door = await doorOf(orgId, spaceId, opts.door);
+            return request('GET', collection(orgId, spaceId, door, pieceId));
+        },
+        /** One piece's translation, as Markdown, whatever the piece is. */
+        get: async (orgId, spaceId, pieceId, locale, opts = {}) => {
+            const door = await doorOf(orgId, spaceId, opts.door);
+            if (door === 'page') {
+                const row = await pageRow(orgId, spaceId, pieceId, locale);
+                if (!row.id)
+                    return { door, locale: row.code, state: 'missing', id: null, title: null, markdown: null, origin: null };
+                const { item } = await request('GET', `${space(orgId, spaceId)}/items/${row.id}`);
+                return { door, locale: row.code, state: row.state, id: row.id, title: item.title, markdown: item.markdown, origin: row.origin };
+            }
+            if (door === 'incident') {
+                const { translations } = await request('GET', collection(orgId, spaceId, door, pieceId));
+                const t = translations.find((x) => x.locale.toLowerCase() === locale.toLowerCase());
+                if (!t)
+                    return { door, locale, state: 'missing', id: null, title: null, markdown: null, updates: {}, origin: null };
+                return {
+                    door,
+                    locale: t.locale,
+                    state: t.stale ? 'outdated' : 'published',
+                    id: null,
+                    title: t.title,
+                    markdown: t.markdown ?? null,
+                    updates: t.updates,
+                    origin: t.origin === 'machine' ? 'machine' : 'human',
+                };
+            }
+            const { translation: t } = await request('GET', `${collection(orgId, spaceId, door, pieceId)}/${enc(locale)}`);
+            return { door, locale: t.code, state: topicState(t), id: null, title: t.title, markdown: t.markdown ?? null, excerpt: t.excerpt, origin: t.origin };
+        },
+        /** Write or correct one piece's translation by hand (it becomes a person's). */
+        put: async (orgId, spaceId, pieceId, locale, input, opts = {}) => {
+            const door = await doorOf(orgId, spaceId, opts.door);
+            if (door === 'page') {
+                const row = await pageRow(orgId, spaceId, pieceId, locale);
+                if (!row.id)
+                    throw Object.assign(new Error(`This page has no ${locale} twin.`), { status: 404 });
+                const item = `${space(orgId, spaceId)}/items/${row.id}`;
+                if (input.title)
+                    await request('PATCH', item, { body: { title: input.title } });
+                if (input.markdown !== undefined)
+                    await request('PUT', `${item}/content`, { body: { body: input.markdown } });
+                if (input.published)
+                    await request('POST', `${item}/publish`, { body: {} });
+            }
+            else if (door === 'incident') {
+                const { title, markdown, updates } = input;
+                await request('PUT', `${collection(orgId, spaceId, door, pieceId)}/${enc(locale)}`, { body: { title, markdown, updates } });
+            }
+            else {
+                const { title, markdown, excerpt, published } = input;
+                await request('PUT', `${collection(orgId, spaceId, door, pieceId)}/${enc(locale)}`, { body: { title, markdown, excerpt, published } });
+            }
+            return api.get(orgId, spaceId, pieceId, locale, { door });
+        },
+        /** Remove one piece's translation (a page twin goes to the trash). */
+        remove: async (orgId, spaceId, pieceId, locale, opts = {}) => {
+            const door = await doorOf(orgId, spaceId, opts.door);
+            if (door === 'page') {
+                const row = await pageRow(orgId, spaceId, pieceId, locale);
+                if (row.id)
+                    await request('DELETE', `${space(orgId, spaceId)}/items/${row.id}`);
+                return;
+            }
+            await request('DELETE', `${collection(orgId, spaceId, door, pieceId)}/${enc(locale)}`);
+        },
+        /** Machine-translate one piece with the org's own provider: `…/translations/{locale}/auto`. */
+        auto: async (orgId, spaceId, pieceId, locale, opts = {}) => {
+            const door = await doorOf(orgId, spaceId, opts.door);
+            const body = { force: opts.force };
+            if (door !== 'incident')
+                body.published = opts.published;
+            return request('POST', `${collection(orgId, spaceId, door, pieceId)}/${enc(locale)}/auto`, { body });
+        },
+        /** A content library entry's machine translation (always a draft twin). */
+        autoEntry: (orgId, libraryId, entryId, locale, opts = {}) => request('POST', `${library(orgId, libraryId)}/entries/${entryId}/translations/${enc(locale)}/auto`, { body: opts }),
+        /** Correct the language a piece is DECLARED to be written in (`PATCH …/items/{id}`). */
+        setItemLocale: (orgId, spaceId, itemId, locale) => request('PATCH', `${space(orgId, spaceId)}/items/${itemId}`, { body: { locale } }),
+        /**
+         * Name translations: a space's (`settings.translations`) and a
+         * collection's. The API replaces the whole map on write, so `set` reads
+         * it first and changes one language — the other languages survive.
+         */
+        names: {
+            get: async (orgId, spaceId, opts = {}) => {
+                if (opts.collectionId) {
+                    const { collection } = await request('GET', `${space(orgId, spaceId)}/collections/${opts.collectionId}`);
+                    return collection.translations ?? {};
+                }
+                const { space: s } = await request('GET', space(orgId, spaceId));
+                return s.settings?.translations ?? {};
+            },
+            /** One language's name (and description); `null` removes that language. */
+            set: async (orgId, spaceId, locale, words, opts = {}) => {
+                const current = { ...(await api.names.get(orgId, spaceId, opts)) };
+                if (words === null)
+                    delete current[locale];
+                else
+                    current[locale] = { ...(current[locale] ?? {}), ...words };
+                const at = opts.collectionId ? `${space(orgId, spaceId)}/collections/${opts.collectionId}` : space(orgId, spaceId);
+                await request('PATCH', at, { body: { translations: Object.keys(current).length ? current : null } });
+                return current;
+            },
+        },
+        /** A library entry's locale twin: its localized fields in one language. */
+        entryLocale: {
+            get: (orgId, libraryId, entryId, locale) => request('GET', `${library(orgId, libraryId)}/entries/${entryId}/locales`, { query: { locale } }),
+            /** Write the twin's DRAFT (made from the source when missing). */
+            put: (orgId, libraryId, entryId, locale, fields) => request('PUT', `${library(orgId, libraryId)}/entries/${entryId}/locales/${enc(locale)}`, { body: { fields } }),
+        },
+        /** The site/space chrome dictionary: every owner-written word, per language. */
+        labels: {
+            strings: (orgId, scope) => request('GET', `${labelsAt(orgId, scope)}/strings`),
+            /** Replace the whole dictionary. */
+            replace: (orgId, scope, labels) => request('PUT', `${labelsAt(orgId, scope)}/labels`, { body: { labels } }),
+            /** Merge word by word; `null` removes a word or a language. */
+            merge: (orgId, scope, labels) => request('PATCH', `${labelsAt(orgId, scope)}/labels`, { body: { labels } }),
+        },
+        /** The organization's own wording for our interface strings, per locale. */
+        overrides: {
+            list: (orgId, locale) => request('GET', `/orgs/${orgId}/translation-overrides`, { query: { locale } }),
+            set: (orgId, input) => request('PUT', `/orgs/${orgId}/translation-overrides`, { body: input }),
+            remove: (orgId, input) => request('DELETE', `/orgs/${orgId}/translation-overrides`, { query: input }),
+            /** Every key a reader page can show and the English it replaces (public). */
+            catalog: (orgId) => request('GET', `/public/orgs/${orgId}/i18n/catalog`),
+            /** The overrides readers in one locale are served (public). */
+            forLocale: (orgId, locale) => request('GET', `/public/orgs/${orgId}/i18n/${enc(locale)}`),
+        },
+        /** The org-wide default for the reader's language switcher. */
+        switcher: {
+            get: (orgId) => request('GET', `/orgs/${orgId}/language-switcher`),
+            set: (orgId, config) => request('PUT', `/orgs/${orgId}/language-switcher`, { body: config }),
+        },
+        /** The org's own DeepL key — what every `auto` uses. */
+        deepl: {
+            status: (orgId) => request('GET', `/orgs/${orgId}/deepl`),
+            connect: (orgId, apiKey) => request('PUT', `/orgs/${orgId}/deepl`, { body: { apiKey } }),
+            disconnect: (orgId) => request('DELETE', `/orgs/${orgId}/deepl`),
+        },
+    };
+    return api;
+}
+//# sourceMappingURL=translations.js.map

package/dist/typed.d.ts

@@ -49,7 +49,7 @@ type ParamsPart<Op> = Op extends {
  * property adds, so `HasKeys` sees the object rather than a union with
  * `undefined` (which would otherwise always look like it has keys).
  */
-type QueryPart<Op> = Op extends {
+export type QueryPart<Op> = Op extends {
     parameters: {
         query: infer Q;
     };
@@ -93,7 +93,7 @@ type BodyPart<Op> = Op extends {
     body?: undefined;
 };
 /** Flatten an intersection into a single object literal for readable hovers. */
-type Simplify<T> = {
+export type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
 /**

package/dist/webhooks.d.ts

@@ -75,4 +75,12 @@ export interface VerifyWebhookInput {
     now?: () => number;
 }
 export declare function verifyWebhookSignature(input: VerifyWebhookInput): Promise<boolean>;
+/**
+ * Verify a delivery, then parse it — the one call a webhook handler needs.
+ *
+ * Throws instead of returning `false` so the parse can never run ahead of the
+ * check: a handler that did `JSON.parse(body)` first and verified second has
+ * already acted on whatever it was sent.
+ */
+export declare function constructWebhookEvent<T = Record<string, unknown>>(input: VerifyWebhookInput): Promise<T>;
 //# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.constructWebhookEvent = constructWebhookEvent;
 async function verifyWebhookSignature(input) {
     const { secret, signature, acceptLegacy = false, toleranceSeconds = 300 } = input;
     if (!secret || !signature)
@@ -37,6 +38,20 @@ async function verifyWebhookSignature(input) {
     }
     return false;
 }
+/**
+ * Verify a delivery, then parse it — the one call a webhook handler needs.
+ *
+ * Throws instead of returning `false` so the parse can never run ahead of the
+ * check: a handler that did `JSON.parse(body)` first and verified second has
+ * already acted on whatever it was sent.
+ */
+async function constructWebhookEvent(input) {
+    if (!(await verifyWebhookSignature(input))) {
+        throw new Error('Forumulate webhook signature did not verify (wrong secret, altered body, or too old)');
+    }
+    const body = typeof input.body === 'string' ? input.body : new TextDecoder().decode(input.body);
+    return JSON.parse(body);
+}
 /** The substring of `haystack` at `needle`'s position, for a constant-time compare. */
 function extractMatch(haystack, needle) {
     const at = haystack.indexOf(needle);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumulate/sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Typed TypeScript client for the Forumulate REST API.",
   "license": "MIT",
   "homepage": "https://forumulate.com/reference",
@@ -20,6 +20,7 @@
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "sideEffects": false,
   "files": [
     "dist",
     "!dist/**/*.map",
@@ -45,9 +46,12 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit --incremental --tsBuildInfoFile node_modules/.cache/tsc-src.tsbuildinfo && tsc -p tsconfig.test.json --incremental --tsBuildInfoFile node_modules/.cache/tsc-test.tsbuildinfo",
+    "typecheck": "node ../../scripts/tsgo.mjs -p tsconfig.json --noEmit --incremental --tsBuildInfoFile node_modules/.cache/tsgo-src.tsbuildinfo && node ../../scripts/tsgo.mjs -p tsconfig.test.json --incremental --tsBuildInfoFile node_modules/.cache/tsgo-test.tsbuildinfo",
+    "typecheck:tsc": "tsc -p tsconfig.json --noEmit --incremental --tsBuildInfoFile node_modules/.cache/tsc-src.tsbuildinfo && tsc -p tsconfig.test.json --incremental --tsBuildInfoFile node_modules/.cache/tsc-test.tsbuildinfo",
     "test": "vitest run",
-    "dump-spec": "tsx scripts/dump-openapi.ts",
-    "generate-schema": "npx -y openapi-typescript@7 openapi.json -o src/schema.ts"
+    "dump-spec": "pnpm --filter @forumulate/api run dump-spec",
+    "generate-schema": "npx -y openapi-typescript@7 openapi.json -o src/schema.ts && node scripts/generate-operations.mjs",
+    "generate-operations": "node scripts/generate-operations.mjs",
+    "spec:refresh": "node ../../scripts/spec-refresh.mjs"
   }
 }