@holochain/client 0.19.0-dev.0 → 0.19.0-dev.2

package/README.md

@@ -179,8 +179,9 @@ You need `holochain` and `hc` on your path, best to get them from nix with `nix-
 
 To perform the pre-requisite DNA compilation steps, and run the Nodejs test, run:
 ```bash
-nix-shell
-./run-test.sh
+nix develop
+./build-fixture.sh
+npm run test
 ```
 
 ## Contribute

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

@@ -120,6 +120,7 @@ export type AppInfo = {
     installed_app_id: InstalledAppId;
     cell_info: Record<RoleName, Array<CellInfo>>;
     status: InstalledAppInfoStatus;
+    installed_at: Timestamp;
 };
 /**
  * @public

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

@@ -1,5 +1,5 @@
 import { UnsubscribeFunction } from "emittery";
-import { AgentPubKey, AppAuthenticationToken, AppInfo, CapSecret, CellId, ClonedCell, DnaHash, DnaProperties, EntryHash, FunctionName, InstalledAppId, MembraneProof, MemproofMap, NetworkInfo, NetworkSeed, Nonce256Bit, RoleName, Timestamp, Transformer, WebsocketConnectionOptions, ZomeName } from "../../index.js";
+import { AgentPubKey, AppAuthenticationToken, AppInfo, CapSecret, CellId, ClonedCell, DnaHash, DnaProperties, EntryHash, FunctionName, InstalledAppId, MembraneProof, MemproofMap, NetworkInfo, NetworkSeed, Nonce256Bit, RoleName, Timestamp, Transformer, WebsocketConnectionOptions, ZomeName, PreflightRequest, SignedAction, SignedActionHashed } from "../../index.js";
 /**
  * @public
  */
@@ -183,6 +183,211 @@ export interface NetworkInfoRequest {
      */
     last_time_queried?: number;
 }
+/**
+ * Cell id for which the countersigning session state is requested.
+ *
+ * @public
+ */
+export type GetCountersigningSessionStateRequest = CellId;
+/**
+ * @public
+ */
+export type GetCountersigningSessionStateResponse = null | CountersigningSessionState;
+/**
+ * Cell id for which the countersigning session should be abandoned.
+ *
+ * @public
+ */
+export type AbandonCountersigningSessionStateRequest = CellId;
+/**
+ * @public
+ */
+export type AbandonCountersigningSessionStateResponse = null;
+/**
+ * Cell id for which the countersigning session should be published.
+ *
+ * @public
+ */
+export type PublishCountersigningSessionStateRequest = CellId;
+/**
+ * @public
+ */
+export type PublishCountersigningSessionStateResponse = null;
+/**
+ * @public
+ */
+export declare enum CountersigningSessionStateType {
+    Accepted = "Accepted",
+    SignaturesCollected = "SignaturesCollected",
+    Unknown = "Unknown"
+}
+/**
+ * @public
+ */
+export type CountersigningSessionState = 
+/**
+ * This is the entry state. Accepting a countersigning session through the HDK will immediately
+ * register the countersigning session in this state, for management by the countersigning workflow.
+ *
+ * The session will stay in this state even when the agent commits their countersigning entry and only
+ * move to the next state when the first signature bundle is received.
+ */
+{
+    [CountersigningSessionStateType.Accepted]: PreflightRequest;
+}
+/**
+ * This is the state where we have collected one or more signatures for a countersigning session.
+ *
+ * This state can be entered from the [CountersigningSessionState::Accepted] state, which happens
+ * when a witness returns a signature bundle to us. While the session has not timed out, we will
+ * stay in this state and wait until one of the signatures bundles we have received is valid for
+ * the session to be completed.
+ *
+ * If we entered this state from the [CountersigningSessionState::Accepted] state, we will either
+ * complete the session successfully or the session will time out. On a timeout we will move
+ * to the [CountersigningSessionState::Unknown] for a limited number of attempts to recover the session.
+ *
+ * This state can also be entered from the [CountersigningSessionState::Unknown] state, which happens when we
+ * have been able to recover the session from the source chain and have requested signed actions
+ * from agent authorities to build a signature bundle.
+ *
+ * If we entered this state from the [CountersigningSessionState::Unknown] state, we will either
+ * complete the session successfully, or if the signatures are invalid, we will return to the
+ * [CountersigningSessionState::Unknown] state.
+ */
+ | {
+    [CountersigningSessionStateType.SignaturesCollected]: {
+        /** The preflight request that has been exchanged among countersigning peers. */
+        preflight_request: PreflightRequest;
+        /** Signed actions of the committed countersigned entries of all participating peers. */
+        signature_bundles: SignedAction[][];
+        /**
+         * This field is set when the signature bundle came from querying agent activity authorities
+         * in the unknown state. If we started from that state, we should return to it if the
+         * signature bundle is invalid. Otherwise, stay in this state and wait for more signatures.
+         */
+        resolution?: SessionResolutionSummary;
+    };
+}
+/**
+ * The session is in an unknown state and needs to be resolved.
+ *
+ * This state is used when we have lost track of the countersigning session. This happens if
+ * we have got far enough to create the countersigning entry but have crashed or restarted
+ * before we could complete the session. In this case we need to try to discover what the other
+ * agent or agents involved in the session have done.
+ *
+ * This state is also entered temporarily when we have published a signature and then the
+ * session has timed out. To avoid deadlocking with two parties both waiting for each other to
+ * proceed, we cannot stay in this state indefinitely. We will make a limited number of attempts
+ * to recover and if we cannot, we will abandon the session.
+ *
+ * The only exception to the attempt limiting is if we are unable to reach agent activity authorities
+ * to progress resolving the session. In this case, the attempts are not counted towards the
+ * configured limit. This does not protect us against a network partition where we can only see
+ * a subset of the network, but it does protect us against Holochain forcing a decision while
+ * it is unable to reach any peers.
+ *
+ * Note that because the [PreflightRequest] is stored here, we only ever enter the unknown state
+ * if we managed to keep the preflight request in memory, or if we have been able to recover it
+ * from the source chain as part of the committed [CounterSigningSessionData]. Otherwise, we
+ * are unable to discover what session we were participating in, and we must abandon the session
+ * without going through this recovery state.
+ */
+ | {
+    [CountersigningSessionStateType.Unknown]: {
+        /** The preflight request that has been exchanged. */
+        preflight_request: PreflightRequest;
+        /** Summary of the attempts to resolve this session. */
+        resolution: SessionResolutionSummary;
+        /** Flag if the session is programmed to be force-abandoned on the next countersigning workflow run. */
+        force_abandon: boolean;
+        /** Flag if the session is programmed to be force-published on the next countersigning workflow run. */
+        force_publish: boolean;
+    };
+};
+/**
+ * Summary of the workflow's attempts to resolve the outcome a failed countersigning session.
+ * This tracks the numbers of attempts and the outcome of the most recent attempt.
+ *
+ * @public
+ */
+export interface SessionResolutionSummary {
+    /** The reason why session resolution is required. */
+    required_reason: ResolutionRequiredReason;
+    /**
+     * How many attempts have been made to resolve the session.
+     *
+     * Attempts are made according to the frequency specified by [RETRY_UNKNOWN_SESSION_STATE_DELAY].
+     *
+     * This count is only correct for the current run of the Holochain conductor. If the conductor
+     * is restarted then this counter is also reset.
+     */
+    attempts: number;
+    /** The time of the last attempt to resolve the session. */
+    last_attempt_at?: Timestamp;
+    /** The outcome of the most recent attempt to resolve the session. */
+    outcomes: SessionResolutionOutcome[];
+}
+/**
+ * The reason why a countersigning session can not be resolved automatically and requires manual resolution.
+ *
+ * @public
+ */
+export declare enum ResolutionRequiredReason {
+    /** The session has timed out, so we should try to resolve its state before abandoning. */
+    Timeout = "Timeout",
+    /** Something happened, like a conductor restart, and we lost track of the session. */
+    Unknown = "Unknown"
+}
+/**
+ * The outcome for a single agent who participated in a countersigning session.
+ *
+ * [NUM_AUTHORITIES_TO_QUERY] authorities are made to agent activity authorities for each agent,
+ * and the decisions are collected into [SessionResolutionOutcome::decisions].
+ *
+ * @public
+ */
+export interface SessionResolutionOutcome {
+    /**
+     * The agent who participated in the countersigning session and is the subject of this
+     * resolution outcome.
+     */
+    agent: AgentPubKey;
+    /** The resolved decision for each authority for the subject agent. */
+    decisions: SessionCompletionDecision[];
+}
+/**
+ * Decision about an incomplete countersigning session.
+ *
+ * @public
+ */
+export declare enum SessionCompletionDecisionType {
+    /** Evidence found on the network that this session completed successfully. */
+    Complete = "Complete",
+    /**
+     * Evidence found on the network that this session was abandoned and other agents have
+     * added to their chain without completing the session.
+     */
+    Abandoned = "Abandoned",
+    /**
+     * No evidence, or inconclusive evidence, was found on the network. Holochain will not make an
+     * automatic decision until the evidence is conclusive.
+     */
+    Indeterminate = "Indeterminate",
+    /**There were errors encountered while trying to resolve the session. Errors such as network
+     * errors are treated differently to inconclusive evidence. We don't want to force a decision
+     * when we're offline, for example. In this case, the resolution must be retried later and this
+     * attempt should not be counted.
+     */
+    Failed = "Failed"
+}
+/**
+ * @public
+ */
+export type SessionCompletionDecision = {
+    [SessionCompletionDecisionType.Complete]: SignedActionHashed;
+} | SessionCompletionDecisionType.Abandoned | SessionCompletionDecisionType.Indeterminate | SessionCompletionDecisionType.Failed;
 /**
  * @public
  */

package/lib/api/app/types.js

@@ -1,3 +1,50 @@
+/**
+ * @public
+ */
+export var CountersigningSessionStateType;
+(function (CountersigningSessionStateType) {
+    CountersigningSessionStateType["Accepted"] = "Accepted";
+    CountersigningSessionStateType["SignaturesCollected"] = "SignaturesCollected";
+    CountersigningSessionStateType["Unknown"] = "Unknown";
+})(CountersigningSessionStateType || (CountersigningSessionStateType = {}));
+/**
+ * The reason why a countersigning session can not be resolved automatically and requires manual resolution.
+ *
+ * @public
+ */
+export var ResolutionRequiredReason;
+(function (ResolutionRequiredReason) {
+    /** The session has timed out, so we should try to resolve its state before abandoning. */
+    ResolutionRequiredReason["Timeout"] = "Timeout";
+    /** Something happened, like a conductor restart, and we lost track of the session. */
+    ResolutionRequiredReason["Unknown"] = "Unknown";
+})(ResolutionRequiredReason || (ResolutionRequiredReason = {}));
+/**
+ * Decision about an incomplete countersigning session.
+ *
+ * @public
+ */
+export var SessionCompletionDecisionType;
+(function (SessionCompletionDecisionType) {
+    /** Evidence found on the network that this session completed successfully. */
+    SessionCompletionDecisionType["Complete"] = "Complete";
+    /**
+     * Evidence found on the network that this session was abandoned and other agents have
+     * added to their chain without completing the session.
+     */
+    SessionCompletionDecisionType["Abandoned"] = "Abandoned";
+    /**
+     * No evidence, or inconclusive evidence, was found on the network. Holochain will not make an
+     * automatic decision until the evidence is conclusive.
+     */
+    SessionCompletionDecisionType["Indeterminate"] = "Indeterminate";
+    /**There were errors encountered while trying to resolve the session. Errors such as network
+     * errors are treated differently to inconclusive evidence. We don't want to force a decision
+     * when we're offline, for example. In this case, the resolution must be retried later and this
+     * attempt should not be counted.
+     */
+    SessionCompletionDecisionType["Failed"] = "Failed";
+})(SessionCompletionDecisionType || (SessionCompletionDecisionType = {}));
 /**
  * @public
  */

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

@@ -1,7 +1,7 @@
 import { UnsubscribeFunction } from "emittery";
 import { AgentPubKey, CellId, InstalledAppId, RoleName } from "../../types.js";
 import { AppInfo, MemproofMap } from "../admin/index.js";
-import { AppCallZomeRequest, AppClient, AppEvents, AppNetworkInfoRequest, AppCreateCloneCellRequest, AppDisableCloneCellRequest, AppEnableCloneCellRequest, SignalCb, CallZomeRequest, CallZomeRequestSigned, CallZomeResponse, CreateCloneCellResponse, DisableCloneCellResponse, EnableCloneCellResponse, NetworkInfoResponse, AppWebsocketConnectionOptions } from "./types.js";
+import { AppCallZomeRequest, AppClient, AppEvents, AppNetworkInfoRequest, AppCreateCloneCellRequest, AppDisableCloneCellRequest, AppEnableCloneCellRequest, SignalCb, CallZomeRequest, CallZomeRequestSigned, NetworkInfoResponse, AppWebsocketConnectionOptions, GetCountersigningSessionStateRequest, GetCountersigningSessionStateResponse, AbandonCountersigningSessionStateRequest, PublishCountersigningSessionStateRequest } from "./types.js";
 import { WsClient } from "../client.js";
 /**
  * A class to establish a websocket connection to an App interface, for a
@@ -25,6 +25,9 @@ export declare class AppWebsocket implements AppClient {
     private readonly enableCloneCellRequester;
     private readonly disableCloneCellRequester;
     private readonly networkInfoRequester;
+    private readonly getCountersigningSessionStateRequester;
+    private readonly abandonCountersigningSessionRequester;
+    private readonly publishCountersigningSessionRequester;
     private constructor();
     /**
      * Instance factory for creating an {@link AppWebsocket}.
@@ -67,33 +70,111 @@ export declare class AppWebsocket implements AppClient {
      * @param timeout - A timeout to override the default.
      * @returns The zome call's response.
      */
-    callZome(request: AppCallZomeRequest, timeout?: number): Promise<CallZomeResponse>;
+    callZome<ReturnType>(request: AppCallZomeRequest, timeout?: number): Promise<ReturnType>;
     /**
      * Clone an existing provisioned cell.
      *
      * @param args - Specify the cell to clone.
      * @returns The created clone cell.
      */
-    createCloneCell(args: AppCreateCloneCellRequest): Promise<CreateCloneCellResponse>;
+    createCloneCell(args: AppCreateCloneCellRequest): Promise<import("../admin/types.js").ClonedCell>;
     /**
      * Enable a disabled clone cell.
      *
      * @param args - Specify the clone cell to enable.
      * @returns The enabled clone cell.
      */
-    enableCloneCell(args: AppEnableCloneCellRequest): Promise<EnableCloneCellResponse>;
+    enableCloneCell(args: AppEnableCloneCellRequest): Promise<import("../admin/types.js").ClonedCell>;
     /**
      * Disable an enabled clone cell.
      *
      * @param args - Specify the clone cell to disable.
      */
-    disableCloneCell(args: AppDisableCloneCellRequest): Promise<DisableCloneCellResponse>;
+    disableCloneCell(args: AppDisableCloneCellRequest): Promise<void>;
     /**
      * 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(args: AppNetworkInfoRequest): Promise<NetworkInfoResponse>;
+    /**
+     * Get the state of a countersigning session.
+     */
+    getCountersigningSessionState(args: GetCountersigningSessionStateRequest): Promise<GetCountersigningSessionStateResponse>;
+    /**
+     * Abandon an unresolved countersigning session.
+     *
+     * If the current session has not been resolved automatically, it can be forcefully abandoned.
+     * A condition for this call to succeed is that at least one attempt has been made to resolve
+     * it automatically.
+     *
+     * # Returns
+     *
+     * [`AppResponse::CountersigningSessionAbandoned`]
+     *
+     * The session is marked for abandoning and the countersigning workflow was triggered. The session
+     * has not been abandoned yet.
+     *
+     * Upon successful abandoning the system signal [`SystemSignal::AbandonedCountersigning`] will
+     * be emitted and the session removed from state, so that [`AppRequest::GetCountersigningSessionState`]
+     * would return `None`.
+     *
+     * In the countersigning workflow it will first be attempted to resolve the session with incoming
+     * signatures of the countersigned entries, before force-abandoning the session. In a very rare event
+     * it could happen that in just the moment where the [`AppRequest::AbandonCountersigningSession`]
+     * is made, signatures for this session come in. If they are valid, the session will be resolved and
+     * published as usual. Should they be invalid, however, the flag to abandon the session is erased.
+     * In such cases this request can be retried until the session has been abandoned successfully.
+     *
+     * # Errors
+     *
+     * [`CountersigningError::WorkspaceDoesNotExist`] likely indicates that an invalid cell id was
+     * passed in to the call.
+     *
+     * [`CountersigningError::SessionNotFound`] when no ongoing session could be found for the provided
+     * cell id.
+     *
+     * [`CountersigningError::SessionNotUnresolved`] when an attempt to resolve the session
+     * automatically has not been made.
+     */
+    abandonCountersigningSession(args: AbandonCountersigningSessionStateRequest): Promise<null>;
+    /**
+     * Publish an unresolved countersigning session.
+     *
+     * If the current session has not been resolved automatically, it can be forcefully published.
+     * A condition for this call to succeed is that at least one attempt has been made to resolve
+     * it automatically.
+     *
+     * # Returns
+     *
+     * [`AppResponse::PublishCountersigningSessionTriggered`]
+     *
+     * The session is marked for publishing and the countersigning workflow was triggered. The session
+     * has not been published yet.
+     *
+     * Upon successful publishing the system signal [`SystemSignal::SuccessfulCountersigning`] will
+     * be emitted and the session removed from state, so that [`AppRequest::GetCountersigningSessionState`]
+     * would return `None`.
+     *
+     * In the countersigning workflow it will first be attempted to resolve the session with incoming
+     * signatures of the countersigned entries, before force-publishing the session. In a very rare event
+     * it could happen that in just the moment where the [`AppRequest::PublishCountersigningSession`]
+     * is made, signatures for this session come in. If they are valid, the session will be resolved and
+     * published as usual. Should they be invalid, however, the flag to publish the session is erased.
+     * In such cases this request can be retried until the session has been published successfully.
+     *
+     * # Errors
+     *
+     * [`CountersigningError::WorkspaceDoesNotExist`] likely indicates that an invalid cell id was
+     * passed in to the call.
+     *
+     * [`CountersigningError::SessionNotFound`] when no ongoing session could be found for the provided
+     * cell id.
+     *
+     * [`CountersigningError::SessionNotUnresolved`] when an attempt to resolve the session
+     * automatically has not been made.
+     */
+    publishCountersigningSession(args: PublishCountersigningSessionStateRequest): Promise<null>;
     /**
      * Register an event listener for signals.
      *
@@ -103,7 +184,6 @@ export declare class AppWebsocket implements AppClient {
      */
     on<Name extends keyof AppEvents>(eventName: Name | readonly Name[], listener: SignalCb): UnsubscribeFunction;
     private static requester;
-    private containsCell;
 }
 /**
  * @public

package/lib/api/app/websocket.js

@@ -1,6 +1,6 @@
 import Emittery from "emittery";
 import { omit } from "lodash-es";
-import { CellType } from "../admin/index.js";
+import { CellType, } from "../admin/index.js";
 import { catchError, DEFAULT_TIMEOUT, getBaseRoleNameFromCloneId, HolochainError, isCloneId, promiseTimeout, requesterTransformer, } from "../common.js";
 import { getHostZomeCallSigner, getLauncherEnvironment, } from "../../environments/launcher.js";
 import { decode, encode } from "@msgpack/msgpack";
@@ -31,6 +31,9 @@ export class AppWebsocket {
     enableCloneCellRequester;
     disableCloneCellRequester;
     networkInfoRequester;
+    getCountersigningSessionStateRequester;
+    abandonCountersigningSessionRequester;
+    publishCountersigningSessionRequester;
     constructor(client, appInfo, callZomeTransform, defaultTimeout) {
         this.client = client;
         this.myPubKey = appInfo.agent_pub_key;
@@ -47,6 +50,9 @@ export class AppWebsocket {
         this.enableCloneCellRequester = AppWebsocket.requester(this.client, "enable_clone_cell", this.defaultTimeout);
         this.disableCloneCellRequester = AppWebsocket.requester(this.client, "disable_clone_cell", this.defaultTimeout);
         this.networkInfoRequester = AppWebsocket.requester(this.client, "network_info", this.defaultTimeout);
+        this.getCountersigningSessionStateRequester = AppWebsocket.requester(this.client, "get_countersigning_session_state", this.defaultTimeout);
+        this.abandonCountersigningSessionRequester = AppWebsocket.requester(this.client, "abandon_countersigning_session", this.defaultTimeout);
+        this.publishCountersigningSessionRequester = AppWebsocket.requester(this.client, "publish_countersigning_session", this.defaultTimeout);
         // Ensure all super methods are bound to this instance because Emittery relies on `this` being the instance.
         // Please retain until the upstream is fixed https://github.com/sindresorhus/emittery/issues/86.
         Object.getOwnPropertyNames(Emittery.prototype).forEach((name) => {
@@ -77,16 +83,10 @@ export class AppWebsocket {
             throw new HolochainError("ConnectionUrlMissing", `unable to connect to Conductor API - no url provided and not in a launcher environment.`);
         }
         const client = await WsClient.connect(options.url, options.wsClientOptions);
-        if (env?.APP_INTERFACE_TOKEN) {
-            // Note: This will only work for multiple connections if a single_use = false token is provided
-            await client.authenticate({ token: env.APP_INTERFACE_TOKEN });
-        }
-        else {
-            if (!options.token) {
-                throw new HolochainError("AppAuthenticationTokenMissing", `unable to connect to Conductor API - no app authentication token provided.`);
-            }
-            await client.authenticate({ token: options.token });
-        }
+        const token = options.token ?? env?.APP_INTERFACE_TOKEN;
+        if (!token)
+            throw new HolochainError("AppAuthenticationTokenMissing", `unable to connect to Conductor API - no app authentication token provided.`);
+        await client.authenticate({ token });
         const appInfo = await AppWebsocket.requester(client, "app_info", DEFAULT_TIMEOUT)(null);
         if (!appInfo) {
             throw new HolochainError("AppNotFound", `The app your connection token was issued for was not found. The app needs to be installed and enabled.`);
@@ -224,6 +224,90 @@ export class AppWebsocket {
             agent_pub_key: this.myPubKey,
         });
     }
+    /**
+     * Get the state of a countersigning session.
+     */
+    async getCountersigningSessionState(args) {
+        return this.getCountersigningSessionStateRequester(args);
+    }
+    /**
+     * Abandon an unresolved countersigning session.
+     *
+     * If the current session has not been resolved automatically, it can be forcefully abandoned.
+     * A condition for this call to succeed is that at least one attempt has been made to resolve
+     * it automatically.
+     *
+     * # Returns
+     *
+     * [`AppResponse::CountersigningSessionAbandoned`]
+     *
+     * The session is marked for abandoning and the countersigning workflow was triggered. The session
+     * has not been abandoned yet.
+     *
+     * Upon successful abandoning the system signal [`SystemSignal::AbandonedCountersigning`] will
+     * be emitted and the session removed from state, so that [`AppRequest::GetCountersigningSessionState`]
+     * would return `None`.
+     *
+     * In the countersigning workflow it will first be attempted to resolve the session with incoming
+     * signatures of the countersigned entries, before force-abandoning the session. In a very rare event
+     * it could happen that in just the moment where the [`AppRequest::AbandonCountersigningSession`]
+     * is made, signatures for this session come in. If they are valid, the session will be resolved and
+     * published as usual. Should they be invalid, however, the flag to abandon the session is erased.
+     * In such cases this request can be retried until the session has been abandoned successfully.
+     *
+     * # Errors
+     *
+     * [`CountersigningError::WorkspaceDoesNotExist`] likely indicates that an invalid cell id was
+     * passed in to the call.
+     *
+     * [`CountersigningError::SessionNotFound`] when no ongoing session could be found for the provided
+     * cell id.
+     *
+     * [`CountersigningError::SessionNotUnresolved`] when an attempt to resolve the session
+     * automatically has not been made.
+     */
+    async abandonCountersigningSession(args) {
+        return this.abandonCountersigningSessionRequester(args);
+    }
+    /**
+     * Publish an unresolved countersigning session.
+     *
+     * If the current session has not been resolved automatically, it can be forcefully published.
+     * A condition for this call to succeed is that at least one attempt has been made to resolve
+     * it automatically.
+     *
+     * # Returns
+     *
+     * [`AppResponse::PublishCountersigningSessionTriggered`]
+     *
+     * The session is marked for publishing and the countersigning workflow was triggered. The session
+     * has not been published yet.
+     *
+     * Upon successful publishing the system signal [`SystemSignal::SuccessfulCountersigning`] will
+     * be emitted and the session removed from state, so that [`AppRequest::GetCountersigningSessionState`]
+     * would return `None`.
+     *
+     * In the countersigning workflow it will first be attempted to resolve the session with incoming
+     * signatures of the countersigned entries, before force-publishing the session. In a very rare event
+     * it could happen that in just the moment where the [`AppRequest::PublishCountersigningSession`]
+     * is made, signatures for this session come in. If they are valid, the session will be resolved and
+     * published as usual. Should they be invalid, however, the flag to publish the session is erased.
+     * In such cases this request can be retried until the session has been published successfully.
+     *
+     * # Errors
+     *
+     * [`CountersigningError::WorkspaceDoesNotExist`] likely indicates that an invalid cell id was
+     * passed in to the call.
+     *
+     * [`CountersigningError::SessionNotFound`] when no ongoing session could be found for the provided
+     * cell id.
+     *
+     * [`CountersigningError::SessionNotUnresolved`] when an attempt to resolve the session
+     * automatically has not been made.
+     */
+    async publishCountersigningSession(args) {
+        return this.publishCountersigningSessionRequester(args);
+    }
     /**
      * Register an event listener for signals.
      *
@@ -237,25 +321,6 @@ export class AppWebsocket {
     static requester(client, tag, defaultTimeout, transformer) {
         return requesterTransformer((req, timeout) => promiseTimeout(client.request(req), tag, timeout || defaultTimeout).then(catchError), tag, transformer);
     }
-    containsCell(cellId) {
-        const appInfo = this.cachedAppInfo;
-        if (!appInfo) {
-            return false;
-        }
-        for (const roleName of Object.keys(appInfo.cell_info)) {
-            for (const cellInfo of appInfo.cell_info[roleName]) {
-                const currentCellId = CellType.Provisioned in cellInfo
-                    ? cellInfo[CellType.Provisioned].cell_id
-                    : CellType.Cloned in cellInfo
-                        ? cellInfo[CellType.Cloned].cell_id
-                        : undefined;
-                if (currentCellId && isSameCell(currentCellId, cellId)) {
-                    return true;
-                }
-            }
-        }
-        return false;
-    }
 }
 const defaultCallZomeTransform = {
     input: async (request) => {
@@ -272,8 +337,6 @@ const defaultCallZomeTransform = {
     },
     output: (response) => decode(response),
 };
-const isSameCell = (cellId1, cellId2) => cellId1[0].every((byte, index) => byte === cellId2[0][index]) &&
-    cellId1[1].every((byte, index) => byte === cellId2[1][index]);
 /**
  * @public
  */

package/lib/api/client.d.ts

@@ -23,8 +23,8 @@ export declare class WsClient extends Emittery {
     options: WsClientOptions;
     private pendingRequests;
     private index;
+    private authenticationToken;
     constructor(socket: IsoWebSocket, url?: URL, options?: WsClientOptions);
-    private setupSocket;
     /**
      * Instance factory for creating WsClients.
      *
@@ -47,6 +47,10 @@ export declare class WsClient extends Emittery {
      * @param request - The authentication request, containing an app authentication token.
      */
     authenticate(request: AppAuthenticationRequest): Promise<void>;
+    /**
+     * Close the websocket connection.
+     */
+    close(code?: number): Promise<IsoWebSocket.CloseEvent>;
     /**
      * Send requests to the connected websocket.
      *
@@ -56,10 +60,9 @@ export declare class WsClient extends Emittery {
     request<Response>(request: unknown): Promise<Response>;
     private exchange;
     private sendMessage;
+    private registerMessageListener;
+    private registerCloseListener;
+    private reconnectWebsocket;
     private handleResponse;
-    /**
-     * Close the websocket connection.
-     */
-    close(code?: number): Promise<CloseEvent>;
 }
 export { IsoWebSocket };

package/lib/api/client.js

@@ -17,74 +17,16 @@ export class WsClient extends Emittery {
     options;
     pendingRequests;
     index;
+    authenticationToken;
     constructor(socket, url, options) {
         super();
+        this.registerMessageListener(socket);
+        this.registerCloseListener(socket);
         this.socket = socket;
         this.url = url;
         this.options = options || {};
         this.pendingRequests = {};
         this.index = 0;
-        this.setupSocket();
-    }
-    setupSocket() {
-        this.socket.onmessage = async (serializedMessage) => {
-            // If data is not a buffer (nodejs), it will be a blob (browser)
-            let deserializedData;
-            if (globalThis.window &&
-                serializedMessage.data instanceof globalThis.window.Blob) {
-                deserializedData = await serializedMessage.data.arrayBuffer();
-            }
-            else {
-                if (typeof Buffer !== "undefined" &&
-                    Buffer.isBuffer(serializedMessage.data)) {
-                    deserializedData = serializedMessage.data;
-                }
-                else {
-                    throw new HolochainError("UnknownMessageFormat", `incoming message has unknown message format - ${deserializedData}`);
-                }
-            }
-            const message = decode(deserializedData);
-            assertHolochainMessage(message);
-            if (message.type === "signal") {
-                if (message.data === null) {
-                    throw new HolochainError("UnknownSignalFormat", "incoming signal has no data");
-                }
-                const deserializedSignal = decode(message.data);
-                assertHolochainSignal(deserializedSignal);
-                if (SignalType.System in deserializedSignal) {
-                    this.emit("signal", {
-                        System: deserializedSignal[SignalType.System],
-                    });
-                }
-                else {
-                    const encodedAppSignal = deserializedSignal[SignalType.App];
-                    // In order to return readable content to the UI, the signal payload must also be deserialized.
-                    const payload = decode(encodedAppSignal.signal);
-                    const signal = {
-                        cell_id: encodedAppSignal.cell_id,
-                        zome_name: encodedAppSignal.zome_name,
-                        payload,
-                    };
-                    this.emit("signal", { App: signal });
-                }
-            }
-            else if (message.type === "response") {
-                this.handleResponse(message);
-            }
-            else {
-                throw new HolochainError("UnknownMessageType", `incoming message has unknown type - ${message.type}`);
-            }
-        };
-        this.socket.onclose = (event) => {
-            const pendingRequestIds = Object.keys(this.pendingRequests).map((id) => parseInt(id));
-            if (pendingRequestIds.length) {
-                pendingRequestIds.forEach((id) => {
-                    const error = new HolochainError("ClientClosedWithPendingRequests", `client closed with pending requests - close event code: ${event.code}, request id: ${id}`);
-                    this.pendingRequests[id].reject(error);
-                    delete this.pendingRequests[id];
-                });
-            }
-        };
     }
     /**
      * Instance factory for creating WsClients.
@@ -96,13 +38,13 @@ export class WsClient extends Emittery {
     static connect(url, options) {
         return new Promise((resolve, reject) => {
             const socket = new IsoWebSocket(url, options);
-            socket.onerror = (errorEvent) => {
+            socket.addEventListener("error", (errorEvent) => {
                 reject(new HolochainError("ConnectionError", `could not connect to Holochain Conductor API at ${url} - ${errorEvent.error}`));
-            };
-            socket.onopen = () => {
+            });
+            socket.addEventListener("open", (_) => {
                 const client = new WsClient(socket, url, options);
                 resolve(client);
-            };
+            }, { once: true });
         });
     }
     /**
@@ -125,16 +67,35 @@ export class WsClient extends Emittery {
      * @param request - The authentication request, containing an app authentication token.
      */
     async authenticate(request) {
-        return this.exchange(request, (request, resolve) => {
+        this.authenticationToken = request.token;
+        return this.exchange(request, (request, resolve, reject) => {
+            const invalidTokenCloseListener = (closeEvent) => {
+                this.authenticationToken = undefined;
+                reject(new HolochainError("InvalidTokenError", `could not connect to ${this.url} due to an invalid app authentication token - close code ${closeEvent.code}`));
+            };
+            this.socket.addEventListener("close", invalidTokenCloseListener, {
+                once: true,
+            });
             const encodedMsg = encode({
                 type: "authenticate",
                 data: encode(request),
             });
             this.socket.send(encodedMsg);
-            // Message just needs to be sent first, no need to wait for a response or even require a flush
-            resolve(null);
+            // Wait before resolving in case authentication fails.
+            setTimeout(() => {
+                this.socket.removeEventListener("close", invalidTokenCloseListener);
+                resolve(null);
+            }, 10);
         });
     }
+    /**
+     * Close the websocket connection.
+     */
+    close(code = 1000) {
+        const closedPromise = new Promise((resolve) => this.socket.addEventListener("close", (closeEvent) => resolve(closeEvent), { once: true }));
+        this.socket.close(code);
+        return closedPromise;
+    }
     /**
      * Send requests to the connected websocket.
      *
@@ -144,15 +105,22 @@ export class WsClient extends Emittery {
     async request(request) {
         return this.exchange(request, this.sendMessage.bind(this));
     }
-    exchange(request, sendHandler) {
+    async exchange(request, sendHandler) {
         if (this.socket.readyState === this.socket.OPEN) {
             const promise = new Promise((resolve, reject) => {
                 sendHandler(request, resolve, reject);
             });
             return promise;
         }
+        else if (this.url && this.authenticationToken) {
+            await this.reconnectWebsocket(this.url, this.authenticationToken);
+            this.registerMessageListener(this.socket);
+            this.registerCloseListener(this.socket);
+            const promise = new Promise((resolve, reject) => sendHandler(request, resolve, reject));
+            return promise;
+        }
         else {
-            return Promise.reject(new Error("Socket is not open"));
+            return Promise.reject(new HolochainError("WebsocketClosedError", "Websocket is not open"));
         }
     }
     sendMessage(request, resolve, reject) {
@@ -166,6 +134,97 @@ export class WsClient extends Emittery {
         this.pendingRequests[id] = { resolve, reject };
         this.index += 1;
     }
+    registerMessageListener(socket) {
+        socket.onmessage = async (serializedMessage) => {
+            // If data is not a buffer (nodejs), it will be a blob (browser)
+            let deserializedData;
+            if (globalThis.window &&
+                serializedMessage.data instanceof globalThis.window.Blob) {
+                deserializedData = await serializedMessage.data.arrayBuffer();
+            }
+            else {
+                if (typeof Buffer !== "undefined" &&
+                    Buffer.isBuffer(serializedMessage.data)) {
+                    deserializedData = serializedMessage.data;
+                }
+                else {
+                    throw new HolochainError("UnknownMessageFormat", `incoming message has unknown message format - ${deserializedData}`);
+                }
+            }
+            const message = decode(deserializedData);
+            assertHolochainMessage(message);
+            if (message.type === "signal") {
+                if (message.data === null) {
+                    throw new HolochainError("UnknownSignalFormat", "incoming signal has no data");
+                }
+                const deserializedSignal = decode(message.data);
+                assertHolochainSignal(deserializedSignal);
+                if (SignalType.System in deserializedSignal) {
+                    this.emit("signal", {
+                        System: deserializedSignal[SignalType.System],
+                    });
+                }
+                else {
+                    const encodedAppSignal = deserializedSignal[SignalType.App];
+                    // In order to return readable content to the UI, the signal payload must also be deserialized.
+                    const payload = decode(encodedAppSignal.signal);
+                    const signal = {
+                        cell_id: encodedAppSignal.cell_id,
+                        zome_name: encodedAppSignal.zome_name,
+                        payload,
+                    };
+                    this.emit("signal", { App: signal });
+                }
+            }
+            else if (message.type === "response") {
+                this.handleResponse(message);
+            }
+            else {
+                throw new HolochainError("UnknownMessageType", `incoming message has unknown type - ${message.type}`);
+            }
+        };
+    }
+    registerCloseListener(socket) {
+        socket.addEventListener("close", (closeEvent) => {
+            const pendingRequestIds = Object.keys(this.pendingRequests).map((id) => parseInt(id));
+            if (pendingRequestIds.length) {
+                pendingRequestIds.forEach((id) => {
+                    const error = new HolochainError("ClientClosedWithPendingRequests", `client closed with pending requests - close event code: ${closeEvent.code}, request id: ${id}`);
+                    this.pendingRequests[id].reject(error);
+                    delete this.pendingRequests[id];
+                });
+            }
+        }, { once: true });
+    }
+    async reconnectWebsocket(url, token) {
+        return new Promise((resolve, reject) => {
+            this.socket = new IsoWebSocket(url, this.options);
+            // This error event never occurs in tests. Could be removed?
+            this.socket.addEventListener("error", (errorEvent) => {
+                this.authenticationToken = undefined;
+                reject(new HolochainError("ConnectionError", `could not connect to Holochain Conductor API at ${url} - ${errorEvent.message}`));
+            }, { once: true });
+            const invalidTokenCloseListener = (closeEvent) => {
+                this.authenticationToken = undefined;
+                reject(new HolochainError("InvalidTokenError", `could not connect to ${this.url} due to an invalid app authentication token - close code ${closeEvent.code}`));
+            };
+            this.socket.addEventListener("close", invalidTokenCloseListener, {
+                once: true,
+            });
+            this.socket.addEventListener("open", async (_) => {
+                const encodedMsg = encode({
+                    type: "authenticate",
+                    data: encode({ token }),
+                });
+                this.socket.send(encodedMsg);
+                // Wait in case authentication fails.
+                setTimeout(() => {
+                    this.socket.removeEventListener("close", invalidTokenCloseListener);
+                    resolve();
+                }, 10);
+            }, { once: true });
+        });
+    }
     handleResponse(msg) {
         const id = msg.id;
         if (this.pendingRequests[id]) {
@@ -181,20 +240,6 @@ export class WsClient extends Emittery {
             console.error(`got response with no matching request. id = ${id} msg = ${msg}`);
         }
     }
-    /**
-     * Close the websocket connection.
-     */
-    close(code = 1000) {
-        const closedPromise = new Promise((resolve) => 
-        // for an unknown reason "addEventListener" is seen as a non-callable
-        // property and gives a ts2349 error
-        // type assertion as workaround
-        this.socket.addEventListener("close", (event) => resolve(event))
-        // }
-        );
-        this.socket.close(code);
-        return closedPromise;
-    }
 }
 function assertHolochainMessage(message) {
     if (typeof message === "object" &&

package/lib/api/common.js

@@ -52,6 +52,7 @@ export const promiseTimeout = (promise, tag, ms) => {
         return res(a);
     })
         .catch((e) => {
+        clearTimeout(id);
         return rej(e);
     }));
 };

package/lib/hdk/action.d.ts

@@ -1,6 +1,13 @@
 import { AgentPubKey, DnaHash, EntryHash, ActionHash, HoloHashed, Signature, Timestamp } from "../types.js";
 import { Entry, EntryType } from "./entry.js";
 import { LinkTag, LinkType, RateWeight } from "./link.js";
+/**
+ * @public
+ */
+export interface SignedAction {
+    data: Action;
+    signature: Signature;
+}
 /**
  * @public
  */

package/lib/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.47.9"
+      "packageVersion": "7.47.11"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holochain/client",
-  "version": "0.19.0-dev.0",
+  "version": "0.19.0-dev.2",
   "description": "A JavaScript client for the Holochain Conductor API",
   "author": "Holochain Foundation <info@holochain.org> (https://holochain.org)",
   "license": "CAL-1.0",
@@ -72,4 +72,4 @@
     "tsx": "^4.7.2",
     "typescript": "^4.9.5"
   }
-}
+}