@siteping/adapter-drizzle 0.1.0 → 0.2.0

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;
 }

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { SitepingStore, ScreenshotStorage } from './siteping-core.cjs';
+import { SitepingStore, SitepingWarnLogger, ScreenshotStorage } from './siteping-core.cjs';
 export { FeedbackRecord, ScreenshotStorage, SitepingStore } from './siteping-core.cjs';
 
 /** Table names — override to fit your naming or avoid collisions. */
@@ -12,16 +12,16 @@ declare const DEFAULT_SITEPING_TABLE_NAMES: SitepingTableNames;
 /**
  * The store returned by the dialect factories — the full contract, including
  * the ownership check, the atomic `createFeedbackIfAbsent` and discussion
- * threads.
+ * threads with the atomic `addCommentIfAbsent`.
  */
-type DrizzleStore = SitepingStore & Required<Pick<SitepingStore, "verifyProjectOwnership" | "createFeedbackIfAbsent" | "addComment" | "deleteComment">>;
+type DrizzleStore = SitepingStore & Required<Pick<SitepingStore, "verifyProjectOwnership" | "createFeedbackIfAbsent" | "addComment" | "addCommentIfAbsent" | "deleteComment">>;
 /**
  * Where the store reports degraded-but-non-fatal situations (failed
- * screenshot uploads or cleanups, inline screenshots). `console` satisfies it.
+ * screenshot uploads or cleanups, inline screenshots) — SitePing's shared
+ * logger, with `warn`: `console` satisfies it, and so does the logger handed
+ * to the server. A logger that throws or rejects never fails the store.
  */
-interface DrizzleStoreLogger {
-    warn(message: string, context: Record<string, unknown>): void;
-}
+type DrizzleStoreLogger = SitepingWarnLogger;
 interface DrizzleStoreOptions {
     /**
      * Upload screenshots to external storage (S3, R2, Cloudflare Images…) and
@@ -42,4 +42,5 @@ interface DrizzleStoreOptions {
     now?: (() => Date) | undefined;
 }
 
-export { DEFAULT_SITEPING_TABLE_NAMES, type DrizzleStore, type DrizzleStoreLogger, type DrizzleStoreOptions, type SitepingTableNames };
+export { DEFAULT_SITEPING_TABLE_NAMES };
+export type { DrizzleStore, DrizzleStoreLogger, DrizzleStoreOptions, SitepingTableNames };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SitepingStore, ScreenshotStorage } from './siteping-core.js';
+import { SitepingStore, SitepingWarnLogger, ScreenshotStorage } from './siteping-core.js';
 export { FeedbackRecord, ScreenshotStorage, SitepingStore } from './siteping-core.js';
 
 /** Table names — override to fit your naming or avoid collisions. */
@@ -12,16 +12,16 @@ declare const DEFAULT_SITEPING_TABLE_NAMES: SitepingTableNames;
 /**
  * The store returned by the dialect factories — the full contract, including
  * the ownership check, the atomic `createFeedbackIfAbsent` and discussion
- * threads.
+ * threads with the atomic `addCommentIfAbsent`.
  */
-type DrizzleStore = SitepingStore & Required<Pick<SitepingStore, "verifyProjectOwnership" | "createFeedbackIfAbsent" | "addComment" | "deleteComment">>;
+type DrizzleStore = SitepingStore & Required<Pick<SitepingStore, "verifyProjectOwnership" | "createFeedbackIfAbsent" | "addComment" | "addCommentIfAbsent" | "deleteComment">>;
 /**
  * Where the store reports degraded-but-non-fatal situations (failed
- * screenshot uploads or cleanups, inline screenshots). `console` satisfies it.
+ * screenshot uploads or cleanups, inline screenshots) — SitePing's shared
+ * logger, with `warn`: `console` satisfies it, and so does the logger handed
+ * to the server. A logger that throws or rejects never fails the store.
  */
-interface DrizzleStoreLogger {
-    warn(message: string, context: Record<string, unknown>): void;
-}
+type DrizzleStoreLogger = SitepingWarnLogger;
 interface DrizzleStoreOptions {
     /**
      * Upload screenshots to external storage (S3, R2, Cloudflare Images…) and
@@ -42,4 +42,5 @@ interface DrizzleStoreOptions {
     now?: (() => Date) | undefined;
 }
 
-export { DEFAULT_SITEPING_TABLE_NAMES, type DrizzleStore, type DrizzleStoreLogger, type DrizzleStoreOptions, type SitepingTableNames };
+export { DEFAULT_SITEPING_TABLE_NAMES };
+export type { DrizzleStore, DrizzleStoreLogger, DrizzleStoreOptions, SitepingTableNames };

package/dist/libsql.cjs

@@ -25,9 +25,14 @@ __export(libsql_exports, {
   StoreLimitError: () => StoreLimitError,
   StoreNotFoundError: () => StoreNotFoundError,
   StorePersistenceError: () => StorePersistenceError,
+  StoreValueTooLongError: () => StoreValueTooLongError,
   createLibSQLSitepingStore: () => createLibSQLSitepingStore,
   createSitepingSqliteTables: () => createSitepingSqliteTables,
-  isStorePersistence: () => isStorePersistence
+  isStoreDuplicate: () => isStoreDuplicate,
+  isStoreLimit: () => isStoreLimit,
+  isStoreNotFound: () => isStoreNotFound,
+  isStorePersistence: () => isStorePersistence,
+  isStoreValueTooLong: () => isStoreValueTooLong
 });
 module.exports = __toCommonJS(libsql_exports);
 var import_drizzle_orm9 = require("drizzle-orm");
@@ -82,6 +87,14 @@ async function settleWithConcurrencyLimit(items, concurrency, task) {
   return results;
 }
 
+// ../core/src/type-utils.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasOwn(value, key) {
+  return isRecord(value) && key in value;
+}
+
 // ../core/src/filters.ts
 var DEFAULT_PAGE_LIMIT = 50;
 var MAX_PAGE_LIMIT = 100;
@@ -97,12 +110,13 @@ function isUnreachableOffset(skip) {
   return !Number.isSafeInteger(skip);
 }
 
-// ../core/src/type-utils.ts
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
-function hasOwn(value, key) {
-  return isRecord(value) && key in value;
+// ../core/src/logger.ts
+function warnSafely(logger, message, context) {
+  try {
+    Promise.resolve(logger.warn(message, context)).catch(() => {
+    });
+  } catch {
+  }
 }
 
 // ../core/src/types.ts
@@ -135,6 +149,13 @@ var StoreLimitError = class extends Error {
     this.name = "StoreLimitError";
   }
 };
+var StoreValueTooLongError = class extends Error {
+  code = "STORE_VALUE_TOO_LONG";
+  constructor(message = "Value too long for the store", options) {
+    super(message, options);
+    this.name = "StoreValueTooLongError";
+  }
+};
 function hasErrorCode(error, code) {
   return hasOwn(error, "code") && error.code === code;
 }
@@ -150,6 +171,14 @@ function isStorePersistence(error) {
   if (error instanceof StorePersistenceError) return true;
   return hasErrorCode(error, "STORE_PERSISTENCE");
 }
+function isStoreLimit(error) {
+  if (error instanceof StoreLimitError) return true;
+  return hasErrorCode(error, "STORE_LIMIT");
+}
+function isStoreValueTooLong(error) {
+  if (error instanceof StoreValueTooLongError) return true;
+  return hasErrorCode(error, "STORE_VALUE_TOO_LONG");
+}
 
 // ../core/src/screenshot-storage.ts
 var SCREENSHOT_DELETE_CONCURRENCY = 32;
@@ -223,6 +252,26 @@ function buildFeedbackRecord(input, ctx) {
   };
 }
 
+// ../core/src/text.ts
+var UNSTORABLE_CODE_UNITS = /\0|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+var REPLACEMENT_CHARACTER = "\uFFFD";
+function toStorableText(text2) {
+  return text2.replace(UNSTORABLE_CODE_UNITS, REPLACEMENT_CHARACTER);
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function toStorableValue(value) {
+  if (typeof value === "string") return toStorableText(value);
+  if (Array.isArray(value)) return value.map(toStorableValue);
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [toStorableText(key), toStorableValue(item)])
+  );
+}
+
 // src/constants/deletes.ts
 var PROJECT_DELETE_CHUNK_SIZE = 500;
 
@@ -264,28 +313,6 @@ function withDriverErrors(gateway) {
   });
 }
 
-// src/constants/text.ts
-var UNSTORABLE_CODE_UNITS = /\0|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
-var REPLACEMENT_CHARACTER = "\uFFFD";
-
-// src/shared/text.ts
-function toStorableText(text2) {
-  return text2.replace(UNSTORABLE_CODE_UNITS, REPLACEMENT_CHARACTER);
-}
-function isPlainObject(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-function toStorableValue(value) {
-  if (typeof value === "string") return toStorableText(value);
-  if (Array.isArray(value)) return value.map(toStorableValue);
-  if (!isPlainObject(value)) return value;
-  return Object.fromEntries(
-    Object.entries(value).map(([key, item]) => [toStorableText(key), toStorableValue(item)])
-  );
-}
-
 // src/shared/store.ts
 var silentLogger = {
   warn() {
@@ -338,8 +365,11 @@ var DrizzleSitepingStore = class {
     this.logger = options.logger ?? silentLogger;
     this.now = options.now ?? systemClock;
   }
+  /** Throws `StoreDuplicateError` when a feedback with the same `clientId` exists. */
   async createFeedback(data) {
-    return (await this.createFeedbackIfAbsent(data)).feedback;
+    const { feedback, created } = await this.createFeedbackIfAbsent(data);
+    if (!created) throw new StoreDuplicateError(`A feedback with clientId ${data.clientId} already exists`);
+    return feedback;
   }
   /**
    * Insert the feedback unless a row with the same `clientId` exists. The
@@ -521,7 +551,15 @@ var DrizzleSitepingStore = class {
    * @throws `StoreLimitError` when a `client` comment meets a thread already holding `MAX_COMMENTS_PER_FEEDBACK` of them.
    * @throws `StorePersistenceError` when a database call fails.
    */
-  async addComment(submittedFeedbackId, submitted) {
+  async addComment(feedbackId, data) {
+    return (await this.addCommentIfAbsent(feedbackId, data)).comment;
+  }
+  /**
+   * {@link addComment}, reporting whether this call inserted the comment: the
+   * single statement inserts at most one row per `clientId`, so of racing
+   * posts exactly one reports `created: true`.
+   */
+  async addCommentIfAbsent(submittedFeedbackId, submitted) {
     const feedbackId = toStorableText(submittedFeedbackId);
     const data = toStorableValue(submitted);
     const comment = buildCommentRecord(data, { id: crypto.randomUUID(), feedbackId, now: this.now() });
@@ -542,13 +580,13 @@ var DrizzleSitepingStore = class {
       if (feedbackGone) throw new StoreNotFoundError();
       throw error;
     }
-    if (inserted) return comment;
+    if (inserted) return { comment, created: true };
     const replayed = await persistMutation(
       "addComment",
       identifiers,
       () => this.gateway.findCommentByClientId(data.clientId)
     );
-    if (replayed) return replayed;
+    if (replayed) return { comment: replayed, created: false };
     const projectName = await persistMutation(
       "addComment",
       identifiers,
@@ -615,7 +653,8 @@ var DrizzleSitepingStore = class {
         });
         return url;
       } catch (error) {
-        this.logger.warn(
+        warnSafely(
+          this.logger,
           "[siteping] DrizzleStore: screenshotStorage.upload failed \u2014 feedback saved without screenshot",
           { clientId, feedbackId, error }
         );
@@ -624,7 +663,8 @@ var DrizzleSitepingStore = class {
     }
     if (!this.inlineScreenshotWarned) {
       this.inlineScreenshotWarned = true;
-      this.logger.warn(
+      warnSafely(
+        this.logger,
         "[siteping] DrizzleStore: no screenshotStorage configured \u2014 screenshots are stored inline as base64. Configure a ScreenshotStorage for production.",
         {}
       );
@@ -667,7 +707,8 @@ var DrizzleSitepingStore = class {
     try {
       referenced = await this.findReferencedScreenshotUrls(candidates);
     } catch (lookupError) {
-      this.logger.warn(
+      warnSafely(
+        this.logger,
         `${DRIZZLE_STORE_MESSAGE_PREFIX}: screenshot references could not be checked \u2014 screenshots kept`,
         { ...context, screenshotUrls: candidates, error: lookupError }
       );
@@ -681,11 +722,15 @@ var DrizzleSitepingStore = class {
     );
     results.forEach((result, index2) => {
       if (result.status === "rejected") {
-        this.logger.warn(`${DRIZZLE_STORE_MESSAGE_PREFIX}: screenshotStorage.delete failed \u2014 object left in place`, {
-          ...context,
-          screenshotUrl: unreferenced[index2],
-          error: result.reason
-        });
+        warnSafely(
+          this.logger,
+          `${DRIZZLE_STORE_MESSAGE_PREFIX}: screenshotStorage.delete failed \u2014 object left in place`,
+          {
+            ...context,
+            screenshotUrl: unreferenced[index2],
+            error: result.reason
+          }
+        );
       }
     });
   }