ironflock 1.5.1 → 1.5.3

package/dist/index.d.ts

@@ -28,6 +28,24 @@ 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";
@@ -200,7 +218,39 @@ export declare class IronFlock {
      *   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>;
     /**
@@ -255,7 +305,37 @@ export declare class IronFlock {
      */
     getSeriesHistory(tablename: string, params: SeriesQueryParams): Promise<unknown>;
     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`.