ironflock 1.3.2 → 1.3.3

package/dist/index.d.ts

@@ -70,6 +70,16 @@ export declare type Details = {
     caller_authrole: string;
 };
 
+/**
+ * Name of the per-databackend system error table. Apps report errors into it via
+ * {@link IronFlock.reportError}; it behaves like any normal table, so it can be
+ * queried (getHistory) and streamed (subscribeToTable) and used in board-templates.
+ */
+export declare const ERROR_LOGS_TABLE = "error-logs";
+
+/** Severity level recorded alongside a reported error. */
+export declare type ErrorLevel = "error" | "warn" | "info" | "debug";
+
 export declare class IronFlock {
     private _connection;
     private _serialNumber;
@@ -90,6 +100,21 @@ export declare class IronFlock {
     stop(): Promise<void>;
     publish(topic: string, args?: unknown[], kwargs?: Record<string, unknown>): Promise<unknown>;
     publishToTable(tablename: string, args?: unknown[], kwargs?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Reports an application error into the databackend's `error-logs` table.
+     *
+     * This is a thin convenience wrapper over {@link publishToTable} /
+     * {@link appendToTable}: it stamps the row with `source: "app"`, a severity
+     * `level`, and a timestamp, then writes it like any normal table row. The error
+     * therefore lands in the same `error-logs` table that fleetdb system errors use
+     * (tagged `source: "system"`), and is delivered in realtime on
+     * `transformed.error-logs` — the channel board-templates consume — without
+     * touching the platform error-toast channel (`databackend.errors.*`).
+     *
+     * @param error  An error message, or an Error whose stack/message is recorded.
+     * @param opts   Optional level (default "error"), append flag, and tsp override.
+     */
+    reportError(error: string | Error, opts?: ReportErrorOptions): Promise<unknown>;
     appendToTable(tablename: string, args?: unknown[], kwargs?: Record<string, unknown>): Promise<unknown>;
     /**
      * Publishes many rows in a single message (bulk insert) to the dedicated topic
@@ -167,6 +192,18 @@ export declare interface PublishParams {
     kwargs?: Record<string, unknown>;
 }
 
+export declare interface ReportErrorOptions {
+    /** Severity level. Defaults to "error". */
+    level?: ErrorLevel;
+    /**
+     * When true, use the RPC append path (resolves with the insert outcome).
+     * Defaults to false: fire-and-forget publish, matching typical logging.
+     */
+    append?: boolean;
+    /** ISO-8601 timestamp override. Defaults to the current time. */
+    tsp?: string;
+}
+
 export declare interface SQLFilterAnd {
     column: string & tags.MinLength<1>;
     operator: string & tags.MinLength<1>;