@holochain/client 0.17.0-dev.8 → 0.18.0-dev.0

package/README.md

@@ -15,12 +15,12 @@ A JavaScript client for the Holochain Conductor API (works with browsers as well
 
 ## Installation
 
-**JS client v0.12.x** is compatible with **Holochain v0.1.x**.  
-
-**JS client v0.16.x** is compatible with **Holochain v0.2.x**.
+**JS client v0.18.x** is compatible with **Holochain v0.4.x**.
 
 **JS client v0.17.x** is compatible with **Holochain v0.3.x**.
 
+**JS client v0.16.x** is compatible with **Holochain v0.2.x**.
+
 To install from NPM, run
 ```bash
 npm install --save-exact @holochain/client

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

@@ -1,7 +1,6 @@
 import { Action, DhtOp, Entry, ZomeCallCapGrant } from "../../hdk/index.js";
 import { ActionHash, AgentPubKey, CellId, DnaHash, DnaProperties, Duration, HoloHash, HoloHashB64, InstalledAppId, KitsuneAgent, KitsuneSpace, RoleName, Signature, Timestamp, WasmHash } from "../../types.js";
 import { Requester } from "../common.js";
-import { DisableCloneCellRequest } from "../index.js";
 /**
  * @public
  */
@@ -12,6 +11,10 @@ export type AttachAppInterfaceRequest = {
      * For example: `http://localhost:3000,http://localhost:3001`
      */
     allowed_origins: string;
+    /**
+     * Optionally, bind this app interface to a specific installed app.
+     */
+    installed_app_id?: InstalledAppId;
 };
 /**
  * @public
@@ -35,11 +38,7 @@ export type EnableAppResponse = {
 /**
  * @public
  */
-export type DeactivationReason = {
-    never_activated: null;
-} | {
-    normal: null;
-} | {
+export type DeactivationReason = "never_activated" | "normal" | {
     quarantined: {
         error: string;
     };
@@ -53,11 +52,7 @@ export type PausedAppReason = {
 /**
  * @public
  */
-export type DisabledAppReason = {
-    never_started: null;
-} | {
-    user: null;
-} | {
+export type DisabledAppReason = "never_started" | "user" | {
     error: string;
 };
 /**
@@ -71,9 +66,7 @@ export type InstalledAppInfoStatus = {
     disabled: {
         reason: DisabledAppReason;
     };
-} | {
-    running: null;
-};
+} | "running";
 /**
  * @public
  */
@@ -447,11 +440,11 @@ export type ListActiveAppsResponse = Array<InstalledAppId>;
  * @public
  */
 export declare enum AppStatusFilter {
-    Enabled = "enabled",
-    Disabled = "disabled",
-    Running = "running",
-    Stopped = "stopped",
-    Paused = "paused"
+    Enabled = "Enabled",
+    Disabled = "Disabled",
+    Running = "Running",
+    Stopped = "Stopped",
+    Paused = "Paused"
 }
 /**
  * @public
@@ -470,7 +463,15 @@ export type ListAppInterfacesRequest = void;
 /**
  * @public
  */
-export type ListAppInterfacesResponse = Array<number>;
+export type ListAppInterfacesResponse = Array<AppInterfaceInfo>;
+/**
+ * @public
+ */
+export interface AppInterfaceInfo {
+    port: number;
+    allowed_origins: string;
+    installed_app_id?: InstalledAppId;
+}
 /**
  * This type is meant to be opaque
  *
@@ -496,11 +497,20 @@ export type AddAgentInfoRequest = {
 /**
  * @public
  */
-export type AddAgentInfoResponse = any;
+export type AddAgentInfoResponse = unknown;
 /**
  * @public
  */
-export type DeleteCloneCellRequest = DisableCloneCellRequest;
+export interface DeleteCloneCellRequest {
+    /**
+     * 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
  */
@@ -719,6 +729,25 @@ export type StorageInfoRequest = void;
  * @public
  */
 export type StorageInfoResponse = StorageInfo;
+/**
+ * @public
+ */
+export interface IssueAppAuthenticationTokenRequest {
+    installed_app_id: InstalledAppId;
+    expiry_seconds?: number;
+    single_use?: boolean;
+}
+/**
+ * @public
+ */
+export type AppAuthenticationToken = number[];
+/**
+ * @public
+ */
+export interface IssueAppAuthenticationTokenResponse {
+    token: AppAuthenticationToken;
+    expires_at?: Timestamp;
+}
 /**
  * @public
  */
@@ -750,5 +779,6 @@ export interface AdminApi {
     deleteCloneCell: Requester<DeleteCloneCellRequest, DeleteCloneCellResponse>;
     grantZomeCallCapability: Requester<GrantZomeCallCapabilityRequest, GrantZomeCallCapabilityResponse>;
     storageInfo: Requester<StorageInfoRequest, StorageInfoResponse>;
+    issueAppAuthenticationToken: Requester<IssueAppAuthenticationTokenRequest, IssueAppAuthenticationTokenResponse>;
     dumpNetworkStats: Requester<DumpNetworkStatsRequest, DumpNetworkStatsResponse>;
 }

package/lib/api/admin/types.js

@@ -46,9 +46,9 @@ export var CellProvisioningStrategy;
  */
 export var AppStatusFilter;
 (function (AppStatusFilter) {
-    AppStatusFilter["Enabled"] = "enabled";
-    AppStatusFilter["Disabled"] = "disabled";
-    AppStatusFilter["Running"] = "running";
-    AppStatusFilter["Stopped"] = "stopped";
-    AppStatusFilter["Paused"] = "paused";
+    AppStatusFilter["Enabled"] = "Enabled";
+    AppStatusFilter["Disabled"] = "Disabled";
+    AppStatusFilter["Running"] = "Running";
+    AppStatusFilter["Stopped"] = "Stopped";
+    AppStatusFilter["Paused"] = "Paused";
 })(AppStatusFilter || (AppStatusFilter = {}));

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

@@ -1,8 +1,8 @@
-import { CapSecret, GrantedFunctions } from "../../hdk/capabilities.js";
+import { CapSecret, GrantedFunctions } from "../../hdk/index.js";
 import type { AgentPubKey, CellId } from "../../types.js";
 import { WsClient } from "../client.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";
+import { Requester, Transformer, WebsocketConnectionOptions } 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, IssueAppAuthenticationTokenRequest, IssueAppAuthenticationTokenResponse, 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.
  *
@@ -107,6 +107,7 @@ export declare class AdminWebsocket implements AdminApi {
      */
     grantZomeCallCapability: Requester<GrantZomeCallCapabilityRequest, GrantZomeCallCapabilityResponse>;
     storageInfo: Requester<StorageInfoRequest, StorageInfoResponse>;
+    issueAppAuthenticationToken: Requester<IssueAppAuthenticationTokenRequest, IssueAppAuthenticationTokenResponse>;
     dumpNetworkStats: Requester<DumpNetworkStatsRequest, DumpNetworkStatsResponse>;
     /**
      * Grant a capability for signing zome calls.

package/lib/api/admin/websocket.js

@@ -1,9 +1,8 @@
 import { getLauncherEnvironment } from "../../environments/launcher.js";
-import { GrantedFunctionsType, } from "../../hdk/capabilities.js";
+import { GrantedFunctionsType, } from "../../hdk/index.js";
 import { WsClient } from "../client.js";
-import { catchError, DEFAULT_TIMEOUT, promiseTimeout, requesterTransformer, HolochainError, } from "../common.js";
+import { DEFAULT_TIMEOUT, HolochainError, catchError, 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.
  *
@@ -33,7 +32,7 @@ export class AdminWebsocket {
         // 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) {
-            options.url = new URL(`ws://127.0.0.1:${env.ADMIN_INTERFACE_PORT}`);
+            options.url = new URL(`ws://localhost:${env.ADMIN_INTERFACE_PORT}`);
         }
         if (!options.url) {
             throw new HolochainError("ConnectionUrlMissing", `unable to connect to Conductor API - no url provided and not in a launcher environment.`);
@@ -102,7 +101,7 @@ export class AdminWebsocket {
     /**
      * List all installed apps.
      */
-    listApps = this._requester("list_apps", listAppsTransform);
+    listApps = this._requester("list_apps");
     /**
      * List all attached app interfaces.
      */
@@ -125,6 +124,7 @@ export class AdminWebsocket {
      */
     grantZomeCallCapability = this._requester("grant_zome_call_capability");
     storageInfo = this._requester("storage_info");
+    issueAppAuthenticationToken = this._requester("issue_app_authentication_token");
     dumpNetworkStats = this._requester("dump_network_stats");
     // zome call signing related methods
     /**
@@ -162,47 +162,13 @@ export class AdminWebsocket {
      */
     authorizeSigningCredentials = async (cellId, functions) => {
         const [keyPair, signingKey] = await generateSigningKeyPair();
-        const capSecret = await this.grantSigningKey(cellId, functions || { [GrantedFunctionsType.All]: null }, signingKey);
+        const capSecret = await this.grantSigningKey(cellId, functions || GrantedFunctionsType.All, signingKey);
         setSigningCredentials(cellId, { capSecret, keyPair, signingKey });
     };
 }
-const listAppsTransform = {
-    input: (req) => {
-        const args = {};
-        if (req.status_filter) {
-            args.status_filter = getAppStatusInApiForm(req.status_filter);
-        }
-        return args;
-    },
-    output: (res) => res,
-};
 const dumpStateTransform = {
     input: (req) => req,
     output: (res) => {
         return JSON.parse(res);
     },
 };
-function getAppStatusInApiForm(status_filter) {
-    switch (status_filter) {
-        case AppStatusFilter.Running:
-            return {
-                Running: null,
-            };
-        case AppStatusFilter.Enabled:
-            return {
-                Enabled: null,
-            };
-        case AppStatusFilter.Paused:
-            return {
-                Paused: null,
-            };
-        case AppStatusFilter.Disabled:
-            return {
-                Disabled: null,
-            };
-        case AppStatusFilter.Stopped:
-            return {
-                Stopped: null,
-            };
-    }
-}

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

@@ -1,6 +1,61 @@
-import { AgentPubKey, CellId, DnaHash, DnaProperties, InstalledAppId, NetworkInfo, RoleName, Timestamp } from "../../types.js";
-import { AppInfo, ClonedCell, FunctionName, MembraneProof, NetworkSeed, ZomeName } from "../admin/types.js";
-import { Requester } from "../common.js";
+import { UnsubscribeFunction } from "emittery";
+import { AgentPubKey, AppAuthenticationToken, AppInfo, CapSecret, CellId, ClonedCell, DnaHash, DnaProperties, FunctionName, MembraneProof, NetworkInfo, NetworkSeed, Nonce256Bit, RoleName, Timestamp, WebsocketConnectionOptions, ZomeName } from "../../index.js";
+/**
+ * @public
+ */
+export type NonProvenanceCallZomeRequest = Omit<CallZomeRequest, "provenance">;
+/**
+ * @public
+ */
+export type RoleNameCallZomeRequest = Omit<NonProvenanceCallZomeRequest, "cell_id"> & {
+    role_name: RoleName;
+};
+/**
+ * @public
+ */
+export type RoleNameCallZomeRequestSigned = Omit<CallZomeRequestSigned, "cell_id"> & {
+    role_name: RoleName;
+};
+/**
+ * @public
+ */
+export type AppCallZomeRequest = NonProvenanceCallZomeRequest | RoleNameCallZomeRequest | CallZomeRequestSigned | RoleNameCallZomeRequestSigned;
+/**
+ * @public
+ */
+export type AppCreateCloneCellRequest = Omit<CreateCloneCellRequest, "app_id">;
+/**
+ * @public
+ */
+export type AppEnableCloneCellRequest = Omit<EnableCloneCellRequest, "app_id">;
+/**
+ * @public
+ */
+export type AppDisableCloneCellRequest = Omit<DisableCloneCellRequest, "app_id">;
+/**
+ * @public
+ */
+export type AppNetworkInfoRequest = Omit<NetworkInfoRequest, "agent_pub_key">;
+/**
+ * @public
+ */
+export interface AppEvents {
+    signal: AppSignal;
+}
+/**
+ * @public
+ */
+export interface CallZomeRequestUnsigned extends CallZomeRequest {
+    cap_secret: CapSecret | null;
+    nonce: Nonce256Bit;
+    expires_at: number;
+}
+/**
+ * @public
+ */
+export interface CallZomeRequestSigned extends CallZomeRequestUnsigned {
+    signature: Uint8Array;
+}
 /**
  * @public
  */
@@ -23,12 +78,6 @@ export type CallZomeResponseGeneric<Payload> = Payload;
  * @public
  */
 export type CallZomeResponse = CallZomeResponseGeneric<any>;
-/**
- * @public
- */
-export type AppInfoRequest = {
-    installed_app_id: InstalledAppId;
-};
 /**
  * @public
  */
@@ -37,10 +86,6 @@ export type AppInfoResponse = AppInfo | null;
  * @public
  */
 export interface CreateCloneCellRequest {
-    /**
-     * The app id that the DNA to clone belongs to
-     */
-    app_id: InstalledAppId;
     /**
      * The DNA's role id to clone.
      */
@@ -88,10 +133,6 @@ export type CreateCloneCellResponse = ClonedCell;
  * @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
      */
@@ -168,9 +209,19 @@ export type NetworkInfoResponse = NetworkInfo[];
 /**
  * @public
  */
-export interface AppApi {
-    appInfo: Requester<AppInfoRequest, AppInfoResponse>;
-    callZome: Requester<CallZomeRequest, CallZomeResponse>;
-    enableCloneCell: Requester<EnableCloneCellRequest, EnableCloneCellResponse>;
-    disableCloneCell: Requester<DisableCloneCellRequest, DisableCloneCellResponse>;
+export interface AppClient {
+    callZome(args: AppCallZomeRequest, timeout?: number): Promise<any>;
+    on<Name extends keyof AppEvents>(eventName: Name | readonly Name[], listener: AppSignalCb): UnsubscribeFunction;
+    appInfo(): Promise<AppInfoResponse>;
+    myPubKey: AgentPubKey;
+    createCloneCell(args: AppCreateCloneCellRequest): Promise<CreateCloneCellResponse>;
+    enableCloneCell(args: AppEnableCloneCellRequest): Promise<EnableCloneCellResponse>;
+    disableCloneCell(args: AppDisableCloneCellRequest): Promise<DisableCloneCellResponse>;
+    networkInfo(args: AppNetworkInfoRequest): Promise<NetworkInfoResponse>;
+}
+/**
+ * @public
+ */
+export interface AppWebsocketConnectionOptions extends WebsocketConnectionOptions {
+    token?: AppAuthenticationToken;
 }

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

@@ -1,35 +1,50 @@
-import Emittery from "emittery";
-import { CapSecret } from "../../hdk/capabilities.js";
-import { InstalledAppId } from "../../types.js";
+import { UnsubscribeFunction } from "emittery";
+import { AgentPubKey, CellId, RoleName } from "../../types.js";
+import { AppInfo } from "../admin/index.js";
+import { AppCallZomeRequest, AppClient, AppEvents, AppNetworkInfoRequest, AppCreateCloneCellRequest, AppDisableCloneCellRequest, AppEnableCloneCellRequest, AppSignalCb, CallZomeRequest, CallZomeRequestSigned, CallZomeResponse, CreateCloneCellResponse, DisableCloneCellResponse, EnableCloneCellResponse, NetworkInfoResponse, AppWebsocketConnectionOptions } from "./types.js";
 import { WsClient } from "../client.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";
 /**
- * A class to establish a websocket connection to an App interface of a
- * Holochain conductor.
+ * A class to establish a websocket connection to an App interface, for a
+ * specific agent and app.
  *
  * @public
  */
-export declare class AppWebsocket extends Emittery implements AppApi {
+export declare class AppWebsocket implements AppClient {
     readonly client: WsClient;
-    defaultTimeout: number;
-    overrideInstalledAppId?: InstalledAppId;
+    readonly myPubKey: AgentPubKey;
+    private readonly defaultTimeout;
+    private readonly emitter;
+    cachedAppInfo?: AppInfo | null;
+    private readonly appInfoRequester;
+    private readonly callZomeRequester;
+    private readonly createCloneCellRequester;
+    private readonly enableCloneCellRequester;
+    private readonly disableCloneCellRequester;
+    private readonly networkInfoRequester;
     private constructor();
     /**
-     * Instance factory for creating AppWebsockets.
+     * Instance factory for creating an {@link AppWebsocket}.
      *
+     * @param token - A token to authenticate the websocket connection. Get a token using AdminWebsocket#issueAppAuthenticationToken.
      * @param options - {@link (WebsocketConnectionOptions:interface)}
      * @returns A new instance of an 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>;
+    static connect(options?: AppWebsocketConnectionOptions): Promise<AppWebsocket>;
     /**
      * Request the app's info, including all cell infos.
      *
+     * @param timeout - A timeout to override the default.
      * @returns The app's {@link AppInfo}.
      */
-    appInfo: Requester<AppInfoRequest, AppInfoResponse>;
+    appInfo(timeout?: number): Promise<AppInfo>;
+    /**
+     * 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.
      *
@@ -37,45 +52,43 @@ export declare class AppWebsocket extends Emittery implements AppApi {
      * @param timeout - A timeout to override the default.
      * @returns The zome call's response.
      */
-    callZome: Requester<CallZomeRequest | CallZomeRequestSigned, CallZomeResponse>;
+    callZome(request: AppCallZomeRequest, timeout?: number): Promise<CallZomeResponse>;
     /**
      * Clone an existing provisioned cell.
      *
      * @param args - Specify the cell to clone.
      * @returns The created clone cell.
      */
-    createCloneCell: Requester<CreateCloneCellRequest, CreateCloneCellResponse>;
+    createCloneCell(args: AppCreateCloneCellRequest): Promise<CreateCloneCellResponse>;
     /**
      * Enable a disabled clone cell.
      *
      * @param args - Specify the clone cell to enable.
      * @returns The enabled clone cell.
      */
-    enableCloneCell: Requester<EnableCloneCellRequest, EnableCloneCellResponse>;
+    enableCloneCell(args: AppEnableCloneCellRequest): Promise<EnableCloneCellResponse>;
     /**
      * Disable an enabled clone cell.
      *
      * @param args - Specify the clone cell to disable.
      */
-    disableCloneCell: Requester<DisableCloneCellRequest, DisableCloneCellResponse>;
+    disableCloneCell(args: AppDisableCloneCellRequest): Promise<DisableCloneCellResponse>;
     /**
      * Request network info about gossip status.
+     *  @param args - Specify the DNAs for which you want network info
+     *  @returns Network info for the specified DNAs
      */
-    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;
+    networkInfo(args: AppNetworkInfoRequest): Promise<NetworkInfoResponse>;
+    /**
+     * 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 AppEvents>(eventName: Name | readonly Name[], listener: AppSignalCb): UnsubscribeFunction;
+    private static requester;
+    private containsCell;
 }
 /**
  * @public