@botlr/next 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,383 @@
+import { BotlrClient, BotlrClientConfig, PublisherScope, PageResponse, LayoutNode } from '@botlr/sdk';
+export * from '@botlr/sdk';
+export { BotlrConflictError, BotlrError, createAssetUrl, createBotlrClient, getAssetFilename, getAssetId, getAssetUrl, isAssetData } from '@botlr/sdk';
+import { Metadata } from 'next';
+import * as react$1 from 'react';
+import { ReactNode, JSX } from 'react';
+import { ComponentRegistry } from '@botlr/react';
+export * from '@botlr/react';
+
+type GetBotlrParams = {
+    /** The app instance ID. Falls back to `BOTLR_APP_ID`. */
+    appId?: string;
+    /** Locale override; defaults to the request's `Accept-Language`, then `en`. */
+    locale?: string;
+    preview?: boolean;
+    /** Site token; falls back to `BOTLR_API_KEY`. Omit in dev mode. */
+    apiKey?: string;
+    /** Preview JWT, forwarded to `/api/resolve` in preview mode. */
+    previewToken?: string;
+    /** API origin; falls back to `BOTLR_API_URL`. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+};
+/**
+ * A Botlr client for the current request, for Server Components, route
+ * handlers and server actions. Reads the locale from `Accept-Language`
+ * unless given.
+ *
+ * ```ts
+ * const botlr = await getBotlrForRoute({ appId: scope.appInstanceId, locale: scope.locale, preview });
+ * const pages = await botlr.getPageList({ tags: ["news"] });
+ * ```
+ */
+declare function getBotlrForRoute(params?: GetBotlrParams): Promise<BotlrClient>;
+/**
+ * `getBotlrForRoute` memoised per request with React `cache`, so several
+ * components in one render share a client.
+ */
+declare const getCachedBotlr: (params?: GetBotlrParams) => Promise<BotlrClient>;
+/**
+ * A client from the environment alone, with no request context. For scripts,
+ * `generateStaticParams`, instrumentation and anywhere `headers()` is not
+ * available.
+ */
+declare function createBotlrFromEnv(overrides?: Partial<GetBotlrParams>): BotlrClient;
+
+/** Environment variables the helpers read. All server-side: the API URL is never exposed to the browser. */
+declare const BOTLR_ENV: {
+    readonly apiUrl: "BOTLR_API_URL";
+    readonly apiKey: "BOTLR_API_KEY";
+    readonly appId: "BOTLR_APP_ID";
+    readonly pat: "BOTLR_PAT";
+    readonly orgSlug: "BOTLR_ORG_SLUG";
+    readonly projectSlug: "BOTLR_PROJECT_SLUG";
+    readonly appInstanceSlug: "BOTLR_APP_INSTANCE_SLUG";
+    readonly environment: "BOTLR_ENVIRONMENT";
+};
+declare const DEFAULT_API_URL = "http://localhost:8888";
+/**
+ * Client config from the environment, with `overrides` winning. Throws when
+ * no app id is known, since every Botlr request needs one.
+ */
+declare function configFromEnv(overrides?: Partial<BotlrClientConfig>): BotlrClientConfig;
+/**
+ * The deployment environment used by visibility rules: `BOTLR_ENVIRONMENT`,
+ * then `ENVIRONMENT`, then `NODE_ENV`, then `fallback`.
+ */
+declare function environmentFromEnv(fallback?: string): string;
+/**
+ * The `PublisherScope` for a locale from `BOTLR_ORG_SLUG`, `BOTLR_PROJECT_SLUG`,
+ * `BOTLR_APP_INSTANCE_SLUG` and `BOTLR_APP_ID`, with `overrides` winning.
+ * Missing slugs become empty strings rather than errors, since only asset
+ * URLs need them.
+ */
+declare function scopeFromEnv(overrides: Partial<PublisherScope> & Pick<PublisherScope, "locale">): PublisherScope;
+
+/** The first language of an `Accept-Language` value, or `fallback`. */
+declare function localeFromAcceptLanguage(header: string | null | undefined, fallback?: string): string;
+
+type ResolvedPage = {
+    kind: "page";
+    pageData: PageResponse;
+} | {
+    kind: "redirect";
+    destination: string;
+} | {
+    kind: "404";
+} | {
+    kind: "error";
+    message: string;
+};
+interface ResolvePageOptions {
+    /**
+     * Non-page content types rendered through a section: the resolved content
+     * is prepended to the `main` region as an inline section of the mapped
+     * type. Defaults to `{ article: "article" }`.
+     */
+    contentSections?: Record<string, string>;
+}
+/**
+ * Resolves a slug to a page through `/api/resolve`, folding redirects, 404s
+ * and errors into one result and injecting article content into the layout.
+ * Not cached; see `createPageResolver`.
+ */
+declare function resolvePage(client: BotlrClient, slug: string, locale?: string, options?: ResolvePageOptions): Promise<ResolvedPage>;
+/**
+ * `resolvePage` bound to a client and memoised per request with React
+ * `cache`, so `generateMetadata` and the page share one fetch.
+ *
+ * ```ts
+ * const resolvePage = createPageResolver(botlr);
+ * const resolved = await resolvePage("about/team", "en");
+ * ```
+ */
+declare function createPageResolver(client: BotlrClient, options?: ResolvePageOptions): (slug: string, locale?: string) => Promise<ResolvedPage>;
+
+interface PageMetadataOptions {
+    /**
+     * The site origin, for example `https://www.example.com`. Needed for the
+     * canonical URL and hreflang alternates; without it only an explicit
+     * `seo_meta.canonical` is emitted.
+     */
+    siteUrl?: string;
+    /** URL prefix of the page's locale, for example `/en`. Empty for the root locale. */
+    folder?: string;
+}
+/**
+ * Next.js `Metadata` from a page's `seo_meta`: title, description, keywords,
+ * Open Graph, Twitter, robots, canonical and hreflang alternates.
+ */
+declare function buildPageMetadata(pageData: PageResponse, options?: PageMetadataOptions): Metadata;
+
+type Layout = Record<string, LayoutNode[]>;
+interface RenderCmsPageOptions {
+    pageData: PageResponse;
+    scope: PublisherScope;
+    /** Section type to component map used for every region. */
+    componentRegistry: ComponentRegistry;
+    /** Defaults to `"published"`; `"draft"` also renders draft sections. */
+    mode?: "draft" | "published";
+    /** Defaults to `scope.locale`. */
+    locale?: string;
+    /** Environment for visibility rules; defaults to `environmentFromEnv()`. */
+    environment?: string;
+    /** Used to fetch shared sections unless `fetchSharedSection` is given. */
+    client?: BotlrClient;
+    /** Fetch a shared section's page by id. Defaults to `client.getPageBySlug(id, locale)`. */
+    fetchSharedSection?: (id: string) => Promise<{
+        layout?: Partial<Layout>;
+    } | null>;
+    /** Show a fixed "draft/published preview" badge; for preview routes only. */
+    showModeBadge?: boolean;
+    /** Rendered when the template cannot be parsed. */
+    renderError?: (error: unknown) => ReactNode;
+}
+/** Ids of every shared section in the layout, grid columns included. */
+declare function collectSharedSectionIds(nodes: LayoutNode[]): string[];
+/**
+ * The template's `{{...}}` placeholders resolved: title, lang, theme css,
+ * `{{{REGION}}}` markers turned into text markers for the parser, and the
+ * body extracted.
+ */
+declare function prepareTemplate(templateHtml: string, pageData: PageResponse, templateCss: string, locale: string): string;
+/** Template sections first, then the page's own, per region. */
+declare function mergeTemplateLayout(pageData: PageResponse): Layout;
+/**
+ * Renders a resolved page: picks the page template (page, then theme, then a
+ * built-in default), merges template and page layouts, applies visibility
+ * rules, fetches shared sections and mounts a `SectionRenderer` at every
+ * `{{{REGION}}}` marker.
+ */
+declare function renderCmsPage({ pageData, scope, componentRegistry, mode, locale, environment, client, fetchSharedSection, showModeBadge, renderError, }: RenderCmsPageOptions): Promise<JSX.Element>;
+
+interface ThemeColorSet {
+    primary?: string;
+    primaryForeground?: string;
+    secondary?: string;
+    secondaryForeground?: string;
+    accent?: string;
+    accentForeground?: string;
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    mutedForeground?: string;
+    border?: string;
+    input?: string;
+    ring?: string;
+    destructive?: string;
+    destructiveForeground?: string;
+    success?: string;
+    successForeground?: string;
+    warning?: string;
+    warningForeground?: string;
+    info?: string;
+    infoForeground?: string;
+}
+interface ThemeSettings {
+    colors?: {
+        light?: ThemeColorSet;
+        dark?: ThemeColorSet;
+    };
+    typography?: {
+        fontFamily?: {
+            heading?: string;
+            body?: string;
+            ui?: string;
+            code?: string;
+            sans?: string;
+            serif?: string;
+            mono?: string;
+        };
+        fontSize?: {
+            h1?: string;
+            h2?: string;
+            h3?: string;
+            h4?: string;
+            h5?: string;
+            h6?: string;
+            xs?: string;
+            sm?: string;
+            base?: string;
+            lg?: string;
+            xl?: string;
+            "2xl"?: string;
+            "3xl"?: string;
+            "4xl"?: string;
+        };
+        fontWeight?: {
+            normal?: string;
+            medium?: string;
+            semibold?: string;
+            bold?: string;
+        };
+        lineHeight?: {
+            tight?: string;
+            normal?: string;
+            relaxed?: string;
+        };
+    };
+    spacing?: {
+        xs?: string;
+        sm?: string;
+        md?: string;
+        lg?: string;
+        xl?: string;
+        "2xl"?: string;
+    };
+    borderRadius?: {
+        none?: string;
+        sm?: string;
+        md?: string;
+        lg?: string;
+        xl?: string;
+        full?: string;
+    };
+    shadows?: {
+        sm?: string;
+        md?: string;
+        lg?: string;
+        xl?: string;
+    };
+    layout?: {
+        containerMaxWidth?: string;
+        sidebarWidth?: string;
+        headerHeight?: string;
+        footerHeight?: string;
+    };
+}
+/**
+ * Theme settings as CSS custom properties: common variables and light colors
+ * on `:root`, dark colors under `prefers-color-scheme: dark` and `.dark`.
+ */
+declare function themeSettingsToCss(settings?: ThemeSettings | Record<string, any>): string;
+
+interface StaticTextFileOptions {
+    /** Defaults to the client's locale, then `en`. */
+    locale?: string;
+    /** Environment for visibility rules; defaults to `environmentFromEnv()`. */
+    environment?: string;
+    /** The section type whose content is served; defaults to `text`. */
+    sectionType?: string;
+    /** Section props tried in order for the text; defaults to `content`, `body`, `text`. */
+    propKeys?: string[];
+}
+/**
+ * A CMS-managed plain-text file such as `robots.txt`, `humans.txt` or
+ * `llms.txt`: the page at `slug`, its visible text sections concatenated.
+ * Serves `defaultContent` when the page has none or cannot be fetched.
+ *
+ * ```ts
+ * // app/robots.txt/route.ts
+ * export const GET = () => serveStaticTextFile(botlr, "robots.txt", defaultRobotsContent());
+ * ```
+ */
+declare function serveStaticTextFile(client: BotlrClient, slug: string, defaultContent: string, options?: StaticTextFileOptions): Promise<Response>;
+/** Allow everything in production, disallow everything elsewhere. */
+declare function defaultRobotsContent(environment?: string): string;
+
+interface LocalePageConfig {
+    /** CMS locale code, for example `da` or `en`. */
+    locale: string;
+    /** URL prefix for this locale, for example `/en`. Empty for the root locale. */
+    folder?: string;
+    /** The client the pages are fetched with; usually one built with `createBotlrFromEnv`. */
+    client: BotlrClient;
+    componentRegistry: ComponentRegistry;
+    /** Overrides on the scope built from the environment. */
+    scope?: Partial<PublisherScope>;
+    /** The site origin, for canonical and hreflang metadata. */
+    siteUrl?: string;
+    /** Environment for visibility rules; defaults to `environmentFromEnv()`. */
+    environment?: string;
+    resolveOptions?: ResolvePageOptions;
+    /** Redirect kind for CMS redirects; defaults to `permanent` (308). */
+    redirect?: "permanent" | "temporary";
+    /** Page slugs fetched for `generateStaticParams`; defaults to 1000. */
+    staticParamsLimit?: number;
+    /** Rendered when resolving fails. */
+    renderError?: (message: string) => ReactNode;
+}
+interface LocalePageProps {
+    params: Promise<{
+        slug?: string[];
+    }>;
+    searchParams?: Promise<Record<string, string | string[] | undefined>>;
+}
+/** The page slug for a catch-all route: the segments joined, or `index`. */
+declare function pageSlugFromParams(params: LocalePageProps["params"]): Promise<string>;
+/**
+ * Everything a static per-locale `[[...slug]]` route needs. The route file
+ * keeps only its segment config, which Next must read statically:
+ *
+ * ```ts
+ * // app/(root)/[[...slug]]/page.tsx
+ * export const revalidate = false;
+ * export const dynamicParams = false;
+ * const page = createLocalePage({ locale: "da", folder: "", client: botlr, componentRegistry });
+ * export const generateStaticParams = page.generateStaticParams;
+ * export const generateMetadata = page.generateMetadata;
+ * export default page.Page;
+ * ```
+ */
+declare function createLocalePage(config: LocalePageConfig): {
+    generateStaticParams: () => Promise<{
+        slug?: string[];
+    }[]>;
+    generateMetadata: ({ params }: LocalePageProps) => Promise<Metadata>;
+    Page: ({ params }: LocalePageProps) => Promise<react$1.JSX.Element>;
+    resolvePage: (slug: string, locale?: string) => Promise<ResolvedPage>;
+    scope: PublisherScope;
+};
+/**
+ * A locale folder that only aliases another, for example `/se/*` to `/sv/*`.
+ * Permanently redirects, keeping the rest of the path.
+ */
+declare function createLocaleAliasPage(targetFolder: string): ({ params }: LocalePageProps) => Promise<never>;
+
+interface RateLimitConfig {
+    /** Max requests allowed in the window */
+    limit: number;
+    /** Window size in seconds */
+    window: number;
+}
+interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    /** Epoch ms when the window resets */
+    resetAt: number;
+}
+/**
+ * A fixed-window in-memory rate limit, per server instance. Enough to slow
+ * down form and forum spam; not shared across instances or restarts.
+ *
+ * ```ts
+ * const rl = rateLimit(`form:${getClientIp(request)}`, { limit: 5, window: 60 });
+ * if (!rl.allowed) return new Response("Too many requests", { status: 429 });
+ * ```
+ */
+declare function rateLimit(key: string, config: RateLimitConfig): RateLimitResult;
+/** The client IP from `x-forwarded-for` or `x-real-ip`, or `"unknown"`. */
+declare function getClientIp(request: Request): string;
+
+export { BOTLR_ENV, DEFAULT_API_URL, type GetBotlrParams, type LocalePageConfig, type LocalePageProps, type PageMetadataOptions, type RateLimitConfig, type RateLimitResult, type RenderCmsPageOptions, type ResolvePageOptions, type ResolvedPage, type StaticTextFileOptions, type ThemeColorSet, type ThemeSettings, buildPageMetadata, collectSharedSectionIds, configFromEnv, createBotlrFromEnv, createLocaleAliasPage, createLocalePage, createPageResolver, defaultRobotsContent, environmentFromEnv, getBotlrForRoute, getCachedBotlr, getClientIp, localeFromAcceptLanguage, mergeTemplateLayout, pageSlugFromParams, prepareTemplate, rateLimit, renderCmsPage, resolvePage, scopeFromEnv, serveStaticTextFile, themeSettingsToCss };