@siteping/widget 0.10.6 → 0.10.8

package/dist/email.d.cts

@@ -0,0 +1,19 @@
+/**
+ * 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`) are real addresses and common in
+ * the audience this widget serves. 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,19 @@
+/**
+ * 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`) are real addresses and common in
+ * the audience this widget serves. 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/filters.d.cts

@@ -12,16 +12,41 @@
  *   5. urlPattern
  *   6. search       (lowercase substring match on `message`)
  *
- * Pagination clamps `limit` to a maximum of 100 and treats `page` as 1-based,
- * matching the public API contract documented on `getFeedbacks`. A page or
- * limit below 1 is clamped up to 1 rather than indexing backwards from the
- * end of the match set.
+ * 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;
 /**
  * Apply the standard feedback filter + pagination pipeline against an
  * in-memory snapshot. Used by `MemoryStore.getFeedbacks` and

package/dist/filters.d.ts

@@ -12,16 +12,41 @@
  *   5. urlPattern
  *   6. search       (lowercase substring match on `message`)
  *
- * Pagination clamps `limit` to a maximum of 100 and treats `page` as 1-based,
- * matching the public API contract documented on `getFeedbacks`. A page or
- * limit below 1 is clamped up to 1 rather than indexing backwards from the
- * end of the match set.
+ * 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;
 /**
  * Apply the standard feedback filter + pagination pipeline against an
  * in-memory snapshot. Used by `MemoryStore.getFeedbacks` and

package/dist/i18n.d.cts

@@ -0,0 +1,67 @@
+/**
+ * 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;
+}
+/**
+ * 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,67 @@
+/**
+ * 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;
+}
+/**
+ * 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;