@siteping/server 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+[![npm version](https://img.shields.io/npm/v/@siteping/server)](https://www.npmjs.com/package/@siteping/server)
+[![Docs](https://img.shields.io/badge/docs-siteping.dev-0066ff)](https://siteping.dev/docs/server)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @siteping/server
+
+The HTTP endpoint of [SitePing](https://github.com/NeosiaNexus/SitePing) over any store, for any framework — validation, auth, CORS, redaction, hooks and webhooks on the Fetch API. No Node built-in: it runs on Node, Bun, Deno and edge workers.
+
+**[Documentation](https://siteping.dev/docs/server)**
+
+## Install
+
+```bash
+npm install @siteping/server
+```
+
+Node ≥ 20, or any runtime with the Fetch API.
+
+## Quick start
+
+```ts
+// app/api/siteping/route.ts — Next.js App Router
+import { createSitepingHandler } from "@siteping/server";
+import { store } from "@/lib/siteping-store"; // Drizzle, memory, Prisma or your own
+
+export const { GET, POST, PATCH, DELETE, OPTIONS } = createSitepingHandler({
+  store,
+  apiKey: process.env.SITEPING_API_KEY,    // Bearer auth — or `access` for your own sessions
+  allowedOrigins: ["https://my-site.com"], // exact-match CORS
+});
+```
+
+One handler per method, Web-standard `Request` → `Response`: mount them from Hono, Express, Remix, SvelteKit, `Bun.serve` or a Worker.
+
+## Documentation
+
+Mounting recipes, every option, custom access with CSRF protection, lifecycle hooks, the full HTTP reference and webhooks: **[siteping.dev/docs/server](https://siteping.dev/docs/server)**.
+
+## License
+
+[MIT](https://github.com/NeosiaNexus/SitePing/blob/main/LICENSE)

package/dist/concurrency.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Run `task` over every item with at most `concurrency` calls in flight and
+ * settle each call on its own, like `Promise.allSettled` over a bounded pool.
+ *
+ * Each call runs inside its own promise, so a task that throws synchronously
+ * is settled as a rejection instead of stopping the pool, and one failure
+ * never skips the remaining items.
+ *
+ * @param items - Inputs, processed in order.
+ * @param concurrency - Maximum number of simultaneous `task` calls (at least 1).
+ * @param task - Operation to run for each item.
+ * @returns The settled result of every call, in the order of `items`.
+ */
+export declare function settleWithConcurrencyLimit<Item, Result>(items: readonly Item[], concurrency: number, task: (item: Item) => Promise<Result>): Promise<Array<PromiseSettledResult<Result>>>;

package/dist/concurrency.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Run `task` over every item with at most `concurrency` calls in flight and
+ * settle each call on its own, like `Promise.allSettled` over a bounded pool.
+ *
+ * Each call runs inside its own promise, so a task that throws synchronously
+ * is settled as a rejection instead of stopping the pool, and one failure
+ * never skips the remaining items.
+ *
+ * @param items - Inputs, processed in order.
+ * @param concurrency - Maximum number of simultaneous `task` calls (at least 1).
+ * @param task - Operation to run for each item.
+ * @returns The settled result of every call, in the order of `items`.
+ */
+export declare function settleWithConcurrencyLimit<Item, Result>(items: readonly Item[], concurrency: number, task: (item: Item) => Promise<Result>): Promise<Array<PromiseSettledResult<Result>>>;

package/dist/deep-link.d.cts

@@ -0,0 +1,14 @@
+import type { FeedbackRecord } from "./types.cjs";
+/**
+ * `url` resolved against `base`, when the result is an http(s) URL. A
+ * record's `url` is client-supplied: without the scheme allowlist, a crafted
+ * feedback (`javascript:…`, `data:…`) would turn into a live link.
+ */
+export declare function parseHttpUrl(url: string, base?: string): URL | null;
+/**
+ * Link that opens a feedback's page with the widget focused on it —
+ * `?<param>=<id>`, read by the widget's `deepLink` option. Relative record
+ * URLs (the widget stores `location.pathname` by default) resolve against
+ * `base`. Null when there is no safe http(s) target.
+ */
+export declare function buildDeepLink(record: Pick<FeedbackRecord, "id" | "url">, param: string, base?: string): string | null;

package/dist/deep-link.d.ts

@@ -0,0 +1,14 @@
+import type { FeedbackRecord } from "./types.js";
+/**
+ * `url` resolved against `base`, when the result is an http(s) URL. A
+ * record's `url` is client-supplied: without the scheme allowlist, a crafted
+ * feedback (`javascript:…`, `data:…`) would turn into a live link.
+ */
+export declare function parseHttpUrl(url: string, base?: string): URL | null;
+/**
+ * Link that opens a feedback's page with the widget focused on it —
+ * `?<param>=<id>`, read by the widget's `deepLink` option. Relative record
+ * URLs (the widget stores `location.pathname` by default) resolve against
+ * `base`. Null when there is no safe http(s) target.
+ */
+export declare function buildDeepLink(record: Pick<FeedbackRecord, "id" | "url">, param: string, base?: string): string | null;

package/dist/email.d.cts

@@ -0,0 +1,22 @@
+/**
+ * The one email pattern every Siteping surface validates against.
+ *
+ * The widget's identity modal and the HTTP handler's schema used to disagree
+ * (a permissive regex on one side, an ASCII-only default on the other), so an
+ * address the modal accepted — and persisted in localStorage for good — came
+ * back as a 400 on every submission afterwards. One pattern, imported on both
+ * sides, makes that drift impossible.
+ *
+ * Deliberately Unicode-aware: internationalised local parts and domains
+ * (`françois@exemple.fr`, `user@münchen.de`, `user@हिंदी.भारत`) are real
+ * addresses and common in the audience this widget serves. Combining marks
+ * (`\p{M}`) are allowed alongside letters — scripts like Devanagari need them,
+ * and NFD-composed input spells `ç` as `c` + U+0327 — except as the first
+ * character of a domain label. Structure follows the usual rules — a local
+ * part of 1 to 64 characters with no leading, trailing or doubled dot,
+ * dot-separated domain labels of at most 63 characters that neither start nor
+ * end with a hyphen, and a final label of at least two characters.
+ */
+export declare const EMAIL_PATTERN: RegExp;
+/** Whether `value` is an email address Siteping accepts — see {@link EMAIL_PATTERN}. */
+export declare function isValidEmail(value: string): boolean;

package/dist/email.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one email pattern every Siteping surface validates against.
+ *
+ * The widget's identity modal and the HTTP handler's schema used to disagree
+ * (a permissive regex on one side, an ASCII-only default on the other), so an
+ * address the modal accepted — and persisted in localStorage for good — came
+ * back as a 400 on every submission afterwards. One pattern, imported on both
+ * sides, makes that drift impossible.
+ *
+ * Deliberately Unicode-aware: internationalised local parts and domains
+ * (`françois@exemple.fr`, `user@münchen.de`, `user@हिंदी.भारत`) are real
+ * addresses and common in the audience this widget serves. Combining marks
+ * (`\p{M}`) are allowed alongside letters — scripts like Devanagari need them,
+ * and NFD-composed input spells `ç` as `c` + U+0327 — except as the first
+ * character of a domain label. Structure follows the usual rules — a local
+ * part of 1 to 64 characters with no leading, trailing or doubled dot,
+ * dot-separated domain labels of at most 63 characters that neither start nor
+ * end with a hyphen, and a final label of at least two characters.
+ */
+export declare const EMAIL_PATTERN: RegExp;
+/** Whether `value` is an email address Siteping accepts — see {@link EMAIL_PATTERN}. */
+export declare function isValidEmail(value: string): boolean;

package/dist/errors.d.cts

@@ -0,0 +1,55 @@
+/**
+ * Typed error hierarchy for Siteping client/server boundaries.
+ *
+ * Consumers can `instanceof`-check or read `code` / `retryable` instead of
+ * pattern-matching error messages. Designed to be additive on top of the
+ * existing store errors (`StoreNotFoundError`, `StoreDuplicateError`) which
+ * remain the canonical signals for server-side store implementations.
+ *
+ * Usage on the widget side (api-client.ts):
+ *   - fetch failures / aborts / timeouts → `SitepingNetworkError` (retryable)
+ *   - HTTP 4xx (except 401/403)         → `SitepingValidationError` (not retryable)
+ *   - HTTP 401 / 403                    → `SitepingAuthError` (not retryable)
+ *   - everything else                   → `SitepingError` generic
+ *
+ * Store mode (store-client.ts): a `createFeedback` that does not settle in
+ * time → `SitepingError` with code `"TIMEOUT"` (retryable).
+ *
+ * `retryable` is meta information surfaced to host apps that want to wire
+ * their own retry/queue/backoff strategy — the widget already retries
+ * network failures via its built-in retry queue.
+ */
+/**
+ * Discriminant string carried by every `SitepingError`. Subclasses pin a
+ * literal value; the base class accepts a wider string so userland can
+ * extend the hierarchy without colliding with built-ins.
+ */
+export type SitepingErrorCode = "NETWORK" | "VALIDATION" | "AUTH" | "SERVER" | "TIMEOUT" | (string & {});
+export declare class SitepingError<TCode extends SitepingErrorCode = SitepingErrorCode> extends Error {
+    readonly code: TCode;
+    readonly retryable: boolean;
+    constructor(message: string, code: TCode, retryable: boolean);
+}
+/** Network-level failure: connection refused, DNS, CORS, timeout, abort. Retryable. */
+export declare class SitepingNetworkError extends SitepingError<"NETWORK"> {
+    constructor(message: string);
+}
+/**
+ * Server rejected the request (4xx, not auth). Validation problem on the
+ * client side. `status` is the HTTP status when a response said so: a 404
+ * (the target is gone) and a 409 (a full thread) call for other answers
+ * than a 400.
+ */
+export declare class SitepingValidationError extends SitepingError<"VALIDATION"> {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number);
+}
+/** Server rejected auth (401 or 403). Not retryable without fresh credentials. */
+export declare class SitepingAuthError extends SitepingError<"AUTH"> {
+    /**
+     * `401`: the credentials are missing or no longer work — drop a dead token
+     * on this one. `403`: they work, and the server's policy refuses this request.
+     */
+    readonly status: 401 | 403;
+    constructor(message: string, status: 401 | 403);
+}

package/dist/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed error hierarchy for Siteping client/server boundaries.
+ *
+ * Consumers can `instanceof`-check or read `code` / `retryable` instead of
+ * pattern-matching error messages. Designed to be additive on top of the
+ * existing store errors (`StoreNotFoundError`, `StoreDuplicateError`) which
+ * remain the canonical signals for server-side store implementations.
+ *
+ * Usage on the widget side (api-client.ts):
+ *   - fetch failures / aborts / timeouts → `SitepingNetworkError` (retryable)
+ *   - HTTP 4xx (except 401/403)         → `SitepingValidationError` (not retryable)
+ *   - HTTP 401 / 403                    → `SitepingAuthError` (not retryable)
+ *   - everything else                   → `SitepingError` generic
+ *
+ * Store mode (store-client.ts): a `createFeedback` that does not settle in
+ * time → `SitepingError` with code `"TIMEOUT"` (retryable).
+ *
+ * `retryable` is meta information surfaced to host apps that want to wire
+ * their own retry/queue/backoff strategy — the widget already retries
+ * network failures via its built-in retry queue.
+ */
+/**
+ * Discriminant string carried by every `SitepingError`. Subclasses pin a
+ * literal value; the base class accepts a wider string so userland can
+ * extend the hierarchy without colliding with built-ins.
+ */
+export type SitepingErrorCode = "NETWORK" | "VALIDATION" | "AUTH" | "SERVER" | "TIMEOUT" | (string & {});
+export declare class SitepingError<TCode extends SitepingErrorCode = SitepingErrorCode> extends Error {
+    readonly code: TCode;
+    readonly retryable: boolean;
+    constructor(message: string, code: TCode, retryable: boolean);
+}
+/** Network-level failure: connection refused, DNS, CORS, timeout, abort. Retryable. */
+export declare class SitepingNetworkError extends SitepingError<"NETWORK"> {
+    constructor(message: string);
+}
+/**
+ * Server rejected the request (4xx, not auth). Validation problem on the
+ * client side. `status` is the HTTP status when a response said so: a 404
+ * (the target is gone) and a 409 (a full thread) call for other answers
+ * than a 400.
+ */
+export declare class SitepingValidationError extends SitepingError<"VALIDATION"> {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number);
+}
+/** Server rejected auth (401 or 403). Not retryable without fresh credentials. */
+export declare class SitepingAuthError extends SitepingError<"AUTH"> {
+    /**
+     * `401`: the credentials are missing or no longer work — drop a dead token
+     * on this one. `403`: they work, and the server's policy refuses this request.
+     */
+    readonly status: 401 | 403;
+    constructor(message: string, status: 401 | 403);
+}

package/dist/filters.d.cts

@@ -0,0 +1,82 @@
+/**
+ * Shared feedback-record filtering and pagination — extracted from
+ * `adapter-memory` and `adapter-localstorage` which previously kept two
+ * near-identical copies of the same logic. Any adapter that holds an
+ * in-memory snapshot of feedbacks can use it.
+ *
+ * A record matches when it passes every active filter (see
+ * {@link matchesFeedbackQuery}):
+ *   - projectName  (always required)
+ *   - type
+ *   - status / statuses  (`statuses` bucket wins when both are set)
+ *   - url
+ *   - urlPattern
+ *   - search       (lowercase substring match on `message`)
+ *
+ * Pagination goes through `clampPagination`: `limit` capped at 100, `page`
+ * 1-based, both clamped up to 1 rather than indexing backwards from the end
+ * of the match set. Query adapters reuse the same helper so every store
+ * paginates identically.
+ */
+import type { FeedbackQuery, FeedbackRecord } from "./types.cjs";
+/** Default page size when the caller omits `query.limit`. */
+export declare const DEFAULT_PAGE_LIMIT = 50;
+/** Maximum allowed page size — defends against memory blow-ups on hostile callers. */
+export declare const MAX_PAGE_LIMIT = 100;
+export interface FilterResult {
+    feedbacks: FeedbackRecord[];
+    total: number;
+}
+/** Normalised pagination window — see {@link clampPagination}. */
+export interface Pagination {
+    /** 1-based page number, at least 1. */
+    page: number;
+    /** Page size in `[1, MAX_PAGE_LIMIT]`. */
+    limit: number;
+    /** Offset of the first row: `(page - 1) * limit`. */
+    skip: number;
+}
+/**
+ * Normalise `page` / `limit` to the store contract: `page` is 1-based and
+ * clamped up to 1, `limit` defaults to 50 and is clamped into `[1, 100]`,
+ * non-finite values fall back to the defaults. `skip` is the derived row
+ * offset for query backends (`OFFSET`, Prisma `skip`).
+ *
+ * Shared by the in-memory pipeline and query adapters (`PrismaStore`) so
+ * every store paginates identically — the HTTP schema clamps the same way,
+ * but direct callers (dashboard store mode, server actions) reach the store
+ * without a schema in front of them.
+ */
+export declare function clampPagination(query: Pick<FeedbackQuery, "page" | "limit">): Pagination;
+/**
+ * Whether a {@link clampPagination} offset lies beyond any row a store can
+ * hold. `clampPagination` bounds `page` from below only, so a direct caller's
+ * huge `page` yields an offset past `Number.MAX_SAFE_INTEGER` — or `Infinity`
+ * — that SQL backends reject (`OFFSET` is a 64-bit integer in PostgreSQL and
+ * SQLite; Prisma's `skip` rejects non-integers and 64-bit overflow).
+ *
+ * Every safe integer fits a signed 64-bit offset and no table holds more rows
+ * than that, so query adapters answer such a page as empty — with the real
+ * `total` — instead of issuing the query: the same result the in-memory
+ * pipeline returns.
+ *
+ * @param skip - The `skip` returned by {@link clampPagination}.
+ * @returns `true` when no row can sit at that offset.
+ */
+export declare function isUnreachableOffset(skip: number): boolean;
+/**
+ * Whether one record passes every filter of `query` — the filter half of
+ * {@link applyFeedbackFilters}, exposed so a client holding a single record
+ * (e.g. the dashboard deciding whether an optimistic edit still belongs in
+ * its list) applies exactly the stores' semantics. Pagination is ignored.
+ */
+export declare function matchesFeedbackQuery(record: FeedbackRecord, query: FeedbackQuery): boolean;
+/**
+ * Apply the standard feedback filter + pagination pipeline against an
+ * in-memory snapshot. Used by `MemoryStore.getFeedbacks` and
+ * `LocalStorageStore.getFeedbacks` so the two never drift.
+ *
+ * @param items  All known feedback records (already include `annotations`).
+ * @param query  Filter and pagination options. `projectName` is required.
+ */
+export declare function applyFeedbackFilters(items: readonly FeedbackRecord[], query: FeedbackQuery): FilterResult;

package/dist/filters.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared feedback-record filtering and pagination — extracted from
+ * `adapter-memory` and `adapter-localstorage` which previously kept two
+ * near-identical copies of the same logic. Any adapter that holds an
+ * in-memory snapshot of feedbacks can use it.
+ *
+ * A record matches when it passes every active filter (see
+ * {@link matchesFeedbackQuery}):
+ *   - projectName  (always required)
+ *   - type
+ *   - status / statuses  (`statuses` bucket wins when both are set)
+ *   - url
+ *   - urlPattern
+ *   - search       (lowercase substring match on `message`)
+ *
+ * Pagination goes through `clampPagination`: `limit` capped at 100, `page`
+ * 1-based, both clamped up to 1 rather than indexing backwards from the end
+ * of the match set. Query adapters reuse the same helper so every store
+ * paginates identically.
+ */
+import type { FeedbackQuery, FeedbackRecord } from "./types.js";
+/** Default page size when the caller omits `query.limit`. */
+export declare const DEFAULT_PAGE_LIMIT = 50;
+/** Maximum allowed page size — defends against memory blow-ups on hostile callers. */
+export declare const MAX_PAGE_LIMIT = 100;
+export interface FilterResult {
+    feedbacks: FeedbackRecord[];
+    total: number;
+}
+/** Normalised pagination window — see {@link clampPagination}. */
+export interface Pagination {
+    /** 1-based page number, at least 1. */
+    page: number;
+    /** Page size in `[1, MAX_PAGE_LIMIT]`. */
+    limit: number;
+    /** Offset of the first row: `(page - 1) * limit`. */
+    skip: number;
+}
+/**
+ * Normalise `page` / `limit` to the store contract: `page` is 1-based and
+ * clamped up to 1, `limit` defaults to 50 and is clamped into `[1, 100]`,
+ * non-finite values fall back to the defaults. `skip` is the derived row
+ * offset for query backends (`OFFSET`, Prisma `skip`).
+ *
+ * Shared by the in-memory pipeline and query adapters (`PrismaStore`) so
+ * every store paginates identically — the HTTP schema clamps the same way,
+ * but direct callers (dashboard store mode, server actions) reach the store
+ * without a schema in front of them.
+ */
+export declare function clampPagination(query: Pick<FeedbackQuery, "page" | "limit">): Pagination;
+/**
+ * Whether a {@link clampPagination} offset lies beyond any row a store can
+ * hold. `clampPagination` bounds `page` from below only, so a direct caller's
+ * huge `page` yields an offset past `Number.MAX_SAFE_INTEGER` — or `Infinity`
+ * — that SQL backends reject (`OFFSET` is a 64-bit integer in PostgreSQL and
+ * SQLite; Prisma's `skip` rejects non-integers and 64-bit overflow).
+ *
+ * Every safe integer fits a signed 64-bit offset and no table holds more rows
+ * than that, so query adapters answer such a page as empty — with the real
+ * `total` — instead of issuing the query: the same result the in-memory
+ * pipeline returns.
+ *
+ * @param skip - The `skip` returned by {@link clampPagination}.
+ * @returns `true` when no row can sit at that offset.
+ */
+export declare function isUnreachableOffset(skip: number): boolean;
+/**
+ * Whether one record passes every filter of `query` — the filter half of
+ * {@link applyFeedbackFilters}, exposed so a client holding a single record
+ * (e.g. the dashboard deciding whether an optimistic edit still belongs in
+ * its list) applies exactly the stores' semantics. Pagination is ignored.
+ */
+export declare function matchesFeedbackQuery(record: FeedbackRecord, query: FeedbackQuery): boolean;
+/**
+ * Apply the standard feedback filter + pagination pipeline against an
+ * in-memory snapshot. Used by `MemoryStore.getFeedbacks` and
+ * `LocalStorageStore.getFeedbacks` so the two never drift.
+ *
+ * @param items  All known feedback records (already include `annotations`).
+ * @param query  Filter and pagination options. `projectName` is required.
+ */
+export declare function applyFeedbackFilters(items: readonly FeedbackRecord[], query: FeedbackQuery): FilterResult;

package/dist/i18n.d.cts

@@ -0,0 +1,85 @@
+/**
+ * Generic i18n machinery shared by the widget and the dashboard.
+ *
+ * Each package owns its `Translations` interface (their key sets differ) and
+ * its locale dictionaries; everything else — locale normalization, the
+ * custom-locale registry, lazy loading of built-ins, the translate-function
+ * factory, interpolation — is identical and lives here once.
+ *
+ * The `loaders` map is typed `Record<Exclude<BuiltinLocale, "en">, …>`: the
+ * moment a locale code is added to {@link BUILTIN_LOCALES}, every consuming
+ * package fails to compile until its loader entry (and therefore its
+ * dictionary file) exists. Adding a locale cannot silently fall back to
+ * English anymore.
+ */
+import { type BuiltinLocale } from "./types.cjs";
+/**
+ * Lazy dictionary loaders for every non-English built-in locale. Use static
+ * `() => import("./xx.cjs").then((m) => m.xx)` thunks — bundlers keep
+ * emitting one chunk per locale, and only the requested one ships.
+ */
+export type LocaleLoaders<T> = Record<Exclude<BuiltinLocale, "en">, () => Promise<T>>;
+/** Translate function over the message catalog `T`. */
+export type TranslateFunction<T> = (key: keyof T & string) => string;
+/** The i18n API returned by {@link createI18n}. */
+export interface I18n<T> {
+    /**
+     * Create a translation function for the given locale.
+     *
+     * Locale resolution: exact language match > English fallback, per key.
+     * Non-English built-in locales are lazy-loaded via `loadLocale` — call
+     * `await loadLocale(locale)` at init if you want the UI to render in the
+     * target language immediately; until the dictionary lands, keys resolve
+     * to English.
+     */
+    createT(locale: string): TranslateFunction<T>;
+    /**
+     * Dynamically import a built-in locale and register it. Returns the
+     * loaded dictionary, or `null` if the locale isn't a known built-in.
+     * Custom locales registered via `registerLocale` bypass this loader —
+     * they are already in the registry (and are returned as registered, so a
+     * partial custom dictionary comes back partial).
+     */
+    loadLocale(locale: string): Promise<Partial<T> | null>;
+    /**
+     * Register a custom locale at runtime. Partial dictionaries are welcome —
+     * missing keys fall back to English per key, so overriding a single
+     * string never requires copying the whole catalog.
+     */
+    registerLocale(code: string, translations: Partial<T>): void;
+}
+/**
+ * `locale` as `Intl` accepts it. Locale options take any string, and a
+ * backend-style tag (`fr_FR` from PHP / WordPress) makes every `Intl`
+ * constructor and `toLocale*` call throw a RangeError: `_` reads as `-`, and
+ * a tag `Intl` still rejects falls back to English, as `createT` does.
+ * Silent, so it is safe on a render path; see `canonicalizeLocale` for the
+ * one-time, warning variant.
+ */
+export declare function intlLocale(locale: string): string;
+/**
+ * The host's locale tag as `Intl` accepts it. `SitepingLocale` takes any
+ * string, and PHP / WordPress hand out POSIX-style tags (`fr_FR`, `pt_BR`)
+ * that every `Intl` constructor rejects with a RangeError: `_` becomes `-`,
+ * then the tag is canonicalised (`fr-FR`). Falls back to `"en"`, with a
+ * warning, only when the tag is still invalid (empty, garbage) — meant to run
+ * once, where the config is read.
+ */
+export declare function canonicalizeLocale(locale: string): string;
+/**
+ * Build the i18n machinery for one message catalog.
+ *
+ * @param en — the complete English catalog, bundled synchronously as the fallback.
+ * @param loaders — lazy import thunks for every other built-in locale.
+ */
+export declare function createI18n<T extends Record<keyof T & string, string>>(en: T, loaders: LocaleLoaders<T>): I18n<T>;
+/**
+ * Interpolate `{paramName}` placeholders in a translated string with the
+ * values from `params`. Stringifies numbers and booleans inline so callers
+ * can pass `t("marker.count")` along with `{ count: 3 }` directly.
+ *
+ * Unknown placeholders are left as-is.
+ */
+export declare function interpolate(template: string, params: Readonly<Record<string, string | number | boolean>>): string;
+/** Shorthand for `interpolate(t(key), params)` — key-checked against the catalog. */
+export declare function tWithParams<K extends string>(t: (key: K) => string, key: K, params: Readonly<Record<string, string | number | boolean>>): string;

package/dist/i18n.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Generic i18n machinery shared by the widget and the dashboard.
+ *
+ * Each package owns its `Translations` interface (their key sets differ) and
+ * its locale dictionaries; everything else — locale normalization, the
+ * custom-locale registry, lazy loading of built-ins, the translate-function
+ * factory, interpolation — is identical and lives here once.
+ *
+ * The `loaders` map is typed `Record<Exclude<BuiltinLocale, "en">, …>`: the
+ * moment a locale code is added to {@link BUILTIN_LOCALES}, every consuming
+ * package fails to compile until its loader entry (and therefore its
+ * dictionary file) exists. Adding a locale cannot silently fall back to
+ * English anymore.
+ */
+import { type BuiltinLocale } from "./types.js";
+/**
+ * Lazy dictionary loaders for every non-English built-in locale. Use static
+ * `() => import("./xx.js").then((m) => m.xx)` thunks — bundlers keep
+ * emitting one chunk per locale, and only the requested one ships.
+ */
+export type LocaleLoaders<T> = Record<Exclude<BuiltinLocale, "en">, () => Promise<T>>;
+/** Translate function over the message catalog `T`. */
+export type TranslateFunction<T> = (key: keyof T & string) => string;
+/** The i18n API returned by {@link createI18n}. */
+export interface I18n<T> {
+    /**
+     * Create a translation function for the given locale.
+     *
+     * Locale resolution: exact language match > English fallback, per key.
+     * Non-English built-in locales are lazy-loaded via `loadLocale` — call
+     * `await loadLocale(locale)` at init if you want the UI to render in the
+     * target language immediately; until the dictionary lands, keys resolve
+     * to English.
+     */
+    createT(locale: string): TranslateFunction<T>;
+    /**
+     * Dynamically import a built-in locale and register it. Returns the
+     * loaded dictionary, or `null` if the locale isn't a known built-in.
+     * Custom locales registered via `registerLocale` bypass this loader —
+     * they are already in the registry (and are returned as registered, so a
+     * partial custom dictionary comes back partial).
+     */
+    loadLocale(locale: string): Promise<Partial<T> | null>;
+    /**
+     * Register a custom locale at runtime. Partial dictionaries are welcome —
+     * missing keys fall back to English per key, so overriding a single
+     * string never requires copying the whole catalog.
+     */
+    registerLocale(code: string, translations: Partial<T>): void;
+}
+/**
+ * `locale` as `Intl` accepts it. Locale options take any string, and a
+ * backend-style tag (`fr_FR` from PHP / WordPress) makes every `Intl`
+ * constructor and `toLocale*` call throw a RangeError: `_` reads as `-`, and
+ * a tag `Intl` still rejects falls back to English, as `createT` does.
+ * Silent, so it is safe on a render path; see `canonicalizeLocale` for the
+ * one-time, warning variant.
+ */
+export declare function intlLocale(locale: string): string;
+/**
+ * The host's locale tag as `Intl` accepts it. `SitepingLocale` takes any
+ * string, and PHP / WordPress hand out POSIX-style tags (`fr_FR`, `pt_BR`)
+ * that every `Intl` constructor rejects with a RangeError: `_` becomes `-`,
+ * then the tag is canonicalised (`fr-FR`). Falls back to `"en"`, with a
+ * warning, only when the tag is still invalid (empty, garbage) — meant to run
+ * once, where the config is read.
+ */
+export declare function canonicalizeLocale(locale: string): string;
+/**
+ * Build the i18n machinery for one message catalog.
+ *
+ * @param en — the complete English catalog, bundled synchronously as the fallback.
+ * @param loaders — lazy import thunks for every other built-in locale.
+ */
+export declare function createI18n<T extends Record<keyof T & string, string>>(en: T, loaders: LocaleLoaders<T>): I18n<T>;
+/**
+ * Interpolate `{paramName}` placeholders in a translated string with the
+ * values from `params`. Stringifies numbers and booleans inline so callers
+ * can pass `t("marker.count")` along with `{ count: 3 }` directly.
+ *
+ * Unknown placeholders are left as-is.
+ */
+export declare function interpolate(template: string, params: Readonly<Record<string, string | number | boolean>>): string;
+/** Shorthand for `interpolate(t(key), params)` — key-checked against the catalog. */
+export declare function tWithParams<K extends string>(t: (key: K) => string, key: K, params: Readonly<Record<string, string | number | boolean>>): string;