@holochain/client 0.11.13 → 0.11.14

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

@@ -2,6 +2,12 @@ import Emittery, { UnsubscribeFunction } from "emittery";
 import { AgentPubKey, CellId, InstalledAppId, RoleName } from "../../types.js";
 import { AppInfo, AppSignalCb, AppWebsocket, CallZomeResponse, CreateCloneCellResponse, DisableCloneCellResponse, EnableCloneCellResponse } from "../index.js";
 import { AppAgentCallZomeRequest, AppAgentClient, AppAgentEvents, AppCreateCloneCellRequest, AppDisableCloneCellRequest, AppEnableCloneCellRequest } from "./types.js";
+/**
+ * A class to establish a websocket connection to an App interface, for a
+ * specific agent and app.
+ *
+ * @public
+ */
 export declare class AppAgentWebsocket implements AppAgentClient {
     myPubKey: AgentPubKey;
     readonly appWebsocket: AppWebsocket;
@@ -9,13 +15,64 @@ export declare class AppAgentWebsocket implements AppAgentClient {
     cachedAppInfo?: AppInfo;
     readonly emitter: Emittery<AppAgentEvents>;
     private constructor();
+    /**
+     * Request the app's info, including all cell infos.
+     *
+     * @returns The app's {@link AppInfo}.
+     */
     appInfo(): Promise<AppInfo>;
+    /**
+     * 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.
+     * @returns A new instance of an AppAgentWebsocket.
+     */
     static connect(url: string, installed_app_id: InstalledAppId, defaultTimeout?: number): Promise<AppAgentWebsocket>;
+    /**
+     * Get a cell id by its role name or clone id.
+     *
+     * @param roleName - The role name or clone id of the cell.
+     * @param appInfo - The app info containing all cell infos.
+     * @returns The cell id or throws an error if not found.
+     */
     getCellIdFromRoleName(roleName: RoleName, appInfo: AppInfo): CellId;
+    /**
+     * Call a zome.
+     *
+     * @param request - The zome call arguments.
+     * @param timeout - A timeout to override the default.
+     * @returns The zome call's response.
+     */
     callZome(request: AppAgentCallZomeRequest, timeout?: number): Promise<CallZomeResponse>;
+    /**
+     * Clone an existing provisioned cell.
+     *
+     * @param args - Specify the cell to clone.
+     * @returns The created clone cell.
+     */
     createCloneCell(args: AppCreateCloneCellRequest): Promise<CreateCloneCellResponse>;
+    /**
+     * Enable a disabled clone cell.
+     *
+     * @param args - Specify the clone cell to enable.
+     * @returns The enabled clone cell.
+     */
     enableCloneCell(args: AppEnableCloneCellRequest): Promise<EnableCloneCellResponse>;
+    /**
+     * Disable an enabled clone cell.
+     *
+     * @param args - Specify the clone cell to disable.
+     */
     disableCloneCell(args: AppDisableCloneCellRequest): Promise<DisableCloneCellResponse>;
+    /**
+     * Register an event listener for signals.
+     *
+     * @param eventName - Event name to listen to (currently only "signal").
+     * @param listener - The function to call when event is triggered.
+     * @returns A function to unsubscribe the event listener.
+     */
     on<Name extends keyof AppAgentEvents>(eventName: Name | readonly Name[], listener: AppSignalCb): UnsubscribeFunction;
     private containsCell;
 }

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

@@ -18,6 +18,12 @@ function getPubKey(appInfo) {
     }
     throw new Error(`This app doesn't have any cells, so we can't return the agent public key for it. This is a known issue, and is going to be fixed in the near future.`);
 }
+/**
+ * A class to establish a websocket connection to an App interface, for a
+ * specific agent and app.
+ *
+ * @public
+ */
 export class AppAgentWebsocket {
     myPubKey;
     appWebsocket;
@@ -36,6 +42,11 @@ export class AppAgentWebsocket {
             }
         });
     }
+    /**
+     * Request the app's info, including all cell infos.
+     *
+     * @returns The app's {@link AppInfo}.
+     */
     async appInfo() {
         const appInfo = await this.appWebsocket.appInfo({
             installed_app_id: this.installedAppId,
@@ -43,6 +54,14 @@ export class AppAgentWebsocket {
         this.cachedAppInfo = appInfo;
         return appInfo;
     }
+    /**
+     * 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.
+     * @returns A new instance of an AppAgentWebsocket.
+     */
     static async connect(url, installed_app_id, defaultTimeout) {
         const appWebsocket = await AppWebsocket.connect(url, defaultTimeout);
         const appInfo = await appWebsocket.appInfo({
@@ -53,6 +72,13 @@ export class AppAgentWebsocket {
         appAgentWs.cachedAppInfo = appInfo;
         return appAgentWs;
     }
+    /**
+     * Get a cell id by its role name or clone id.
+     *
+     * @param roleName - The role name or clone id of the cell.
+     * @param appInfo - The app info containing all cell infos.
+     * @returns The cell id or throws an error if not found.
+     */
     getCellIdFromRoleName(roleName, appInfo) {
         if (isCloneId(roleName)) {
             const baseRoleName = getBaseRoleNameFromCloneId(roleName);
@@ -74,6 +100,13 @@ export class AppAgentWebsocket {
         }
         return cell[CellType.Provisioned].cell_id;
     }
+    /**
+     * Call a zome.
+     *
+     * @param request - The zome call arguments.
+     * @param timeout - A timeout to override the default.
+     * @returns The zome call's response.
+     */
     async callZome(request, timeout) {
         if (!("provenance" in request)) {
             request = {
@@ -98,6 +131,12 @@ export class AppAgentWebsocket {
             throw new Error("callZome requires a role_name or cell_id arg");
         }
     }
+    /**
+     * Clone an existing provisioned cell.
+     *
+     * @param args - Specify the cell to clone.
+     * @returns The created clone cell.
+     */
     async createCloneCell(args) {
         const clonedCell = this.appWebsocket.createCloneCell({
             app_id: this.installedAppId,
@@ -106,18 +145,36 @@ export class AppAgentWebsocket {
         this.cachedAppInfo = undefined;
         return clonedCell;
     }
+    /**
+     * Enable a disabled clone cell.
+     *
+     * @param args - Specify the clone cell to enable.
+     * @returns The enabled clone cell.
+     */
     async enableCloneCell(args) {
         return this.appWebsocket.enableCloneCell({
             app_id: this.installedAppId,
             ...args,
         });
     }
+    /**
+     * Disable an enabled clone cell.
+     *
+     * @param args - Specify the clone cell to disable.
+     */
     async disableCloneCell(args) {
         return this.appWebsocket.disableCloneCell({
             app_id: this.installedAppId,
             ...args,
         });
     }
+    /**
+     * Register an event listener for signals.
+     *
+     * @param eventName - Event name to listen to (currently only "signal").
+     * @param listener - The function to call when event is triggered.
+     * @returns A function to unsubscribe the event listener.
+     */
     on(eventName, listener) {
         return this.emitter.on(eventName, listener);
     }
@@ -143,4 +200,3 @@ export class AppAgentWebsocket {
 }
 const isSameCell = (cellId1, cellId2) => cellId1[0].every((byte, index) => byte === cellId2[0][index]) &&
     cellId1[1].every((byte, index) => byte === cellId2[1][index]);
-//# sourceMappingURL=websocket.js.map

package/lib/api/client.d.ts

@@ -2,16 +2,13 @@
 import { decode } from "@msgpack/msgpack";
 import Emittery from "emittery";
 import Websocket from "isomorphic-ws";
-interface HolochainMessage {
-    id: number;
-    type: "response" | "signal";
-    data: ArrayLike<number> | null;
-}
 /**
  * A Websocket client which can make requests and receive responses,
- * as well as send and receive signals
+ * as well as send and receive signals.
  *
  * Uses Holochain's websocket WireMessage for communication.
+ *
+ * @public
  */
 export declare class WsClient extends Emittery {
     socket: Websocket;
@@ -21,10 +18,29 @@ export declare class WsClient extends Emittery {
     }>;
     index: number;
     constructor(socket: Websocket);
+    /**
+     * Instance factory for creating WsClients.
+     *
+     * @param url - The `ws://` URL to connect to.
+     * @returns An new instance of the WsClient.
+     */
     static connect(url: string): Promise<WsClient>;
+    /**
+     * Sends data as a signal.
+     *
+     * @param data - Data to send.
+     */
     emitSignal(data: unknown): void;
-    request<Req, Res>(data: Req): Promise<Res>;
-    handleResponse(msg: HolochainMessage): void;
+    /**
+     * Send requests to the connected websocket.
+     *
+     * @param request - The request to send over the websocket.
+     * @returns
+     */
+    request<Req, Res>(request: Req): Promise<Res>;
+    private handleResponse;
+    /**
+     * Close the websocket connection.
+     */
     close(): Promise<void>;
 }
-export {};

package/lib/api/client.js

@@ -4,9 +4,11 @@ import Websocket from "isomorphic-ws";
 import { SignalType } from "./app/types.js";
 /**
  * A Websocket client which can make requests and receive responses,
- * as well as send and receive signals
+ * as well as send and receive signals.
  *
  * Uses Holochain's websocket WireMessage for communication.
+ *
+ * @public
  */
 export class WsClient extends Emittery {
     socket;
@@ -39,19 +41,20 @@ export class WsClient extends Emittery {
                 if (message.data === null) {
                     throw new Error("received a signal without data");
                 }
-                const derializedSignal = decode(message.data);
-                assertHolochainSignal(derializedSignal);
-                if (!(SignalType.App in derializedSignal)) {
+                const deserializedSignal = decode(message.data);
+                assertHolochainSignal(deserializedSignal);
+                if (SignalType.System in deserializedSignal) {
                     // We have received a system signal, do nothing
                     return;
                 }
-                // Holochain currently returns signals as an array of two values: cellId and the serialized signal payload
-                // and this array is nested within the App key within the returned message.
-                const cell_id = derializedSignal.App[0];
+                const encodedAppSignal = deserializedSignal[SignalType.App];
                 // In order to return readible content to the UI, the signal payload must also be deserialized.
-                const payload = decode(derializedSignal.App[1]);
-                // Return a uniform format to UI (ie: { type, data } - the same format as with callZome and appInfo...)
-                const signal = { cell_id, payload };
+                const payload = decode(encodedAppSignal.signal);
+                const signal = {
+                    cell_id: encodedAppSignal.cell_id,
+                    zome_name: encodedAppSignal.zome_name,
+                    payload,
+                };
                 this.emit("signal", signal);
             }
             else if (message.type === "response") {
@@ -62,6 +65,12 @@ export class WsClient extends Emittery {
             }
         };
     }
+    /**
+     * Instance factory for creating WsClients.
+     *
+     * @param url - The `ws://` URL to connect to.
+     * @returns An new instance of the WsClient.
+     */
     static connect(url) {
         return new Promise((resolve, reject) => {
             const socket = new Websocket(url);
@@ -77,6 +86,11 @@ export class WsClient extends Emittery {
             };
         });
     }
+    /**
+     * Sends data as a signal.
+     *
+     * @param data - Data to send.
+     */
     emitSignal(data) {
         const encodedMsg = encode({
             type: "signal",
@@ -84,13 +98,19 @@ export class WsClient extends Emittery {
         });
         this.socket.send(encodedMsg);
     }
-    request(data) {
+    /**
+     * Send requests to the connected websocket.
+     *
+     * @param request - The request to send over the websocket.
+     * @returns
+     */
+    request(request) {
         const id = this.index;
         this.index += 1;
         const encodedMsg = encode({
             id,
             type: "request",
-            data: encode(data),
+            data: encode(request),
         });
         const promise = new Promise((resolve, reject) => {
             this.pendingRequests[id] = { resolve, reject };
@@ -118,6 +138,9 @@ export class WsClient extends Emittery {
             console.error(`Got response with no matching request. id=${id}`);
         }
     }
+    /**
+     * Close the websocket connection.
+     */
     close() {
         const closedPromise = new Promise((resolve) => this.socket.on("close", resolve));
         this.socket.close();
@@ -141,4 +164,3 @@ function assertHolochainSignal(signal) {
     }
     throw new Error(`unknown signal format ${JSON.stringify(signal, null, 4)}`);
 }
-//# sourceMappingURL=client.js.map

package/lib/api/common.d.ts

@@ -1,11 +1,23 @@
 import { RoleName } from "../types.js";
 export declare const DEFAULT_TIMEOUT = 15000;
+/**
+ * @public
+ */
 export declare type Transformer<ReqI, ReqO, ResI, ResO> = {
     input: (req: ReqI) => ReqO;
     output: (res: ResI) => ResO;
 };
+/**
+ * @public
+ */
 export declare type Requester<Req, Res> = (req: Req, timeout?: number) => Promise<Res>;
+/**
+ * @public
+ */
 export declare type RequesterUnit<Res> = () => Promise<Res>;
+/**
+ * @public
+ */
 export declare type Tagged<T> = {
     type: string;
     data: T;
@@ -14,17 +26,34 @@ export declare type Tagged<T> = {
  * Take a Requester function which deals with tagged requests and responses,
  * and return a Requester which deals only with the inner data types, also
  * with the optional Transformer applied to further modify the input and output.
+ *
+ * @public
  */
 export declare const requesterTransformer: <ReqI, ReqO, ResI, ResO>(requester: Requester<Tagged<ReqO>, Tagged<ResI>>, tag: string, transform?: Transformer<ReqI, ReqO, ResI, ResO>) => (req: ReqI, timeout?: number) => Promise<ResO>;
 export declare const catchError: (res: any) => Promise<any>;
 export declare const promiseTimeout: (promise: Promise<unknown>, tag: string, ms: number) => Promise<unknown>;
+/**
+ * Check if a cell's role name is a valid clone id.
+ *
+ * @param roleName - The role name to check.
+ *
+ * @public
+ */
 export declare const isCloneId: (roleName: RoleName) => boolean;
+/**
+ * Parse a clone id and get the role name part of it.
+ *
+ * @param roleName - The role name to parse.
+ * @public
+ */
 export declare const getBaseRoleNameFromCloneId: (roleName: RoleName) => string;
 /**
  * Identifier of a clone cell, composed of the DNA's role id and the index
  * of the clone, starting at 0.
  *
  * Example: `profiles.0`
+ *
+ * @public
  */
 export declare class CloneId {
     private readonly roleName;
@@ -32,7 +61,7 @@ export declare class CloneId {
     constructor(roleName: RoleName, index: number);
     /**
      * Parse a role id of a clone cell to obtain a clone id instance.
-     * @param roleName Role id to parse.
+     * @param roleName - Role id to parse.
      * @returns A clone id instance.
      */
     static fromRoleName(roleName: RoleName): CloneId;

package/lib/api/common.js

@@ -4,6 +4,8 @@ export const DEFAULT_TIMEOUT = 15000;
  * Take a Requester function which deals with tagged requests and responses,
  * and return a Requester which deals only with the inner data types, also
  * with the optional Transformer applied to further modify the input and output.
+ *
+ * @public
  */
 export const requesterTransformer = (requester, tag, transform = identityTransformer) => async (req, timeout) => {
     const transformedInput = await transform.input(req);
@@ -40,7 +42,20 @@ export const promiseTimeout = (promise, tag, ms) => {
     });
 };
 const CLONE_ID_DELIMITER = ".";
+/**
+ * Check if a cell's role name is a valid clone id.
+ *
+ * @param roleName - The role name to check.
+ *
+ * @public
+ */
 export const isCloneId = (roleName) => roleName.includes(CLONE_ID_DELIMITER);
+/**
+ * Parse a clone id and get the role name part of it.
+ *
+ * @param roleName - The role name to parse.
+ * @public
+ */
 export const getBaseRoleNameFromCloneId = (roleName) => {
     if (!isCloneId(roleName)) {
         throw new Error("invalid clone id: no clone id delimiter found in role name");
@@ -52,6 +67,8 @@ export const getBaseRoleNameFromCloneId = (roleName) => {
  * of the clone, starting at 0.
  *
  * Example: `profiles.0`
+ *
+ * @public
  */
 export class CloneId {
     roleName;
@@ -62,7 +79,7 @@ export class CloneId {
     }
     /**
      * Parse a role id of a clone cell to obtain a clone id instance.
-     * @param roleName Role id to parse.
+     * @param roleName - Role id to parse.
      * @returns A clone id instance.
      */
     static fromRoleName(roleName) {
@@ -79,4 +96,3 @@ export class CloneId {
         return this.roleName;
     }
 }
-//# sourceMappingURL=common.js.map

package/lib/api/index.d.ts

@@ -2,5 +2,6 @@ export { hashZomeCall } from "@holochain/serialization";
 export * from "./admin/index.js";
 export * from "./app-agent/index.js";
 export * from "./app/index.js";
-export { CloneId } from "./common.js";
+export { CloneId, Requester, Transformer } from "./common.js";
+export { WsClient } from "./client.js";
 export * from "./zome-call-signing.js";

package/lib/api/index.js

@@ -3,5 +3,5 @@ export * from "./admin/index.js";
 export * from "./app-agent/index.js";
 export * from "./app/index.js";
 export { CloneId } from "./common.js";
+export { WsClient } from "./client.js";
 export * from "./zome-call-signing.js";
-//# sourceMappingURL=index.js.map

package/lib/api/zome-call-signing.d.ts

@@ -1,7 +1,13 @@
 import nacl from "tweetnacl";
 import { CapSecret } from "../hdk/capabilities.js";
 import { AgentPubKey, CellId } from "../types.js";
+/**
+ * @public
+ */
 export declare type Nonce256Bit = Uint8Array;
+/**
+ * @public
+ */
 export interface SigningCredentials {
     capSecret: CapSecret;
     keyPair: nacl.SignKeyPair;
@@ -12,25 +18,42 @@ export interface SigningCredentials {
  *
  * @param cellId - Cell id to get credentials of.
  * @returns The keys and cap secret required for signing a zome call.
+ *
+ * @public
  */
 export declare const getSigningCredentials: (cellId: CellId) => SigningCredentials | undefined;
 /**
  * Set credentials for signing zome calls.
  *
  * @param cellId - Cell id to set credentials for.
- * @param cellId - Cell id to set credentials for.
+ *
+ * @public
  */
 export declare const setSigningCredentials: (cellId: CellId, credentials: SigningCredentials) => void;
 /**
  * Generates a key pair for signing zome calls.
  *
  * @returns The signing key pair and an agent pub key based on the public key.
+ *
+ * @public
  */
 export declare const generateSigningKeyPair: () => [
     nacl.SignKeyPair,
     AgentPubKey
 ];
+/**
+ * @public
+ */
 export declare const randomCapSecret: () => Promise<CapSecret>;
+/**
+ * @public
+ */
 export declare const randomNonce: () => Promise<Nonce256Bit>;
+/**
+ * @public
+ */
 export declare const randomByteArray: (length: number) => Promise<Uint8Array>;
+/**
+ * @public
+ */
 export declare const getNonceExpiration: () => number;

package/lib/api/zome-call-signing.js

@@ -6,6 +6,8 @@ const signingCredentials = new Map();
  *
  * @param cellId - Cell id to get credentials of.
  * @returns The keys and cap secret required for signing a zome call.
+ *
+ * @public
  */
 export const getSigningCredentials = (cellId) => {
     const cellIdB64 = encodeHashToBase64(cellId[0]).concat(encodeHashToBase64(cellId[1]));
@@ -15,7 +17,8 @@ export const getSigningCredentials = (cellId) => {
  * Set credentials for signing zome calls.
  *
  * @param cellId - Cell id to set credentials for.
- * @param cellId - Cell id to set credentials for.
+ *
+ * @public
  */
 export const setSigningCredentials = (cellId, credentials) => {
     const cellIdB64 = encodeHashToBase64(cellId[0]).concat(encodeHashToBase64(cellId[1]));
@@ -25,14 +28,25 @@ export const setSigningCredentials = (cellId, credentials) => {
  * Generates a key pair for signing zome calls.
  *
  * @returns The signing key pair and an agent pub key based on the public key.
+ *
+ * @public
  */
 export const generateSigningKeyPair = () => {
     const keyPair = nacl.sign.keyPair();
     const signingKey = new Uint8Array([132, 32, 36].concat(...keyPair.publicKey).concat(...[0, 0, 0, 0]));
     return [keyPair, signingKey];
 };
+/**
+ * @public
+ */
 export const randomCapSecret = () => randomByteArray(64);
+/**
+ * @public
+ */
 export const randomNonce = async () => randomByteArray(32);
+/**
+ * @public
+ */
 export const randomByteArray = async (length) => {
     if (typeof window !== "undefined" &&
         "crypto" in window &&
@@ -44,5 +58,7 @@ export const randomByteArray = async (length) => {
         return new Uint8Array(crypto.randomBytes(length));
     }
 };
+/**
+ * @public
+ */
 export const getNonceExpiration = () => (Date.now() + 5 * 60 * 1000) * 1000; // 5 mins from now in microseconds
-//# sourceMappingURL=zome-call-signing.js.map

package/lib/environments/launcher.js

@@ -31,4 +31,3 @@ export const signZomeCallTauri = async (request) => {
     };
     return signedZomeCall;
 };
-//# sourceMappingURL=launcher.js.map