@parity/truapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parity Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @parity/truapi
+
+_Typed TypeScript client for products that talk to a TrUAPI host._
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](../../../LICENSE)
+[![Types](https://img.shields.io/badge/types-included-3178C6?style=flat-square&logo=typescript)](./package.json)
+
+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
+
+```bash
+npm install @parity/truapi
+```
+
+## Quick start
+
+```ts
+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:
+
+```ts
+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.
+
+## Wire format
+
+Frames are SCALE encoded:
+
+```text
+[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`](../../../rust/crates/truapi-codegen/) from the Rust crate and are ignored by git. Do not edit generated files directly. Run from the repo root:
+
+```bash
+./scripts/codegen.sh
+```
+
+## Develop
+
+```bash
+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 smoke tests under [bun](https://bun.sh/), so bun must also be installed (`curl -fsSL https://bun.sh/install | bash`). The tests load the source `.ts` files directly without a build step.
+
+## License
+
+[MIT](../../../LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import { type Provider, type Subscription, type TrUApiTransport } from "./transport.js";
+export type { Subscription, TrUApiTransport };
+/**
+ * Version overrides used when constructing a transport.
+ */
+export interface CreateTransportOptions {
+    /**
+     * Highest TrUAPI protocol version exposed by the transport.
+     */
+    truapiVersion?: number;
+    /**
+     * SCALE codec version advertised during host handshake negotiation.
+     */
+    codecVersion?: number;
+}
+/**
+ * Build a `TrUApiTransport` on top of a `Provider`, adding request/response
+ * correlation and subscription start/receive/stop lifecycle handling.
+ */
+export declare function createTransport(provider: Provider, options?: CreateTransportOptions): TrUApiTransport;

package/dist/client.js

@@ -0,0 +1,320 @@
+import { decodeWireMessage, encodeWireMessage, } from "./transport.js";
+import { indexedTaggedUnion, Result, _void, } from "./scale.js";
+import { TRUAPI_CODEC_VERSION, TRUAPI_VERSION } from "./generated/client.js";
+import * as T from "./generated/types.js";
+import * as W from "./generated/wire-table.js";
+/**
+ * Convert a positive protocol version number into the generated version tag
+ * used by TrUAPI wire wrappers.
+ */
+function protocolVersionTag(version) {
+    if (!Number.isInteger(version) || version < 1) {
+        throw new Error(`Invalid TrUAPI protocol version: ${version}`);
+    }
+    return `V${version}`;
+}
+const HANDSHAKE_WIRE_VERSION = 1;
+/**
+ * Build the versioned handshake response codec for the selected wire version.
+ */
+function handshakeResponseCodec(version) {
+    return indexedTaggedUnion({
+        [protocolVersionTag(version)]: [
+            version - 1,
+            Result(_void, T.HostHandshakeError),
+        ],
+    });
+}
+/**
+ * Encode a successful host-handshake response payload.
+ */
+function encodeSuccessfulHandshakeResponse(version) {
+    return encodeHandshakeResponse(version, {
+        tag: protocolVersionTag(version),
+        value: {
+            success: true,
+            value: undefined,
+        },
+    });
+}
+/**
+ * Encode a host-handshake response that reports an unsupported codec version.
+ */
+function encodeUnsupportedHandshakeResponse(version) {
+    return encodeHandshakeResponse(version, {
+        tag: protocolVersionTag(version),
+        value: {
+            success: false,
+            value: {
+                tag: "UnsupportedProtocolVersion",
+                value: undefined,
+            },
+        },
+    });
+}
+/**
+ * Encode a typed handshake response with the versioned response codec.
+ */
+function encodeHandshakeResponse(version, response) {
+    return handshakeResponseCodec(version).enc(response);
+}
+/**
+ * Check whether a decoded SCALE value has the generated `{ tag, value }`
+ * wrapper shape used for versioned wire payloads.
+ */
+function isVersionedWireValue(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "tag" in value &&
+        "value" in value &&
+        typeof value.tag === "string" &&
+        /^V\d+$/.test(value.tag));
+}
+/**
+ * Return the inner payload from a versioned wire wrapper, or the original
+ * value when the payload is already unwrapped.
+ */
+function unwrapVersionedWireValue(value) {
+    return isVersionedWireValue(value) ? value.value : value;
+}
+/**
+ * Build a `TrUApiTransport` on top of a `Provider`, adding request/response
+ * correlation and subscription start/receive/stop lifecycle handling.
+ */
+export function createTransport(provider, options = {}) {
+    const truapiVersion = options.truapiVersion ?? TRUAPI_VERSION;
+    const codecVersion = options.codecVersion ?? TRUAPI_CODEC_VERSION;
+    let idCounter = 0;
+    let closedError = null;
+    const pending = new Map();
+    const subscriptions = new Map();
+    /**
+     * Normalize arbitrary thrown values into `Error` instances.
+     */
+    function toError(error) {
+        return error instanceof Error ? error : new Error(String(error));
+    }
+    /**
+     * Close the transport once, rejecting pending requests and notifying live
+     * subscriptions.
+     */
+    function closeWithError(error) {
+        const nextError = toError(error);
+        if (closedError) {
+            return;
+        }
+        closedError = nextError;
+        for (const [requestId, entry] of pending) {
+            pending.delete(requestId);
+            entry.reject(nextError);
+        }
+        for (const [requestId, subscription] of subscriptions) {
+            subscriptions.delete(requestId);
+            subscription.onClose?.(nextError);
+        }
+    }
+    const unsubscribeClose = provider.subscribeClose?.((error) => {
+        closeWithError(error);
+    });
+    const unsubscribeMessage = provider.subscribe((message) => {
+        if (closedError) {
+            return;
+        }
+        const decoded = decodeWireMessage(message);
+        if (decoded.isErr()) {
+            closeWithError(decoded.error);
+            return;
+        }
+        const { requestId, payload } = decoded.value;
+        if (payload.id === W.SYSTEM_HANDSHAKE.request) {
+            // Auto-respond to inbound `host_handshake_request` frames.
+            //
+            // Legacy hosts shipping `@novasamatech/host-api@0.6.x` (e.g. dotli)
+            // initiate their own handshake from the host side at startup and ping
+            // the iframe with `host_handshake_request` every 50ms until they see a
+            // matching response. The legacy host-api `createTransport` registered
+            // an internal handler for this message; preserving that behaviour
+            // keeps `@parity/truapi` a drop-in replacement for legacy bridges.
+            //
+            // Respond with the handshake method's selected wire version. The inner
+            // request carries the wire codec version.
+            let response;
+            try {
+                const request = unwrapVersionedWireValue(T.VersionedHostHandshakeRequest.dec(payload.value));
+                const requestedCodecVersion = request.codecVersion;
+                response =
+                    requestedCodecVersion === codecVersion
+                        ? encodeSuccessfulHandshakeResponse(HANDSHAKE_WIRE_VERSION)
+                        : encodeUnsupportedHandshakeResponse(HANDSHAKE_WIRE_VERSION);
+            }
+            catch (error) {
+                closeWithError(toError(error));
+                return;
+            }
+            try {
+                send({
+                    requestId,
+                    payload: {
+                        id: W.SYSTEM_HANDSHAKE.response,
+                        value: response,
+                    },
+                });
+            }
+            catch {
+                // provider already closed
+            }
+            return;
+        }
+        const p = pending.get(requestId);
+        if (p) {
+            if (payload.id !== p.ids.response) {
+                return;
+            }
+            pending.delete(requestId);
+            try {
+                p.resolve(payload.value);
+            }
+            catch (error) {
+                p.reject(toError(error));
+            }
+            return;
+        }
+        const subscription = subscriptions.get(requestId);
+        if (subscription) {
+            if (payload.id === subscription.ids.receive) {
+                try {
+                    subscription.onReceive(payload.value);
+                }
+                catch (error) {
+                    // A consumer-side decode/handler error must not tear down the
+                    // provider's message loop and silently break every other
+                    // subscription on the same transport. Surface via onClose and
+                    // drop this subscription; siblings stay alive.
+                    subscriptions.delete(requestId);
+                    subscription.onClose?.(toError(error));
+                }
+            }
+            else if (payload.id === subscription.ids.interrupt) {
+                subscriptions.delete(requestId);
+                subscription.onInterrupt?.(payload.value);
+            }
+        }
+    });
+    /**
+     * Encode and post a protocol message through the underlying provider.
+     */
+    function send(message) {
+        if (closedError) {
+            throw closedError;
+        }
+        const encoded = encodeWireMessage(message);
+        if (encoded.isErr()) {
+            closeWithError(encoded.error);
+            throw encoded.error;
+        }
+        try {
+            provider.postMessage(encoded.value);
+        }
+        catch (error) {
+            closeWithError(error);
+            throw toError(error);
+        }
+    }
+    return {
+        truapiVersion,
+        codecVersion,
+        /**
+         * Send one request frame and resolve with the decoded response payload.
+         */
+        request({ ids, payload, decodeResponse, }) {
+            return new Promise((resolve, reject) => {
+                if (closedError) {
+                    reject(closedError);
+                    return;
+                }
+                const requestId = `p:${++idCounter}`;
+                pending.set(requestId, {
+                    ids,
+                    resolve: (response) => resolve(decodeResponse(response)),
+                    reject,
+                });
+                try {
+                    send({
+                        requestId,
+                        payload: {
+                            id: ids.request,
+                            value: payload,
+                        },
+                    });
+                }
+                catch (error) {
+                    pending.delete(requestId);
+                    reject(toError(error));
+                }
+            });
+        },
+        /**
+         * Start a raw subscription and route incoming receive/interrupt frames to
+         * the supplied callbacks.
+         */
+        subscribeRaw({ ids, payload, onReceive, onInterrupt, onClose, }) {
+            if (closedError) {
+                onClose?.(closedError);
+                return { unsubscribe: () => { }, subscriptionId: "" };
+            }
+            const requestId = `p:${++idCounter}`;
+            subscriptions.set(requestId, {
+                ids,
+                onReceive,
+                onInterrupt,
+                onClose,
+            });
+            try {
+                send({
+                    requestId,
+                    payload: {
+                        id: ids.start,
+                        value: payload,
+                    },
+                });
+            }
+            catch (error) {
+                subscriptions.delete(requestId);
+                onClose?.(toError(error));
+                return { unsubscribe: () => { }, subscriptionId: requestId };
+            }
+            return {
+                subscriptionId: requestId,
+                unsubscribe: () => {
+                    // Skip the `_stop` frame when the host already terminated the stream
+                    // via `_interrupt` (which removes the entry from `subscriptions`).
+                    if (!subscriptions.has(requestId))
+                        return;
+                    subscriptions.delete(requestId);
+                    try {
+                        send({
+                            requestId,
+                            payload: {
+                                id: ids.stop,
+                                value: _void.enc(undefined),
+                            },
+                        });
+                    }
+                    catch {
+                        // provider already closed
+                    }
+                },
+            };
+        },
+        /**
+         * Close this transport and detach its provider listeners.
+         */
+        dispose() {
+            // Idempotent: closeWithError is a no-op once closedError is set, and
+            // unsubscribe handles tolerate being called twice.
+            closeWithError(new Error("transport disposed"));
+            unsubscribeMessage();
+            unsubscribeClose?.();
+        },
+    };
+}