@we8/client 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @we8/client
+
+A typed client for the we8 public API. It is a thin convenience layer over the
+OpenAPI-documented HTTP contract: every method maps 1:1 to a `/v1` route, so you
+never lose anything by dropping down to `fetch`. The API is the product; this
+package is the ergonomic way to call it.
+
+- Zero runtime dependencies. The wire contract lives in this package as plain
+  TypeScript (`src/contract.ts`), so nothing is pulled in at build or run time.
+- Runs in browsers, Node, and edge runtimes (anywhere `fetch` exists).
+- Speaks the same `/v1` dialect as a managed we8 tenant, so the same code works
+  against a self-hosted CMS and a managed one.
+
+## Requirements
+
+- Node 20 or newer, any modern browser, or an edge runtime. Zero runtime
+  dependencies.
+- A we8 CMS to talk to: the self-hosted `@we8/cms` or a managed we8.io tenant.
+  Both speak the same `/v1` dialect. For a self-hosted CMS, pass its origin as
+  `baseUrl` (the default `/api` is the managed platform's same-origin shape).
+- A publishable (`pk_`) key for reads and beacons; a secret (`sk_`) key only
+  where a route demands one.
+## Install
+
+```sh
+npm install @we8/client
+```
+
+## Quick start
+
+```ts
+import { createClient } from '@we8/client';
+
+const we8 = createClient({
+  key: process.env.WE8_PUBLISHABLE_KEY!, // pk_... (public) or sk_... (server only)
+  baseUrl: 'https://cms.example.com', // your CMS origin, no path on the end
+});
+
+// Posts
+const page = await we8.posts.list({ page: 1, pageSize: 10, tag: 'launch' });
+const { post, jsonld } = await we8.posts.get('hello-world');
+
+// Site identity (name, canonical URL, SEO fallbacks, publisher)
+const site = await we8.site.config();
+
+// Forms (formKey plus arbitrary fields; the API validates per form)
+const { id } = await we8.forms.submit('contact', { email: 'a@b.com', body: 'hi' });
+
+// Events (analytics; safe to fire from the browser with a pk_ key)
+await we8.events.visit({ pathname: '/', sessionId });
+```
+
+## Keys and the base URL
+
+- A publishable key (`pk_...`) is sent as `X-We8-Key` and is safe to embed in a
+  shipped frontend. A secret key (`sk_...`) is sent as `Authorization: Bearer`
+  and is for server or build-time use only; never ship it to a browser.
+- `baseUrl` is the API base every route hangs off: the client requests
+  `${baseUrl}/v1/...`. **Pass it explicitly for a self-hosted we8 CMS**, as the
+  CMS origin with no path on the end (`https://cms.example.com`, or
+  `http://localhost:8787` in development). The default is the same-origin
+  `/api`, which is the managed platform's shape, and it 404s against a
+  standalone CMS.
+- Pass a `fetch` implementation via `options.fetch` in tests or runtimes without
+  a global `fetch`.
+
+## Surface
+
+| Group       | Methods                                                                       |
+| ----------- | ----------------------------------------------------------------------------- |
+| `posts`     | `list(params?)`, `get(slug)`, `view(slug, sessionId)`, `like(slug, sessionId)` |
+| `authors`   | `get(slug)`                                                                   |
+| `site`      | `config()`                                                                    |
+| `documents` | `get(kind)` where `kind` is `'design-md'` or `'llms-txt'`                     |
+| `forms`     | `submit(formKey, data, { turnstileToken? })`                                  |
+| `events`    | `visit(input)`, `consent(input)`                                              |
+| top level   | `sitemapUrl()`                                                                |
+
+Every call throws a `We8ApiError` (carrying the API's stable `code` and the HTTP
+`status`) on failure; a transport failure surfaces as `code: 'internal'`,
+`status: 0`. Use `isWe8ApiError(err)` to narrow without importing the class.
+
+## The contract
+
+`src/contract.ts` is the typed statement of the `/v1` dialect: the response
+envelope, the frozen vocabularies (`POST_TYPES`, `AUTHOR_TYPES`,
+`CONSENT_DECISIONS`, `SITE_DOCUMENT_KINDS`, `CTA_STYLES`, `ERROR_CODES`), and
+the record shapes. The vocabularies are exported as runtime constants as well
+as types, so a frontend can build a filter or a select box from them without
+restating the list. `test/contract.test.ts` pins every member, so a change to
+the dialect cannot land quietly.
+
+The full, authoritative interface is the OpenAPI document your CMS serves:
+
+```
+https://cms.example.com/v1/openapi.json
+```
+
+It is keyless, so you can read the contract before anyone has issued you a key.
+
+## Environment contract
+
+Headless and build-time callers typically read these from the environment and
+pass them in:
+
+- `WE8_API_URL`: the absolute API base given to `createClient({ baseUrl })`,
+  which for a self-hosted CMS is its origin.
+- `WE8_PUBLISHABLE_KEY`: the publishable (`pk_`) key given to
+  `createClient({ key })`.
+
+See [the API doc](https://github.com/reveriext/we8-package/blob/main/docs/api.md) for the dialect in prose, and [the
+frontend doc](https://github.com/reveriext/we8-package/blob/main/docs/frontend.md) for how `@we8/astro` and the starter
+template build on this.

package/dist/client.d.ts

@@ -0,0 +1,74 @@
+import type { SiteDocumentKind } from './contract.js';
+import type { We8Author, We8ConsentInput, We8Document, We8FormData, We8FormSubmitOptions, We8JsonLd, We8LikeResult, We8PostDetail, We8PostList, We8PostListParams, We8SiteConfig, We8VisitInput } from './types.js';
+export interface We8ClientOptions {
+    /**
+     * The site API key. A publishable key (`pk_...`) is sent as `X-We8-Key`; a
+     * secret key (`sk_...`) is sent as `Authorization: Bearer`. Publishable keys
+     * are safe to embed in a shipped frontend (that is their purpose); secret
+     * keys are for server and build-time use only and must never reach a browser.
+     */
+    key: string;
+    /**
+     * API base URL: every route is requested as `${baseUrl}/v1/...`. It
+     * defaults to the same-origin `/api`, which is the shape managed we8 serves
+     * behind its router. A SELF-HOSTED @we8/cms worker is the API origin itself
+     * and serves `/v1` at its root, so pass its origin with no path on the end:
+     * `https://cms.example.com`, or `http://localhost:8787` in development.
+     */
+    baseUrl?: string;
+    /**
+     * A `fetch` implementation to use instead of the global. Useful in tests and
+     * in runtimes without a global `fetch`.
+     */
+    fetch?: typeof fetch;
+}
+/** Result of `forms.submit`. `id` is null when the submission was accepted but silently dropped (honeypot or dedupe). */
+export interface We8FormSubmitResult {
+    id: string | null;
+}
+export interface We8Client {
+    posts: {
+        /** List published posts (paged, optionally filtered by tag, category, or type). */
+        list(params?: We8PostListParams): Promise<We8PostList>;
+        /** Fetch a single published post by slug, with its JSON-LD. */
+        get(slug: string): Promise<We8PostDetail>;
+        /** Record a view for a post (deduped per session by the API). */
+        view(slug: string, sessionId: string): Promise<void>;
+        /** Toggle a like for a post; returns the new liked state and count. */
+        like(slug: string, sessionId: string): Promise<We8LikeResult>;
+    };
+    authors: {
+        /** Fetch a single author profile by slug. */
+        get(slug: string): Promise<We8Author>;
+    };
+    site: {
+        /** Fetch the site identity card: name, canonical URL, SEO fallbacks, publisher, content paths. */
+        config(): Promise<We8SiteConfig>;
+    };
+    documents: {
+        /** Fetch a site document (design.md or llms.txt); empty content when never written. */
+        get(kind: SiteDocumentKind): Promise<We8Document>;
+    };
+    forms: {
+        /** Submit a form by its key. Extra fields pass through; the API validates per form. */
+        submit(formKey: string, data: We8FormData, options?: We8FormSubmitOptions): Promise<We8FormSubmitResult>;
+    };
+    events: {
+        /** Record a page visit. */
+        visit(input: We8VisitInput): Promise<void>;
+        /** Record a cookie-consent decision. */
+        consent(input: We8ConsentInput): Promise<void>;
+    };
+    /**
+     * The absolute-or-relative URL of this site's sitemap, fetchable AS-IS: the
+     * public router requires a key on every request, so for a publishable
+     * (`pk_`) key the key is embedded as `?key=` (pk keys are public by design;
+     * this is what makes the URL usable in a robots.txt or by a search engine).
+     * A secret (`sk_`) key must never appear in a URL, so an sk-keyed client
+     * gets the bare URL and must fetch it with auth headers itself.
+     */
+    sitemapUrl(): string;
+}
+export declare function createClient(options: We8ClientOptions): We8Client;
+export type { We8JsonLd };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE3E,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,SAAS,EACT,aAAa,EACb,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,yHAAyH;AACzH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE;QACL,mFAAmF;QACnF,IAAI,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;QACvD,+DAA+D;QAC/D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;QAC1C,iEAAiE;QACjE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACrD,uEAAuE;QACvE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;KAC/D,CAAC;IACF,OAAO,EAAE;QACP,6CAA6C;QAC7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;KACvC,CAAC;IACF,IAAI,EAAE;QACJ,kGAAkG;QAClG,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;KAClC,CAAC;IACF,SAAS,EAAE;QACT,uFAAuF;QACvF,GAAG,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;KACnD,CAAC;IACF,KAAK,EAAE;QACL,uFAAuF;QACvF,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAAC;KACjC,CAAC;IACF,MAAM,EAAE;QACN,2BAA2B;QAC3B,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,wCAAwC;QACxC,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAChD,CAAC;IACF;;;;;;;OAOG;IACH,UAAU,IAAI,MAAM,CAAC;CACtB;AAiCD,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA+HjE;AAED,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/dist/client.js

@@ -0,0 +1,143 @@
+import { We8ApiError } from './errors.js';
+function authHeader(key) {
+    // The public router accepts a secret key via `Authorization: Bearer` and a
+    // publishable key via `X-We8-Key`. Anything that is not explicitly `sk_` is
+    // treated as publishable, so an unknown or future key prefix still reaches
+    // the router on the header that does not read as a bearer credential.
+    return key.startsWith('sk_') ? { Authorization: `Bearer ${key}` } : { 'X-We8-Key': key };
+}
+function statusToCode(status) {
+    switch (status) {
+        case 400:
+            return 'validation_error';
+        case 401:
+            return 'unauthorized';
+        case 403:
+            return 'forbidden';
+        case 404:
+            return 'not_found';
+        case 413:
+            return 'payload_too_large';
+        case 429:
+            return 'rate_limited';
+        default:
+            return 'internal';
+    }
+}
+function messageOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+export function createClient(options) {
+    if (!options.key)
+        throw new Error('createClient: a `key` is required');
+    const { key } = options;
+    const baseUrl = (options.baseUrl ?? '/api').replace(/\/+$/, '');
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('createClient: no global `fetch` found; pass one via `options.fetch`');
+    }
+    function buildUrl(path, query) {
+        let url = `${baseUrl}/v1/${path}`;
+        if (query) {
+            const qs = new URLSearchParams(query).toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        return url;
+    }
+    async function request(method, path, opts = {}) {
+        const url = buildUrl(path, opts.query);
+        const headers = { Accept: 'application/json', ...authHeader(key) };
+        let body;
+        if (opts.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(opts.body);
+        }
+        let res;
+        try {
+            res = await fetchImpl(url, { method, headers, ...(body === undefined ? {} : { body }) });
+        }
+        catch (cause) {
+            // Transport-level failure (offline, DNS, CORS block): no HTTP status.
+            throw new We8ApiError('internal', `request to ${url} failed: ${messageOf(cause)}`, 0);
+        }
+        const text = await res.text();
+        let envelope;
+        if (text) {
+            try {
+                envelope = JSON.parse(text);
+            }
+            catch {
+                // Non-JSON body; handled below by the status checks.
+            }
+        }
+        if (envelope && envelope.ok === false) {
+            throw new We8ApiError(envelope.code, envelope.error, res.status);
+        }
+        if (!res.ok) {
+            throw new We8ApiError(statusToCode(res.status), `HTTP ${res.status} from ${url}`, res.status);
+        }
+        if (!envelope) {
+            throw new We8ApiError('internal', `unexpected non-JSON response from ${url}`, res.status);
+        }
+        // Strip the `ok: true` discriminant, leaving just the typed data payload.
+        const { ok: _ok, ...data } = envelope;
+        return data;
+    }
+    const enc = encodeURIComponent;
+    // Normalize the typed list params into a string query record, dropping
+    // absent or empty values. Explicit (rather than a generic index signature)
+    // so it stays clean under exactOptionalPropertyTypes and the client owns
+    // exactly which query keys it forwards.
+    function postListQuery(params) {
+        const q = {};
+        if (params?.page !== undefined)
+            q['page'] = String(params.page);
+        if (params?.pageSize !== undefined)
+            q['pageSize'] = String(params.pageSize);
+        if (params?.tag)
+            q['tag'] = params.tag;
+        if (params?.category)
+            q['category'] = params.category;
+        if (params?.type)
+            q['type'] = params.type;
+        return q;
+    }
+    return {
+        posts: {
+            list: (params) => request('GET', 'posts', { query: postListQuery(params) }),
+            get: (slug) => request('GET', `posts/${enc(slug)}`),
+            view: (slug, sessionId) => request('POST', `posts/${enc(slug)}/view`, {
+                body: { sessionId },
+            }).then(() => undefined),
+            like: (slug, sessionId) => request('POST', `posts/${enc(slug)}/like`, { body: { sessionId } }),
+        },
+        authors: {
+            get: (slug) => request('GET', `authors/${enc(slug)}`).then((d) => d.author),
+        },
+        site: {
+            config: () => request('GET', 'site').then((d) => d.site),
+        },
+        documents: {
+            get: (kind) => request('GET', `documents/${enc(kind)}`).then((d) => d.document),
+        },
+        forms: {
+            submit: (formKey, data, opts) => request('POST', `forms/${enc(formKey)}/submissions`, {
+                body: opts?.turnstileToken ? { ...data, turnstileToken: opts.turnstileToken } : data,
+            }),
+        },
+        events: {
+            visit: (input) => request('POST', 'events/visit', { body: input }).then(() => undefined),
+            consent: (input) => request('POST', 'events/consent', { body: input }).then(() => undefined),
+        },
+        sitemapUrl: () => {
+            const url = `${baseUrl}/v1/sitemap.xml`;
+            // Without a key the public router 401s (it requires a key on EVERY
+            // path), so a bare URL would be dead on arrival for any consumer that
+            // cannot send headers (robots.txt, a search engine). Embed a
+            // publishable key via the router's ?key= channel; never embed a secret.
+            return key.startsWith('sk_') ? url : `${url}?key=${encodeURIComponent(key)}`;
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/contract.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The wire contract of the we8 public API, expressed as plain TypeScript.
+ *
+ * In the managed platform these shapes are derived from Zod schemas in a
+ * shared package. This package has zero runtime dependencies by design, so the
+ * contract is restated here as types plus a handful of frozen vocabularies.
+ * The `/v1` dialect is the same one a managed we8 tenant speaks, so a site
+ * built on this client works against either backend unchanged.
+ *
+ * Everything here is the PUBLIC half of the contract: what `/v1/*` serves and
+ * accepts. Admin-only shapes live in the CMS package, not here.
+ */
+/** Every stable machine-readable error code the API can return. */
+export declare const ERROR_CODES: readonly ["validation_error", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "payload_too_large", "internal"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+/** A successful envelope: `ok: true` plus the payload fields, flattened. */
+export type Ok<T extends object = object> = {
+    ok: true;
+} & T;
+/** A failed envelope. `code` is stable; `error` is a human-readable message. */
+export interface Err {
+    ok: false;
+    error: string;
+    code: ErrorCode;
+}
+export type Envelope<T extends object = object> = Ok<T> | Err;
+/**
+ * Content types: a fixed vocabulary, deliberately not extensible per site,
+ * because type drives routing (contentPaths), the sitemap, the JSON-LD
+ * `@type`, template switching, and filters. Adding a member later is an
+ * additive change; open values would break all five consumers.
+ */
+export declare const POST_TYPES: readonly ["blog", "article", "news", "research", "whitepaper", "case-study"];
+export type PostType = (typeof POST_TYPES)[number];
+export declare const AUTHOR_TYPES: readonly ["team", "guest", "advisor", "partner"];
+export type AuthorType = (typeof AUTHOR_TYPES)[number];
+export declare const CONSENT_DECISIONS: readonly ["accepted", "partial", "declined"];
+export type ConsentDecision = (typeof CONSENT_DECISIONS)[number];
+/**
+ * Site documents: small site-authored texts served at the frontend's root.
+ * A fixed two-member vocabulary, one entry per document the platform knows how
+ * to serve.
+ */
+export declare const SITE_DOCUMENT_KINDS: readonly ["design-md", "llms-txt"];
+export type SiteDocumentKind = (typeof SITE_DOCUMENT_KINDS)[number];
+export declare const CTA_STYLES: readonly ["link", "gated-download"];
+export type CtaStyle = (typeof CTA_STYLES)[number];
+/**
+ * An inline call to action, versioned with the post's content. `link` renders
+ * a plain button to `url`. `gated-download` embeds the form named by `formKey`
+ * and reveals `assetUrl` once the form submits successfully: thank-you-surface
+ * delivery, not DRM.
+ */
+export interface Cta {
+    style: CtaStyle;
+    heading?: string;
+    buttonLabel: string;
+    /** Required when `style` is `link`. */
+    url?: string;
+    /** The form's stable key (for example `contact`). Required when `style` is `gated-download`. */
+    formKey?: string;
+    /** The asset revealed after a successful gated submission. */
+    assetUrl?: string;
+}
+/**
+ * The content fields of a published version. `We8Post` composes this with the
+ * post-level identity and counters to form what `/v1/posts` serves.
+ */
+export interface PostVersionRecord {
+    id: string;
+    postId: string;
+    version: number;
+    title: string;
+    excerpt: string | null;
+    content: string;
+    coverImageUrl: string | null;
+    category: string | null;
+    tags: string[];
+    ogTitle: string | null;
+    ogDescription: string | null;
+    ogImageUrl: string | null;
+    /** AEO (0.1): editor-authored answer summary. Absent on older backends. */
+    answerSummary?: string | null;
+    /** AEO (0.1): the question this post answers. Absent on older backends. */
+    questionHeading?: string | null;
+    cta: Cta | null;
+    authorIds: string[];
+    wordCount: number | null;
+    note: string | null;
+    publishedAt: string;
+    publishedBy: string | null;
+}
+export interface AuthorLink {
+    label: string;
+    url: string;
+}
+export interface AuthorRecord {
+    id: string;
+    slug: string;
+    name: string;
+    type: AuthorType;
+    roleTitle?: string;
+    avatarUrl?: string;
+    bio?: string;
+    links: AuthorLink[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SiteDocumentRecord {
+    kind: SiteDocumentKind;
+    content: string;
+    /** AEO (0.1): editor-authored answer summary. Absent on older backends. */
+    answerSummary?: string | null;
+    /** `null` when the document was never written. */
+    updatedAt: string | null;
+}
+export interface VisitEventInput {
+    pathname: string;
+    referrer?: string;
+    sessionId: string;
+}
+export interface ConsentEventInput {
+    sessionId: string;
+    decision: ConsentDecision;
+    analytics: boolean;
+    performance: boolean;
+}
+/**
+ * Site-level SEO fallbacks. A template's own values always win; these fill the
+ * gaps. `titleTemplate` uses `%s` as the page-title placeholder, for example
+ * `%s | Northgate Tools`.
+ */
+export interface SeoSettings {
+    defaultTitle?: string;
+    titleTemplate?: string;
+    metaDescription?: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImageUrl?: string;
+    twitterHandle?: string;
+    discourageSearchEngines: boolean;
+}
+/** schema.org Organization, minimal shape. Used as the JSON-LD `publisher`. */
+export interface PublisherSettings {
+    name: string;
+    logoUrl?: string;
+}
+/** Brand asset slots: the minimal icon set plus display logos. */
+export interface BrandSettings {
+    logoUrl?: string;
+    logoDarkUrl?: string;
+    iconSvgUrl?: string;
+    faviconIcoUrl?: string;
+    appleTouchIconUrl?: string;
+    icon192Url?: string;
+    icon512Url?: string;
+    icon512MaskUrl?: string;
+}
+/** A partial map from post type to the path prefix that section is served at. */
+export type ContentPaths = Partial<Record<PostType, string>>;
+/**
+ * The public site-config payload (`GET /v1/site`): the site's identity card
+ * for templates and SDKs. The code-first merge over `seo` lives in
+ * `@we8/astro` `mergeSeo`, not in the backend.
+ */
+export interface SiteConfig {
+    name: string | null;
+    siteUrl: string;
+    seo: SeoSettings;
+    publisher: PublisherSettings | null;
+    /** The universal prefix used for any type without its own path. */
+    postsPathPrefix: string;
+    /** Fully resolved per-type paths: every post type is present. */
+    contentPaths: Record<PostType, string>;
+    /** `null` when unconfigured; `''` is never served. */
+    gaMeasurementId: string | null;
+    brand: BrandSettings;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

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

package/dist/contract.js

@@ -0,0 +1,53 @@
+/**
+ * The wire contract of the we8 public API, expressed as plain TypeScript.
+ *
+ * In the managed platform these shapes are derived from Zod schemas in a
+ * shared package. This package has zero runtime dependencies by design, so the
+ * contract is restated here as types plus a handful of frozen vocabularies.
+ * The `/v1` dialect is the same one a managed we8 tenant speaks, so a site
+ * built on this client works against either backend unchanged.
+ *
+ * Everything here is the PUBLIC half of the contract: what `/v1/*` serves and
+ * accepts. Admin-only shapes live in the CMS package, not here.
+ */
+/* -------------------------------------------------------------------------- */
+/* Response envelope                                                          */
+/* -------------------------------------------------------------------------- */
+/** Every stable machine-readable error code the API can return. */
+export const ERROR_CODES = [
+    'validation_error',
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'conflict',
+    'rate_limited',
+    'payload_too_large',
+    'internal',
+];
+/* -------------------------------------------------------------------------- */
+/* Frozen vocabularies                                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Content types: a fixed vocabulary, deliberately not extensible per site,
+ * because type drives routing (contentPaths), the sitemap, the JSON-LD
+ * `@type`, template switching, and filters. Adding a member later is an
+ * additive change; open values would break all five consumers.
+ */
+export const POST_TYPES = [
+    'blog',
+    'article',
+    'news',
+    'research',
+    'whitepaper',
+    'case-study',
+];
+export const AUTHOR_TYPES = ['team', 'guest', 'advisor', 'partner'];
+export const CONSENT_DECISIONS = ['accepted', 'partial', 'declined'];
+/**
+ * Site documents: small site-authored texts served at the frontend's root.
+ * A fixed two-member vocabulary, one entry per document the platform knows how
+ * to serve.
+ */
+export const SITE_DOCUMENT_KINDS = ['design-md', 'llms-txt'];
+export const CTA_STYLES = ['link', 'gated-download'];
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,mEAAmE;AACnE,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,kBAAkB;IAClB,cAAc;IACd,WAAW;IACX,WAAW;IACX,UAAU;IACV,cAAc;IACd,mBAAmB;IACnB,UAAU;CACF,CAAC;AAgBX,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM;IACN,SAAS;IACT,MAAM;IACN,UAAU;IACV,YAAY;IACZ,YAAY;CACJ,CAAC;AAIX,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAU,CAAC;AAG7E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAG9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,WAAW,EAAE,UAAU,CAAU,CAAC;AAGtE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAU,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+import type { ErrorCode } from './contract.js';
+/**
+ * The single error type every we8 client call can throw. It carries the API's
+ * own error `code` (the stable machine-readable enum from the response
+ * envelope) and the HTTP `status`, so callers can branch on either.
+ *
+ * - A non-2xx response with a decodable error envelope surfaces that envelope's
+ *   `code`/`error` verbatim.
+ * - A non-2xx response WITHOUT a usable envelope synthesizes a code from the
+ *   status (for example 404 becomes `not_found`, else `internal`).
+ * - A transport failure (fetch rejected, DNS, offline) surfaces as
+ *   `code: 'internal'`, `status: 0`.
+ */
+export declare class We8ApiError extends Error {
+    readonly code: ErrorCode;
+    readonly status: number;
+    constructor(code: ErrorCode, message: string, status: number);
+}
+/** Narrowing helper so consumers do not need to import the class to `instanceof`. */
+export declare function isWe8ApiError(value: unknown): value is We8ApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAS7D;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE"}

package/dist/errors.js

@@ -0,0 +1,30 @@
+/**
+ * The single error type every we8 client call can throw. It carries the API's
+ * own error `code` (the stable machine-readable enum from the response
+ * envelope) and the HTTP `status`, so callers can branch on either.
+ *
+ * - A non-2xx response with a decodable error envelope surfaces that envelope's
+ *   `code`/`error` verbatim.
+ * - A non-2xx response WITHOUT a usable envelope synthesizes a code from the
+ *   status (for example 404 becomes `not_found`, else `internal`).
+ * - A transport failure (fetch rejected, DNS, offline) surfaces as
+ *   `code: 'internal'`, `status: 0`.
+ */
+export class We8ApiError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'We8ApiError';
+        this.code = code;
+        this.status = status;
+        // Restore the prototype chain when the output is transpiled down to ES5-ish
+        // targets (a bundler may do this for older browser targets).
+        Object.setPrototypeOf(this, We8ApiError.prototype);
+    }
+}
+/** Narrowing helper so consumers do not need to import the class to `instanceof`. */
+export function isWe8ApiError(value) {
+    return value instanceof We8ApiError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAY;IAChB,MAAM,CAAS;IAExB,YAAY,IAAe,EAAE,OAAe,EAAE,MAAc;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,4EAA4E;QAC5E,6DAA6D;QAC7D,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,KAAK,YAAY,WAAW,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createClient } from './client.js';
+export type { We8Client, We8ClientOptions, We8FormSubmitResult } from './client.js';
+export { We8ApiError, isWe8ApiError } from './errors.js';
+export type { SiteDocumentKind, We8Author, We8ConsentInput, We8Document, We8FormData, We8FormSubmitOptions, We8JsonLd, We8LikeResult, We8Post, We8PostDetail, We8PostList, We8PostListParams, We8SiteConfig, We8VisitInput, } from './types.js';
+export { AUTHOR_TYPES, CONSENT_DECISIONS, CTA_STYLES, ERROR_CODES, POST_TYPES, SITE_DOCUMENT_KINDS, } from './contract.js';
+export type { AuthorLink, AuthorRecord, AuthorType, BrandSettings, ConsentDecision, ConsentEventInput, ContentPaths, Cta, CtaStyle, Envelope, Err, ErrorCode, Ok, PostType, PostVersionRecord, PublisherSettings, SeoSettings, SiteConfig, SiteDocumentRecord, VisitEventInput, } from './contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,SAAS,EACT,aAAa,EACb,OAAO,EACP,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,UAAU,EACV,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,GAAG,EACH,SAAS,EACT,EAAE,EACF,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,eAAe,GAChB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createClient } from './client.js';
+export { We8ApiError, isWe8ApiError } from './errors.js';
+// The wire contract itself. Types are what most callers need; the frozen
+// vocabularies are exported as runtime constants too, so a template can build
+// a type filter or a select box from them without restating the list.
+export { AUTHOR_TYPES, CONSENT_DECISIONS, CTA_STYLES, ERROR_CODES, POST_TYPES, SITE_DOCUMENT_KINDS, } from './contract.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAkBzD,yEAAyE;AACzE,8EAA8E;AAC9E,sEAAsE;AACtE,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,UAAU,EACV,mBAAmB,GACpB,MAAM,eAAe,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+import type { AuthorRecord, ConsentEventInput, PostType, PostVersionRecord, SiteConfig, SiteDocumentKind, SiteDocumentRecord, VisitEventInput } from './contract.js';
+/**
+ * A published post as returned by the public API: the current published
+ * version's content fields, plus the post-level `slug`, `type`, `viewCount`,
+ * and `likeCount`.
+ */
+export type We8Post = PostVersionRecord & {
+    slug: string;
+    /** The structural content type: picks the site section via contentPaths. */
+    type: PostType;
+    viewCount: number;
+    likeCount: number;
+};
+/** A public author profile. */
+export type We8Author = AuthorRecord;
+/**
+ * JSON-LD blob the API builds for a post's detail page (schema.org
+ * `BlogPosting`/`Article`). Opaque to the client: pass it straight into a
+ * `<script type="application/ld+json">` tag.
+ */
+export type We8JsonLd = Record<string, unknown>;
+/** `GET /v1/posts`: a page of published posts. */
+export interface We8PostList {
+    items: We8Post[];
+    page: number;
+    pageSize: number;
+    total: number;
+}
+/**
+ * `GET /v1/posts/:slug`: a single post, its bylined authors, and its JSON-LD.
+ *
+ * `authors` ships resolved rather than as the post's `authorIds`, because a
+ * public consumer has no way to turn an id into a name or an avatar: the
+ * public authors route is by-slug only. Any frontend rendering a byline needs
+ * them, and the route already loads them to build the JSON-LD.
+ */
+export interface We8PostDetail {
+    post: We8Post;
+    authors: We8Author[];
+    jsonld: We8JsonLd;
+}
+/** Filters and paging for `posts.list()`. All optional; the API applies defaults. */
+export interface We8PostListParams {
+    page?: number;
+    pageSize?: number;
+    tag?: string;
+    category?: string;
+    type?: PostType;
+}
+/** Result of toggling a like on a post. */
+export interface We8LikeResult {
+    liked: boolean;
+    likeCount: number;
+}
+/** Fields for a form submission. Arbitrary keys; the API validates per form. */
+export type We8FormData = Record<string, unknown>;
+/** Options for `forms.submit()`. */
+export interface We8FormSubmitOptions {
+    /** A Cloudflare Turnstile token, when the target form requires one. */
+    turnstileToken?: string;
+}
+/** A visit beacon payload. */
+export type We8VisitInput = VisitEventInput;
+/** A cookie-consent decision payload. */
+export type We8ConsentInput = ConsentEventInput;
+/**
+ * The site identity card (`GET /v1/site`): name, canonical URL, SEO
+ * fallbacks, publisher, brand assets, and the content paths. The code-first
+ * merge over `seo` lives in `@we8/astro` `mergeSeo`.
+ */
+export type We8SiteConfig = SiteConfig;
+/**
+ * A site document (`GET /v1/documents/:kind`): design.md or llms.txt.
+ * `content` is `''` and `updatedAt` is `null` when the site never wrote one,
+ * the same meaning a 404 would carry elsewhere, not an error.
+ */
+export type We8Document = SiteDocumentRecord;
+/** The fixed document-kind vocabulary, re-exported so callers can type a `kind` parameter. */
+export type { SiteDocumentKind };
+//# 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":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,QAAQ,EACR,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAChB,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,iBAAiB,GAAG;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,+BAA+B;AAC/B,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC;AAErC;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,oCAAoC;AACpC,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8BAA8B;AAC9B,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAE5C,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAC;AAE7C,8FAA8F;AAC9F,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@we8/client",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reveriext/we8-package.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/reveriext/we8-package/tree/main/packages/client#readme",
+  "bugs": "https://github.com/reveriext/we8-package/issues",
+  "type": "module",
+  "description": "Typed client for the we8 public API. No runtime dependencies; works in browsers, Node, and edge runtimes.",
+  "keywords": [
+    "we8",
+    "cms",
+    "headless-cms",
+    "api-client",
+    "typescript"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@we8/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}