Skip to content

holochain/holochain-client-js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

30287e9 · Feb 21, 2025
Feb 19, 2025
Feb 19, 2025
Feb 19, 2025
Feb 19, 2025
Nov 29, 2023
Jun 6, 2022
Oct 28, 2024
Feb 20, 2025
Jul 5, 2022
Nov 21, 2024
Oct 10, 2024
Dec 6, 2023
Oct 28, 2024
Jan 19, 2023
Nov 16, 2023
May 13, 2024
Nov 28, 2024
May 13, 2024
Nov 28, 2024
Feb 19, 2025
Oct 18, 2024
Feb 21, 2025
Feb 20, 2025
Jan 19, 2023
Nov 29, 2023

Repository files navigation

Project Discord License: CAL 1.0 Integration Tests Bundling Tests Twitter Follow

Holochain Client - JavaScript

A JavaScript client for the Holochain Conductor API (works with browsers as well as Nodejs).

API Reference

Complete API reference

Installation

JS client v0.19.x is compatible with Holochain v0.5.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.

To install from NPM, run

npm install --save-exact @holochain/client

This code is under beta development and you may wish to lock to an exact version of the library for that reason, as shown in the above command.

Sample usage

Use AppWebsocket with implicit zome call signing

import {
  AdminWebsocket,
  AppWebsocket,
  CellType,
  type ActionHash,
  type CallZomeRequest,
} from "@holochain/client";

const adminWs = await AdminWebsocket.connect({
  url: new URL("ws://127.0.0.1:65000"),
  wsClientOptions: { origin: "my-happ" },
});
const agent_key = await adminWs.generateAgentPubKey();
const role_name = "foo";
const installed_app_id = "test-app";
const appInfo = await adminWs.installApp({
  agent_key,
  path: "./test/e2e/fixture/test.happ",
  installed_app_id,
  membrane_proofs: {},
});
await adminWs.enableApp({ installed_app_id });
if (!(CellType.Provisioned in appInfo.cell_info[role_name][0])) {
  throw new Error(`No cell found under role name ${role_name}`);
}
const { cell_id } = appInfo.cell_info[role_name][0][CellType.Provisioned];
await adminWs.authorizeSigningCredentials(cell_id);
await adminWs.attachAppInterface({ port: 65001, allowed_origins: "my-happ" });
const issuedToken = await adminWs.issueAppAuthenticationToken({
  installed_app_id,
});
const appWs = await AppWebsocket.connect({
  url: new URL("ws://127.0.0.1:65001"),
  token: issuedToken.token,
  wsClientOptions: { origin: "my-happ" },
});

const zomeCallPayload: CallZomeRequest = {
  cell_id,
  zome_name: "foo",
  fn_name: "foo",
  provenance: agent_key,
  payload: null,
};

const response: ActionHash = await appWs.callZome(zomeCallPayload, 30000);
console.log("zome call response is", response);

await appWs.client.close();
await adminWs.client.close();

Subscribe to signals

import { AdminWebsocket, AppWebsocket, CellType } from "@holochain/client";

const adminWs = await AdminWebsocket.connect({
  url: new URL("ws://127.0.0.1:65000"),
  wsClientOptions: { origin: "my-happ" },
});
const agent_key = await adminWs.generateAgentPubKey();
const role_name = "foo";
const installed_app_id = "test-app";
const appInfo = await adminWs.installApp({
  agent_key,
  path: "./test/e2e/fixture/test.happ",
  installed_app_id,
  membrane_proofs: {},
});
await adminWs.enableApp({ installed_app_id });
if (!(CellType.Provisioned in appInfo.cell_info[role_name][0])) {
  throw new Error(`No cell found under role name ${role_name}`);
}
const { cell_id } = appInfo.cell_info[role_name][0][CellType.Provisioned];
await adminWs.authorizeSigningCredentials(cell_id);
await adminWs.attachAppInterface({ port: 65001, allowed_origins: "my-happ" });
const issuedToken = await adminWs.issueAppAuthenticationToken({
  installed_app_id,
});
const appWs = await AppWebsocket.connect({
  url: new URL("ws://127.0.0.1:65001"),
  token: issuedToken.token,
  wsClientOptions: { origin: "my-happ" },
});

let signalCb;
const signalReceived = new Promise<void>((resolve) => {
  signalCb = (signal) => {
    console.log("signal received", signal);
    // act on signal
    resolve();
  };
});

appWs.on("signal", signalCb);

// trigger an emit_signal
await appWs.callZome({
  cell_id,
  zome_name: "foo",
  fn_name: "emitter",
  provenance: agent_key,
  payload: null,
});
await signalReceived;

await appWs.client.close();
await adminWs.client.close();

Managing zome call signing credentials in a pure JavaScript browser application

Here is a pattern to manage signing keys for signing zome calls when running pure JavaScript web hApps in a web browser:

const cellIdB64 =
    encodeHashToBase64(cell_id[0]) + encodeHashToBase64(cell_id[1]);
// in case the zome call signing credentials are stored locally in the browser
const signingCredentialsJson = localStorage.getItem(cellIdB64);
let signingCredentials: SigningCredentials | null =
  signingCredentialsJson && JSON.parse(signingCredentialsJson);

if (!signingCredentials) {
  const [keyPair, signingKey] = generateSigningKeyPair();
  const capSecret = await admin.grantSigningKey(
    cell_id,
    { [GrantedFunctionsType.All]: null },
    signingKey
  );
  signingCredentials = {
    capSecret,
    keyPair,
    signingKey,
  };
}
setSigningCredentials(cell_id, signingCredentials);
// possibly store the zome call signing credentials locally in the browser
localStorage.setItem(cellIdB64, JSON.stringify(signingCredentials));

Running tests

You need a version (stable toolchain) of Rust available.

You need holochain and hc on your path, best to get them from nix with nix-shell.

To perform the pre-requisite DNA compilation steps, and run the Nodejs test, run:

nix develop
./build-fixture.sh
npm run test

Contribute

Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our contribution guidelines for our general practices and protocols on participating in the community, as well as specific expectations around things like code formatting, testing practices, continuous integration, etc.

License

License: CAL 1.0

Copyright (C) 2020-2024, Holochain Foundation

This program is free software: you can redistribute it and/or modify it under the terms of the license provided in the LICENSE file (CAL-1.0). This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.