@holochain/client 0.17.0-dev.5 → 0.17.0-dev.6

package/README.md

@@ -34,7 +34,7 @@ npm install --save-exact @holochain/client
 ```typescript
 import { ActionHash, AdminWebsocket, AppAgentWebsocket, CellType } from "@holochain/client";
 
-const adminWs = await AdminWebsocket.connect("ws://127.0.0.1:65000");
+const adminWs = await AdminWebsocket.connect({url: "ws://127.0.0.1:65000"});
 const agent_key = await adminWs.generateAgentPubKey();
 const role_name = "role";
 const installed_app_id = "test-app";
@@ -51,10 +51,7 @@ if (!(CellType.Provisioned in appInfo.cell_info[role_name][0])) {
 const { cell_id } = appInfo.cell_info[role_name][0][CellType.Provisioned];
 await adminWs.authorizeSigningCredentials(cell_id);
 await adminWs.attachAppInterface({ port: 65001 });
-const appAgentWs = await AppAgentWebsocket.connect(
-  "ws://127.0.0.1:65001",
-  installed_app_id
-);
+const appAgentWs = await AppAgentWebsocket.connect(installed_app_id, {url: "ws://127.0.0.1:65001"});
 
 const zomeCallPayload: CallZomeRequest = {
   cell_id,
@@ -74,7 +71,7 @@ await adminWs.client.close();
 ```typescript
 import { AdminWebsocket, AppWebsocket, CellType } from "@holochain/client";
 
-const adminWs = await AdminWebsocket.connect("ws://127.0.0.1:65000");
+const adminWs = await AdminWebsocket.connect({url: "ws://127.0.0.1:65000"});
 const agent_key = await adminWs.generateAgentPubKey();
 const installed_app_id = "test-app";
 const appInfo = await adminWs.installApp({
@@ -90,7 +87,7 @@ if (!(CellType.Provisioned in appInfo.cell_info["role"][0])) {
 const { cell_id } = appInfo.cell_info["role"][0][CellType.Provisioned];
 await adminWs.authorizeSigningCredentials(cell_id);
 await adminWs.attachAppInterface({ port: 65001 });
-const appWs = await AppWebsocket.connect("ws://127.0.0.1:65001");
+const appWs = await AppWebsocket.connect({url: "ws://127.0.0.1:65001"});
 
 let signalCb;
 const signalReceived = new Promise<void>((resolve) => {

package/lib/api/admin/websocket.d.ts

@@ -1,7 +1,7 @@
 import { CapSecret, GrantedFunctions } from "../../hdk/capabilities.js";
 import type { AgentPubKey, CellId } from "../../types.js";
 import { WsClient } from "../client.js";
-import { Requester, Transformer } from "../common.js";
+import { WebsocketConnectionOptions, Requester, Transformer } from "../common.js";
 import { AddAgentInfoRequest, AddAgentInfoResponse, AdminApi, AgentInfoRequest, AgentInfoResponse, AttachAppInterfaceRequest, AttachAppInterfaceResponse, DeleteCloneCellRequest, DeleteCloneCellResponse, DisableAppRequest, DisableAppResponse, DumpFullStateRequest, DumpFullStateResponse, DumpNetworkStatsRequest, DumpNetworkStatsResponse, DumpStateRequest, DumpStateResponse, EnableAppRequest, EnableAppResponse, GenerateAgentPubKeyRequest, GenerateAgentPubKeyResponse, GetDnaDefinitionRequest, GetDnaDefinitionResponse, GrantZomeCallCapabilityRequest, GrantZomeCallCapabilityResponse, InstallAppRequest, InstallAppResponse, ListAppInterfacesRequest, ListAppInterfacesResponse, ListAppsRequest, ListAppsResponse, ListCellIdsRequest, ListCellIdsResponse, ListDnasRequest, ListDnasResponse, RegisterDnaRequest, RegisterDnaResponse, StorageInfoRequest, StorageInfoResponse, UninstallAppRequest, UninstallAppResponse, UpdateCoordinatorsRequest, UpdateCoordinatorsResponse } from "./types.js";
 /**
  * A class for interacting with a conductor's Admin API.
@@ -21,11 +21,10 @@ export declare class AdminWebsocket implements AdminApi {
     /**
      * Factory mehtod to create a new instance connected to the given URL.
      *
-     * @param url - A `ws://` URL used as the connection address.
-     * @param defaultTimeout - The default timeout for any request.
+     * @param options - {@link (WebsocketConnectionOptions:interface)}
      * @returns A promise for a new connected instance.
      */
-    static connect(url: URL, defaultTimeout?: number): Promise<AdminWebsocket>;
+    static connect(options?: WebsocketConnectionOptions): Promise<AdminWebsocket>;
     _requester<ReqI, ReqO, ResI, ResO>(tag: string, transformer?: Transformer<ReqI, ReqO, ResI, ResO>): (req: ReqI, timeout?: number | undefined) => Promise<ResO>;
     /**
      * Send a request to open the given port for {@link AppWebsocket} connections.

package/lib/api/admin/websocket.js

@@ -26,18 +26,20 @@ export class AdminWebsocket {
     /**
      * Factory mehtod to create a new instance connected to the given URL.
      *
-     * @param url - A `ws://` URL used as the connection address.
-     * @param defaultTimeout - The default timeout for any request.
+     * @param options - {@link (WebsocketConnectionOptions:interface)}
      * @returns A promise for a new connected instance.
      */
-    static async connect(url, defaultTimeout) {
+    static async connect(options = {}) {
         // Check if we are in the launcher's environment, and if so, redirect the url to connect to
         const env = getLauncherEnvironment();
         if (env?.ADMIN_INTERFACE_PORT) {
-            url = new URL(`ws://127.0.0.1:${env.ADMIN_INTERFACE_PORT}`);
+            options.url = new URL(`ws://127.0.0.1:${env.ADMIN_INTERFACE_PORT}`);
         }
-        const wsClient = await WsClient.connect(url);
-        return new AdminWebsocket(wsClient, defaultTimeout);
+        if (!options.url) {
+            throw new Error("Unable to connect to Admin Websocket: No url provided and not in a Launcher environment.");
+        }
+        const wsClient = await WsClient.connect(options.url);
+        return new AdminWebsocket(wsClient, options.defaultTimeout);
     }
     _requester(tag, transformer) {
         return requesterTransformer((req, timeout) => promiseTimeout(this.client.request(req), tag, timeout || this.defaultTimeout).then(catchError), tag, transformer);

package/lib/api/app/websocket.d.ts

@@ -2,7 +2,7 @@ import Emittery from "emittery";
 import { CapSecret } from "../../hdk/capabilities.js";
 import { InstalledAppId } from "../../types.js";
 import { WsClient } from "../client.js";
-import { Requester, Transformer } from "../common.js";
+import { WebsocketConnectionOptions, Requester, Transformer } from "../common.js";
 import { Nonce256Bit } from "../zome-call-signing.js";
 import { AppApi, AppInfoRequest, AppInfoResponse, CallZomeRequest, CallZomeResponse, CreateCloneCellRequest, CreateCloneCellResponse, DisableCloneCellRequest, DisableCloneCellResponse, EnableCloneCellRequest, EnableCloneCellResponse, NetworkInfoRequest, NetworkInfoResponse } from "./types.js";
 /**
@@ -19,11 +19,10 @@ export declare class AppWebsocket extends Emittery implements AppApi {
     /**
      * Instance factory for creating AppWebsockets.
      *
-     * @param url - The `ws://` URL of the App API to connect to.
-     * @param defaultTimeout - Timeout to default to for all operations.
+     * @param options - {@link (WebsocketConnectionOptions:interface)}
      * @returns A new instance of an AppWebsocket.
      */
-    static connect(url: URL, defaultTimeout?: number): Promise<AppWebsocket>;
+    static connect(options?: WebsocketConnectionOptions): Promise<AppWebsocket>;
     _requester<ReqI, ReqO, ResI, ResO>(tag: string, transformer?: Transformer<ReqI, ReqO, ResI, ResO>): (req: ReqI, timeout?: number | undefined) => Promise<ResO>;
     /**
      * Request the app's info, including all cell infos.

package/lib/api/app/websocket.js

@@ -36,18 +36,20 @@ export class AppWebsocket extends Emittery {
     /**
      * Instance factory for creating AppWebsockets.
      *
-     * @param url - The `ws://` URL of the App API to connect to.
-     * @param defaultTimeout - Timeout to default to for all operations.
+     * @param options - {@link (WebsocketConnectionOptions:interface)}
      * @returns A new instance of an AppWebsocket.
      */
-    static async connect(url, defaultTimeout) {
+    static async connect(options = {}) {
         // Check if we are in the launcher's environment, and if so, redirect the url to connect to
         const env = getLauncherEnvironment();
         if (env?.APP_INTERFACE_PORT) {
-            url = new URL(`ws://127.0.0.1:${env.APP_INTERFACE_PORT}`);
+            options.url = new URL(`ws://127.0.0.1:${env.APP_INTERFACE_PORT}`);
         }
-        const wsClient = await WsClient.connect(url);
-        const appWebsocket = new AppWebsocket(wsClient, defaultTimeout, env?.INSTALLED_APP_ID);
+        if (!options.url) {
+            throw new Error("Unable to connect to App Websocket: No url provided and not in a Launcher environment.");
+        }
+        const wsClient = await WsClient.connect(options.url);
+        const appWebsocket = new AppWebsocket(wsClient, options.defaultTimeout, env?.INSTALLED_APP_ID);
         wsClient.on("signal", (signal) => appWebsocket.emit("signal", signal));
         return appWebsocket;
     }

package/lib/api/app-agent/websocket.d.ts

@@ -3,6 +3,7 @@ import { AgentPubKey, CellId, InstalledAppId, RoleName } from "../../types.js";
 import { AppInfo } from "../admin/types.js";
 import { AppSignalCb, CallZomeResponse, CreateCloneCellResponse, DisableCloneCellResponse, EnableCloneCellResponse, NetworkInfoResponse } from "../app/types.js";
 import { AppWebsocket } from "../app/websocket.js";
+import { WebsocketConnectionOptions } from "../common.js";
 import { AppAgentCallZomeRequest, AppAgentClient, AppAgentEvents, AppAgentNetworkInfoRequest, AppCreateCloneCellRequest, AppDisableCloneCellRequest, AppEnableCloneCellRequest } from "./types.js";
 /**
  * A class to establish a websocket connection to an App interface, for a
@@ -26,12 +27,11 @@ export declare class AppAgentWebsocket implements AppAgentClient {
     /**
      * Instance factory for creating AppAgentWebsockets.
      *
-     * @param url - The `ws://` URL of the App API to connect to.
      * @param installed_app_id - ID of the App to link to.
-     * @param defaultTimeout - Timeout to default to for all operations.
+     * @param options - {@link (WebsocketConnectionOptions:interface)}
      * @returns A new instance of an AppAgentWebsocket.
      */
-    static connect(url: URL, installed_app_id: InstalledAppId, defaultTimeout?: number): Promise<AppAgentWebsocket>;
+    static connect(installed_app_id: InstalledAppId, options?: WebsocketConnectionOptions): Promise<AppAgentWebsocket>;
     /**
      * Get a cell id by its role name or clone id.
      *

package/lib/api/app-agent/websocket.js

@@ -3,7 +3,7 @@ import { omit } from "lodash-es";
 import { getLauncherEnvironment } from "../../environments/launcher.js";
 import { CellType } from "../admin/types.js";
 import { AppWebsocket } from "../app/websocket.js";
-import { getBaseRoleNameFromCloneId, isCloneId } from "../common.js";
+import { getBaseRoleNameFromCloneId, isCloneId, } from "../common.js";
 /**
  * A class to establish a websocket connection to an App interface, for a
  * specific agent and app.
@@ -52,13 +52,12 @@ export class AppAgentWebsocket {
     /**
      * Instance factory for creating AppAgentWebsockets.
      *
-     * @param url - The `ws://` URL of the App API to connect to.
      * @param installed_app_id - ID of the App to link to.
-     * @param defaultTimeout - Timeout to default to for all operations.
+     * @param options - {@link (WebsocketConnectionOptions:interface)}
      * @returns A new instance of an AppAgentWebsocket.
      */
-    static async connect(url, installed_app_id, defaultTimeout) {
-        const appWebsocket = await AppWebsocket.connect(url, defaultTimeout);
+    static async connect(installed_app_id, options = {}) {
+        const appWebsocket = await AppWebsocket.connect(options);
         const appInfo = await appWebsocket.appInfo({
             installed_app_id: installed_app_id,
         });

package/lib/api/client.d.ts

@@ -14,7 +14,7 @@ export declare class WsClient extends Emittery {
     url: URL | undefined;
     private pendingRequests;
     private index;
-    constructor(socket: IsoWebSocket, url: URL);
+    constructor(socket: IsoWebSocket, url?: URL);
     private setupSocket;
     /**
      * Instance factory for creating WsClients.

package/lib/api/common.d.ts

@@ -78,3 +78,18 @@ export declare class CloneId {
     toString(): string;
     getBaseRoleName(): string;
 }
+/**
+ * Options for a Websocket connection.
+ *
+ * @public
+ */
+export interface WebsocketConnectionOptions {
+    /**
+     * The `ws://` URL of the Websocket server to connect to. Not required when connecting to App API from a Launcher or Kangaroo environment.
+     */
+    url?: URL;
+    /**
+     * Timeout to default to for all operations.
+     */
+    defaultTimeout?: number;
+}

package/lib/api/index.d.ts

@@ -3,5 +3,5 @@ export * from "./admin/index.js";
 export * from "./app-agent/index.js";
 export * from "./app/index.js";
 export { IsoWebSocket, WsClient } from "./client.js";
-export { CloneId, HolochainError, Requester, Transformer, getBaseRoleNameFromCloneId, isCloneId, } from "./common.js";
+export { CloneId, HolochainError, Requester, Transformer, WebsocketConnectionOptions, getBaseRoleNameFromCloneId, isCloneId, } from "./common.js";
 export * from "./zome-call-signing.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holochain/client",
-  "version": "0.17.0-dev.5",
+  "version": "0.17.0-dev.6",
   "description": "A JavaScript client for the Holochain Conductor API",
   "author": "Holochain Foundation <info@holochain.org> (http://holochain.org)",
   "license": "CAL-1.0",