@charleslemaux/cms 1.0.0-rc.1

package/dist/index.d.cts

@@ -0,0 +1,192 @@
+/** The payloads of the ICRC - CMS public API v1 (spec 7.3). JSON keys are camelCase. */
+interface Language {
+    /** API language code, e.g. "fr". */
+    code: string;
+    /** The name a visitor reads, e.g. "Français". */
+    name: string;
+}
+interface CategoryCount {
+    slug: string;
+    name: string;
+    /** Live articles of the zone in this category. */
+    count: number;
+}
+interface CaptchaSettings {
+    provider: 'turnstile';
+    siteKey: string;
+}
+interface NewsletterSettings {
+    enabled: boolean;
+    /** Null when the zone has no captcha: signups are then protected by rate limits only. */
+    captcha: CaptchaSettings | null;
+}
+interface Zone {
+    code: string;
+    name: string;
+    siteUrl: string;
+    /** The default language first. */
+    languages: Language[];
+    defaultLanguage: string;
+    newsletter: NewsletterSettings;
+    categories: CategoryCount[];
+}
+interface ImageSource {
+    width: number;
+    src: string;
+}
+interface Cover {
+    /** The largest version (1920 pixels wide at most). */
+    src: string;
+    width: number;
+    height: number;
+    alt: string;
+    caption: string;
+    /** Every version, smallest first: ready for srcset. */
+    sources: ImageSource[];
+}
+interface Category {
+    slug: string;
+    name: string;
+}
+interface Tag {
+    slug: string;
+    name: string;
+}
+interface Author {
+    name: string;
+    role: string;
+}
+interface ArticleSummary {
+    slug: string;
+    /** The article on this zone's website, in the served language. */
+    url: string;
+    /** The article on its primary website, in the served language. */
+    canonicalUrl: string;
+    /** The language served: the source language when `fallback` is true. */
+    lang: string;
+    sourceLang: string;
+    /** True when the article has no version in the asked language. */
+    fallback: boolean;
+    availableLangs: string[];
+    title: string;
+    subtitle: string;
+    excerpt: string;
+    cover: Cover | null;
+    category: Category | null;
+    tags: Tag[];
+    author: Author;
+    /** When the article went live on this zone (ISO 8601, UTC). */
+    publishedAt: string;
+    /** The latest change of the article or of the served translation (ISO 8601, UTC). */
+    updatedAt: string;
+    readingTimeMinutes: number;
+}
+interface Alternate {
+    lang: string;
+    url: string;
+}
+interface Article extends ArticleSummary {
+    /** Cleaned by Odoo with a strict allowlist (spec 7.6). */
+    bodyHtml: string;
+    /** The real translations, when the zone's article URL pattern has {lang}; else empty. */
+    alternates: Alternate[];
+    /** Up to 3 articles of the same zone. */
+    related: ArticleSummary[];
+}
+interface Page<T> {
+    items: T[];
+    page: number;
+    limit: number;
+    total: number;
+}
+interface SubscribeResult {
+    status: 'pending';
+}
+interface ConfirmResult {
+    status: 'confirmed';
+    zone: string;
+    lang: string;
+}
+interface UnsubscribeResult {
+    status: 'unsubscribed';
+    zone: string;
+}
+
+interface CmsClientOptions {
+    /** Address of the Odoo that serves the CMS, e.g. "https://b.projekts.com". */
+    baseUrl: string;
+    /** The zone (website) code, e.g. "projekts". */
+    zone: string;
+    /** A fetch implementation. Default: the global `fetch`, looked up at each call. */
+    fetch?: typeof fetch;
+    /** Added to the read calls, e.g. `{ next: { revalidate: 60 } }` in Next.js. Never to the newsletter calls. */
+    fetchOptions?: RequestInit & Record<string, unknown>;
+}
+interface ReadOptions {
+    /** "fr", "fr-FR" or "fr_FR". Default: the zone's default language. */
+    lang?: string;
+    /** Cancels the request. */
+    signal?: AbortSignal;
+}
+interface ListArticlesParams extends ReadOptions {
+    /** A category slug. */
+    category?: string;
+    /** A tag slug. */
+    tag?: string;
+    /** From 1. */
+    page?: number;
+    /** From 1 to 50. Default: 12. */
+    limit?: number;
+}
+interface SubscribeParams {
+    email: string;
+    /** Language of the newsletter the visitor joins. Default: the zone's default language. */
+    lang?: string;
+    /** The visitor ticked the consent box. */
+    consent: true;
+    /** The Cloudflare Turnstile token, when the zone has a captcha. */
+    captchaToken?: string;
+    /** The honeypot: people leave it empty. */
+    website?: string;
+}
+interface CmsClient {
+    readonly baseUrl: string;
+    readonly zone: string;
+    getZone(options?: ReadOptions): Promise<Zone>;
+    listArticles(params?: ListArticlesParams): Promise<Page<ArticleSummary>>;
+    /** Null when the article is not live on this zone. */
+    getArticle(slug: string, options?: ReadOptions): Promise<Article | null>;
+    /** Call it from the visitor's browser: Odoo checks the page's origin and limits signups per visitor. */
+    subscribe(params: SubscribeParams): Promise<SubscribeResult>;
+    confirm(token: string): Promise<ConfirmResult>;
+    unsubscribe(token: string): Promise<UnsubscribeResult>;
+}
+declare function createCmsClient(options: CmsClientOptions): CmsClient;
+
+/** What went wrong: the API's codes (spec 12), and three the client adds. */
+type CmsErrorCode = 'not_found' | 'invalid_request' | 'invalid_email' | 'consent_required' | 'origin_not_allowed' | 'captcha_failed' | 'captcha_unavailable' | 'invalid_token' | 'payload_too_large' | 'unsupported_media_type' | 'rate_limited' | 'network_error' | 'invalid_response' | 'http_error';
+declare class CmsError extends Error {
+    /** The HTTP status; 0 when the CMS could not be reached. */
+    readonly status: number;
+    readonly code: CmsErrorCode | (string & {});
+    /** Seconds to wait before trying again, on a 429. */
+    readonly retryAfter?: number;
+    constructor(status: number, code: CmsErrorCode | (string & {}), message: string, retryAfter?: number);
+}
+/** True for a CmsError, including one thrown by another copy of this package. */
+declare function isCmsError(value: unknown): value is CmsError;
+
+/** Where a newsletter page reads its link: a URL, a path, a query string, URLSearchParams or Next.js searchParams. */
+type NewsletterSource = string | URL | URLSearchParams | Record<string, string | string[] | undefined>;
+interface NewsletterAction {
+    action: 'confirm' | 'unsubscribe';
+    token: string;
+}
+/**
+ * The action a newsletter link asks for: `?confirm=<token>` or `?unsubscribe=<token>`.
+ * Null when there is none, when the token is malformed, or when the link is ambiguous
+ * (both parameters, or one given twice).
+ */
+declare function readNewsletterAction(source: NewsletterSource | null | undefined): NewsletterAction | null;
+
+export { type Alternate, type Article, type ArticleSummary, type Author, type CaptchaSettings, type Category, type CategoryCount, type CmsClient, type CmsClientOptions, CmsError, type CmsErrorCode, type ConfirmResult, type Cover, type ImageSource, type Language, type ListArticlesParams, type NewsletterAction, type NewsletterSettings, type NewsletterSource, type Page, type ReadOptions, type SubscribeParams, type SubscribeResult, type Tag, type UnsubscribeResult, type Zone, createCmsClient, isCmsError, readNewsletterAction };

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+/** The payloads of the ICRC - CMS public API v1 (spec 7.3). JSON keys are camelCase. */
+interface Language {
+    /** API language code, e.g. "fr". */
+    code: string;
+    /** The name a visitor reads, e.g. "Français". */
+    name: string;
+}
+interface CategoryCount {
+    slug: string;
+    name: string;
+    /** Live articles of the zone in this category. */
+    count: number;
+}
+interface CaptchaSettings {
+    provider: 'turnstile';
+    siteKey: string;
+}
+interface NewsletterSettings {
+    enabled: boolean;
+    /** Null when the zone has no captcha: signups are then protected by rate limits only. */
+    captcha: CaptchaSettings | null;
+}
+interface Zone {
+    code: string;
+    name: string;
+    siteUrl: string;
+    /** The default language first. */
+    languages: Language[];
+    defaultLanguage: string;
+    newsletter: NewsletterSettings;
+    categories: CategoryCount[];
+}
+interface ImageSource {
+    width: number;
+    src: string;
+}
+interface Cover {
+    /** The largest version (1920 pixels wide at most). */
+    src: string;
+    width: number;
+    height: number;
+    alt: string;
+    caption: string;
+    /** Every version, smallest first: ready for srcset. */
+    sources: ImageSource[];
+}
+interface Category {
+    slug: string;
+    name: string;
+}
+interface Tag {
+    slug: string;
+    name: string;
+}
+interface Author {
+    name: string;
+    role: string;
+}
+interface ArticleSummary {
+    slug: string;
+    /** The article on this zone's website, in the served language. */
+    url: string;
+    /** The article on its primary website, in the served language. */
+    canonicalUrl: string;
+    /** The language served: the source language when `fallback` is true. */
+    lang: string;
+    sourceLang: string;
+    /** True when the article has no version in the asked language. */
+    fallback: boolean;
+    availableLangs: string[];
+    title: string;
+    subtitle: string;
+    excerpt: string;
+    cover: Cover | null;
+    category: Category | null;
+    tags: Tag[];
+    author: Author;
+    /** When the article went live on this zone (ISO 8601, UTC). */
+    publishedAt: string;
+    /** The latest change of the article or of the served translation (ISO 8601, UTC). */
+    updatedAt: string;
+    readingTimeMinutes: number;
+}
+interface Alternate {
+    lang: string;
+    url: string;
+}
+interface Article extends ArticleSummary {
+    /** Cleaned by Odoo with a strict allowlist (spec 7.6). */
+    bodyHtml: string;
+    /** The real translations, when the zone's article URL pattern has {lang}; else empty. */
+    alternates: Alternate[];
+    /** Up to 3 articles of the same zone. */
+    related: ArticleSummary[];
+}
+interface Page<T> {
+    items: T[];
+    page: number;
+    limit: number;
+    total: number;
+}
+interface SubscribeResult {
+    status: 'pending';
+}
+interface ConfirmResult {
+    status: 'confirmed';
+    zone: string;
+    lang: string;
+}
+interface UnsubscribeResult {
+    status: 'unsubscribed';
+    zone: string;
+}
+
+interface CmsClientOptions {
+    /** Address of the Odoo that serves the CMS, e.g. "https://b.projekts.com". */
+    baseUrl: string;
+    /** The zone (website) code, e.g. "projekts". */
+    zone: string;
+    /** A fetch implementation. Default: the global `fetch`, looked up at each call. */
+    fetch?: typeof fetch;
+    /** Added to the read calls, e.g. `{ next: { revalidate: 60 } }` in Next.js. Never to the newsletter calls. */
+    fetchOptions?: RequestInit & Record<string, unknown>;
+}
+interface ReadOptions {
+    /** "fr", "fr-FR" or "fr_FR". Default: the zone's default language. */
+    lang?: string;
+    /** Cancels the request. */
+    signal?: AbortSignal;
+}
+interface ListArticlesParams extends ReadOptions {
+    /** A category slug. */
+    category?: string;
+    /** A tag slug. */
+    tag?: string;
+    /** From 1. */
+    page?: number;
+    /** From 1 to 50. Default: 12. */
+    limit?: number;
+}
+interface SubscribeParams {
+    email: string;
+    /** Language of the newsletter the visitor joins. Default: the zone's default language. */
+    lang?: string;
+    /** The visitor ticked the consent box. */
+    consent: true;
+    /** The Cloudflare Turnstile token, when the zone has a captcha. */
+    captchaToken?: string;
+    /** The honeypot: people leave it empty. */
+    website?: string;
+}
+interface CmsClient {
+    readonly baseUrl: string;
+    readonly zone: string;
+    getZone(options?: ReadOptions): Promise<Zone>;
+    listArticles(params?: ListArticlesParams): Promise<Page<ArticleSummary>>;
+    /** Null when the article is not live on this zone. */
+    getArticle(slug: string, options?: ReadOptions): Promise<Article | null>;
+    /** Call it from the visitor's browser: Odoo checks the page's origin and limits signups per visitor. */
+    subscribe(params: SubscribeParams): Promise<SubscribeResult>;
+    confirm(token: string): Promise<ConfirmResult>;
+    unsubscribe(token: string): Promise<UnsubscribeResult>;
+}
+declare function createCmsClient(options: CmsClientOptions): CmsClient;
+
+/** What went wrong: the API's codes (spec 12), and three the client adds. */
+type CmsErrorCode = 'not_found' | 'invalid_request' | 'invalid_email' | 'consent_required' | 'origin_not_allowed' | 'captcha_failed' | 'captcha_unavailable' | 'invalid_token' | 'payload_too_large' | 'unsupported_media_type' | 'rate_limited' | 'network_error' | 'invalid_response' | 'http_error';
+declare class CmsError extends Error {
+    /** The HTTP status; 0 when the CMS could not be reached. */
+    readonly status: number;
+    readonly code: CmsErrorCode | (string & {});
+    /** Seconds to wait before trying again, on a 429. */
+    readonly retryAfter?: number;
+    constructor(status: number, code: CmsErrorCode | (string & {}), message: string, retryAfter?: number);
+}
+/** True for a CmsError, including one thrown by another copy of this package. */
+declare function isCmsError(value: unknown): value is CmsError;
+
+/** Where a newsletter page reads its link: a URL, a path, a query string, URLSearchParams or Next.js searchParams. */
+type NewsletterSource = string | URL | URLSearchParams | Record<string, string | string[] | undefined>;
+interface NewsletterAction {
+    action: 'confirm' | 'unsubscribe';
+    token: string;
+}
+/**
+ * The action a newsletter link asks for: `?confirm=<token>` or `?unsubscribe=<token>`.
+ * Null when there is none, when the token is malformed, or when the link is ambiguous
+ * (both parameters, or one given twice).
+ */
+declare function readNewsletterAction(source: NewsletterSource | null | undefined): NewsletterAction | null;
+
+export { type Alternate, type Article, type ArticleSummary, type Author, type CaptchaSettings, type Category, type CategoryCount, type CmsClient, type CmsClientOptions, CmsError, type CmsErrorCode, type ConfirmResult, type Cover, type ImageSource, type Language, type ListArticlesParams, type NewsletterAction, type NewsletterSettings, type NewsletterSource, type Page, type ReadOptions, type SubscribeParams, type SubscribeResult, type Tag, type UnsubscribeResult, type Zone, createCmsClient, isCmsError, readNewsletterAction };

package/dist/index.js

@@ -0,0 +1,192 @@
+// src/errors.ts
+var CmsError = class extends Error {
+  constructor(status, code, message, retryAfter) {
+    super(message);
+    this.name = "CmsError";
+    this.status = status;
+    this.code = code;
+    if (retryAfter !== void 0) this.retryAfter = retryAfter;
+  }
+};
+function isCmsError(value) {
+  return value instanceof Error && value.name === "CmsError" && typeof value.status === "number" && typeof value.code === "string";
+}
+
+// src/client.ts
+var API_PATH = "/cms/api/v1";
+function createCmsClient(options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const zone = typeof options.zone === "string" ? options.zone.trim() : "";
+  if (!zone) {
+    throw new TypeError('createCmsClient: `zone` is required, e.g. "projekts".');
+  }
+  const zonePath = `${API_PATH}/zones/${encodeURIComponent(zone)}`;
+  async function send(path, init, query) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new TypeError("createCmsClient: no fetch available here. Pass `fetch` in the options.");
+    }
+    let response;
+    try {
+      response = await fetchImpl(buildUrl(baseUrl, path, query), init);
+    } catch (error) {
+      if (isAbortError(error) || init.signal?.aborted) throw error;
+      throw new CmsError(0, "network_error", `Could not reach ${baseUrl}: ${describeError(error)}`);
+    }
+    if (!response.ok) {
+      throw await errorFromResponse(response, init.signal);
+    }
+    try {
+      return await response.json();
+    } catch (error) {
+      if (isAbortError(error) || init.signal?.aborted) throw error;
+      throw new CmsError(response.status, "invalid_response", "The CMS did not answer with JSON.");
+    }
+  }
+  function read(path, query, signal) {
+    const extra = options.fetchOptions ?? {};
+    const headers = new Headers(extra.headers);
+    headers.set("Accept", "application/json");
+    return send(path, { ...extra, method: "GET", headers, signal: signal ?? extra.signal }, query);
+  }
+  function post(path, body) {
+    return send(path, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify(body),
+      referrerPolicy: "no-referrer"
+    });
+  }
+  return {
+    baseUrl,
+    zone,
+    getZone: (readOptions = {}) => read(zonePath, { lang: readOptions.lang }, readOptions.signal),
+    listArticles: (params = {}) => read(
+      `${zonePath}/articles`,
+      { lang: params.lang, category: params.category, tag: params.tag, page: params.page, limit: params.limit },
+      params.signal
+    ),
+    async getArticle(slug, readOptions = {}) {
+      if (typeof slug !== "string" || !slug) {
+        throw new TypeError("getArticle: `slug` is required.");
+      }
+      try {
+        return await read(
+          `${zonePath}/articles/${encodeURIComponent(slug)}`,
+          { lang: readOptions.lang },
+          readOptions.signal
+        );
+      } catch (error) {
+        if (isCmsError(error) && error.status === 404) return null;
+        throw error;
+      }
+    },
+    subscribe: (params) => post(`${zonePath}/newsletter/subscribe`, {
+      email: params.email,
+      lang: params.lang,
+      consent: params.consent,
+      captchaToken: params.captchaToken,
+      website: params.website ?? ""
+    }),
+    confirm: (token) => post(`${API_PATH}/newsletter/confirm`, { token }),
+    unsubscribe: (token) => post(`${API_PATH}/newsletter/unsubscribe`, { token })
+  };
+}
+function normalizeBaseUrl(value) {
+  const text = typeof value === "string" ? value.trim() : "";
+  let url;
+  try {
+    url = new URL(text);
+  } catch {
+    url = void 0;
+  }
+  if (!url || url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new TypeError(
+      `createCmsClient: \`baseUrl\` must be an absolute http(s) address such as "https://b.projekts.com", not "${text}".`
+    );
+  }
+  return `${url.origin}${url.pathname}`.replace(/\/+$/, "");
+}
+function buildUrl(baseUrl, path, query = {}) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0 && value !== "") search.set(key, String(value));
+  }
+  const text = search.toString();
+  return `${baseUrl}${path}${text ? `?${text}` : ""}`;
+}
+async function errorFromResponse(response, signal) {
+  const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+  let code = "http_error";
+  let message = `The CMS answered with the status ${response.status}.`;
+  try {
+    const data = await response.json();
+    const error = isRecord(data) && isRecord(data.error) ? data.error : void 0;
+    if (error && typeof error.code === "string") {
+      code = error.code;
+      if (typeof error.message === "string") message = error.message;
+    }
+  } catch (error) {
+    if (isAbortError(error) || signal?.aborted) throw error;
+  }
+  return new CmsError(response.status, code, message, retryAfter);
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, Math.ceil(seconds));
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, Math.ceil((date - Date.now()) / 1e3));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isAbortError(error) {
+  return isRecord(error) && error.name === "AbortError";
+}
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/newsletter-action.ts
+var ACTIONS = ["confirm", "unsubscribe"];
+var TOKEN_RE = /^[A-Za-z0-9_-]{16,512}$/;
+function readNewsletterAction(source) {
+  if (source == null) return null;
+  const params = toSearchParams(source);
+  let found = null;
+  for (const action of ACTIONS) {
+    const values = params.getAll(action);
+    if (values.length === 0) continue;
+    if (values.length > 1 || found) return null;
+    found = { action, token: values[0] ?? "" };
+  }
+  return found && TOKEN_RE.test(found.token) ? found : null;
+}
+function toSearchParams(source) {
+  if (typeof source === "string") {
+    const query = source.includes("?") ? source.slice(source.indexOf("?") + 1) : source;
+    return new URLSearchParams(query.split("#")[0]);
+  }
+  if (isSearchParams(source)) return source;
+  if (isUrl(source)) return source.searchParams;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(source)) {
+    const values = Array.isArray(value) ? value : value === void 0 ? [] : [value];
+    for (const item of values) params.append(key, item);
+  }
+  return params;
+}
+function isSearchParams(value) {
+  return typeof value.getAll === "function" && typeof value.append === "function";
+}
+function isUrl(value) {
+  const url = value;
+  return typeof url.href === "string" && typeof url.searchParams === "object" && isSearchParams(url.searchParams);
+}
+export {
+  CmsError,
+  createCmsClient,
+  isCmsError,
+  readNewsletterAction
+};