@brandfine/client 0.1.0

package/dist/index-_XBy9Y81.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Shared public types for the Brandfine SDK.
+ *
+ * Types that round-trip with the API are kept here so consumers
+ * can import them directly (`import type { BrandfinePost } from
+ * '@brandfine/client'`). Implementation-internal types stay
+ * private to their respective modules.
+ */
+/**
+ * A post as returned by `/external/posts`. `TConfig` lets consumers
+ * narrow the `customConfig` field — Brandfine round-trips arbitrary
+ * JSON here without interpretation, so each consumer site defines
+ * its own shape (olavisa uses it for `apply`, `faq`, etc.).
+ *
+ * Default is `unknown` so misuse is caught at the type level rather
+ * than letting `any` leak into consumer code.
+ */
+type BrandfinePost<TConfig = unknown> = {
+    postId: string;
+    /** Per-locale URL slug. */
+    slug: string;
+    /** Stable identifier shared across all locale variants of the
+     *  same article. Use this for cross-locale lookups. */
+    canonicalSlug: string;
+    title: string;
+    metaDescription: string | null;
+    imageUrl: string | null;
+    tags: string[];
+    /** Wyrote-specific taxonomy fields, kept generic so other sources
+     *  can populate them too. Null when not used. */
+    offerTitle: string | null;
+    offerSlug: string | null;
+    topicTitle: string | null;
+    topicSlug: string | null;
+    category: BrandfineCategory | null;
+    authorName: string | null;
+    customConfig: TConfig | null;
+    publishedAt: string;
+    contentHtml: string | null;
+    contentMarkdown: string | null;
+    /** Optional per-post JSON-LD payload. Shape is consumer-defined;
+     *  Brandfine round-trips it untouched. */
+    jsonLd: unknown;
+};
+type BrandfinePostListResponse<TConfig = unknown> = {
+    items: BrandfinePost<TConfig>[];
+    pageInfo: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasNext: boolean;
+        hasPrev: boolean;
+    };
+};
+type BrandfineCategory = {
+    id: string;
+    slug: string;
+    name: string;
+};
+/**
+ * Workspace metadata + config. `TCustomConfig` and `TSchemaOrg`
+ * narrow the two JSON payload fields when the consumer wants
+ * stronger typing — both default to `Record<string, unknown>` so
+ * consumers can opt into typing incrementally.
+ */
+type BrandfineWorkspace<TCustomConfig = Record<string, unknown>, TSchemaOrg = Record<string, unknown>> = {
+    id: string;
+    slug: string;
+    name: string;
+    /** BCP47 locale codes the workspace serves. */
+    locales: string[];
+    defaultLocale: string;
+    customConfig: TCustomConfig | null;
+    /** Schema.org structured-data payload keyed by `@type` (Organization,
+     *  WebSite, LocalBusiness, …). Merged by the consumer into per-page
+     *  JSON-LD output. */
+    schemaOrg: TSchemaOrg | null;
+};
+type BrandfineNavItemType = 'CUSTOM_URL' | 'POST' | 'HEADING';
+type BrandfineNavItem = {
+    id: string;
+    parentId: string | null;
+    position: number;
+    type: BrandfineNavItemType;
+    /** CUSTOM_URL: free-form path or absolute URL. */
+    customUrl: string | null;
+    /** `{ [locale]: string }` map. May be null on POST items —
+     *  consumers fall back to the post's per-locale `title` then. */
+    labels: Record<string, string> | null;
+    /** Locales where the item should not render. */
+    hiddenLocales: string[];
+    /** POST items only. Pre-resolved by the API so consumers can build
+     *  per-locale URLs without a second round-trip. */
+    post: BrandfineNavPost | null;
+};
+type BrandfineNavPost = {
+    id: string;
+    canonicalSlug: string;
+    postTypeId: string | null;
+    /** Post-type slug — typically used by consumers as the URL prefix
+     *  (`/${postTypeSlug}/${slug}`). Null when the post's post type was
+     *  deleted (orphaned). */
+    postTypeSlug: string | null;
+    /** Every published translation of this post — `slug` is the
+     *  per-locale URL slug, `title` is the per-locale title. Consumers
+     *  pick the entry matching the active locale, falling back to the
+     *  workspace default when missing. */
+    locales: Array<{
+        locale: string;
+        slug: string;
+        title: string;
+    }>;
+};
+type BrandfineNavigation = {
+    key: string;
+    name: string;
+    items: BrandfineNavItem[];
+};
+type ListPostsOptions = {
+    /** Post-type slug. Default server-side is `'blog'`; pass `'*'` to
+     *  fetch every type. */
+    type?: string;
+    /** BCP47 locale filter. Omit to fetch every locale. */
+    locale?: string;
+    /** Opt past the API's default 50-per-page cap via the cms's
+     *  `force_limit=` escape hatch. Worth doing for content types
+     *  with 50+ entries to avoid multiple round-trips. */
+    forceLimit?: number;
+};
+type ListCategoriesOptions = {
+    /** Restrict to categories that have at least one published post
+     *  in this locale. Defaults server-side to the workspace's
+     *  `defaultLocale`. Pass `'*'` to ignore the filter. */
+    locale?: string;
+};
+
+/**
+ * Locale helpers.
+ *
+ * Pure functions over BCP47 locale codes. Olavisa's in-tree
+ * version reads `LOCALES` and `DEFAULT_LOCALE` from module-level
+ * constants — the package takes them as options instead so a
+ * single SDK instance can serve callers with different locale
+ * sets (multi-tenant, preview environments, tests).
+ *
+ * The conventional URL shape these helpers assume:
+ *   - The `defaultLocale` is served at the bare URL: `/about`
+ *   - Other locales get a path prefix: `/pt/about`, `/es/about`
+ *   - `pickLocale` falls back to `defaultLocale` for unknown
+ *     inputs. Don't throw — `Astro.currentLocale` is `string |
+ *     undefined`, and callers shouldn't have to defend against
+ *     every framework's quirk.
+ */
+type LocaleOptions = {
+    /** Locales the consumer serves, in any order. The list is used
+     *  for membership checks (`isLocale`), prefix detection
+     *  (`stripLocalePrefix`), and as the codomain of `pickLocale`. */
+    locales: readonly string[];
+    /** The locale served at bare URLs. Must appear in `locales`. */
+    defaultLocale: string;
+};
+/**
+ * Type guard. Narrows `unknown` inputs to a known locale so the
+ * caller can use them without further coercion.
+ *
+ *   if (isLocale(value, ['en', 'pt'])) {
+ *     // value: string (known to be 'en' | 'pt' at runtime)
+ *   }
+ */
+declare function isLocale(value: unknown, locales: readonly string[]): value is string;
+/**
+ * Coerce arbitrary input into a known locale, falling back to
+ * `defaultLocale` for unknowns. Convenient at the consumer's
+ * framework boundary (Astro.currentLocale, request headers, etc.).
+ */
+declare function pickLocale(input: unknown, opts: LocaleOptions): string;
+/**
+ * Convert a canonical (default-locale) path into the locale-prefixed
+ * variant for `locale`. The default locale's URLs are bare; every
+ * other locale prefixes with `/<locale>`.
+ *
+ *   localizePath('/services/uk-eta', 'en', { defaultLocale: 'en' })
+ *     → '/services/uk-eta'
+ *   localizePath('/services/uk-eta', 'pt', { defaultLocale: 'en' })
+ *     → '/pt/services/uk-eta'
+ *   localizePath('/',                'pt', { defaultLocale: 'en' })
+ *     → '/pt'
+ */
+declare function localizePath(path: string, locale: string, opts: {
+    defaultLocale: string;
+}): string;
+/**
+ * Strip a non-default locale prefix off a pathname. The inverse
+ * of `localizePath` — useful for normalising back to a canonical
+ * path before re-localising for a different locale (the language
+ * switcher's main job).
+ *
+ *   stripLocalePrefix('/pt/about',  ...) → '/about'
+ *   stripLocalePrefix('/about',     ...) → '/about'    (already canonical)
+ *   stripLocalePrefix('/pt',        ...) → '/'
+ *   stripLocalePrefix('/en/foo',    { defaultLocale: 'en', … })
+ *     → '/en/foo'   (en is default — no prefix to strip)
+ */
+declare function stripLocalePrefix(pathname: string, opts: LocaleOptions): string;
+
+/**
+ * Navigation resolver.
+ *
+ * Turns a `BrandfineNavigation` (locale-agnostic shape from the
+ * external API) into a `HydratedNav` ready for a specific locale —
+ * URLs computed, labels picked, hidden items dropped, children
+ * grouped under their parent. Header / Footer components consume
+ * the hydrated form directly.
+ *
+ * The semantics encoded here come from olavisa but are
+ * generalised:
+ *   - POST items resolve URLs via `post.locales`. If the active
+ *     locale has no translation, fall back to the default-locale
+ *     URL. Consumers can override the URL pattern entirely via
+ *     `urlForPost`.
+ *   - CUSTOM_URL items: paths (start with `/`) run through
+ *     `localizePath`; anything with a scheme (https://, mailto:)
+ *     passes through unchanged.
+ *   - Labels: per-locale override → default-locale label → any
+ *     populated label (last-resort, covers single-locale fills) →
+ *     for POST items, the post's per-locale title.
+ *   - `hiddenLocales` drops the item entirely for that locale.
+ */
+
+type HydratedNavItem = {
+    /** Final URL, ready to render in an `<a href>`. `null` for
+     *  HEADING items (label-only) and for POST items whose post
+     *  has been deleted (orphan). */
+    href: string | null;
+    label: string;
+    type: 'CUSTOM_URL' | 'POST' | 'HEADING';
+    children: HydratedNavItem[];
+};
+type HydratedNav = {
+    key: string;
+    name: string;
+    items: HydratedNavItem[];
+};
+type ResolveNavigationOptions = {
+    defaultLocale: string;
+    /** Override the URL pattern for POST items. Default:
+     *  `localizePath('/${postTypeSlug}/${sibling.slug}', linkLocale)`.
+     *
+     *  Use when a consumer routes posts under a non-default prefix
+     *  (e.g. `/blog/<slug>` instead of `/posts/<slug>`), or wants
+     *  to omit the locale prefix for specific post types. */
+    urlForPost?: (args: {
+        post: BrandfineNavPost;
+        sibling: BrandfineNavPost['locales'][number];
+        locale: string;
+        defaultLocale: string;
+    }) => string | null;
+};
+declare function resolveNavigation(nav: BrandfineNavigation, locale: string, opts: ResolveNavigationOptions): HydratedNav;
+
+export { type BrandfinePost as B, type HydratedNav as H, type ListPostsOptions as L, type ResolveNavigationOptions as R, type ListCategoriesOptions as a, type BrandfineCategory as b, type BrandfineWorkspace as c, type BrandfineNavigation as d, type BrandfineNavItem as e, type BrandfineNavItemType as f, type BrandfineNavPost as g, type BrandfinePostListResponse as h, type HydratedNavItem as i, type LocaleOptions as j, isLocale as k, localizePath as l, pickLocale as p, resolveNavigation as r, stripLocalePrefix as s };

package/dist/index.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+var chunkXJFKL2HU_cjs = require('./chunk-XJFKL2HU.cjs');
+var chunkOKIEA3AD_cjs = require('./chunk-OKIEA3AD.cjs');
+var chunkKHHMR2NX_cjs = require('./chunk-KHHMR2NX.cjs');
+
+// src/client.ts
+var BrandfineApiError = class extends Error {
+  name = "BrandfineApiError";
+  status;
+  statusText;
+  body;
+  url;
+  constructor(args) {
+    super(
+      `[brandfine] ${args.status} ${args.statusText} on ${args.url} \u2014 ${args.body.slice(0, 200)}`
+    );
+    this.status = args.status;
+    this.statusText = args.statusText;
+    this.body = args.body;
+    this.url = args.url;
+  }
+};
+var DEFAULT_USER_AGENT = "@brandfine/client";
+function createBrandfineClient(config) {
+  if (!config.baseUrl)
+    throw new Error("createBrandfineClient: `baseUrl` is required");
+  if (!config.apiKey)
+    throw new Error("createBrandfineClient: `apiKey` is required");
+  const baseUrl = config.baseUrl.replace(/\/$/, "");
+  const apiKey = config.apiKey;
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const userAgent = config.userAgent ?? DEFAULT_USER_AGENT;
+  async function get(path, opts = {}) {
+    const url = `${baseUrl}${path}`;
+    const res = await fetchImpl(url, {
+      method: "GET",
+      headers: {
+        "X-Api-Key": apiKey,
+        Accept: "application/json",
+        "User-Agent": userAgent
+      },
+      signal: opts.signal
+    });
+    if (res.status === 404 && opts.nullable404) {
+      await res.text().catch(() => "");
+      return null;
+    }
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new BrandfineApiError({
+        status: res.status,
+        statusText: res.statusText,
+        body,
+        url
+      });
+    }
+    return await res.json();
+  }
+  const posts = {
+    async list(opts = {}) {
+      const out = [];
+      let page = 1;
+      const typeQuery = opts.type ? `&type=${encodeURIComponent(opts.type)}` : "";
+      const localeQuery = opts.locale ? `&locale=${encodeURIComponent(opts.locale)}` : "";
+      const sizeQuery = opts.forceLimit ? `&force_limit=${opts.forceLimit}` : "&limit=50";
+      const MAX_PAGES = 200;
+      while (page <= MAX_PAGES) {
+        const data = await get(
+          `/external/posts?include=content${sizeQuery}&page=${page}${typeQuery}${localeQuery}`
+        );
+        out.push(...data.items);
+        if (!data.pageInfo.hasNext) break;
+        page += 1;
+      }
+      return out;
+    },
+    async getBySlug(slug) {
+      return get(
+        `/external/posts/${encodeURIComponent(slug)}`,
+        { nullable404: true }
+      );
+    }
+  };
+  const categories = {
+    async list(opts = {}) {
+      const qs = opts.locale ? `?locale=${encodeURIComponent(opts.locale)}` : "";
+      const data = await get(
+        `/external/categories${qs}`
+      );
+      return data.items;
+    }
+  };
+  const workspace = {
+    get() {
+      return get(
+        "/external/workspace"
+      );
+    }
+  };
+  const navigations = {
+    get(key) {
+      return get(
+        `/external/navigations/${encodeURIComponent(key)}`,
+        { nullable404: true }
+      );
+    }
+  };
+  return { get, posts, categories, workspace, navigations };
+}
+
+// src/index.ts
+var SDK_VERSION = "0.0.0";
+
+Object.defineProperty(exports, "createCache", {
+  enumerable: true,
+  get: function () { return chunkXJFKL2HU_cjs.createCache; }
+});
+Object.defineProperty(exports, "createKeyedCache", {
+  enumerable: true,
+  get: function () { return chunkXJFKL2HU_cjs.createKeyedCache; }
+});
+Object.defineProperty(exports, "isLocale", {
+  enumerable: true,
+  get: function () { return chunkOKIEA3AD_cjs.isLocale; }
+});
+Object.defineProperty(exports, "localizePath", {
+  enumerable: true,
+  get: function () { return chunkOKIEA3AD_cjs.localizePath; }
+});
+Object.defineProperty(exports, "pickLocale", {
+  enumerable: true,
+  get: function () { return chunkOKIEA3AD_cjs.pickLocale; }
+});
+Object.defineProperty(exports, "resolveNavigation", {
+  enumerable: true,
+  get: function () { return chunkOKIEA3AD_cjs.resolveNavigation; }
+});
+Object.defineProperty(exports, "stripLocalePrefix", {
+  enumerable: true,
+  get: function () { return chunkOKIEA3AD_cjs.stripLocalePrefix; }
+});
+Object.defineProperty(exports, "createBrandfineWebhookHandler", {
+  enumerable: true,
+  get: function () { return chunkKHHMR2NX_cjs.createBrandfineWebhookHandler; }
+});
+Object.defineProperty(exports, "parseWebhookPayload", {
+  enumerable: true,
+  get: function () { return chunkKHHMR2NX_cjs.parseWebhookPayload; }
+});
+Object.defineProperty(exports, "verifyWebhookSecret", {
+  enumerable: true,
+  get: function () { return chunkKHHMR2NX_cjs.verifyWebhookSecret; }
+});
+exports.BrandfineApiError = BrandfineApiError;
+exports.SDK_VERSION = SDK_VERSION;
+exports.createBrandfineClient = createBrandfineClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/index.ts"],"names":[],"mappings":";;;;;;;AA8CO,IAAM,iBAAA,GAAN,cAAgC,KAAA,CAAM;AAAA,EACzB,IAAA,GAAO,mBAAA;AAAA,EAChB,MAAA;AAAA,EACA,UAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EAET,YAAY,IAAA,EAKT;AACD,IAAA,KAAA;AAAA,MACE,CAAA,YAAA,EAAe,IAAA,CAAK,MAAM,CAAA,CAAA,EAAI,KAAK,UAAU,CAAA,IAAA,EAAO,IAAA,CAAK,GAAG,WAAM,IAAA,CAAK,IAAA,CAAK,KAAA,CAAM,CAAA,EAAG,GAAG,CAAC,CAAA;AAAA,KAC3F;AACA,IAAA,IAAA,CAAK,SAAS,IAAA,CAAK,MAAA;AACnB,IAAA,IAAA,CAAK,aAAa,IAAA,CAAK,UAAA;AACvB,IAAA,IAAA,CAAK,OAAO,IAAA,CAAK,IAAA;AACjB,IAAA,IAAA,CAAK,MAAM,IAAA,CAAK,GAAA;AAAA,EAClB;AACF;AAoDA,IAAM,kBAAA,GAAqB,mBAAA;AAEpB,SAAS,sBACd,MAAA,EACiB;AACjB,EAAA,IAAI,CAAC,MAAA,CAAO,OAAA;AACV,IAAA,MAAM,IAAI,MAAM,8CAA8C,CAAA;AAChE,EAAA,IAAI,CAAC,MAAA,CAAO,MAAA;AACV,IAAA,MAAM,IAAI,MAAM,6CAA6C,CAAA;AAE/D,EAAA,MAAM,OAAA,GAAU,MAAA,CAAO,OAAA,CAAQ,OAAA,CAAQ,OAAO,EAAE,CAAA;AAChD,EAAA,MAAM,SAAS,MAAA,CAAO,MAAA;AAGtB,EAAA,MAAM,SAAA,GAA0B,MAAA,CAAO,KAAA,IAAS,UAAA,CAAW,KAAA;AAC3D,EAAA,MAAM,SAAA,GAAY,OAAO,SAAA,IAAa,kBAAA;AAEtC,EAAA,eAAe,GAAA,CAAO,IAAA,EAAc,IAAA,GAAuB,EAAC,EAAe;AACzE,IAAA,MAAM,GAAA,GAAM,CAAA,EAAG,OAAO,CAAA,EAAG,IAAI,CAAA,CAAA;AAC7B,IAAA,MAAM,GAAA,GAAM,MAAM,SAAA,CAAU,GAAA,EAAK;AAAA,MAC/B,MAAA,EAAQ,KAAA;AAAA,MACR,OAAA,EAAS;AAAA,QACP,WAAA,EAAa,MAAA;AAAA,QACb,MAAA,EAAQ,kBAAA;AAAA,QACR,YAAA,EAAc;AAAA,OAChB;AAAA,MACA,QAAQ,IAAA,CAAK;AAAA,KACd,CAAA;AACD,IAAA,IAAI,GAAA,CAAI,MAAA,KAAW,GAAA,IAAO,IAAA,CAAK,WAAA,EAAa;AAI1C,MAAA,MAAM,GAAA,CAAI,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM,EAAE,CAAA;AAC/B,MAAA,OAAO,IAAA;AAAA,IACT;AACA,IAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,MAAA,MAAM,OAAO,MAAM,GAAA,CAAI,MAAK,CAAE,KAAA,CAAM,MAAM,EAAE,CAAA;AAC5C,MAAA,MAAM,IAAI,iBAAA,CAAkB;AAAA,QAC1B,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,YAAY,GAAA,CAAI,UAAA;AAAA,QAChB,IAAA;AAAA,QACA;AAAA,OACD,CAAA;AAAA,IACH;AACA,IAAA,OAAQ,MAAM,IAAI,IAAA,EAAK;AAAA,EACzB;AAEA,EAAA,MAAM,KAAA,GAAkB;AAAA,IACtB,MAAM,IAAA,CAAwB,IAAA,GAAyB,EAAC,EAAG;AACzD,MAAA,MAAM,MAAgC,EAAC;AACvC,MAAA,IAAI,IAAA,GAAO,CAAA;AACX,MAAA,MAAM,SAAA,GAAY,KAAK,IAAA,GAAO,CAAA,MAAA,EAAS,mBAAmB,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,GAAK,EAAA;AACzE,MAAA,MAAM,WAAA,GAAc,KAAK,MAAA,GACrB,CAAA,QAAA,EAAW,mBAAmB,IAAA,CAAK,MAAM,CAAC,CAAA,CAAA,GAC1C,EAAA;AAIJ,MAAA,MAAM,YAAY,IAAA,CAAK,UAAA,GACnB,CAAA,aAAA,EAAgB,IAAA,CAAK,UAAU,CAAA,CAAA,GAC/B,WAAA;AAIJ,MAAA,MAAM,SAAA,GAAY,GAAA;AAClB,MAAA,OAAO,QAAQ,SAAA,EAAW;AACxB,QAAA,MAAM,OAAO,MAAM,GAAA;AAAA,UACjB,kCAAkC,SAAS,CAAA,MAAA,EAAS,IAAI,CAAA,EAAG,SAAS,GAAG,WAAW,CAAA;AAAA,SACpF;AACA,QAAA,GAAA,CAAI,IAAA,CAAK,GAAG,IAAA,CAAK,KAAK,CAAA;AACtB,QAAA,IAAI,CAAC,IAAA,CAAK,QAAA,CAAS,OAAA,EAAS;AAC5B,QAAA,IAAA,IAAQ,CAAA;AAAA,MACV;AACA,MAAA,OAAO,GAAA;AAAA,IACT,CAAA;AAAA,IACA,MAAM,UAA6B,IAAA,EAAc;AAC/C,MAAA,OAAO,GAAA;AAAA,QACL,CAAA,gBAAA,EAAmB,kBAAA,CAAmB,IAAI,CAAC,CAAA,CAAA;AAAA,QAC3C,EAAE,aAAa,IAAA;AAAK,OACtB;AAAA,IACF;AAAA,GACF;AAEA,EAAA,MAAM,UAAA,GAA4B;AAAA,IAChC,MAAM,IAAA,CAAK,IAAA,GAA8B,EAAC,EAAG;AAC3C,MAAA,MAAM,EAAA,GAAK,KAAK,MAAA,GAAS,CAAA,QAAA,EAAW,mBAAmB,IAAA,CAAK,MAAM,CAAC,CAAA,CAAA,GAAK,EAAA;AACxE,MAAA,MAAM,OAAO,MAAM,GAAA;AAAA,QACjB,uBAAuB,EAAE,CAAA;AAAA,OAC3B;AACA,MAAA,OAAO,IAAA,CAAK,KAAA;AAAA,IACd;AAAA,GACF;AAEA,EAAA,MAAM,SAAA,GAA0B;AAAA,IAC9B,GAAA,GAGI;AACF,MAAA,OAAO,GAAA;AAAA,QACL;AAAA,OACF;AAAA,IACF;AAAA,GACF;AAEA,EAAA,MAAM,WAAA,GAA8B;AAAA,IAClC,IAAI,GAAA,EAAa;AACf,MAAA,OAAO,GAAA;AAAA,QACL,CAAA,sBAAA,EAAyB,kBAAA,CAAmB,GAAG,CAAC,CAAA,CAAA;AAAA,QAChD,EAAE,aAAa,IAAA;AAAK,OACtB;AAAA,IACF;AAAA,GACF;AAEA,EAAA,OAAO,EAAE,GAAA,EAAK,KAAA,EAAO,UAAA,EAAY,WAAW,WAAA,EAAY;AAC1D;;;AC5NO,IAAM,WAAA,GAAc","file":"index.cjs","sourcesContent":["/**\n * `createBrandfineClient` — the SDK's entry point.\n *\n * Returns a stateless, multi-instance-safe handle scoped to a\n * single `(baseUrl, apiKey)` pair. Pattern follows the Stripe /\n * Algolia / OpenAI SDKs — explicit construction with config,\n * namespaced methods (`bf.posts.list(...)`, `bf.workspace.get()`),\n * no module-level singletons.\n *\n * Why factory not module-level state: multi-tenant consumers\n * sometimes need two clients in the same process (e.g. main site\n * + admin preview). Module-level env reading makes that impossible\n * without monkey-patching.\n */\n\nimport type {\n  BrandfineCategory,\n  BrandfineNavigation,\n  BrandfinePost,\n  BrandfinePostListResponse,\n  BrandfineWorkspace,\n  ListCategoriesOptions,\n  ListPostsOptions,\n} from './types'\n\nexport type BrandfineClientConfig = {\n  /** Base URL of the Brandfine API. No trailing slash — the client\n   *  trims one if you pass it anyway. e.g. `https://api.brandfine.co` */\n  baseUrl: string\n  /** Workspace-scoped API key. Generated from the cms's Workspace\n   *  settings; identifies which workspace the client talks to. */\n  apiKey: string\n  /** Optional fetch override. Useful for tests (inject a stub),\n   *  for runtimes that need a custom implementation (edge workers\n   *  with non-standard fetch), or to add cross-cutting concerns\n   *  like tracing / retries. Defaults to `globalThis.fetch`. */\n  fetch?: typeof globalThis.fetch\n  /** Optional User-Agent header. Falls back to a generic SDK tag. */\n  userAgent?: string\n}\n\n/**\n * Structured error thrown by every request helper on non-2xx\n * responses. Carries the raw body so consumers can log it for\n * debugging without re-fetching.\n */\nexport class BrandfineApiError extends Error {\n  override readonly name = 'BrandfineApiError'\n  readonly status: number\n  readonly statusText: string\n  readonly body: string\n  readonly url: string\n\n  constructor(args: {\n    status: number\n    statusText: string\n    body: string\n    url: string\n  }) {\n    super(\n      `[brandfine] ${args.status} ${args.statusText} on ${args.url} — ${args.body.slice(0, 200)}`,\n    )\n    this.status = args.status\n    this.statusText = args.statusText\n    this.body = args.body\n    this.url = args.url\n  }\n}\n\ntype RequestOptions = {\n  /** When true and the response is 404, return `null` instead of\n   *  throwing. Used by endpoints where 404 is a meaningful empty\n   *  state (navigation by key, single post by slug). */\n  nullable404?: boolean\n  signal?: AbortSignal\n}\n\nexport type BrandfineClient = {\n  /** Low-level GET. Reserved for endpoints we don't have a typed\n   *  helper for yet. Adds the X-Api-Key header automatically. */\n  get: <T>(path: string, opts?: RequestOptions) => Promise<T>\n  posts: PostsApi\n  categories: CategoriesApi\n  workspace: WorkspaceApi\n  navigations: NavigationsApi\n}\n\ntype PostsApi = {\n  /** Paginated list of published posts. Handles the cms's\n   *  pagination transparently — caller gets a flat array. */\n  list: <TConfig = unknown>(\n    opts?: ListPostsOptions,\n  ) => Promise<BrandfinePost<TConfig>[]>\n  /** Single post by per-locale URL slug, scoped to the active\n   *  locale on the workspace's content. Returns `null` for 404 so\n   *  callers can render their own \"not found\" page without try/catch. */\n  getBySlug: <TConfig = unknown>(\n    slug: string,\n  ) => Promise<BrandfinePost<TConfig> | null>\n}\n\ntype CategoriesApi = {\n  list: (opts?: ListCategoriesOptions) => Promise<BrandfineCategory[]>\n}\n\ntype WorkspaceApi = {\n  get: <\n    TCustomConfig = Record<string, unknown>,\n    TSchemaOrg = Record<string, unknown>,\n  >() => Promise<BrandfineWorkspace<TCustomConfig, TSchemaOrg>>\n}\n\ntype NavigationsApi = {\n  /** Navigation by its workspace-scoped `key` (e.g. `'header'`).\n   *  Returns `null` for 404 so consumers can fall back to a\n   *  hardcoded default without try/catch. */\n  get: (key: string) => Promise<BrandfineNavigation | null>\n}\n\nconst DEFAULT_USER_AGENT = '@brandfine/client'\n\nexport function createBrandfineClient(\n  config: BrandfineClientConfig,\n): BrandfineClient {\n  if (!config.baseUrl)\n    throw new Error('createBrandfineClient: `baseUrl` is required')\n  if (!config.apiKey)\n    throw new Error('createBrandfineClient: `apiKey` is required')\n\n  const baseUrl = config.baseUrl.replace(/\\/$/, '')\n  const apiKey = config.apiKey\n  // Resolve fetch lazily so consumers in environments without a\n  // global fetch can polyfill before constructing the client.\n  const fetchImpl: typeof fetch = config.fetch ?? globalThis.fetch\n  const userAgent = config.userAgent ?? DEFAULT_USER_AGENT\n\n  async function get<T>(path: string, opts: RequestOptions = {}): Promise<T> {\n    const url = `${baseUrl}${path}`\n    const res = await fetchImpl(url, {\n      method: 'GET',\n      headers: {\n        'X-Api-Key': apiKey,\n        Accept: 'application/json',\n        'User-Agent': userAgent,\n      },\n      signal: opts.signal,\n    })\n    if (res.status === 404 && opts.nullable404) {\n      // Drain the body so the underlying socket can be reused —\n      // fetch implementations that don't auto-drain (older Node)\n      // can leak otherwise.\n      await res.text().catch(() => '')\n      return null as T\n    }\n    if (!res.ok) {\n      const body = await res.text().catch(() => '')\n      throw new BrandfineApiError({\n        status: res.status,\n        statusText: res.statusText,\n        body,\n        url,\n      })\n    }\n    return (await res.json()) as T\n  }\n\n  const posts: PostsApi = {\n    async list<TConfig = unknown>(opts: ListPostsOptions = {}) {\n      const out: BrandfinePost<TConfig>[] = []\n      let page = 1\n      const typeQuery = opts.type ? `&type=${encodeURIComponent(opts.type)}` : ''\n      const localeQuery = opts.locale\n        ? `&locale=${encodeURIComponent(opts.locale)}`\n        : ''\n      // Default pagination at the cms's 50-per-page cap. `forceLimit`\n      // opts past it for content types that would otherwise need\n      // many round-trips.\n      const sizeQuery = opts.forceLimit\n        ? `&force_limit=${opts.forceLimit}`\n        : '&limit=50'\n      // Pathological safety brake — 200 pages × 50 = 10k posts. If\n      // a workspace ever needs more, callers should hit the API\n      // directly with their own pagination logic.\n      const MAX_PAGES = 200\n      while (page <= MAX_PAGES) {\n        const data = await get<BrandfinePostListResponse<TConfig>>(\n          `/external/posts?include=content${sizeQuery}&page=${page}${typeQuery}${localeQuery}`,\n        )\n        out.push(...data.items)\n        if (!data.pageInfo.hasNext) break\n        page += 1\n      }\n      return out\n    },\n    async getBySlug<TConfig = unknown>(slug: string) {\n      return get<BrandfinePost<TConfig> | null>(\n        `/external/posts/${encodeURIComponent(slug)}`,\n        { nullable404: true },\n      )\n    },\n  }\n\n  const categories: CategoriesApi = {\n    async list(opts: ListCategoriesOptions = {}) {\n      const qs = opts.locale ? `?locale=${encodeURIComponent(opts.locale)}` : ''\n      const data = await get<{ items: BrandfineCategory[] }>(\n        `/external/categories${qs}`,\n      )\n      return data.items\n    },\n  }\n\n  const workspace: WorkspaceApi = {\n    get<\n      TCustomConfig = Record<string, unknown>,\n      TSchemaOrg = Record<string, unknown>,\n    >() {\n      return get<BrandfineWorkspace<TCustomConfig, TSchemaOrg>>(\n        '/external/workspace',\n      )\n    },\n  }\n\n  const navigations: NavigationsApi = {\n    get(key: string) {\n      return get<BrandfineNavigation | null>(\n        `/external/navigations/${encodeURIComponent(key)}`,\n        { nullable404: true },\n      )\n    },\n  }\n\n  return { get, posts, categories, workspace, navigations }\n}\n","/**\n * @brandfine/client — root entry.\n *\n * The full SDK surface is exposed here for \"import everything from\n * one place\" usage. Tree-shaking + `sideEffects: false` mean\n * consumers don't pay a bundle cost for what they don't import.\n *\n * Heavier or framework-coupled pieces still live under subpath\n * exports (`@brandfine/client/cache`, `/resolvers`, `/webhook`) so\n * consumers with poor tree-shaking — or who only need one slice —\n * can scope their imports.\n */\n\nexport const SDK_VERSION = '0.0.0' as const\n\nexport {\n  BrandfineApiError,\n  createBrandfineClient,\n  type BrandfineClient,\n  type BrandfineClientConfig,\n} from './client'\n\nexport {\n  createCache,\n  createKeyedCache,\n  type Cache,\n  type CacheOptions,\n  type KeyedCache,\n  type KeyedCacheOptions,\n} from './cache/index'\n\nexport {\n  isLocale,\n  localizePath,\n  pickLocale,\n  resolveNavigation,\n  stripLocalePrefix,\n  type HydratedNav,\n  type HydratedNavItem,\n  type LocaleOptions,\n  type ResolveNavigationOptions,\n} from './resolvers/index'\n\nexport {\n  createBrandfineWebhookHandler,\n  parseWebhookPayload,\n  verifyWebhookSecret,\n  type BrandfineWebhookEvent,\n  type BrandfineWebhookHandlerOptions,\n  type BrandfineWebhookPayload,\n} from './webhook/index'\n\nexport type {\n  BrandfineCategory,\n  BrandfineNavItem,\n  BrandfineNavItemType,\n  BrandfineNavPost,\n  BrandfineNavigation,\n  BrandfinePost,\n  BrandfinePostListResponse,\n  BrandfineWorkspace,\n  ListCategoriesOptions,\n  ListPostsOptions,\n} from './types'\n"]}

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+import { L as ListPostsOptions, B as BrandfinePost, a as ListCategoriesOptions, b as BrandfineCategory, c as BrandfineWorkspace, d as BrandfineNavigation } from './index-_XBy9Y81.cjs';
+export { e as BrandfineNavItem, f as BrandfineNavItemType, g as BrandfineNavPost, h as BrandfinePostListResponse, H as HydratedNav, i as HydratedNavItem, j as LocaleOptions, R as ResolveNavigationOptions, k as isLocale, l as localizePath, p as pickLocale, r as resolveNavigation, s as stripLocalePrefix } from './index-_XBy9Y81.cjs';
+export { Cache, CacheOptions, KeyedCache, KeyedCacheOptions, createCache, createKeyedCache } from './cache/index.cjs';
+export { BrandfineWebhookEvent, BrandfineWebhookHandlerOptions, BrandfineWebhookPayload, createBrandfineWebhookHandler, parseWebhookPayload, verifyWebhookSecret } from './webhook/index.cjs';
+
+/**
+ * `createBrandfineClient` — the SDK's entry point.
+ *
+ * Returns a stateless, multi-instance-safe handle scoped to a
+ * single `(baseUrl, apiKey)` pair. Pattern follows the Stripe /
+ * Algolia / OpenAI SDKs — explicit construction with config,
+ * namespaced methods (`bf.posts.list(...)`, `bf.workspace.get()`),
+ * no module-level singletons.
+ *
+ * Why factory not module-level state: multi-tenant consumers
+ * sometimes need two clients in the same process (e.g. main site
+ * + admin preview). Module-level env reading makes that impossible
+ * without monkey-patching.
+ */
+
+type BrandfineClientConfig = {
+    /** Base URL of the Brandfine API. No trailing slash — the client
+     *  trims one if you pass it anyway. e.g. `https://api.brandfine.co` */
+    baseUrl: string;
+    /** Workspace-scoped API key. Generated from the cms's Workspace
+     *  settings; identifies which workspace the client talks to. */
+    apiKey: string;
+    /** Optional fetch override. Useful for tests (inject a stub),
+     *  for runtimes that need a custom implementation (edge workers
+     *  with non-standard fetch), or to add cross-cutting concerns
+     *  like tracing / retries. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Optional User-Agent header. Falls back to a generic SDK tag. */
+    userAgent?: string;
+};
+/**
+ * Structured error thrown by every request helper on non-2xx
+ * responses. Carries the raw body so consumers can log it for
+ * debugging without re-fetching.
+ */
+declare class BrandfineApiError extends Error {
+    readonly name = "BrandfineApiError";
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    readonly url: string;
+    constructor(args: {
+        status: number;
+        statusText: string;
+        body: string;
+        url: string;
+    });
+}
+type RequestOptions = {
+    /** When true and the response is 404, return `null` instead of
+     *  throwing. Used by endpoints where 404 is a meaningful empty
+     *  state (navigation by key, single post by slug). */
+    nullable404?: boolean;
+    signal?: AbortSignal;
+};
+type BrandfineClient = {
+    /** Low-level GET. Reserved for endpoints we don't have a typed
+     *  helper for yet. Adds the X-Api-Key header automatically. */
+    get: <T>(path: string, opts?: RequestOptions) => Promise<T>;
+    posts: PostsApi;
+    categories: CategoriesApi;
+    workspace: WorkspaceApi;
+    navigations: NavigationsApi;
+};
+type PostsApi = {
+    /** Paginated list of published posts. Handles the cms's
+     *  pagination transparently — caller gets a flat array. */
+    list: <TConfig = unknown>(opts?: ListPostsOptions) => Promise<BrandfinePost<TConfig>[]>;
+    /** Single post by per-locale URL slug, scoped to the active
+     *  locale on the workspace's content. Returns `null` for 404 so
+     *  callers can render their own "not found" page without try/catch. */
+    getBySlug: <TConfig = unknown>(slug: string) => Promise<BrandfinePost<TConfig> | null>;
+};
+type CategoriesApi = {
+    list: (opts?: ListCategoriesOptions) => Promise<BrandfineCategory[]>;
+};
+type WorkspaceApi = {
+    get: <TCustomConfig = Record<string, unknown>, TSchemaOrg = Record<string, unknown>>() => Promise<BrandfineWorkspace<TCustomConfig, TSchemaOrg>>;
+};
+type NavigationsApi = {
+    /** Navigation by its workspace-scoped `key` (e.g. `'header'`).
+     *  Returns `null` for 404 so consumers can fall back to a
+     *  hardcoded default without try/catch. */
+    get: (key: string) => Promise<BrandfineNavigation | null>;
+};
+declare function createBrandfineClient(config: BrandfineClientConfig): BrandfineClient;
+
+/**
+ * @brandfine/client — root entry.
+ *
+ * The full SDK surface is exposed here for "import everything from
+ * one place" usage. Tree-shaking + `sideEffects: false` mean
+ * consumers don't pay a bundle cost for what they don't import.
+ *
+ * Heavier or framework-coupled pieces still live under subpath
+ * exports (`@brandfine/client/cache`, `/resolvers`, `/webhook`) so
+ * consumers with poor tree-shaking — or who only need one slice —
+ * can scope their imports.
+ */
+declare const SDK_VERSION: "0.0.0";
+
+export { BrandfineApiError, BrandfineCategory, type BrandfineClient, type BrandfineClientConfig, BrandfineNavigation, BrandfinePost, BrandfineWorkspace, ListCategoriesOptions, ListPostsOptions, SDK_VERSION, createBrandfineClient };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { L as ListPostsOptions, B as BrandfinePost, a as ListCategoriesOptions, b as BrandfineCategory, c as BrandfineWorkspace, d as BrandfineNavigation } from './index-_XBy9Y81.js';
+export { e as BrandfineNavItem, f as BrandfineNavItemType, g as BrandfineNavPost, h as BrandfinePostListResponse, H as HydratedNav, i as HydratedNavItem, j as LocaleOptions, R as ResolveNavigationOptions, k as isLocale, l as localizePath, p as pickLocale, r as resolveNavigation, s as stripLocalePrefix } from './index-_XBy9Y81.js';
+export { Cache, CacheOptions, KeyedCache, KeyedCacheOptions, createCache, createKeyedCache } from './cache/index.js';
+export { BrandfineWebhookEvent, BrandfineWebhookHandlerOptions, BrandfineWebhookPayload, createBrandfineWebhookHandler, parseWebhookPayload, verifyWebhookSecret } from './webhook/index.js';
+
+/**
+ * `createBrandfineClient` — the SDK's entry point.
+ *
+ * Returns a stateless, multi-instance-safe handle scoped to a
+ * single `(baseUrl, apiKey)` pair. Pattern follows the Stripe /
+ * Algolia / OpenAI SDKs — explicit construction with config,
+ * namespaced methods (`bf.posts.list(...)`, `bf.workspace.get()`),
+ * no module-level singletons.
+ *
+ * Why factory not module-level state: multi-tenant consumers
+ * sometimes need two clients in the same process (e.g. main site
+ * + admin preview). Module-level env reading makes that impossible
+ * without monkey-patching.
+ */
+
+type BrandfineClientConfig = {
+    /** Base URL of the Brandfine API. No trailing slash — the client
+     *  trims one if you pass it anyway. e.g. `https://api.brandfine.co` */
+    baseUrl: string;
+    /** Workspace-scoped API key. Generated from the cms's Workspace
+     *  settings; identifies which workspace the client talks to. */
+    apiKey: string;
+    /** Optional fetch override. Useful for tests (inject a stub),
+     *  for runtimes that need a custom implementation (edge workers
+     *  with non-standard fetch), or to add cross-cutting concerns
+     *  like tracing / retries. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Optional User-Agent header. Falls back to a generic SDK tag. */
+    userAgent?: string;
+};
+/**
+ * Structured error thrown by every request helper on non-2xx
+ * responses. Carries the raw body so consumers can log it for
+ * debugging without re-fetching.
+ */
+declare class BrandfineApiError extends Error {
+    readonly name = "BrandfineApiError";
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    readonly url: string;
+    constructor(args: {
+        status: number;
+        statusText: string;
+        body: string;
+        url: string;
+    });
+}
+type RequestOptions = {
+    /** When true and the response is 404, return `null` instead of
+     *  throwing. Used by endpoints where 404 is a meaningful empty
+     *  state (navigation by key, single post by slug). */
+    nullable404?: boolean;
+    signal?: AbortSignal;
+};
+type BrandfineClient = {
+    /** Low-level GET. Reserved for endpoints we don't have a typed
+     *  helper for yet. Adds the X-Api-Key header automatically. */
+    get: <T>(path: string, opts?: RequestOptions) => Promise<T>;
+    posts: PostsApi;
+    categories: CategoriesApi;
+    workspace: WorkspaceApi;
+    navigations: NavigationsApi;
+};
+type PostsApi = {
+    /** Paginated list of published posts. Handles the cms's
+     *  pagination transparently — caller gets a flat array. */
+    list: <TConfig = unknown>(opts?: ListPostsOptions) => Promise<BrandfinePost<TConfig>[]>;
+    /** Single post by per-locale URL slug, scoped to the active
+     *  locale on the workspace's content. Returns `null` for 404 so
+     *  callers can render their own "not found" page without try/catch. */
+    getBySlug: <TConfig = unknown>(slug: string) => Promise<BrandfinePost<TConfig> | null>;
+};
+type CategoriesApi = {
+    list: (opts?: ListCategoriesOptions) => Promise<BrandfineCategory[]>;
+};
+type WorkspaceApi = {
+    get: <TCustomConfig = Record<string, unknown>, TSchemaOrg = Record<string, unknown>>() => Promise<BrandfineWorkspace<TCustomConfig, TSchemaOrg>>;
+};
+type NavigationsApi = {
+    /** Navigation by its workspace-scoped `key` (e.g. `'header'`).
+     *  Returns `null` for 404 so consumers can fall back to a
+     *  hardcoded default without try/catch. */
+    get: (key: string) => Promise<BrandfineNavigation | null>;
+};
+declare function createBrandfineClient(config: BrandfineClientConfig): BrandfineClient;
+
+/**
+ * @brandfine/client — root entry.
+ *
+ * The full SDK surface is exposed here for "import everything from
+ * one place" usage. Tree-shaking + `sideEffects: false` mean
+ * consumers don't pay a bundle cost for what they don't import.
+ *
+ * Heavier or framework-coupled pieces still live under subpath
+ * exports (`@brandfine/client/cache`, `/resolvers`, `/webhook`) so
+ * consumers with poor tree-shaking — or who only need one slice —
+ * can scope their imports.
+ */
+declare const SDK_VERSION: "0.0.0";
+
+export { BrandfineApiError, BrandfineCategory, type BrandfineClient, type BrandfineClientConfig, BrandfineNavigation, BrandfinePost, BrandfineWorkspace, ListCategoriesOptions, ListPostsOptions, SDK_VERSION, createBrandfineClient };