ironflock 1.5.2 → 1.6.0

package/dist/index.d.ts

@@ -5,6 +5,14 @@ import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Subscription } from 'autobahn';
 import { tags } from 'typia';
 
+/**
+ * Rejects a `latest` marker (or a legacy latest_flag predicate) in series
+ * query filters before the request reaches the backend: the series SQL path
+ * has no latest-per-entity mode and would generate invalid SQL. Read current
+ * values with getHistory and `filterAnd: [{ latest: true }]` instead.
+ */
+export declare function assertNoLatestMarker(params: SeriesQueryParams | null | undefined): void;
+
 export declare type AuthPayload = {
     success: boolean;
     role: string;
@@ -87,9 +95,20 @@ export declare class ConsumedApp {
      * 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. */
+    /**
+     * Queries history rows of a shared table or transform. To read the CURRENT
+     * value(s), add the `latest` marker to the filters:
+     * `{ filterAnd: [{ latest: true }], limit: 100 }` — the provider's data
+     * backend derives the latest row per entity in SQL (the physical
+     * `latest_flag` column no longer exists).
+     */
     getHistory(tablename: string, queryParams?: TableQueryParams): Promise<unknown>;
-    /** Queries down-sampled series history of a shared table (tables only — no series RPC exists for transforms). */
+    /**
+     * Queries down-sampled series history of a shared table (tables only — no
+     * series RPC exists for transforms). Series queries do not support the
+     * `latest` marker; use {@link getHistory} with
+     * `filterAnd: [{ latest: true }]` to read current values.
+     */
     getSeriesHistory(tablename: string, params: SeriesQueryParams): Promise<unknown>;
     /** Closes the underlying connection to the provider's realm. */
     close(): Promise<void>;
@@ -150,6 +169,10 @@ export declare class CrossbarConnection extends EventEmitter {
     private onOpen;
     private onClose;
     private handleManualReconnect;
+    /**
+     * Waits for an open session; `context` names the pending operation so the
+     * timeout error explains what could not be performed and why.
+     */
     private sessionWait;
     waitForConnection(): Promise<void | undefined>;
     getSession(): default_2.Session | undefined;
@@ -163,8 +186,8 @@ export declare class CrossbarConnection extends EventEmitter {
     private reregisterAll;
     register(topic: string, endpoint: default_2.RegisterEndpoint, options?: default_2.IRegisterOptions): Promise<default_2.IRegistration | undefined>;
     unregister(registration: default_2.Registration): Promise<void>;
-    call<T>(procedure: string, args?: any[], kwargs?: object, options?: any): Promise<T | undefined>;
-    publish(topic: string, args?: any[], kwargs?: object, options?: any): Promise<default_2.IPublication | undefined>;
+    call<T>(procedure: string, args?: any[], kwargs?: object, options?: any): Promise<T>;
+    publish(topic: string, args?: any[], kwargs?: object, options?: any): Promise<default_2.IPublication>;
 }
 
 export declare type Details = {
@@ -297,15 +320,70 @@ export declare class IronFlock {
     /** @deprecated Use registerDeviceFunction() instead. */
     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>;
+    /**
+     * Queries history rows of an own table or transform via
+     * `history.transformed.{tablename}`.
+     *
+     * To read the CURRENT value(s) instead of raw history, add the `latest`
+     * marker to `filterAnd`: `{ filterAnd: [{ latest: true }], limit: 100 }`.
+     * The data backend then derives the latest row per entity in SQL (the
+     * entity key is the table's `maintainLatestFlagFor` columns; without one,
+     * the single most recent row is returned). The former physical
+     * `latest_flag` column no longer exists.
+     *
+     * @throws {Error} on invalid parameters, when the history procedure is not
+     *   registered (table missing / data backend down), or when the call fails.
+     */
     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).
+     * exists for transforms). Series queries do not support the `latest`
+     * marker; use {@link getHistory} with `filterAnd: [{ latest: true }]` to
+     * read current values.
+     *
+     * @throws {Error} on invalid parameters, when the series procedure is not
+     *   registered (table missing / data backend down), or when the call fails.
      */
     getSeriesHistory(tablename: string, params: SeriesQueryParams): Promise<unknown>;
+    /**
+     * Updates the device's location in the platform master data.
+     *
+     * @throws {Error} on invalid coordinates or when the location service call
+     *   fails (e.g. not connected).
+     */
     setDeviceLocation(long: number, lat: number): Promise<unknown>;
-    getRemoteAccessUrlForPort(port: number): string | null;
+    /**
+     * Public URL under which a declared port (port-template.yml) is reachable
+     * from the internet once its tunnel is active.
+     *
+     * For `http`/`https` ports, composes the platform's tunnel label
+     * `{device_key}-{app_name}-{port}` (`https` ports carry the platform's
+     * `secure-` prefix) on the tunnel domain the device agent injects
+     * (`TUNNEL_DOMAIN`; the cloud edge, or the operator's appliance domain).
+     * On devices that belong to an instance (appliance), the agent injects
+     * `INSTANCE_KEY` and the cloud-forwarded route
+     * `https://i{instance_key}-{label}.{cloud edge}` is returned instead —
+     * reachable while the instance forwards its tunnels to the cloud.
+     *
+     * For `tcp`/`udp` ports, the URL uses the tunnel-assigned public port,
+     * which the platform injects under the port-template's
+     * `remote_port_environment` name — pass that name here. On instance
+     * devices the internet-facing port arrives as `{name}_CLOUD`; when it is
+     * not (yet) present, the instance-local URL built from `{name}` is
+     * returned as a fallback.
+     *
+     * Port values are read live from the agent-maintained files under
+     * `/data/env` (falling back to the process environment), so this method
+     * returns the CURRENT url: the instance cloud port is allocated shortly
+     * after the tunnel first connects and appears here within seconds — call
+     * the method again rather than caching its result.
+     *
+     * Returns null when the identity or required env vars are unavailable,
+     * the protocol is unknown, or the label is not a valid DNS label (longer
+     * than 63 characters, or a dot in the app name).
+     */
+    getRemoteAccessUrlForPort(port: number, protocol?: string, remotePortEnvironment?: string): string | null;
     /**
      * Create an IronFlock instance by fetching configuration from a server endpoint.
      * The endpoint should return JSON matching `IronFlockOptions`.
@@ -340,6 +418,20 @@ export declare interface ISOTimeRange {
     end: string & tags.Format<"date-time">;
 }
 
+/**
+ * Mode marker for `filterAnd`: requests "latest row per entity" instead of
+ * adding a WHERE predicate. fleetdb derives the latest rows in SQL
+ * (DISTINCT ON over the entity key the table declares via
+ * `maintainLatestFlagFor` in its data-template; a table without an entity key
+ * yields the single most recent row). Replaces the removed physical
+ * `latest_flag` column — a legacy `{column: "latest_flag", operator: "=",
+ * value: true}` predicate is still accepted by the server and treated as this
+ * marker.
+ */
+export declare interface LatestMarker {
+    latest: true;
+}
+
 export declare interface LocationParams {
     longitude: number & tags.Minimum<-180> & tags.Maximum<180>;
     latitude: number & tags.Minimum<-90> & tags.Maximum<90>;
@@ -380,6 +472,7 @@ export declare interface SeriesQueryParams {
     /** Required — the series RPC rejects queries without a time range. */
     timeRange: SeriesTimeRange;
     groupBy?: string[] | null;
+    /** WHERE predicates only — the `latest` marker is not supported in series queries. */
     filterAnd?: SQLFilterAnd[] | null;
 }
 
@@ -400,6 +493,9 @@ export declare enum Stage {
     PRODUCTION = "prod"
 }
 
+/** One entry of `filterAnd`: a WHERE predicate or the `latest` mode marker. */
+export declare type TableFilter = SQLFilterAnd | LatestMarker;
+
 export declare interface TableParams {
     tablename: string & tags.MinLength<1>;
     args?: unknown[];
@@ -410,7 +506,12 @@ export declare interface TableQueryParams {
     limit: number & tags.Type<"uint32"> & tags.Minimum<1> & tags.Maximum<10000>;
     offset?: number & tags.Type<"uint32"> & tags.Minimum<0>;
     timeRange?: ISOTimeRange;
-    filterAnd?: SQLFilterAnd[];
+    filterAnd?: TableFilter[];
+    /**
+     * Columns to return (the system columns tsp, device_key and authid are
+     * always included). Omit for all columns.
+     */
+    columns?: string[];
 }
 
 export declare const validateBulkTableParams: ((input: unknown) => default_3.IValidation<BulkTableParams>) & StandardSchemaV1<BulkTableParams, BulkTableParams>;
@@ -427,4 +528,19 @@ export declare const validateTableParams: ((input: unknown) => default_3.IValida
 
 export declare const validateTableQueryParams: ((input: unknown) => default_3.IValidation<TableQueryParams>) & StandardSchemaV1<TableQueryParams, TableQueryParams>;
 
+/**
+ * Error thrown when a WAMP operation (call/publish/subscribe/register) is
+ * rejected by the router or the remote handler. autobahn rejects with a plain
+ * `{error: <uri>, args, kwargs}` object that is not a native Error and prints
+ * as "[object Object]" — this preserves the WAMP error URI and payload while
+ * giving callers a readable message and a stack trace.
+ */
+export declare class WampError extends Error {
+    /** WAMP error URI, e.g. "wamp.error.no_such_procedure". */
+    readonly error: string;
+    readonly args: unknown[];
+    readonly kwargs: Record<string, unknown>;
+    constructor(message: string, uri: string, args?: unknown[], kwargs?: Record<string, unknown>);
+}
+
 export { }