@parity/truapi

Typed TypeScript client for products that talk to a TrUAPI host.

This package gives a product running inside a Polkadot host (Desktop Browser, Triangle webview) a fully typed client for every TrUAPI method. The transport, SCALE codecs, generated types, and generated domain clients are all bundled together.

Install

npm install @parity/truapi

Quick start

import {
  createClient,
  createMessagePortProvider,
  createTransport,
  type Client,
  type HostAccountGetResponse,
} from "@parity/truapi";

const provider = createMessagePortProvider(port);
const transport = createTransport(provider);
const truapi: Client = createClient(transport);

const result = await truapi.accountManagement.accountGet({
  productAccountId: { dotNsIdentifier: "my-product.dot", derivationIndex: 0 },
});

if (result.isErr()) throw result.error;
const account: HostAccountGetResponse = result.value;

Request methods take the inner request value directly. The transport adds the wire-level version wrapper and unwraps versioned responses before the generated method returns.

Subscriptions

Streaming methods return a small Observable-compatible object:

import type { Subscription, RemoteChainHeadFollowItem } from "@parity/truapi";

const sub: Subscription = truapi.chainInteraction
  .chainHeadFollow({ request: { genesisHash, withRuntime: false } })
  .subscribe({
    next(event: RemoteChainHeadFollowItem) {
      console.log(event);
    },
    error(error: Error) {
      console.error(error);
    },
    complete() {
      console.log("stream ended");
    },
  });

sub.unsubscribe();

What's in the package

• Transport providers for MessagePort pipes (used by both webview hosts and iframe hosts).
• TrUAPI transport that handles request, response, subscription, and handshake framing.
• Generated domain clients and types produced from the Rust API contract.
• SCALE codec helpers used by the generated code, also re-exported for direct use.
• Sandbox bootstrap (@parity/truapi/sandbox) that detects the host environment, builds the matching provider, and exposes a cached client — see below.

Sandbox bootstrap

@parity/truapi/sandbox wires up a client for browser-embedded hosts: it detects whether the app runs inside a TrUAPI host (iframe or webview), builds the matching provider, and caches the resulting client. Use it instead of assembling createTransport / createClient by hand.

import {
  getClientSync,
  isCorrectEnvironment,
  subscribeConnectionStatus,
} from "@parity/truapi/sandbox";

const client = getClientSync(); // null outside a host container
if (client) {
  // …make host calls
}

// Or drive UI off connection status:
const unsubscribe = subscribeConnectionStatus((status) => {
  // "disconnected" | "connected"
});

| Export | Purpose | | ------------------------------------------- | ----------------------------------------------- | | isCorrectEnvironment(): boolean | Synchronous host-environment detection. | | getClientSync(): TrUApiClient \| null | Cached client; null outside a host container. | | subscribeConnectionStatus(cb): () => void | Connected / disconnected status listener. |

Wire format

Frames are SCALE encoded:

[requestId: SCALE str][discriminant: u8][payload bytes...]

The discriminant table is generated from Rust #[wire(request_id = N)] and #[wire(start_id = N)] annotations and is written to src/generated/wire-table.ts.

Generated files

src/generated/, src/playground/codegen/, and test/generated/examples/ are produced by truapi-codegen from the Rust crate and are ignored by git. Do not edit generated files directly. Run from the repo root:

./scripts/codegen.sh

Develop

npm install
npm run build
npm test

On a clean checkout, the first build or test run will generate the ignored TypeScript outputs from the Rust sources, so Rust stable + nightly must be installed locally. npm test runs the package's bun test suite (src/**/*.test.ts) directly against the source .ts files (no build step), so bun must also be installed.

License

MIT