@siteping/server 0.1.1 → 0.2.1

package/README.md

@@ -14,7 +14,7 @@ The HTTP endpoint of [SitePing](https://github.com/NeosiaNexus/SitePing) over an
 npm install @siteping/server
 ```
 
-Node ≥ 20, or any runtime with the Fetch API.
+Node ≥ 22, or any runtime with the Fetch API.
 
 ## Quick start
 

package/dist/deep-link.d.cts

@@ -5,6 +5,16 @@ import type { FeedbackRecord } from "./types.cjs";
  * feedback (`javascript:…`, `data:…`) would turn into a live link.
  */
 export declare function parseHttpUrl(url: string, base?: string): URL | null;
+/**
+ * Whether a screenshot URL is safe to render as an `<img src>`, in the
+ * widget's panel and the dashboard alike. A store can hold any string there
+ * (a direct store caller, a custom `ScreenshotStorage`, a migrated database):
+ * a `javascript:`, `data:text/html` or `data:image/svg+xml` URL — SVG can
+ * carry external `<image href>` references — or an arbitrary host would make
+ * the viewer fetch from it, leaking their IP and user agent. Browsers never
+ * run scripts from an `<img>`, but the fetch itself still happens.
+ */
+export declare function isSafeImageUrl(url: string): boolean;
 /**
  * Link that opens a feedback's page with the widget focused on it —
  * `?<param>=<id>`, read by the widget's `deepLink` option. Relative record

package/dist/deep-link.d.ts

@@ -5,6 +5,16 @@ import type { FeedbackRecord } from "./types.js";
  * feedback (`javascript:…`, `data:…`) would turn into a live link.
  */
 export declare function parseHttpUrl(url: string, base?: string): URL | null;
+/**
+ * Whether a screenshot URL is safe to render as an `<img src>`, in the
+ * widget's panel and the dashboard alike. A store can hold any string there
+ * (a direct store caller, a custom `ScreenshotStorage`, a migrated database):
+ * a `javascript:`, `data:text/html` or `data:image/svg+xml` URL — SVG can
+ * carry external `<image href>` references — or an arbitrary host would make
+ * the viewer fetch from it, leaking their IP and user agent. Browsers never
+ * run scripts from an `<img>`, but the fetch itself still happens.
+ */
+export declare function isSafeImageUrl(url: string): boolean;
 /**
  * Link that opens a feedback's page with the widget focused on it —
  * `?<param>=<id>`, read by the widget's `deepLink` option. Relative record

package/dist/errors.d.cts

@@ -1,30 +1,30 @@
 /**
  * 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.
+ * Consumers match an error with a guard — `isSitepingError`,
+ * `isSitepingConfigError`, a store guard such as `isStoreNotFound` — then
+ * read `code` / `retryable` instead of pattern-matching messages. The guards
+ * are structural, never `instanceof`: every published package bundles its
+ * own copy of these classes (tsup `noExternal`), so an error one package
+ * throws fails `instanceof` against another's class. The widget and the
+ * dashboard export the guard and the types, not the classes.
  *
  * Usage on the widget side (api-client.ts):
  *   - fetch failures / aborts / timeouts → `SitepingNetworkError` (retryable)
- *   - HTTP 4xx (except 401/403)         → `SitepingValidationError` (not retryable)
+ *   - HTTP 4xx (except 401/403/408/429) → `SitepingValidationError` (not retryable)
  *   - HTTP 401 / 403                    → `SitepingAuthError` (not retryable)
- *   - everything else                   → `SitepingError` generic
+ *   - HTTP 5xx / 408 / 429              → `SitepingError` code `"SERVER"` (retryable)
  *
  * Store mode (store-client.ts): a `createFeedback` that does not settle in
- * time → `SitepingError` with code `"TIMEOUT"` (retryable).
+ * time → `SitepingError` with code `"TIMEOUT"` (retryable); a reply to a
+ * store that keeps no comments → `"SERVER"`, not 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.
+ * `retryable` says whether the same request may succeed later, unchanged —
+ * meta information for host apps that wire their own retry/queue/backoff
+ * strategy; the widget already retries and queues transient failures itself.
  */
-/**
- * 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 & {});
+/** Discriminant string carried by every `SitepingError`. */
+export type SitepingErrorCode = "NETWORK" | "VALIDATION" | "AUTH" | "SERVER" | "TIMEOUT";
 export declare class SitepingError<TCode extends SitepingErrorCode = SitepingErrorCode> extends Error {
     readonly code: TCode;
     readonly retryable: boolean;
@@ -53,3 +53,33 @@ export declare class SitepingAuthError extends SitepingError<"AUTH"> {
     readonly status: 401 | 403;
     constructor(message: string, status: 401 | 403);
 }
+/**
+ * Every error the widget and the dashboard report for a failed call, told
+ * apart by `code`: narrowing on it reaches a subclass's own fields, such as
+ * an `AUTH` error's `status`.
+ */
+export type SitepingClientError = SitepingNetworkError | SitepingValidationError | SitepingAuthError | SitepingError<"SERVER" | "TIMEOUT">;
+/**
+ * Whether `error` is a `SitepingError` (any subclass) — matched on its
+ * fields, a known `code` and a boolean `retryable`, so it holds for an error
+ * another package's copy of the class threw. Anything else reaching an
+ * `onError` (a store's own error, a panel action's) fails it.
+ */
+export declare function isSitepingError(error: unknown): error is SitepingClientError;
+/** Stable codes of the errors a handler factory throws for options it cannot run with. */
+export type SitepingConfigErrorCode = "CONFIG_STORE_MISSING" | "CONFIG_MAX_BODY_BYTES_INVALID" | "CONFIG_OWNERSHIP_CHECK_MISSING" | "CONFIG_WEBHOOK_TIMEOUT_INVALID" | "CONFIG_API_KEY_REQUIRED";
+/**
+ * Thrown by `createSitepingHandler` while it is created, never per request,
+ * when its options cannot run safely. The message says how to fix it; branch
+ * on `code`, after {@link isSitepingConfigError}.
+ */
+export declare class SitepingConfigError extends Error {
+    readonly code: SitepingConfigErrorCode;
+    constructor(code: SitepingConfigErrorCode, message: string);
+}
+/**
+ * Whether `error` is a `SitepingConfigError` — matched on its `name` and a
+ * `CONFIG_` code rather than `instanceof`, for the same cross-bundle reason
+ * as {@link isSitepingError}.
+ */
+export declare function isSitepingConfigError(error: unknown): error is SitepingConfigError;

package/dist/errors.d.ts

@@ -1,30 +1,30 @@
 /**
  * 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.
+ * Consumers match an error with a guard — `isSitepingError`,
+ * `isSitepingConfigError`, a store guard such as `isStoreNotFound` — then
+ * read `code` / `retryable` instead of pattern-matching messages. The guards
+ * are structural, never `instanceof`: every published package bundles its
+ * own copy of these classes (tsup `noExternal`), so an error one package
+ * throws fails `instanceof` against another's class. The widget and the
+ * dashboard export the guard and the types, not the classes.
  *
  * Usage on the widget side (api-client.ts):
  *   - fetch failures / aborts / timeouts → `SitepingNetworkError` (retryable)
- *   - HTTP 4xx (except 401/403)         → `SitepingValidationError` (not retryable)
+ *   - HTTP 4xx (except 401/403/408/429) → `SitepingValidationError` (not retryable)
  *   - HTTP 401 / 403                    → `SitepingAuthError` (not retryable)
- *   - everything else                   → `SitepingError` generic
+ *   - HTTP 5xx / 408 / 429              → `SitepingError` code `"SERVER"` (retryable)
  *
  * Store mode (store-client.ts): a `createFeedback` that does not settle in
- * time → `SitepingError` with code `"TIMEOUT"` (retryable).
+ * time → `SitepingError` with code `"TIMEOUT"` (retryable); a reply to a
+ * store that keeps no comments → `"SERVER"`, not 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.
+ * `retryable` says whether the same request may succeed later, unchanged —
+ * meta information for host apps that wire their own retry/queue/backoff
+ * strategy; the widget already retries and queues transient failures itself.
  */
-/**
- * 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 & {});
+/** Discriminant string carried by every `SitepingError`. */
+export type SitepingErrorCode = "NETWORK" | "VALIDATION" | "AUTH" | "SERVER" | "TIMEOUT";
 export declare class SitepingError<TCode extends SitepingErrorCode = SitepingErrorCode> extends Error {
     readonly code: TCode;
     readonly retryable: boolean;
@@ -53,3 +53,33 @@ export declare class SitepingAuthError extends SitepingError<"AUTH"> {
     readonly status: 401 | 403;
     constructor(message: string, status: 401 | 403);
 }
+/**
+ * Every error the widget and the dashboard report for a failed call, told
+ * apart by `code`: narrowing on it reaches a subclass's own fields, such as
+ * an `AUTH` error's `status`.
+ */
+export type SitepingClientError = SitepingNetworkError | SitepingValidationError | SitepingAuthError | SitepingError<"SERVER" | "TIMEOUT">;
+/**
+ * Whether `error` is a `SitepingError` (any subclass) — matched on its
+ * fields, a known `code` and a boolean `retryable`, so it holds for an error
+ * another package's copy of the class threw. Anything else reaching an
+ * `onError` (a store's own error, a panel action's) fails it.
+ */
+export declare function isSitepingError(error: unknown): error is SitepingClientError;
+/** Stable codes of the errors a handler factory throws for options it cannot run with. */
+export type SitepingConfigErrorCode = "CONFIG_STORE_MISSING" | "CONFIG_MAX_BODY_BYTES_INVALID" | "CONFIG_OWNERSHIP_CHECK_MISSING" | "CONFIG_WEBHOOK_TIMEOUT_INVALID" | "CONFIG_API_KEY_REQUIRED";
+/**
+ * Thrown by `createSitepingHandler` while it is created, never per request,
+ * when its options cannot run safely. The message says how to fix it; branch
+ * on `code`, after {@link isSitepingConfigError}.
+ */
+export declare class SitepingConfigError extends Error {
+    readonly code: SitepingConfigErrorCode;
+    constructor(code: SitepingConfigErrorCode, message: string);
+}
+/**
+ * Whether `error` is a `SitepingConfigError` — matched on its `name` and a
+ * `CONFIG_` code rather than `instanceof`, for the same cross-bundle reason
+ * as {@link isSitepingError}.
+ */
+export declare function isSitepingConfigError(error: unknown): error is SitepingConfigError;

package/dist/i18n.d.cts

@@ -12,7 +12,7 @@
  * dictionary file) exists. Adding a locale cannot silently fall back to
  * English anymore.
  */
-import { type BuiltinLocale } from "./types.cjs";
+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
@@ -26,7 +26,8 @@ export interface I18n<T> {
     /**
      * Create a translation function for the given locale.
      *
-     * Locale resolution: exact language match > English fallback, per key.
+     * Locale resolution, per key: `registerLocale` override > built-in
+     * dictionary of the language > English fallback.
      * 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
@@ -34,17 +35,20 @@ export interface I18n<T> {
      */
     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).
+     * Dynamically import a built-in locale (once) and register it. Returns the
+     * locale as `createT` resolves it — the built-in dictionary with any
+     * `registerLocale` overrides on top — or `null` for a code that is neither
+     * built in nor registered. A custom code never hits a loader: it comes
+     * back 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.
+     * Register translations at runtime, for a new locale or over a built-in
+     * one. Partial dictionaries are welcome: the keys given override the
+     * built-in dictionary (whenever it loads), every other key keeps its
+     * built-in value, then falls back to English — so overriding a single
+     * string never requires copying the whole catalog. Calls for the same
+     * code accumulate.
      */
     registerLocale(code: string, translations: Partial<T>): void;
 }

package/dist/i18n.d.ts

@@ -12,7 +12,7 @@
  * dictionary file) exists. Adding a locale cannot silently fall back to
  * English anymore.
  */
-import { type BuiltinLocale } from "./types.js";
+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
@@ -26,7 +26,8 @@ export interface I18n<T> {
     /**
      * Create a translation function for the given locale.
      *
-     * Locale resolution: exact language match > English fallback, per key.
+     * Locale resolution, per key: `registerLocale` override > built-in
+     * dictionary of the language > English fallback.
      * 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
@@ -34,17 +35,20 @@ export interface I18n<T> {
      */
     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).
+     * Dynamically import a built-in locale (once) and register it. Returns the
+     * locale as `createT` resolves it — the built-in dictionary with any
+     * `registerLocale` overrides on top — or `null` for a code that is neither
+     * built in nor registered. A custom code never hits a loader: it comes
+     * back 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.
+     * Register translations at runtime, for a new locale or over a built-in
+     * one. Partial dictionaries are welcome: the keys given override the
+     * built-in dictionary (whenever it loads), every other key keeps its
+     * built-in value, then falls back to English — so overriding a single
+     * string never requires copying the whole catalog. Calls for the same
+     * code accumulate.
      */
     registerLocale(code: string, translations: Partial<T>): void;
 }