@holochain/client 0.11.12 → 0.11.14

package/lib/api/admin/types.js

@@ -1,9 +1,49 @@
+/**
+ * @public
+ */
 export var CellType;
 (function (CellType) {
     CellType["Provisioned"] = "Provisioned";
     CellType["Cloned"] = "Cloned";
     CellType["Stem"] = "Stem";
 })(CellType || (CellType = {}));
+/**
+ * @public
+ */
+export var CellProvisioningStrategy;
+(function (CellProvisioningStrategy) {
+    /**
+     * Always create a new Cell when installing this App
+     */
+    CellProvisioningStrategy["Create"] = "create";
+    /**
+     * Always create a new Cell when installing the App,
+     * and use a unique network seed to ensure a distinct DHT network.
+     *
+     * Not implemented
+     */
+    // CreateClone = "create_clone",
+    /**
+     * Require that a Cell is already installed which matches the DNA version
+     * spec, and which has an Agent that's associated with this App's agent
+     * via DPKI. If no such Cell exists, *app installation fails*.
+     */
+    CellProvisioningStrategy["UseExisting"] = "use_existing";
+    /**
+     * Try `UseExisting`, and if that fails, fallback to `Create`
+     */
+    CellProvisioningStrategy["CreateIfNoExists"] = "create_if_no_exists";
+    /**
+     * Disallow provisioning altogether. In this case, we expect
+     * `clone_limit > 0`: otherwise, no Cells will ever be created.
+     *
+     * Not implemented
+     */
+    // Disabled = "disabled",
+})(CellProvisioningStrategy || (CellProvisioningStrategy = {}));
+/**
+ * @public
+ */
 export var AppStatusFilter;
 (function (AppStatusFilter) {
     AppStatusFilter["Enabled"] = "enabled";
@@ -12,4 +52,3 @@ export var AppStatusFilter;
     AppStatusFilter["Stopped"] = "stopped";
     AppStatusFilter["Paused"] = "paused";
 })(AppStatusFilter || (AppStatusFilter = {}));
-//# sourceMappingURL=types.js.map

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

@@ -3,30 +3,109 @@ import type { AgentPubKey, CellId } from "../../types.js";
 import { WsClient } from "../client.js";
 import { Requester, Transformer } from "../common.js";
 import { AddAgentInfoRequest, AddAgentInfoResponse, AdminApi, AgentInfoRequest, AgentInfoResponse, AttachAppInterfaceRequest, AttachAppInterfaceResponse, DeleteCloneCellRequest, DeleteCloneCellResponse, DisableAppRequest, DisableAppResponse, DumpFullStateRequest, DumpFullStateResponse, DumpStateRequest, DumpStateResponse, EnableAppRequest, EnableAppResponse, GenerateAgentPubKeyRequest, GenerateAgentPubKeyResponse, GetDnaDefinitionRequest, GetDnaDefinitionResponse, GrantZomeCallCapabilityRequest, GrantZomeCallCapabilityResponse, InstallAppRequest, InstallAppResponse, ListAppInterfacesRequest, ListAppInterfacesResponse, ListAppsRequest, ListAppsResponse, ListCellIdsRequest, ListCellIdsResponse, ListDnasRequest, ListDnasResponse, RegisterDnaRequest, RegisterDnaResponse, StartAppRequest, StartAppResponse, UninstallAppRequest, UninstallAppResponse } from "./types.js";
+/**
+ * A class for interacting with a conductor's Admin API.
+ *
+ * @public
+ */
 export declare class AdminWebsocket implements AdminApi {
+    /**
+     * The websocket client used for transporting requests and responses.
+     */
     readonly client: WsClient;
+    /**
+     * Default timeout for any request made over the websocket.
+     */
     defaultTimeout: number;
     private constructor();
+    /**
+     * 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.
+     * @returns A promise for a new connected instance.
+     */
     static connect(url: string, defaultTimeout?: number): Promise<AdminWebsocket>;
-    _requester: <ReqO, ReqI, ResI, ResO>(tag: string, transformer?: Transformer<ReqO, ReqI, ResI, ResO> | undefined) => (req: ReqO, timeout?: number | undefined) => Promise<ResO>;
+    _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.
+     */
     attachAppInterface: Requester<AttachAppInterfaceRequest, AttachAppInterfaceResponse>;
+    /**
+     * Enable a stopped app.
+     */
     enableApp: Requester<EnableAppRequest, EnableAppResponse>;
+    /**
+     * Disable a running app.
+     */
     disableApp: Requester<DisableAppRequest, DisableAppResponse>;
+    /**
+     * Start an app.
+     */
     startApp: Requester<StartAppRequest, StartAppResponse>;
+    /**
+     * Dump the state of the specified cell, including its source chain, as JSON.
+     */
     dumpState: Requester<DumpStateRequest, DumpStateResponse>;
+    /**
+     * Dump the full state of the specified cell, including its chain and DHT
+     * shard, as JSON.
+     */
     dumpFullState: Requester<DumpFullStateRequest, DumpFullStateResponse>;
+    /**
+     * Generate a new agent pub key.
+     */
     generateAgentPubKey: Requester<GenerateAgentPubKeyRequest, GenerateAgentPubKeyResponse>;
+    /**
+     * Register a DNA for later app installation.
+     *
+     * Stores the given DNA into the Holochain DNA database and returns the hash of it.
+     */
     registerDna: Requester<RegisterDnaRequest, RegisterDnaResponse>;
+    /**
+     * Get the DNA definition for the specified DNA hash.
+     */
     getDnaDefinition: Requester<GetDnaDefinitionRequest, GetDnaDefinitionResponse>;
+    /**
+     * Uninstall the specified app from Holochain.
+     */
     uninstallApp: Requester<UninstallAppRequest, UninstallAppResponse>;
+    /**
+     * Install the specified app into Holochain.
+     */
     installApp: Requester<InstallAppRequest, InstallAppResponse>;
+    /**
+     * List all registered DNAs.
+     */
     listDnas: Requester<ListDnasRequest, ListDnasResponse>;
+    /**
+     * List all installed cell ids.
+     */
     listCellIds: Requester<ListCellIdsRequest, ListCellIdsResponse>;
+    /**
+     * List all installed apps.
+     */
     listApps: Requester<ListAppsRequest, ListAppsResponse>;
+    /**
+     * List all attached app interfaces.
+     */
     listAppInterfaces: Requester<ListAppInterfacesRequest, ListAppInterfacesResponse>;
+    /**
+     * Request all available info about an agent.
+     */
     agentInfo: Requester<AgentInfoRequest, AgentInfoResponse>;
+    /**
+     * Add an existing agent to Holochain.
+     */
     addAgentInfo: Requester<AddAgentInfoRequest, AddAgentInfoResponse>;
+    /**
+     * Delete a disabled clone cell.
+     */
     deleteCloneCell: Requester<DeleteCloneCellRequest, DeleteCloneCellResponse>;
+    /**
+     * Grant a zome call capability for an agent, to be used for signing zome
+     * calls.
+     */
     grantZomeCallCapability: Requester<GrantZomeCallCapabilityRequest, GrantZomeCallCapabilityResponse>;
     /**
      * Grant a capability for signing zome calls.

package/lib/api/admin/websocket.js

@@ -4,14 +4,32 @@ import { WsClient } from "../client.js";
 import { catchError, DEFAULT_TIMEOUT, promiseTimeout, requesterTransformer, } from "../common.js";
 import { generateSigningKeyPair, randomCapSecret, setSigningCredentials, } from "../zome-call-signing.js";
 import { AppStatusFilter, } from "./types.js";
+/**
+ * A class for interacting with a conductor's Admin API.
+ *
+ * @public
+ */
 export class AdminWebsocket {
+    /**
+     * The websocket client used for transporting requests and responses.
+     */
     client;
+    /**
+     * Default timeout for any request made over the websocket.
+     */
     defaultTimeout;
     constructor(client, defaultTimeout) {
         this.client = client;
         this.defaultTimeout =
             defaultTimeout === undefined ? DEFAULT_TIMEOUT : defaultTimeout;
     }
+    /**
+     * 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.
+     * @returns A promise for a new connected instance.
+     */
     static async connect(url, defaultTimeout) {
         // Check if we are in the launcher's environment, and if so, redirect the url to connect to
         const env = getLauncherEnvironment();
@@ -21,27 +39,88 @@ export class AdminWebsocket {
         const wsClient = await WsClient.connect(url);
         return new AdminWebsocket(wsClient, defaultTimeout);
     }
-    _requester = (tag, transformer) => requesterTransformer((req, timeout) => promiseTimeout(this.client.request(req), tag, timeout || this.defaultTimeout).then(catchError), tag, transformer);
-    // the specific request/response types come from the Interface
-    // which this class implements
+    _requester(tag, transformer) {
+        return requesterTransformer((req, timeout) => promiseTimeout(this.client.request(req), tag, timeout || this.defaultTimeout).then(catchError), tag, transformer);
+    }
+    /**
+     * Send a request to open the given port for {@link AppWebsocket} connections.
+     */
     attachAppInterface = this._requester("attach_app_interface");
+    /**
+     * Enable a stopped app.
+     */
     enableApp = this._requester("enable_app");
+    /**
+     * Disable a running app.
+     */
     disableApp = this._requester("disable_app");
+    /**
+     * Start an app.
+     */
     startApp = this._requester("start_app");
+    /**
+     * Dump the state of the specified cell, including its source chain, as JSON.
+     */
     dumpState = this._requester("dump_state", dumpStateTransform);
+    /**
+     * Dump the full state of the specified cell, including its chain and DHT
+     * shard, as JSON.
+     */
     dumpFullState = this._requester("dump_full_state");
+    /**
+     * Generate a new agent pub key.
+     */
     generateAgentPubKey = this._requester("generate_agent_pub_key");
+    /**
+     * Register a DNA for later app installation.
+     *
+     * Stores the given DNA into the Holochain DNA database and returns the hash of it.
+     */
     registerDna = this._requester("register_dna");
+    /**
+     * Get the DNA definition for the specified DNA hash.
+     */
     getDnaDefinition = this._requester("get_dna_definition");
+    /**
+     * Uninstall the specified app from Holochain.
+     */
     uninstallApp = this._requester("uninstall_app");
+    /**
+     * Install the specified app into Holochain.
+     */
     installApp = this._requester("install_app");
+    /**
+     * List all registered DNAs.
+     */
     listDnas = this._requester("list_dnas");
+    /**
+     * List all installed cell ids.
+     */
     listCellIds = this._requester("list_cell_ids");
+    /**
+     * List all installed apps.
+     */
     listApps = this._requester("list_apps", listAppsTransform);
+    /**
+     * List all attached app interfaces.
+     */
     listAppInterfaces = this._requester("list_app_interfaces");
+    /**
+     * Request all available info about an agent.
+     */
     agentInfo = this._requester("agent_info");
+    /**
+     * Add an existing agent to Holochain.
+     */
     addAgentInfo = this._requester("add_agent_info");
+    /**
+     * Delete a disabled clone cell.
+     */
     deleteCloneCell = this._requester("delete_clone_cell");
+    /**
+     * Grant a zome call capability for an agent, to be used for signing zome
+     * calls.
+     */
     grantZomeCallCapability = this._requester("grant_zome_call_capability");
     // zome call signing related methods
     /**
@@ -123,4 +202,3 @@ function getAppStatusInApiForm(status_filter) {
             };
     }
 }
-//# sourceMappingURL=websocket.js.map

package/lib/api/app/index.js

@@ -1,3 +1,2 @@
 export * from "./types.js";
 export * from "./websocket.js";
-//# sourceMappingURL=index.js.map

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

@@ -1,6 +1,9 @@
 import { AgentPubKey, CellId, DnaHash, DnaProperties, InstalledAppId, InstalledCell, NetworkInfo, RoleName, Timestamp } from "../../types.js";
 import { AppInfo, FunctionName, MembraneProof, NetworkSeed, ZomeName } from "../admin/index.js";
 import { Requester } from "../common.js";
+/**
+ * @public
+ */
 export declare type CallZomeRequestGeneric<Payload> = {
     cell_id: CellId;
     zome_name: ZomeName;
@@ -8,13 +11,31 @@ export declare type CallZomeRequestGeneric<Payload> = {
     payload: Payload;
     provenance: AgentPubKey;
 };
+/**
+ * @public
+ */
 export declare type CallZomeRequest = CallZomeRequestGeneric<any>;
+/**
+ * @public
+ */
 export declare type CallZomeResponseGeneric<Payload> = Payload;
+/**
+ * @public
+ */
 export declare type CallZomeResponse = CallZomeResponseGeneric<any>;
+/**
+ * @public
+ */
 export declare type AppInfoRequest = {
     installed_app_id: InstalledAppId;
 };
+/**
+ * @public
+ */
 export declare type AppInfoResponse = AppInfo;
+/**
+ * @public
+ */
 export interface CreateCloneCellRequest {
     /**
      * The app id that the DNA to clone belongs to
@@ -59,32 +80,86 @@ export interface CreateCloneCellRequest {
      */
     name?: string;
 }
+/**
+ * @public
+ */
 export declare type CreateCloneCellResponse = InstalledCell;
+/**
+ * @public
+ */
 export interface DisableCloneCellRequest {
+    /**
+     * The app id that the clone cell belongs to
+     */
     app_id: InstalledAppId;
+    /**
+     * The clone id or cell id of the clone cell
+     */
     clone_cell_id: RoleName | CellId;
 }
+/**
+ * @public
+ */
 export declare type DisableCloneCellResponse = void;
+/**
+ * @public
+ */
 export declare type EnableCloneCellRequest = DisableCloneCellRequest;
+/**
+ * @public
+ */
 export declare type EnableCloneCellResponse = CreateCloneCellResponse;
+/**
+ * @public
+ */
 export interface NetworkInfoRequest {
-    /** The DNAs for which to get network info */
+    /**
+     * The DNAs for which to get network info
+     */
     dnas: DnaHash[];
 }
+/**
+ * @public
+ */
 export declare const SignalType: {
     readonly App: "App";
     readonly System: "System";
 };
+/**
+ * @public
+ */
 export declare type Signal = {
-    [SignalType.App]: [CellId, any];
+    [SignalType.App]: EncodedAppSignal;
+} | {
     [SignalType.System]: unknown;
 };
+/**
+ * @public
+ */
+export declare type EncodedAppSignal = {
+    cell_id: CellId;
+    zome_name: string;
+    signal: Uint8Array;
+};
+/**
+ * @public
+ */
 export declare type AppSignal = {
     cell_id: CellId;
-    payload: any;
+    zome_name: string;
+    payload: unknown;
 };
+/**
+ * @public
+ */
 export declare type AppSignalCb = (signal: AppSignal) => void;
+/**
+ * @public
+ */
 export declare type NetworkInfoResponse = NetworkInfo[];
+/**
+ * @public
+ */
 export interface AppApi {
     appInfo: Requester<AppInfoRequest, AppInfoResponse>;
     callZome: Requester<CallZomeRequest, CallZomeResponse>;

package/lib/api/app/types.js

@@ -1,5 +1,7 @@
+/**
+ * @public
+ */
 export const SignalType = {
     App: "App",
     System: "System",
 };
-//# sourceMappingURL=types.js.map

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

@@ -5,26 +5,80 @@ import { WsClient } from "../client.js";
 import { 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";
+/**
+ * A class to establish a websocket connection to an App interface of a
+ * Holochain conductor.
+ *
+ * @public
+ */
 export declare class AppWebsocket extends Emittery implements AppApi {
     readonly client: WsClient;
     defaultTimeout: number;
     overrideInstalledAppId?: InstalledAppId;
     private constructor();
+    /**
+     * 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.
+     * @returns A new instance of an AppWebsocket.
+     */
     static connect(url: string, defaultTimeout?: number): Promise<AppWebsocket>;
     _requester: <ReqI, ReqO, ResI, ResO>(tag: string, transformer?: Transformer<ReqI, ReqO, ResI, ResO> | undefined) => (req: ReqI, timeout?: number | undefined) => Promise<ResO>;
+    /**
+     * Request the app's info, including all cell infos.
+     *
+     * @returns The app's {@link AppInfo}.
+     */
     appInfo: Requester<AppInfoRequest, AppInfoResponse>;
+    /**
+     * Call a zome.
+     *
+     * @param request - The zome call arguments.
+     * @param timeout - A timeout to override the default.
+     * @returns The zome call's response.
+     */
     callZome: Requester<CallZomeRequest | CallZomeRequestSigned, CallZomeResponse>;
+    /**
+     * Clone an existing provisioned cell.
+     *
+     * @param args - Specify the cell to clone.
+     * @returns The created clone cell.
+     */
     createCloneCell: Requester<CreateCloneCellRequest, CreateCloneCellResponse>;
+    /**
+     * Enable a disabled clone cell.
+     *
+     * @param args - Specify the clone cell to enable.
+     * @returns The enabled clone cell.
+     */
     enableCloneCell: Requester<EnableCloneCellRequest, EnableCloneCellResponse>;
+    /**
+     * Disable an enabled clone cell.
+     *
+     * @param args - Specify the clone cell to disable.
+     */
     disableCloneCell: Requester<DisableCloneCellRequest, DisableCloneCellResponse>;
+    /**
+     * Request network info about gossip status.
+     */
     networkInfo: Requester<NetworkInfoRequest, NetworkInfoResponse>;
 }
+/**
+ * @public
+ */
 export interface CallZomeRequestUnsigned extends CallZomeRequest {
     cap_secret: CapSecret | null;
     nonce: Nonce256Bit;
     expires_at: number;
 }
+/**
+ * @public
+ */
 export interface CallZomeRequestSigned extends CallZomeRequestUnsigned {
     signature: Uint8Array;
 }
+/**
+ * @public
+ */
 export declare const signZomeCall: (request: CallZomeRequest) => Promise<CallZomeRequestSigned>;

package/lib/api/app/websocket.js

@@ -7,6 +7,12 @@ import { encodeHashToBase64 } from "../../utils/base64.js";
 import { WsClient } from "../client.js";
 import { catchError, DEFAULT_TIMEOUT, promiseTimeout, requesterTransformer, } from "../common.js";
 import { getNonceExpiration, getSigningCredentials, randomNonce, } from "../zome-call-signing.js";
+/**
+ * A class to establish a websocket connection to an App interface of a
+ * Holochain conductor.
+ *
+ * @public
+ */
 export class AppWebsocket extends Emittery {
     client;
     defaultTimeout;
@@ -18,6 +24,13 @@ export class AppWebsocket extends Emittery {
             defaultTimeout === undefined ? DEFAULT_TIMEOUT : defaultTimeout;
         this.overrideInstalledAppId = overrideInstalledAppId;
     }
+    /**
+     * 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.
+     * @returns A new instance of an AppWebsocket.
+     */
     static async connect(url, defaultTimeout) {
         // Check if we are in the launcher's environment, and if so, redirect the url to connect to
         const env = getLauncherEnvironment();
@@ -30,11 +43,43 @@ export class AppWebsocket extends Emittery {
         return appWebsocket;
     }
     _requester = (tag, transformer) => requesterTransformer((req, timeout) => promiseTimeout(this.client.request(req), tag, timeout || this.defaultTimeout).then(catchError), tag, transformer);
+    /**
+     * Request the app's info, including all cell infos.
+     *
+     * @returns The app's {@link AppInfo}.
+     */
     appInfo = this._requester("app_info", appInfoTransform(this));
+    /**
+     * Call a zome.
+     *
+     * @param request - The zome call arguments.
+     * @param timeout - A timeout to override the default.
+     * @returns The zome call's response.
+     */
     callZome = this._requester("call_zome", callZomeTransform);
+    /**
+     * Clone an existing provisioned cell.
+     *
+     * @param args - Specify the cell to clone.
+     * @returns The created clone cell.
+     */
     createCloneCell = this._requester("create_clone_cell");
+    /**
+     * Enable a disabled clone cell.
+     *
+     * @param args - Specify the clone cell to enable.
+     * @returns The enabled clone cell.
+     */
     enableCloneCell = this._requester("enable_clone_cell");
+    /**
+     * Disable an enabled clone cell.
+     *
+     * @param args - Specify the clone cell to disable.
+     */
     disableCloneCell = this._requester("disable_clone_cell");
+    /**
+     * Request network info about gossip status.
+     */
     networkInfo = this._requester("network_info");
 }
 const callZomeTransform = {
@@ -60,6 +105,9 @@ const appInfoTransform = (appWs) => ({
     },
     output: (response) => response,
 });
+/**
+ * @public
+ */
 export const signZomeCall = async (request) => {
     const signingCredentialsForCell = getSigningCredentials(request.cell_id);
     if (!signingCredentialsForCell) {
@@ -85,4 +133,3 @@ export const signZomeCall = async (request) => {
     };
     return signedZomeCall;
 };
-//# sourceMappingURL=websocket.js.map

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

@@ -1,3 +1,2 @@
 export * from "./types.js";
 export * from "./websocket.js";
-//# sourceMappingURL=index.js.map

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

@@ -2,20 +2,47 @@ import { UnsubscribeFunction } from "emittery";
 import { AgentPubKey, RoleName } from "../../index.js";
 import { AppInfoResponse, AppSignal, AppSignalCb, CallZomeRequest, CallZomeRequestSigned, DisableCloneCellRequest, EnableCloneCellRequest, EnableCloneCellResponse } from "../app/index.js";
 import { CreateCloneCellRequest, CreateCloneCellResponse, DisableCloneCellResponse } from "../index.js";
+/**
+ * @public
+ */
 export declare type NonProvenanceCallZomeRequest = Omit<CallZomeRequest, "provenance">;
+/**
+ * @public
+ */
 export declare type RoleNameCallZomeRequest = Omit<NonProvenanceCallZomeRequest, "cell_id"> & {
     role_name: RoleName;
 };
+/**
+ * @public
+ */
 export declare type RoleNameCallZomeRequestSigned = Omit<CallZomeRequestSigned, "cell_id"> & {
     role_name: RoleName;
 };
+/**
+ * @public
+ */
 export declare type AppAgentCallZomeRequest = NonProvenanceCallZomeRequest | RoleNameCallZomeRequest | CallZomeRequestSigned | RoleNameCallZomeRequestSigned;
+/**
+ * @public
+ */
 export declare type AppCreateCloneCellRequest = Omit<CreateCloneCellRequest, "app_id">;
+/**
+ * @public
+ */
 export declare type AppEnableCloneCellRequest = Omit<EnableCloneCellRequest, "app_id">;
+/**
+ * @public
+ */
 export declare type AppDisableCloneCellRequest = Omit<DisableCloneCellRequest, "app_id">;
+/**
+ * @public
+ */
 export interface AppAgentEvents {
     signal: AppSignal;
 }
+/**
+ * @public
+ */
 export interface AppAgentClient {
     callZome(args: AppAgentCallZomeRequest, timeout?: number): Promise<any>;
     on<Name extends keyof AppAgentEvents>(eventName: Name | readonly Name[], listener: AppSignalCb): UnsubscribeFunction;

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

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map