ironflock 1.5.2 → 1.5.3

package/dist/index.d.ts

@@ -305,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`.