ironflock 1.3.3 → 1.5.2

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,113 @@ export declare interface CallParams {
     kwargs?: Record<string, unknown>;
 }
 
+export declare interface ConnectToAllAppsOptions {
+    /** Provider stage to connect to. Defaults to this app's own stage (ENV). */
+    stage?: "dev" | "prod";
+    /**
+     * Invoked with the failure of each provider that could not be opened (only
+     * when continueOnError is true — otherwise the first failure rejects), and
+     * with a {@link CrossAppAccessError} if an already-opened provider connection
+     * is later fatally denied (grant revoked → refused reconnect).
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * When true (the default) a provider that fails to open is reported via
+     * onError and omitted from the result. When false the first failure rejects
+     * connectToAllApps.
+     */
+    continueOnError?: boolean;
+}
+
+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 +172,9 @@ 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
@@ -92,12 +197,60 @@ 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>;
+    /**
+     * Lists every non-private provider catalog in this project for an app holding
+     * the wildcard consume grant (`consumes: [{app: "*"}]`). One
+     * `sys.appaccess.list` call; opens no consumed-app connections. A picker (e.g.
+     * a Node-RED node) renders the returned catalogs, then calls
+     * {@link connectToApp} per chosen provider; {@link connectToAllApps} opens
+     * them all eagerly.
+     *
+     * @throws {CrossAppAccessError} NO_GRANT when this app holds no wildcard grant.
+     */
+    listConsumableApps(): Promise<ConsumedAppInfo[]>;
+    /**
+     * Opens read-only connections to every non-private provider in this project
+     * (wildcard consumers only). Enumerates providers via {@link listConsumableApps}
+     * and opens each directly from its resolved info — no per-app resolve
+     * round-trip. Each handle is cached under the same `${app}:${stage}` key
+     * {@link connectToApp} uses, so a later `connectToApp(name)` returns the warmed
+     * handle. Providers lacking a data backend for the requested stage are skipped.
+     *
+     * @throws {CrossAppAccessError} NO_GRANT when this app holds no wildcard grant.
+     */
+    connectToAllApps(opts?: ConnectToAllAppsOptions): Promise<ConsumedApp[]>;
+    private openConsumedApp;
+    /** Caches (or reuses) a connection opened directly from a resolved provider
+     * info, using the same `${app}:${stage}` key as {@link connectToApp}. */
+    private openCachedFromInfo;
+    /**
+     * Opens the second CrossbarConnection to a provider realm from an already
+     * resolved {@link ConsumedAppInfo} — everything after the sys.appaccess.resolve
+     * round-trip. Shared by {@link connectToApp} (which resolves one provider) and
+     * {@link connectToAllApps} (which lists every provider in one call).
+     */
+    private openFromInfo;
     publish(topic: string, args?: unknown[], kwargs?: Record<string, unknown>): Promise<unknown>;
     publishToTable(tablename: string, args?: unknown[], kwargs?: Record<string, unknown>): Promise<unknown>;
     /**
@@ -145,6 +298,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;
     /**
@@ -186,6 +345,14 @@ 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[];
@@ -204,6 +371,24 @@ export declare interface ReportErrorOptions {
     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>;
@@ -236,6 +421,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>;