@richardmcquiston01/error-log-adapter 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -10,6 +10,17 @@ interface ErrorLogEntry<TCode extends string = string> {
     source?: string;
     /** ISO 8601 timestamp. Adapters fill this in when it is omitted. */
     timestamp?: string;
+    /**
+     * Optional UUID that identifies this entry. Adapters generate a new one for
+     * every `log` call when it is omitted, so logging the same entry twice stores
+     * it twice. Supply the same `id` (and, for S3, the same `timestamp`) to make
+     * a retry safe: sinks that can detect a repeat overwrite or skip the existing
+     * record instead of adding another. It must be a UUID, for example from
+     * `crypto.randomUUID()`; anything else makes `log` return `ok: false`.
+     * Redis, the flat file and NDJSON file adapters, and the console cannot
+     * detect a repeat.
+     */
+    id?: string;
 }
 /** Outcome of a `log` call. Callers should check `ok`. */
 interface ErrorLogResult {
@@ -34,8 +45,16 @@ interface SerializedErrorLogEntry {
     timestamp: string;
 }
 /**
- * Converts `Error` instances into plain objects, since `JSON.stringify`
- * renders them as `{}`. Other values are returned unchanged.
+ * Returns a copy of `cause` that `JSON.stringify` can always handle, so a
+ * strange cause can never stop an entry from being stored.
+ *
+ * - `Error` objects (including ones from another realm) become
+ *   `{ name, message, stack }`, plus `cause` and, for an `AggregateError`,
+ *   `errors`, which are converted the same way.
+ * - Circular references become `"[Circular]"`, and anything nested deeper than
+ *   `MAX_CAUSE_DEPTH` levels becomes `"[Truncated]"`.
+ * - `BigInt`, `Symbol` and function values, and non-finite numbers, become strings.
+ * - A property or `toJSON` that throws is replaced by a short description.
  */
 declare function serializeCause(cause: unknown): unknown;
 /** Returns a JSON-safe copy of the entry, adding a timestamp if missing. */
@@ -56,13 +75,34 @@ interface WebhookErrorOptions {
     headers?: Record<string, string>;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * Allow a plain `http://` URL. Entries contain error messages and stack
+     * traces, so they are only sent over `https://` unless this is `true`.
+     * `http://localhost`, `127.0.0.1` and `[::1]` are always allowed.
+     * Defaults to `false`.
+     */
+    allowInsecure?: boolean;
+    /**
+     * How long to wait for the webhook to answer, in milliseconds. Defaults to
+     * 10000. Pass `Infinity` to wait without limit. When it passes, the request is
+     * cancelled, so the connection is closed rather than left open; the server may
+     * still have received the entry.
+     */
+    timeoutMs?: number;
 }
 declare class WebhookErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly url;
     private readonly options;
     private readonly prefix;
+    private readonly timeoutMs;
+    /** Scheme and host only. Webhook URLs often carry a secret in the path or query. */
+    private readonly target;
+    /** @throws {RangeError} if `url` is not a valid `https://` URL (see `allowInsecure`) or `timeoutMs` is invalid. */
     constructor(url: string, options?: WebhookErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+    private redirectMessage;
+    /** Replaces the full URL in a message with its origin, in case the runtime put it there. */
+    private redact;
     private fail;
 }
 
@@ -73,26 +113,63 @@ interface CollectionLike {
 interface MongoDbErrorOptions {
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for the insert before giving up, in milliseconds. Defaults to
+     * 10000. Pass `Infinity` to wait without limit. The call cannot be cancelled,
+     * so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 declare class MongoDbErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly collection;
     private readonly prefix;
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or Infinity. */
     constructor(collection: CollectionLike, options?: MongoDbErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
 }
 
+interface CompositeErrorOptions {
+    /**
+     * How long to wait for each adapter before reporting it as failed, in
+     * milliseconds. Defaults to 30000, longer than the 10000 default of the built-in
+     * adapters so their own, more specific timeout messages come first. This only
+     * matters for a custom adapter that can hang: one stuck adapter then cannot
+     * hold back the result of the others. Pass `Infinity` to wait without limit.
+     */
+    timeoutMs?: number;
+}
 /** Sends every entry to several adapters. Succeeds only if all of them do. */
 declare class CompositeErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly adapters;
-    constructor(adapters: ReadonlyArray<ErrorLogAdapter<TCode>>);
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or Infinity. */
+    constructor(adapters: ReadonlyArray<ErrorLogAdapter<TCode>>, options?: CompositeErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
 }
 
 /** Event handler slot. Typed loosely so real DOM `IDBTransaction` objects fit. */
 type IdbHandler = ((event: never) => unknown) | null;
+/** The error object of a failed request or transaction (a `DOMException`). */
+interface IdbErrorLike {
+    name?: string;
+    message?: string;
+}
+/** The subset of an `IDBRequest` this adapter uses. */
+interface IdbRequestLike {
+    onerror: IdbHandler;
+    readonly error?: IdbErrorLike | null;
+}
 /** The subset of an `IDBObjectStore` this adapter uses. */
 interface IdbObjectStoreLike {
+    /** Returns an `IDBRequest`. Fakes that return nothing also work. */
     add(value: unknown): unknown;
+    /**
+     * Replaces the record with the same key. Used for entries that carry their own
+     * `id`, so logging one again does not fail on the existing key. A real
+     * `IDBObjectStore` has it; a fake without it falls back to `add`.
+     */
+    put?(value: unknown): unknown;
 }
 /** The subset of an `IDBTransaction` this adapter uses. */
 interface IdbTransactionLike {
@@ -100,9 +177,7 @@ interface IdbTransactionLike {
     oncomplete: IdbHandler;
     onerror: IdbHandler;
     onabort: IdbHandler;
-    readonly error?: {
-        message?: string;
-    } | null;
+    readonly error?: IdbErrorLike | null;
 }
 /** The subset of an `IDBDatabase` this adapter uses. */
 interface IdbDatabaseLike {
@@ -128,6 +203,13 @@ interface IndexedDbErrorOptions {
     storeName?: string;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for the transaction to finish, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. A transaction can stay
+     * pending when a version change in another tab blocks it, or when the browser
+     * has evicted the origin's storage. The write may still finish afterwards.
+     */
+    timeoutMs?: number;
 }
 /**
  * Creates the error log object store (UUID `id` key, `timestamp` index).
@@ -138,9 +220,18 @@ declare class IndexedDbErrorAdapter<TCode extends string = string> implements Er
     private readonly database;
     private readonly storeName;
     private readonly prefix;
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or Infinity. */
     constructor(database: IdbDatabaseLike, options?: IndexedDbErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
-    /** Resolves once the transaction commits; rejects if it errors or aborts. */
+    /**
+     * Resolves once the transaction commits; rejects if the request fails, the
+     * transaction aborts, or it does not finish within `timeoutMs`.
+     *
+     * Error events are handled here (`preventDefault` and `stopPropagation`), so a
+     * failed log write does not reach the `onerror` handler an app may have set on
+     * its own database object.
+     */
     private write;
 }
 
@@ -166,6 +257,12 @@ interface SqliteErrorOptions {
     createTable?: boolean;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for the driver before giving up, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. The call cannot be
+     * cancelled, so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 /**
  * Returns the statements that create the error log table and its index.
@@ -177,13 +274,16 @@ declare class SqliteErrorAdapter<TCode extends string = string> implements Error
     private readonly tableName;
     private readonly createTable;
     private readonly prefix;
+    private readonly timeoutMs;
     private tableReady;
-    /** @throws {RangeError} if `options.tableName` is not a plain identifier. */
+    /** @throws {RangeError} if `options.tableName` is not a plain identifier or `options.timeoutMs` is invalid. */
     constructor(client: SqliteClientLike, options?: SqliteErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
     /** Creates the table once. A failed attempt is retried on the next log call. */
     private ensureTable;
     private runCreateStatements;
+    /** Runs one statement, giving up waiting after `timeoutMs`. */
+    private run;
 }
 
 /**
@@ -194,6 +294,14 @@ interface StorageLike {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
 }
+/**
+ * The part of `navigator.locks` this adapter uses. `localStorage` is shared by
+ * every tab of an origin and has no atomic update, so a lock keeps two tabs from
+ * overwriting each other's entry.
+ */
+interface LockManagerLike {
+    request<T>(name: string, callback: () => T | Promise<T>): Promise<T>;
+}
 /** A stored record: the serialized entry plus its generated UUID. */
 interface WebStorageErrorRecord extends SerializedErrorLogEntry {
     id: string;
@@ -205,24 +313,51 @@ interface WebStorageErrorOptions {
     maxEntries?: number;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * Lock manager that makes tabs sharing a `localStorage` take turns. Defaults to
+     * `navigator.locks` when the browser has it. This reduces lost entries but does
+     * not remove them: a tab in another process can still read a stale copy
+     * (measured in Chromium). Pass `null` to turn locking off.
+     */
+    locks?: LockManagerLike | null;
 }
 /**
  * Keeps the newest entries in a Web Storage object (`sessionStorage` or
  * `localStorage`) as a JSON array under one key, capped at `maxEntries`.
  * When the store is full, the oldest entries are dropped until the new one fits.
+ *
+ * `sessionStorage` belongs to one tab, so it is safe. `localStorage` is shared by
+ * every tab of the origin and has no atomic update: two tabs logging at the same
+ * moment can overwrite each other's entry while both get `ok: true`. In Chromium,
+ * tabs in separate processes (the usual case) even read a stale copy, so a lock
+ * reduces the loss without removing it. Where tabs may log at the same time and
+ * every entry matters, use `IndexedDbErrorAdapter`, whose writes are transactional.
  */
 declare class WebStorageErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly storage;
     private readonly key;
     private readonly maxEntries;
     private readonly prefix;
+    private readonly locks;
     /** @throws {RangeError} if `options.maxEntries` is not a positive integer. */
     constructor(storage: StorageLike, options?: WebStorageErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
-    /** Reads, appends, trims, and writes back. Runs without awaiting, so calls never interleave. */
+    /**
+     * Appends under a cross-tab lock when one is available. If the lock itself
+     * cannot be taken (for example a sandboxed frame), the entry is still written
+     * without it rather than lost.
+     */
+    private appendLocked;
+    /** Reads, appends, trims, and writes back. Runs without awaiting, so calls in one tab never interleave. */
     private append;
     /** Returns the stored records, or none if the value is missing or unreadable. */
     private readRecords;
+    /**
+     * Copies an unusable value to `<key>.corrupt` before it is replaced, so data
+     * the host app stored under the same key is not silently destroyed. Only the
+     * first one is kept; a later unusable value would not overwrite it.
+     */
+    private setAside;
 }
 
 /**
@@ -281,7 +416,7 @@ declare class FlatFileErrorAdapter<TCode extends string = string> implements Err
     private readonly prefix;
     private fs;
     private directoryReady;
-    private queue;
+    private readonly queue;
     /** @throws {RangeError} if `maxBytes` or `maxFiles` is not a positive integer. */
     constructor(filePath: string, options?: FlatFileErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -334,7 +469,7 @@ declare class JsonFileErrorAdapter<TCode extends string = string> implements Err
     private readonly prefix;
     private fs;
     private directoryReady;
-    private queue;
+    private readonly queue;
     /** @throws {RangeError} if `maxEntries` or `indent` is invalid, or `maxEntries` is used outside array mode. */
     constructor(filePath: string, options?: JsonFileErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -371,6 +506,12 @@ interface SqlErrorOptions {
     createTable?: boolean;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for each database statement before giving up, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. The call cannot be
+     * cancelled, so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 /**
  * Returns the statements that create the error log table and its index for a
@@ -381,6 +522,12 @@ interface SqlErrorOptions {
  * cause, and `DATETIME(3)` columns holding UTC times.
  */
 declare function buildErrorLogTableDdl(dialect: SqlDialect, tableName?: string): string[];
+/**
+ * Returns the statement that widens the `code` and `source` columns of a MySQL
+ * table created by `buildErrorLogTableDdl` in 0.4.0 or earlier, where they were
+ * `VARCHAR(255)` and a longer value made the insert fail. Run it once.
+ */
+declare function buildMySqlWidenColumnsSql(tableName?: string): string[];
 /** Shared by the Postgres and MySQL adapters: only the SQL text and time format differ. */
 declare abstract class SqlErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly client;
@@ -389,6 +536,7 @@ declare abstract class SqlErrorAdapter<TCode extends string = string> implements
     private readonly tableName;
     private readonly createTable;
     private readonly prefix;
+    private readonly timeoutMs;
     private tableReady;
     protected constructor(client: SqlClientLike, dialect: SqlDialect, adapterName: string, options: SqlErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -396,6 +544,8 @@ declare abstract class SqlErrorAdapter<TCode extends string = string> implements
     /** Creates the table once. A failed attempt is retried on the next log call. */
     private ensureTable;
     private runCreateStatements;
+    /** Runs one statement, giving up waiting after `timeoutMs`. */
+    private query;
 }
 /**
  * Writes entries to Postgres. Pass a `pg` `Pool` or `Client`.
@@ -454,6 +604,12 @@ interface RedisErrorOptions {
     side?: 'left' | 'right';
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for each Redis command before giving up, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. The call cannot be
+     * cancelled, so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 /**
  * Writes entries to Redis, either as a capped list of JSON strings or as a
@@ -467,6 +623,7 @@ declare class RedisErrorAdapter<TCode extends string = string> implements ErrorL
     private readonly maxEntries;
     private readonly side;
     private readonly prefix;
+    private readonly timeoutMs;
     /** @throws {RangeError} if `key` is empty, `maxEntries` is not a positive integer, or `mode` / `side` is unknown. */
     constructor(client: RedisClientLike, options?: RedisErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -476,6 +633,8 @@ declare class RedisErrorAdapter<TCode extends string = string> implements ErrorL
      * stored by now, so a trim failure is reported but does not fail the call;
      * the next successful write trims the list again.
      */
+    /** Sends one command, giving up waiting after `timeoutMs`. */
+    private send;
     private trimList;
 }
 
@@ -492,6 +651,11 @@ interface S3PutObjectInput {
  * it is, and so does anything else that follows the S3 API, including
  * DigitalOcean Spaces, Cloudflare R2 and MinIO when you point the client at
  * their endpoint.
+ *
+ * Some S3-compatible providers reject the checksum headers that recent AWS SDK
+ * v3 versions add by default. If uploads fail with a checksum or header error,
+ * create the client with `requestChecksumCalculation: 'WHEN_REQUIRED'` and
+ * `responseChecksumValidation: 'WHEN_REQUIRED'`.
  */
 interface S3ClientLike {
     putObject(input: S3PutObjectInput): Promise<unknown>;
@@ -523,6 +687,13 @@ interface S3ErrorOptions {
     batch?: S3BatchOptions;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long an upload may take before `log` (or `flush`) gives up waiting, in
+     * milliseconds. Defaults to 10000. Pass `Infinity` to wait without limit. The
+     * upload cannot be cancelled, so it may still finish afterwards; in batch mode
+     * the entries stay buffered and are uploaded again by the next flush.
+     */
+    timeoutMs?: number;
 }
 /**
  * Stores entries as objects in an S3-compatible bucket, keyed by date and UUID:
@@ -541,9 +712,10 @@ declare class S3ErrorAdapter<TCode extends string = string> implements ErrorLogA
     private readonly contentType;
     private readonly batch;
     private readonly logPrefix;
+    private readonly timeoutMs;
     private buffer;
     private timer;
-    private flushQueue;
+    private readonly flushQueue;
     /** @throws {RangeError} if `bucket` is empty or the batch options are invalid. */
     constructor(client: S3ClientLike, bucket: string, options?: S3ErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -559,4 +731,202 @@ declare class S3ErrorAdapter<TCode extends string = string> implements ErrorLogA
     private fail;
 }
 
-export { type CollectionLike, CompositeErrorAdapter, ConsoleErrorAdapter, type ConsoleErrorOptions, type ErrorLogAdapter, type ErrorLogEntry, type ErrorLogResult, type FileSystemLike, FlatFileErrorAdapter, type FlatFileErrorOptions, type IdbDatabaseLike, type IdbObjectStoreLike, type IdbTransactionLike, type IdbUpgradeDatabaseLike, IndexedDbErrorAdapter, type IndexedDbErrorOptions, type IndexedDbErrorRecord, JsonFileErrorAdapter, type JsonFileErrorOptions, type JsonFileErrorRecord, MongoDbErrorAdapter, type MongoDbErrorOptions, MySqlErrorAdapter, PostgresErrorAdapter, type ReadWriteFileSystemLike, type RedisClientLike, RedisErrorAdapter, type RedisErrorOptions, type S3BatchOptions, type S3ClientLike, S3ErrorAdapter, type S3ErrorOptions, type S3PutObjectInput, type SerializedErrorLogEntry, type SqlClientLike, type SqlDialect, type SqlErrorOptions, type SqliteClientLike, SqliteErrorAdapter, type SqliteErrorOptions, type StorageLike, WebStorageErrorAdapter, type WebStorageErrorOptions, type WebStorageErrorRecord, WebhookErrorAdapter, type WebhookErrorOptions, buildCreateErrorLogTableSql, buildErrorLogTableDdl, createErrorLogStore, formatErrorLogLine, serializeCause, serializeEntry };
+/** The fields stored for each entry, in Firestore and in the Realtime Database. */
+interface FirebaseErrorRecord {
+    /** UUID. In Firestore it is also the document id. */
+    id: string;
+    code: string;
+    message: string;
+    /** ISO 8601 timestamp of the entry. */
+    timestamp: string;
+    source?: string;
+    /**
+     * The entry's cause as a JSON string. Plain text avoids Firestore's limits on
+     * custom objects and nested arrays, and the Realtime Database's limits on key
+     * characters, so an odd cause can never make the write fail.
+     */
+    cause?: string;
+}
+/**
+ * The only thing the Firestore adapter needs from a collection: `doc(id).set(data)`.
+ * A `firebase-admin` collection (`getFirestore().collection('error_log')`) fits
+ * as it is. With the web SDK, wrap it:
+ *
+ * ```ts
+ * const collectionLike: FirestoreCollectionLike = {
+ *   doc: (id) => ({ set: (data) => setDoc(doc(db, 'error_log', id), data) }),
+ * };
+ * ```
+ */
+interface FirestoreCollectionLike {
+    doc(documentId: string): {
+        set(data: FirebaseErrorRecord): Promise<unknown>;
+    };
+}
+/**
+ * The only thing the Realtime Database adapter needs from a reference:
+ * `push(value)`, which resolves once the write is saved. A `firebase-admin`
+ * reference (`getDatabase().ref('error_log')`) fits as it is. With the web SDK, wrap it:
+ *
+ * ```ts
+ * const refLike: RealtimeDatabaseRefLike = {
+ *   push: (value) => push(ref(db, 'error_log'), value),
+ *   child: (key) => ({ set: (value) => set(ref(db, `error_log/${key}`), value) }),
+ * };
+ * ```
+ *
+ * `child(key).set(value)` is only needed for entries that carry their own `id`
+ * (see `ErrorLogEntry.id`): they are written under that key, so logging the same
+ * entry again overwrites the record instead of adding a second one.
+ */
+interface RealtimeDatabaseRefLike {
+    push(value: FirebaseErrorRecord): PromiseLike<unknown>;
+    child?(key: string): {
+        set(value: FirebaseErrorRecord): PromiseLike<unknown>;
+    };
+}
+interface FirebaseErrorOptions {
+    /**
+     * How long `log` waits for the write to be saved before giving up, in
+     * milliseconds. Defaults to 10000. Pass `Infinity` to wait without limit.
+     *
+     * The Firebase SDKs keep writes queued while the connection is down, and
+     * their promises stay pending until it returns, so without a limit `log`
+     * could hang for as long as an outage lasts. A write that timed out is still
+     * queued by the SDK and may be saved later. Retry a timeout only with the same
+     * `ErrorLogEntry.id`, so the retry overwrites the first write instead of
+     * adding a second one.
+     */
+    timeoutMs?: number;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * Writes each entry as a document in a Firestore collection. The document id is
+ * the entry's UUID, so the SDK finishing one queued write twice cannot create two
+ * documents. Calling `log` again without an `id` on the entry is a new write
+ * with a new UUID: if a call reported a timeout, the first write may still be
+ * saved later, and logging the same entry again can store it twice. Give the
+ * entry an `id` and the retry overwrites the same document.
+ */
+declare class FirestoreErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly collection;
+    private readonly prefix;
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or `Infinity`. */
+    constructor(collection: FirestoreCollectionLike, options?: FirebaseErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+/**
+ * Writes each entry under a Realtime Database reference with `push`, which
+ * generates a chronologically ordered key.
+ */
+declare class RealtimeDatabaseErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly reference;
+    private readonly prefix;
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or `Infinity`. */
+    constructor(reference: RealtimeDatabaseRefLike, options?: FirebaseErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+
+/** The row inserted for each entry. The columns match the Postgres adapter's table. */
+interface SupabaseErrorRow {
+    /** UUID primary key. */
+    id: string;
+    code: string;
+    message: string;
+    /** The cause as JSON, or `null` when the entry has none. */
+    cause: unknown;
+    source: string | null;
+    /** ISO 8601 timestamp of the entry. */
+    occurred_at: string;
+}
+/** The error object `supabase-js` returns (a `PostgrestError`) instead of throwing. */
+interface SupabaseErrorLike {
+    message: string;
+    code?: string;
+    details?: string | null;
+    hint?: string | null;
+}
+/** What `insert` resolves to. The status fields are used when the error has no message. */
+interface SupabaseInsertResult {
+    error: SupabaseErrorLike | null;
+    status?: number;
+    statusText?: string;
+}
+/**
+ * The only thing the Supabase adapter needs from a client: `from(table).insert(row)`.
+ * A `supabase-js` client (`createClient(url, key)`) fits as it is.
+ */
+interface SupabaseClientLike {
+    from(table: string): {
+        insert(row: SupabaseErrorRow): PromiseLike<SupabaseInsertResult>;
+    };
+}
+interface SupabaseErrorOptions {
+    /** Table to write to. Defaults to `error_log`. Letters, digits and `_` only. */
+    tableName?: string;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+    /**
+     * How long `log` waits for Supabase to answer before giving up, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. The call cannot be
+     * cancelled, so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
+}
+interface SupabaseSetupOptions {
+    /**
+     * Postgres roles allowed to insert through the API, for example
+     * `['authenticated']`. Leave empty when only a server using the service role
+     * key logs: that role bypasses row level security, so it needs no policy, and
+     * its key must never be shipped to a browser.
+     *
+     * The generated policy only checks the size of each field. It does not tie a
+     * row to a user, so any holder of an allowed role's key can still add entries
+     * of their own making: forged entries can hide real incidents, and a flood of
+     * them uses up your database quota. Prefer `authenticated` over `anon`.
+     */
+    insertRoles?: string[];
+    /**
+     * Required to allow `anon` (or `public`) to insert. The `anon` key is part of
+     * your frontend, so this lets anyone who loads the page write to the log.
+     * Defaults to `false`.
+     */
+    allowPublicInsert?: boolean;
+}
+/**
+ * Returns the SQL to run once in the Supabase SQL editor: the error log table,
+ * with row level security turned on (as Supabase recommends for every table in
+ * an exposed schema) and, optionally, an insert-only policy for the given roles.
+ * The policy limits the size of each field. Nobody but the service role can read
+ * the log through the API.
+ *
+ * @throws {RangeError} if the table name or a role is not a plain identifier, or
+ * `anon` / `public` is listed without `allowPublicInsert: true`.
+ */
+declare function buildSupabaseSetupSql(tableName?: string, options?: SupabaseSetupOptions): string[];
+/**
+ * Writes entries to a Supabase table through `supabase-js`. Create the table
+ * first with `buildSupabaseSetupSql` (or `buildErrorLogTableDdl('postgres')`).
+ *
+ * ```ts
+ * const adapter = new SupabaseErrorAdapter(createClient(url, serviceRoleKey));
+ * ```
+ *
+ * `supabase-js` reports failures in a returned `error` field rather than
+ * throwing; the adapter turns both that and a thrown error into `{ ok: false }`.
+ */
+declare class SupabaseErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly client;
+    private readonly tableName;
+    private readonly prefix;
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.tableName` is not a plain identifier or `options.timeoutMs` is invalid. */
+    constructor(client: SupabaseClientLike, options?: SupabaseErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+    private fail;
+}
+
+export { type CollectionLike, CompositeErrorAdapter, type CompositeErrorOptions, ConsoleErrorAdapter, type ConsoleErrorOptions, type ErrorLogAdapter, type ErrorLogEntry, type ErrorLogResult, type FileSystemLike, type FirebaseErrorOptions, type FirebaseErrorRecord, type FirestoreCollectionLike, FirestoreErrorAdapter, FlatFileErrorAdapter, type FlatFileErrorOptions, type IdbDatabaseLike, type IdbObjectStoreLike, type IdbRequestLike, type IdbTransactionLike, type IdbUpgradeDatabaseLike, IndexedDbErrorAdapter, type IndexedDbErrorOptions, type IndexedDbErrorRecord, JsonFileErrorAdapter, type JsonFileErrorOptions, type JsonFileErrorRecord, type LockManagerLike, MongoDbErrorAdapter, type MongoDbErrorOptions, MySqlErrorAdapter, PostgresErrorAdapter, type ReadWriteFileSystemLike, RealtimeDatabaseErrorAdapter, type RealtimeDatabaseRefLike, type RedisClientLike, RedisErrorAdapter, type RedisErrorOptions, type S3BatchOptions, type S3ClientLike, S3ErrorAdapter, type S3ErrorOptions, type S3PutObjectInput, type SerializedErrorLogEntry, type SqlClientLike, type SqlDialect, type SqlErrorOptions, type SqliteClientLike, SqliteErrorAdapter, type SqliteErrorOptions, type StorageLike, type SupabaseClientLike, SupabaseErrorAdapter, type SupabaseErrorLike, type SupabaseErrorOptions, type SupabaseErrorRow, type SupabaseInsertResult, type SupabaseSetupOptions, WebStorageErrorAdapter, type WebStorageErrorOptions, type WebStorageErrorRecord, WebhookErrorAdapter, type WebhookErrorOptions, buildCreateErrorLogTableSql, buildErrorLogTableDdl, buildMySqlWidenColumnsSql, buildSupabaseSetupSql, createErrorLogStore, formatErrorLogLine, serializeCause, serializeEntry };