@charleslemaux/cms 1.0.0-rc.1

package/dist/react.d.cts

@@ -0,0 +1,268 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+interface ArticleBodyProps extends Omit<HTMLAttributes<HTMLElement>, 'children' | 'dangerouslySetInnerHTML'> {
+    /** The article's `bodyHtml`. */
+    html: string;
+    /**
+     * Cleans the HTML once more before it is rendered, e.g. `(html) => DOMPurify.sanitize(html)`.
+     * Odoo already cleans `bodyHtml` with a strict allowlist: this is defence in depth.
+     */
+    sanitize?: (html: string) => string;
+    /** The wrapping element. Default: div. */
+    as?: 'div' | 'article' | 'section';
+}
+declare function ArticleBody({ html, sanitize, as: Tag, ...rest }: ArticleBodyProps): react.JSX.Element;
+
+/** 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 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>;
+}
+
+/** 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);
+}
+
+interface AsyncState<T> {
+    /** The answer, once it arrived. */
+    data: T | undefined;
+    error: CmsError | undefined;
+    loading: boolean;
+}
+declare function useZone(client: CmsClient, options?: {
+    lang?: string;
+}): AsyncState<Zone>;
+declare function useArticles(client: CmsClient, params?: Omit<ListArticlesParams, 'signal'>): AsyncState<Page<ArticleSummary>>;
+/** `data` is null when the article is not live on the zone. */
+declare function useArticle(client: CmsClient, slug: string | null | undefined, options?: {
+    lang?: string;
+}): AsyncState<Article | null>;
+
+interface NewsletterFormLabels {
+    email: string;
+    emailPlaceholder: string;
+    /** The consent checkbox's label; may hold a link to the privacy policy. */
+    consent: ReactNode;
+    submit: string;
+    sending: string;
+    sent: string;
+    invalidEmail: string;
+    consentRequired: string;
+    captchaRequired: string;
+    captchaFailed: string;
+    rateLimited: string;
+    unavailable: string;
+}
+interface NewsletterPageLabels {
+    confirmIntro: string;
+    confirmButton: string;
+    confirming: string;
+    confirmed: string;
+    unsubscribeIntro: string;
+    unsubscribeButton: string;
+    unsubscribing: string;
+    unsubscribed: string;
+    invalidLink: string;
+    noLink: string;
+    failed: string;
+}
+/** The form's labels in `lang` (English when there is no such set), with `overrides` on top. */
+declare function newsletterFormLabels(lang?: string, overrides?: Partial<NewsletterFormLabels>): NewsletterFormLabels;
+/** The newsletter page's labels in `lang` (English when there is no such set), with `overrides` on top. */
+declare function newsletterPageLabels(lang?: string, overrides?: Partial<NewsletterPageLabels>): NewsletterPageLabels;
+
+interface NewsletterFormProps {
+    client: CmsClient;
+    /** The visitor's language, e.g. "fr": the newsletter they join, and the captcha's and labels' language. */
+    lang?: string;
+    /** The zone's newsletter settings (`zone.newsletter`). Omitted: read with `client.getZone()`. */
+    settings?: NewsletterSettings;
+    /** Replaces some of the default labels. */
+    labels?: Partial<NewsletterFormLabels>;
+    className?: string;
+    captchaTheme?: 'auto' | 'light' | 'dark';
+    /** The confirmation email is on its way to this address. */
+    onSuccess?: (email: string) => void;
+    onError?: (error: CmsError) => void;
+}
+declare function NewsletterForm({ client, lang, settings: givenSettings, labels: overrides, className, captchaTheme, onSuccess, onError, }: NewsletterFormProps): react.JSX.Element | null;
+
+/** 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 NewsletterPageProps {
+    client: CmsClient;
+    /** Where the link's `?confirm=` or `?unsubscribe=` is read, e.g. Next.js `searchParams`. Default: the address bar. */
+    search?: NewsletterSource;
+    /** The labels' language. */
+    lang?: string;
+    labels?: Partial<NewsletterPageLabels>;
+    className?: string;
+    /** The subscription is confirmed, or cancelled. */
+    onDone?: (result: ConfirmResult | UnsubscribeResult) => void;
+    /** Remove the token from the address bar once done. Default: true. */
+    cleanUrl?: boolean;
+}
+/**
+ * The page a newsletter link opens. It shows one button and calls the API only on its click, so
+ * mailbox link scanners never confirm or unsubscribe anybody (spec 10).
+ */
+declare function NewsletterPage({ client, search, lang, labels: overrides, className, onDone, cleanUrl, }: NewsletterPageProps): react.JSX.Element;
+
+export { ArticleBody, type ArticleBodyProps, type AsyncState, NewsletterForm, type NewsletterFormLabels, type NewsletterFormProps, NewsletterPage, type NewsletterPageLabels, type NewsletterPageProps, newsletterFormLabels, newsletterPageLabels, useArticle, useArticles, useZone };

package/dist/react.d.ts

@@ -0,0 +1,268 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+interface ArticleBodyProps extends Omit<HTMLAttributes<HTMLElement>, 'children' | 'dangerouslySetInnerHTML'> {
+    /** The article's `bodyHtml`. */
+    html: string;
+    /**
+     * Cleans the HTML once more before it is rendered, e.g. `(html) => DOMPurify.sanitize(html)`.
+     * Odoo already cleans `bodyHtml` with a strict allowlist: this is defence in depth.
+     */
+    sanitize?: (html: string) => string;
+    /** The wrapping element. Default: div. */
+    as?: 'div' | 'article' | 'section';
+}
+declare function ArticleBody({ html, sanitize, as: Tag, ...rest }: ArticleBodyProps): react.JSX.Element;
+
+/** 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 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>;
+}
+
+/** 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);
+}
+
+interface AsyncState<T> {
+    /** The answer, once it arrived. */
+    data: T | undefined;
+    error: CmsError | undefined;
+    loading: boolean;
+}
+declare function useZone(client: CmsClient, options?: {
+    lang?: string;
+}): AsyncState<Zone>;
+declare function useArticles(client: CmsClient, params?: Omit<ListArticlesParams, 'signal'>): AsyncState<Page<ArticleSummary>>;
+/** `data` is null when the article is not live on the zone. */
+declare function useArticle(client: CmsClient, slug: string | null | undefined, options?: {
+    lang?: string;
+}): AsyncState<Article | null>;
+
+interface NewsletterFormLabels {
+    email: string;
+    emailPlaceholder: string;
+    /** The consent checkbox's label; may hold a link to the privacy policy. */
+    consent: ReactNode;
+    submit: string;
+    sending: string;
+    sent: string;
+    invalidEmail: string;
+    consentRequired: string;
+    captchaRequired: string;
+    captchaFailed: string;
+    rateLimited: string;
+    unavailable: string;
+}
+interface NewsletterPageLabels {
+    confirmIntro: string;
+    confirmButton: string;
+    confirming: string;
+    confirmed: string;
+    unsubscribeIntro: string;
+    unsubscribeButton: string;
+    unsubscribing: string;
+    unsubscribed: string;
+    invalidLink: string;
+    noLink: string;
+    failed: string;
+}
+/** The form's labels in `lang` (English when there is no such set), with `overrides` on top. */
+declare function newsletterFormLabels(lang?: string, overrides?: Partial<NewsletterFormLabels>): NewsletterFormLabels;
+/** The newsletter page's labels in `lang` (English when there is no such set), with `overrides` on top. */
+declare function newsletterPageLabels(lang?: string, overrides?: Partial<NewsletterPageLabels>): NewsletterPageLabels;
+
+interface NewsletterFormProps {
+    client: CmsClient;
+    /** The visitor's language, e.g. "fr": the newsletter they join, and the captcha's and labels' language. */
+    lang?: string;
+    /** The zone's newsletter settings (`zone.newsletter`). Omitted: read with `client.getZone()`. */
+    settings?: NewsletterSettings;
+    /** Replaces some of the default labels. */
+    labels?: Partial<NewsletterFormLabels>;
+    className?: string;
+    captchaTheme?: 'auto' | 'light' | 'dark';
+    /** The confirmation email is on its way to this address. */
+    onSuccess?: (email: string) => void;
+    onError?: (error: CmsError) => void;
+}
+declare function NewsletterForm({ client, lang, settings: givenSettings, labels: overrides, className, captchaTheme, onSuccess, onError, }: NewsletterFormProps): react.JSX.Element | null;
+
+/** 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 NewsletterPageProps {
+    client: CmsClient;
+    /** Where the link's `?confirm=` or `?unsubscribe=` is read, e.g. Next.js `searchParams`. Default: the address bar. */
+    search?: NewsletterSource;
+    /** The labels' language. */
+    lang?: string;
+    labels?: Partial<NewsletterPageLabels>;
+    className?: string;
+    /** The subscription is confirmed, or cancelled. */
+    onDone?: (result: ConfirmResult | UnsubscribeResult) => void;
+    /** Remove the token from the address bar once done. Default: true. */
+    cleanUrl?: boolean;
+}
+/**
+ * The page a newsletter link opens. It shows one button and calls the API only on its click, so
+ * mailbox link scanners never confirm or unsubscribe anybody (spec 10).
+ */
+declare function NewsletterPage({ client, search, lang, labels: overrides, className, onDone, cleanUrl, }: NewsletterPageProps): react.JSX.Element;
+
+export { ArticleBody, type ArticleBodyProps, type AsyncState, NewsletterForm, type NewsletterFormLabels, type NewsletterFormProps, NewsletterPage, type NewsletterPageLabels, type NewsletterPageProps, newsletterFormLabels, newsletterPageLabels, useArticle, useArticles, useZone };