ironflock 1.3.2 → 1.5.1

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { default as default_2 } from 'autobahn';
 import { default as default_3 } from 'typia';
 import { EventEmitter } from 'eventemitter3';
 import { StandardSchemaV1 } from '@standard-schema/spec';
+import { Subscription } from 'autobahn';
 import { tags } from 'typia';
 
 export declare type AuthPayload = {
@@ -27,12 +28,95 @@ export declare interface CallParams {
     kwargs?: Record<string, unknown>;
 }
 
+export declare interface ConnectToAppOptions {
+    /** Provider stage to connect to. Defaults to this app's own stage (ENV). */
+    stage?: "dev" | "prod";
+    /**
+     * Invoked when the consumed-app connection is fatally denied AFTER
+     * connectToApp resolved (e.g. the grant was revoked and the next reconnect
+     * was refused). While connectToApp is still pending, the same condition
+     * surfaces as a rejection instead.
+     */
+    onError?: (error: CrossAppAccessError) => void;
+}
+
+/**
+ * Read-only handle on another app's data backend, returned by
+ * {@link IronFlock.connectToApp}. Wraps a dedicated WAMP connection to the
+ * provider's realm; the router restricts it to subscribing `transformed.*`
+ * and calling `history.transformed.*`. Transforms (views) are consumable
+ * exactly like tables — same topic/RPC names — except for series history,
+ * which exists for tables only.
+ */
+export declare class ConsumedApp {
+    /** Provider app name, as declared in `consumes:`. */
+    readonly app: string;
+    /** Provider stage this handle is connected to. */
+    readonly stage: "dev" | "prod";
+    /** Non-private tables the provider shares on this stage. */
+    readonly tables: ProviderTableInfo[];
+    /** Non-private transforms (views) the provider shares on this stage. */
+    readonly transforms: ProviderTableInfo[];
+    private _connection;
+    private _onClosed?;
+    constructor(app: string, stage: "dev" | "prod", catalog: ConsumedAppStageCatalog, connection: CrossbarConnection, onClosed?: () => void);
+    get connection(): CrossbarConnection;
+    get isConnected(): boolean;
+    private assertInCatalog;
+    /**
+     * Subscribes to realtime rows of a shared table or transform. Bulk inserts
+     * (`transformed.bulk.{t}`) are unrolled row-by-row through the same handler,
+     * so caller code always sees the single-row shape.
+     */
+    subscribeToTable(tablename: string, handler: (...args: any[]) => void, options?: object): Promise<Subscription<any[], any, string> | undefined>;
+    /** Queries history rows of a shared table or transform. */
+    getHistory(tablename: string, queryParams?: TableQueryParams): Promise<unknown>;
+    /** Queries down-sampled series history of a shared table (tables only — no series RPC exists for transforms). */
+    getSeriesHistory(tablename: string, params: SeriesQueryParams): Promise<unknown>;
+    /** Closes the underlying connection to the provider's realm. */
+    close(): Promise<void>;
+}
+
+/**
+ * Result of `sys.appaccess.resolve`. A stage is present only when the provider's
+ * data backend exists for that stage; catalogs list non-private entries only.
+ */
+export declare interface ConsumedAppInfo {
+    app: string;
+    provider_app_key: number;
+    stages: {
+        dev?: ConsumedAppStageCatalog;
+        prod?: ConsumedAppStageCatalog;
+    };
+}
+
+/** Per-stage catalog of what a provider app shares. */
+export declare interface ConsumedAppStageCatalog {
+    tables: ProviderTableInfo[];
+    transforms: ProviderTableInfo[];
+}
+
+/** Raised when reading another app's data backend is declined or misused. */
+export declare class CrossAppAccessError extends Error {
+    readonly code: CrossAppAccessErrorCode;
+    constructor(code: CrossAppAccessErrorCode, message?: string);
+}
+
+export declare type CrossAppAccessErrorCode = "NO_GRANT" | "PROVIDER_NOT_INSTALLED" | "UNKNOWN_APP" | "PRIVATE_TABLE" | "NOT_AUTHORIZED";
+
 export declare class CrossbarConnection extends EventEmitter {
     session?: default_2.Session;
     connection?: default_2.Connection;
     serial_number?: string;
     socketURI?: string;
     realm?: string;
+    /**
+     * Opt-in (used for consumed-app connections): treat an auth/authorization
+     * denial on close as fatal — stop all reconnect attempts and emit
+     * "auth_failure" instead of retrying forever. The primary own-realm
+     * connection keeps the default (false): retry through every failure.
+     */
+    failOnAuthError: boolean;
     private subscriptions;
     private registrations;
     private firstConnection?;
@@ -70,6 +154,19 @@ export declare type Details = {
     caller_authrole: string;
 };
 
+/** Down-sampling aggregation applied per time bucket in a series query. */
+export declare type DownSampleMethod = "AVG" | "SUM" | "COUNT" | "MIN" | "MAX" | "FIRST" | "LAST";
+
+/**
+ * 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;
@@ -82,14 +179,45 @@ export declare class IronFlock {
     private _isConfigured;
     private _reswarmUrl?;
     private _cburl?;
+    private _consumedApps;
     constructor(options?: IronFlockOptions);
     get connection(): CrossbarConnection;
     get isConnected(): boolean;
     private configureConnection;
     start(cburl?: string): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Opens a read-only connection to another app's data backend in the same
+     * project. The provider app must be declared in this app's data-template
+     * `consumes:` section and the project user must have granted access.
+     *
+     * Resolves the provider via `sys.appaccess.resolve`, then connects to the
+     * provider's realm with this device's credentials (router role
+     * `app_reader`). Connections are cached per app+stage and closed by
+     * {@link stop}.
+     *
+     * @throws {CrossAppAccessError} NO_GRANT | PROVIDER_NOT_INSTALLED |
+     *   UNKNOWN_APP | NOT_AUTHORIZED
+     */
+    connectToApp(appName: string, opts?: ConnectToAppOptions): Promise<ConsumedApp>;
+    private openConsumedApp;
     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
@@ -120,6 +248,12 @@ export declare class IronFlock {
     registerFunction(topic: string, endpoint: (...args: any[]) => any, options?: default_2.IRegisterOptions): Promise<default_2.IRegistration<any, any[], any, string> | undefined>;
     register(topic: string, endpoint: (...args: any[]) => any, options?: default_2.IRegisterOptions): Promise<default_2.IRegistration<any, any[], any, string> | undefined>;
     getHistory(tablename: string, queryParams?: TableQueryParams): Promise<unknown>;
+    /**
+     * Queries down-sampled series history of an own table by calling
+     * `history.transformed.series.{tablename}` (tables only — no series RPC
+     * exists for transforms).
+     */
+    getSeriesHistory(tablename: string, params: SeriesQueryParams): Promise<unknown>;
     setDeviceLocation(long: number, lat: number): Promise<unknown>;
     getRemoteAccessUrlForPort(port: number): string | null;
     /**
@@ -161,12 +295,50 @@ export declare interface LocationParams {
     latitude: number & tags.Minimum<-90> & tags.Maximum<90>;
 }
 
+/** A non-private table or transform another app shares, as listed in its catalog. */
+export declare interface ProviderTableInfo {
+    tablename: string;
+    description?: string;
+    /** Column definitions as declared in the provider's data-template. */
+    columns?: Array<Record<string, unknown>>;
+}
+
 export declare interface PublishParams {
     topic: string & tags.MinLength<1>;
     args?: unknown[];
     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;
+}
+
+/** Query parameters for `history.transformed.series.{tablename}` (mirrors fleetdb's SeriesQueryParams). */
+export declare interface SeriesQueryParams {
+    /** Numeric columns to down-sample. */
+    metrics: string[];
+    method: DownSampleMethod;
+    limit: number & tags.Type<"uint32"> & tags.Minimum<1> & tags.Maximum<10000>;
+    /** Required — the series RPC rejects queries without a time range. */
+    timeRange: SeriesTimeRange;
+    groupBy?: string[] | null;
+    filterAnd?: SQLFilterAnd[] | null;
+}
+
+/**
+ * [start, end] tuple — ISO date-time strings or epoch-ms numbers; null = open end.
+ * Mirrors fleetdb's TimeRangeInput (a tuple, unlike TableQueryParams.timeRange).
+ */
+export declare type SeriesTimeRange = [string | null, string | null] | [number | null, number | null];
+
 export declare interface SQLFilterAnd {
     column: string & tags.MinLength<1>;
     operator: string & tags.MinLength<1>;
@@ -199,6 +371,8 @@ export declare const validateLocationParams: ((input: unknown) => default_3.IVal
 
 export declare const validatePublishParams: ((input: unknown) => default_3.IValidation<PublishParams>) & StandardSchemaV1<PublishParams, PublishParams>;
 
+export declare const validateSeriesQueryParams: ((input: unknown) => default_3.IValidation<SeriesQueryParams>) & StandardSchemaV1<SeriesQueryParams, SeriesQueryParams>;
+
 export declare const validateTableParams: ((input: unknown) => default_3.IValidation<TableParams>) & StandardSchemaV1<TableParams, TableParams>;
 
 export declare const validateTableQueryParams: ((input: unknown) => default_3.IValidation<TableQueryParams>) & StandardSchemaV1<TableQueryParams, TableQueryParams>;