@forumulate/sdk 0.1.0

package/dist/schema.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/typed.d.ts

@@ -0,0 +1,121 @@
+import type { paths } from './schema';
+export type { paths };
+/** HTTP verbs a generated path entry can carry (openapi-typescript's key set). */
+export type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
+/**
+ * The verbs that actually exist on a path. openapi-typescript stamps every
+ * absent verb as `put?: never`, so we drop the `never` slots to leave real
+ * operations only — this is what powers method autocomplete on `typed()`.
+ */
+export type MethodsOf<P extends keyof paths> = {
+    [M in keyof paths[P]]: paths[P][M] extends never ? never : M extends HttpMethod ? M : never;
+}[keyof paths[P]];
+/** The generated operation object for a `(path, method)` pair. */
+export type OperationOf<P extends keyof paths, M extends keyof paths[P]> = paths[P][M];
+/** `true` when `T` has at least one key (used to decide required vs. optional). */
+type HasKeys<T> = [keyof T] extends [never] ? false : true;
+/** The `params` slot: required when the route has path params, absent otherwise. */
+type ParamsPart<Op> = Op extends {
+    parameters: {
+        path: infer P;
+    };
+} ? HasKeys<P> extends true ? {
+    params: P;
+} : {
+    params?: undefined;
+} : {
+    params?: undefined;
+};
+/**
+ * The `query` slot: present when the route declares query params, and required
+ * only when the route has at least one REQUIRED one.
+ *
+ * The required pattern is tested first, then the optional one — the same order
+ * and for the same reason as `BodyPart` below. openapi-typescript emits
+ * `query?: {…}` (an OPTIONAL property) whenever every query parameter on the
+ * route is itself optional, and an optional property does not satisfy
+ * `{ query: infer Q }`. Matching only the required form therefore fell through
+ * to `{ query?: undefined }` and made `typed()` REFUSE a perfectly legal query
+ * argument on every such route — which is most of them: of 1,220 operations,
+ * the ones with all-optional query params are the common case.
+ *
+ * `GET /orgs/{orgId}/spaces` is the case that caught it: `deleted`, `limit` and
+ * `cursor` are all optional, so passing any of them was a type error even
+ * though the route has always accepted them. `ParamsPart` above is unaffected
+ * only by luck — a path parameter is never optional, so it is always emitted in
+ * the required form.
+ *
+ * `NonNullable` strips the `| undefined` that inferring through an optional
+ * 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 {
+    parameters: {
+        query: infer Q;
+    };
+} ? HasKeys<NonNullable<Q>> extends true ? {
+    query: NonNullable<Q>;
+} : {
+    query?: undefined;
+} : Op extends {
+    parameters: {
+        query?: infer Q;
+    };
+} ? HasKeys<NonNullable<Q>> extends true ? {
+    query?: NonNullable<Q>;
+} : {
+    query?: undefined;
+} : {
+    query?: undefined;
+};
+/**
+ * The `body` slot. A required `requestBody` (no `?` in the schema) yields a
+ * required `body`; an optional one yields an optional `body`. The required
+ * pattern is tested first because an optional `requestBody` does not satisfy it.
+ */
+type BodyPart<Op> = Op extends {
+    requestBody: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? {
+    body: B;
+} : Op extends {
+    requestBody?: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? {
+    body?: B;
+} : {
+    body?: undefined;
+};
+/** Flatten an intersection into a single object literal for readable hovers. */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The `init` argument for `typed(method, path, init)`, derived from the route:
+ * path params, query params and JSON body are each required exactly when the
+ * spec says so, plus a `raw` escape to get the untouched `Response` back.
+ */
+export type TypedRequestInit<Op> = Simplify<ParamsPart<Op> & QueryPart<Op> & BodyPart<Op> & {
+    raw?: boolean;
+}>;
+/** Pull the `application/json` payload out of one response entry. */
+type JsonBody<R> = R extends {
+    content: {
+        'application/json': infer D;
+    };
+} ? D : unknown;
+/**
+ * The success payload for a route: the 200, then 201, then 202 body, or
+ * `undefined` for a 204. Routes whose spec response is empty resolve to
+ * `unknown` — the value is still whatever the API returns, just not narrowed.
+ */
+export type TypedResponse<Op> = Op extends {
+    responses: infer R;
+} ? 200 extends keyof R ? JsonBody<R[200]> : 201 extends keyof R ? JsonBody<R[201]> : 202 extends keyof R ? JsonBody<R[202]> : 204 extends keyof R ? undefined : unknown : unknown;
+//# sourceMappingURL=typed.d.ts.map

package/dist/typed.d.ts.map

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

package/dist/typed.js

@@ -0,0 +1,14 @@
+"use strict";
+// Type-level machinery that turns the machine-generated `paths` interface in
+// `schema.ts` into an ergonomic, fully-typed request signature. This is the
+// bridge that gives the hand-written client typed coverage of the WHOLE REST
+// API (every route in `openapi.json`) instead of only the ~30 curated helpers.
+//
+// Everything here is types-only — no runtime code, no runtime dependency. The
+// generated `schema.ts` is likewise types-only, so adding it costs nothing at
+// runtime and cannot drift from the client's behaviour.
+//
+// See `ForumulateClient.typed()` in `index.ts` for the method these types shape,
+// and the header of `schema.ts` for how to regenerate the source `paths`.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=typed.js.map

package/dist/typed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed.js","sourceRoot":"","sources":["../src/typed.ts"],"names":[],"mappings":";AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,+EAA+E;AAC/E,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,wDAAwD;AACxD,EAAE;AACF,iFAAiF;AACjF,0EAA0E"}

package/dist/types.d.ts

@@ -0,0 +1,179 @@
+export type Role = 'OWNER' | 'ADMIN' | 'MAINTAINER' | 'EDITOR' | 'VIEWER';
+export type SpaceType = 'DOCS' | 'BLOG' | 'FORUM';
+export type SpaceVisibility = 'PRIVATE' | 'PUBLIC';
+export type WebhookFormat = 'json' | 'slack' | 'discord';
+/** A ProseMirror/TipTap-style document node. */
+export interface BlockNode {
+    type: string;
+    content?: BlockNode[];
+    text?: string;
+    attrs?: Record<string, unknown>;
+    marks?: {
+        type: string;
+        attrs?: Record<string, unknown>;
+    }[];
+}
+export interface BlockDoc {
+    type: 'doc';
+    content: BlockNode[];
+}
+export interface Organization {
+    id: string;
+    name: string;
+    slug: string;
+}
+export interface Space {
+    id: string;
+    name: string;
+    slug: string;
+    type: SpaceType;
+    visibility: SpaceVisibility;
+}
+export interface Collection {
+    id: string;
+    name: string;
+    slug: string;
+}
+export interface Page {
+    id: string;
+    title: string;
+    slug: string;
+    status?: 'draft' | 'published';
+}
+export interface SearchHit {
+    pageId: string;
+    title: string;
+    snippet: string;
+}
+/** A result from the org-wide unified search (docs, forum, blog). */
+export interface UnifiedHit {
+    sourceType: 'docs' | 'topic' | 'blog';
+    id: string;
+    spaceId: string;
+    spaceName: string;
+    title: string;
+    snippet: string;
+    url: string;
+    score: number;
+}
+export interface Comment {
+    id: string;
+    parentId: string | null;
+    authorName: string;
+    body: string;
+    status: 'visible' | 'pending' | 'hidden';
+    reactions: Record<string, number>;
+    createdAt: string;
+}
+export interface Webhook {
+    id: string;
+    url: string;
+    events: string[];
+    format: WebhookFormat;
+    active: boolean;
+}
+export interface PublicPage {
+    title: string;
+    content: BlockDoc;
+    metadata: {
+        icon?: string;
+        coverUrl?: string;
+        layout?: 'default' | 'wide';
+    };
+    variables: Record<string, string>;
+    version: string;
+    locale: string;
+}
+/** What a shape says is still missing from a piece. Computed, never enforced. */
+export interface Conformance {
+    conforms: boolean;
+    missing: string[];
+    extra: string[];
+    duplicate: string[];
+}
+/** One piece of a space — a page, a topic or an incident, depending on the space. */
+export interface Item {
+    id: string;
+    kind: 'page' | 'topic' | 'incident';
+    title: string;
+    slug?: string;
+    conformance: Conformance;
+    /** When it last changed, ISO 8601. What a walk is ordered by. */
+    updatedAt?: string;
+    /** Markdown per named slot, when `include` asked for `sections`. */
+    sections?: Record<string, string>;
+    /** The whole piece as markdown, when `include` asked for `body`. */
+    markdown?: string;
+    /**
+     * WHICH of `sections` and `markdown` holds this piece's content.
+     *
+     * `sections` is populated only for a piece written against a shape, so a
+     * free-form piece returns `{}` — indistinguishable, without this, from a
+     * piece that is genuinely empty. Asking for `sections` alone and trusting an
+     * empty object is how a sync reports success having carried nothing.
+     */
+    contentIn?: 'sections' | 'markdown';
+}
+/** Where a walk through a collection continues from. */
+export interface PageInfo {
+    has_more: boolean;
+    next_cursor?: string | null;
+    total?: number;
+}
+/**
+ * The shape types, mirrored rather than imported.
+ *
+ * This package is published on its own, so it cannot depend on the workspace
+ * package these are defined in — the same reason `Page` and `Space` are
+ * mirrored here. They are structural, so they stay assignable either way.
+ */
+export interface ShapeSection {
+    key: string;
+    label: string;
+    kind: 'prose' | 'list' | 'steps' | 'table';
+    required?: boolean;
+    hint?: string;
+    example?: string;
+    schemaProperty?: string;
+    render?: 'labelled' | 'lede' | 'plain';
+}
+export interface ShapeField {
+    key: string;
+    label: string;
+    type: 'text' | 'select' | 'url' | 'date' | 'boolean';
+    options?: readonly string[];
+    hint?: string;
+    placeholder?: string;
+}
+/** What a space is: what a reader arrives at, how they move, who may add. */
+export interface SpaceArchitecture {
+    index: 'landing' | 'list' | 'board' | 'single';
+    order: 'manual' | 'chronological' | 'activity' | 'votes' | 'status';
+    nav: 'tree' | 'categories' | 'tags' | 'sections' | 'none';
+    whoCreates: 'staff' | 'members' | 'anyone';
+    summary: readonly string[];
+}
+export interface EffectiveShape {
+    space: SpaceArchitecture;
+    params: ShapeField[];
+    sections: ShapeSection[];
+    /** Keys an override named that no longer exist. Reported, never fatal. */
+    unknown: string[];
+}
+/** A space's own changes, stored as a patch so upstream improvements still land. */
+export interface ShapeOverride {
+    space?: Partial<SpaceArchitecture>;
+    sections?: {
+        add?: ShapeSection[];
+        omit?: string[];
+        order?: string[];
+        set?: Record<string, Partial<Omit<ShapeSection, 'key'>>>;
+    };
+    params?: {
+        add?: ShapeField[];
+        omit?: string[];
+        order?: string[];
+        set?: Record<string, Partial<Omit<ShapeField, 'key'>>>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+// Wire types for the Forumulate REST API. Kept intentionally lightweight and
+// hand-curated for the stable surface; the full machine-readable schema is
+// available from the running API at `/docs-json` (see README → Regenerating).
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E"}

package/dist/webhooks.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Verifying a webhook delivery, as the receiver actually has to do it.
+ *
+ * The published contract said:
+ *
+ *     X-Forumulate-Signature: v1,sha256=<hex>
+ *
+ * and a reader does the obvious thing with that — compute one value and
+ * compare the header to it. Every delivery to an endpoint still on the default
+ * `signatureVersion: 'both'`, and every delivery during a secret rotation,
+ * then fails to verify, because the real header is a comma-separated LIST:
+ *
+ *     v1,sha256=<a>, v1,sha256=<b>, sha256=<c>, sha256=<d>
+ *       ^ current secret, v1    ^ previous secret, v1
+ *                               ^ the legacy body-only signature, both secrets
+ *
+ * The sender was right and the document was wrong. Two secrets ride along
+ * through a rotation so nobody's verifier breaks on a day we choose, and the
+ * legacy body-only signature rides along until the endpoint's owner turns it
+ * off — and a receiver is meant to accept the delivery if ANY entry matches
+ * the one it computes. That is three facts a sentence in a reference page kept
+ * getting wrong, so here is the function instead.
+ *
+ * Verify `v1`. It signs `<timestamp>.<raw body>`, which is what makes a
+ * captured delivery un-replayable: the legacy `sha256=` covers the body alone
+ * and is therefore replayable forever. This accepts only `v1` unless you ask
+ * for the legacy one explicitly.
+ *
+ *     import { verifyWebhookSignature } from '@forumulate/sdk';
+ *
+ *     app.post('/hooks/forumulate', async (req, res) => {
+ *       const ok = await verifyWebhookSignature({
+ *         secret: process.env.FORUMULATE_WEBHOOK_SECRET!,
+ *         // The RAW body, before any JSON parsing. A re-serialised body has
+ *         // different bytes and will never verify.
+ *         body: req.rawBody,
+ *         signature: req.header('X-Forumulate-Signature'),
+ *         timestamp: req.header('X-Forumulate-Timestamp'),
+ *       });
+ *       if (!ok) return res.sendStatus(401);
+ *       // X-Forumulate-Delivery is the key to dedupe on — retries reuse it.
+ *       res.sendStatus(200);
+ *     });
+ *
+ * WebCrypto, so this is the same code in Node, Bun, Deno, Cloudflare Workers
+ * and a browser. It is async for that reason alone.
+ */
+export interface VerifyWebhookInput {
+    /** The endpoint's signing secret. */
+    secret: string;
+    /** The raw request body, exactly as received — bytes, or the string of them. */
+    body: string | Uint8Array;
+    /** The `X-Forumulate-Signature` header value, whole. */
+    signature: string | null | undefined;
+    /** The `X-Forumulate-Timestamp` header value (unix seconds). */
+    timestamp: string | number | null | undefined;
+    /**
+     * How old a delivery may be, in seconds. Default 300.
+     *
+     * This is the part that makes the timestamp worth signing: without a window,
+     * a captured delivery verifies forever and the signature proves only that we
+     * sent it ONCE. Set it to 0 to skip the check (for a replay of a stored
+     * delivery in a test, say).
+     */
+    toleranceSeconds?: number;
+    /**
+     * Accept the legacy body-only `sha256=` signature as well. Default false.
+     *
+     * It is still sent while an endpoint's `signatureVersion` is `both`, and it
+     * is replayable by construction, so accepting it is a decision rather than a
+     * default.
+     */
+    acceptLegacy?: boolean;
+    /** Overridable for tests. Defaults to now. */
+    now?: () => number;
+}
+export declare function verifyWebhookSignature(input: VerifyWebhookInput): Promise<boolean>;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1B,wDAAwD;IACxD,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC,gEAAgE;IAChE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgCxF"}

package/dist/webhooks.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = verifyWebhookSignature;
+async function verifyWebhookSignature(input) {
+    const { secret, signature, acceptLegacy = false, toleranceSeconds = 300 } = input;
+    if (!secret || !signature)
+        return false;
+    const timestamp = Number(input.timestamp);
+    if (!Number.isFinite(timestamp) || timestamp <= 0)
+        return false;
+    if (toleranceSeconds > 0) {
+        const now = Math.floor((input.now?.() ?? Date.now()) / 1000);
+        // Both directions: a delivery from the future is as suspicious as a stale
+        // one, and clock skew is why the window is seconds rather than exact.
+        if (Math.abs(now - timestamp) > toleranceSeconds)
+            return false;
+    }
+    const body = typeof input.body === 'string' ? input.body : new TextDecoder().decode(input.body);
+    // Entries, not an equality check: a rotation and the legacy overlap both put
+    // more than one signature in this header, and `header === expected` is the
+    // mistake the document invited.
+    const offered = signature.split(',').map((part) => part.trim().toLowerCase());
+    const expected = [`v1,sha256=${await hmacHex(secret, `${timestamp}.${body}`)}`];
+    if (acceptLegacy)
+        expected.push(`sha256=${await hmacHex(secret, body)}`);
+    for (const candidate of expected) {
+        // `v1,sha256=<hex>` contains the comma we just split on, so put it back.
+        const [prefix, value] = candidate.split('=', 2);
+        const wanted = `${prefix}=${value}`;
+        const rejoined = offered.join(',');
+        // Membership against the rejoined list rather than the split parts, so the
+        // `v1,` prefix survives the split that produced the parts.
+        if (!rejoined.includes(wanted))
+            continue;
+        if (timingSafeEqual(wanted, extractMatch(rejoined, wanted)))
+            return true;
+    }
+    return false;
+}
+/** The substring of `haystack` at `needle`'s position, for a constant-time compare. */
+function extractMatch(haystack, needle) {
+    const at = haystack.indexOf(needle);
+    return at < 0 ? '' : haystack.slice(at, at + needle.length);
+}
+async function hmacHex(secret, message) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const mac = await crypto.subtle.sign('HMAC', key, encoder.encode(message));
+    return [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Length-independent, content-constant-time comparison.
+ *
+ * Both sides here are hex of a fixed length, so this is belt and braces — but
+ * a verifier is exactly the place where "it does not matter here" ages badly.
+ */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

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

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@forumulate/sdk",
+  "version": "0.1.0",
+  "description": "Typed TypeScript client for the Forumulate REST API.",
+  "license": "MIT",
+  "homepage": "https://forumulate.com/reference",
+  "bugs": {
+    "url": "https://forumulate.com/community"
+  },
+  "keywords": [
+    "forumulate",
+    "docs",
+    "documentation",
+    "api",
+    "sdk",
+    "typescript",
+    "openapi",
+    "knowledge-base",
+    "forum"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4",
+    "@forumulate/api": "0.0.0"
+  },
+  "author": "Forumulate",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "dump-spec": "tsx scripts/dump-openapi.ts",
+    "generate-schema": "npx -y openapi-typescript@7 openapi.json -o src/schema.ts"
+  }
+}