Cell Client

Temporary wrapper around @holochain/client and @holo-host/web-sdk.

This is useful to build agnostic UIs, that can potentially connect both with Holo and with Holochain infrastructure transparently.

Note that this will only be useful until there is a unified API for both cases.

Installing

npm i @holochain-open-dev/cell-client

Setup

Connecting to Holochain

import { HolochainClient } from "@holochain-open-dev/cell-client";
import { RoleName, AppWebsocket } from "@holochain/client";

async function setupClient() {
  const appWebsocket = await AppWebsocket.connect(
    "ws://localhost:8888"
  );

  const client = new HolochainClient(appWebsocket);

  return client;
}

Connecting to Chaperone (Holo)

Follow the main instructions for the @holo-host/web-sdk here. Then, create a HoloClient:

import { HoloClient } from "@holochain-open-dev/cell-client";
import WebSdk from '@holo-host/web-sdk'

async function setupClient() {
  const client = await WebSdk.connect({
    chaperoneUrl: 'http://localhost:24274' // Connect to holo-dev-server
    authFormCustomization: {
      logoUrl: "my-logo.png",
      appName: "My App",
      requireRegistrationCode: false
    }
  });

  // We just started up, so we're still connecting. Let's wait for isAvailable == true
  const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
  while (!client.agent.isAvailable) {
    await sleep(50)
    // In a real UI, we would register an event handler for `client.on('agent-state')`
    // and store the agent state in a reactive UI state so that our components can just branch on isAvailable.
  }

  // WebSdk defaults to an anonymous connection where you can't write to the source chain. Sign in so we can commit something
  await client.signIn()
  
  // The credentials overlay is now visible to the user. Wait for them to sign in
  while (client.agent.isAnonymous || !client.agent.isAvailable) {
    await sleep(50)
    // Again, this while/sleep pattern is for demo only. See comment above about doing this using an event handler
  }

  const appInfo = await client.appInfo();

  return new HoloClient(client, appInfo);
}

Usage

There are two layers that you can use:

HolochainClient / HoloClient (both implement the AgnosticClient interface)

Use this layer if you need to be switching which cell you are making the call to. This is specially needed in apps that use the pattern of cloning cells.

const client: HolochainClient = await setupClient();

const appInfo = await client.appWebsocket.appInfo({
  installed_app_id: 'test-app'
});

// Find the cell you want to make the call to
const cellId = appInfo.cell_data[0].cell_id;

const response = await client.callZome(cellId, "my-zome", "my_fn_name", {
  this: "is a sample payload",
});

const { unsubscribe } = client.addSignalHandler((signal) =>
  console.log("Received signal from any of the cells", signal)
);

...

// You can unsubscribe from listening to the signal whenever needed
unsubscribe();

Here, use AgnosticClient instead of HolochainClient or HoloClient if you want your calls to be Holo/Holochain agnostic.

CellClient

Use this layer if you only have one cell, or predefined set of cells.

const client: HolochainClient = await setupClient();

const appInfo = await client.appWebsocket.appInfo({
  installed_app_id: 'test-app'
});

// Find the cell you want to make the call to
const cell = appInfo.cell_data[0];

const cellClient = new CellClient(client, cell);

// Now the calls and signals will only interact with the desired cell
const response = await cellClient.callZome("my-zome", "my_fn_name", {
  this: "is a sample payload",
});

const { unsubscribe } = client.addSignalHandler((signal) =>
  console.log(`Received signal for cell`, cell, signal)
);

...

// You can unsubscribe from listening to the signal whenever needed
unsubscribe();