@parity/truapi 0.1.0 → 0.3.1

package/dist/playground/services-types.d.ts

@@ -1,10 +1,19 @@
 export interface MethodInfo {
     name: string;
     type: "unary" | "subscription";
+    /** TS-shaped signature for the method (e.g. `getAccount(request: HostAccountGetRequest): Promise<…>`). */
+    signature?: string;
+    /** Cargo-doc URL fragment for this method (relative to the rustdoc root for the truapi crate). */
+    docUrl?: string;
     description?: string;
     requestDescription?: string;
-    defaultRequest?: string;
-    noParams?: boolean;
+    exampleSource?: string;
+    /** DataType id (kebab-case) of the method's request payload, when applicable. */
+    requestType?: string;
+    /** DataType id of the method's response. */
+    responseType?: string;
+    /** DataType id of the method's error. */
+    errorType?: string;
 }
 export interface ServiceInfo {
     name: string;

package/dist/scale.d.ts

@@ -7,7 +7,14 @@
 import { type Codec } from "scale-ts";
 export type { Codec };
 export type { ResultPayload } from "scale-ts";
-export { Enum, Option, Result, Struct, Tuple, Vector, _void, bool, i8, i16, i32, i64, i128, str, u8, u16, u32, u64, u128, } from "scale-ts";
+export { Enum, Option, Result, Struct, Tuple, Vector, _void, bool, compact, i8, i16, i32, i64, i128, str, u8, u16, u32, u64, u128, } from "scale-ts";
+/**
+ * Substrate `OptionBool`: a one-byte `Option<bool>`.
+ *
+ * Canonical SCALE encoding (matches `parity_scale_codec::OptionBool`):
+ * `undefined` → `0`, `true` → `1`, `false` → `2`.
+ */
+export declare const OptionBool: Codec<boolean | undefined>;
 /** Hex-encoded byte string, e.g. `"0xdeadbeef"`. */
 export type HexString = `0x${string}`;
 /** Assert that a string is a valid hex string (`0x...`). */

package/dist/scale.js

@@ -5,7 +5,25 @@
  * lazy recursive codecs, and `V<N>`-indexed tagged unions).
  */
 import { Bytes, Enum, createCodec, createDecoder, enhanceCodec, u8, } from "scale-ts";
-export { Enum, Option, Result, Struct, Tuple, Vector, _void, bool, i8, i16, i32, i64, i128, str, u8, u16, u32, u64, u128, } from "scale-ts";
+export { Enum, Option, Result, Struct, Tuple, Vector, _void, bool, compact, i8, i16, i32, i64, i128, str, u8, u16, u32, u64, u128, } from "scale-ts";
+/**
+ * Substrate `OptionBool`: a one-byte `Option<bool>`.
+ *
+ * Canonical SCALE encoding (matches `parity_scale_codec::OptionBool`):
+ * `undefined` → `0`, `true` → `1`, `false` → `2`.
+ */
+export const OptionBool = enhanceCodec(u8, (value) => (value === undefined ? 0 : value ? 1 : 2), (byte) => {
+    switch (byte) {
+        case 0:
+            return undefined;
+        case 1:
+            return true;
+        case 2:
+            return false;
+        default:
+            throw new Error(`Unknown OptionBool byte: ${byte}. Expected 0, 1, or 2.`);
+    }
+});
 /** Assert that a string is a valid hex string (`0x...`). */
 export function toHexString(value) {
     if (!value.startsWith("0x")) {

package/dist/transport.d.ts

@@ -1,4 +1,5 @@
-import { type Result } from "neverthrow";
+import { type Result, type ResultAsync } from "neverthrow";
+import { type ResultPayload } from "./scale.js";
 /**
  * Handle returned by TrUAPI subscription APIs.
  **/
@@ -60,14 +61,26 @@ export interface Observer<Item, Reason = never> {
      **/
     complete(): void;
 }
+declare global {
+    interface SymbolConstructor {
+        readonly observable: unique symbol;
+    }
+}
 /**
  * Minimal Observable-compatible object returned by generated subscription APIs.
+ *
+ * Implements the ES Observable interop protocol so that consumers can pass
+ * an instance straight to `rxjs.from(...)`.
  **/
 export interface ObservableLike<Item, Reason = never> {
     /**
      * Start the stream and receive `next`, `error`, and `complete` callbacks.
      **/
     subscribe(observer?: Partial<Observer<Item, Reason>>): Subscription;
+    /**
+     * Observable interop hook. Returns `this`.
+     **/
+    [Symbol.observable](): ObservableLike<Item, Reason>;
 }
 /**
  * Numeric frame ids for a one-shot request method.
@@ -106,7 +119,7 @@ export interface SubscriptionFrameIds {
 /**
  * Options accepted by `TrUApiTransport.request`.
  **/
-export interface RequestParams<Response> {
+export interface RequestParams<Ok, Err> {
     /**
      * Wire discriminants for this request method.
      **/
@@ -116,9 +129,10 @@ export interface RequestParams<Response> {
      **/
     payload: Uint8Array;
     /**
-     * Decode SCALE response payload bytes into the generated client return type.
+     * Decode SCALE response payload bytes into the wire `ResultPayload`
+     * envelope. The transport unwraps the envelope into `ResultAsync<Ok, Err>`.
      **/
-    decodeResponse: (payload: Uint8Array) => Response;
+    decodeResponse: (payload: Uint8Array) => ResultPayload<Ok, Err>;
 }
 /**
  * Options accepted by `TrUApiTransport.subscribeRaw`.
@@ -158,9 +172,9 @@ export interface TrUApiTransport {
      **/
     readonly codecVersion: number;
     /**
-     * Send a one-shot request and resolve with the decoded response payload.
+     * Send a one-shot request and resolve with the typed Ok/Err outcome.
      **/
-    request<Response>(params: RequestParams<Response>): Promise<Response>;
+    request<Ok, Err>(params: RequestParams<Ok, Err>): ResultAsync<Ok, Err>;
     /**
      * Start a subscription and return a handle that can stop it.
      **/
@@ -231,6 +245,19 @@ export declare function encodeWireMessage(message: ProtocolMessage): Result<Uint
  * Decode a SCALE wire frame into a `ProtocolMessage`.
  **/
 export declare function decodeWireMessage(message: Uint8Array): Result<ProtocolMessage, Error>;
+/**
+ * Create a provider for the child side of an iframe `postMessage` channel.
+ *
+ * `target` is the `Window` the provider posts to (typically `window.parent`);
+ * `hostOrigin` is the pinned `targetOrigin` for outbound frames and the
+ * required `event.origin` of inbound frames. The provider only delivers
+ * frames whose `event.source === target` and `event.origin === hostOrigin`,
+ * so it cannot be coerced by an unrelated frame parent.
+ **/
+export declare function createIframeProvider(options: {
+    target: Window;
+    hostOrigin: string;
+}): Provider;
 /**
  * Create a provider from a web or Electron `MessagePort`.
  **/

package/dist/transport.js

@@ -1,5 +1,11 @@
 import { err, ok } from "neverthrow";
 import { str, u8 } from "./scale.js";
+/**
+ * Coerce an unknown thrown value into an `Error` instance.
+ */
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
 /**
  * Terminal error delivered through `Observer.error` for every non-normal
  * subscription end. When the peer interrupted the stream with a typed payload,
@@ -118,32 +124,137 @@ function scanStrEnd(bytes) {
     }
     return ok(total);
 }
+/**
+ * Internal listener bookkeeping and close-once state machine shared by the
+ * built-in `Provider` implementations. Transport-specific code wires its
+ * inbound source to `deliver`, registers cleanup via `onClose`, and exposes
+ * `subscribe`/`subscribeClose` to callers.
+ **/
+function createBaseProvider() {
+    const listeners = new Set();
+    const closeListeners = new Set();
+    const onCloseCleanup = new Set();
+    let closedError = null;
+    return {
+        /** Current close error, or `null` while the provider is open. */
+        closed: () => closedError,
+        /** Dispatch an inbound frame to every active subscriber. */
+        deliver(message) {
+            if (closedError)
+                return;
+            for (const listener of [...listeners])
+                listener(message);
+        },
+        /** Transition to the closed state. Idempotent. */
+        close(error) {
+            if (closedError)
+                return;
+            closedError = toError(error);
+            for (const fn of [...onCloseCleanup]) {
+                try {
+                    fn();
+                }
+                catch {
+                    // ignore cleanup failure
+                }
+            }
+            onCloseCleanup.clear();
+            for (const listener of [...closeListeners])
+                listener(closedError);
+            listeners.clear();
+            closeListeners.clear();
+        },
+        /** Register a cleanup function to run exactly once when `close` fires. */
+        onClose(fn) {
+            if (closedError) {
+                try {
+                    fn();
+                }
+                catch {
+                    // ignore cleanup failure
+                }
+                return;
+            }
+            onCloseCleanup.add(fn);
+        },
+        /** Register an inbound message listener. No-op after close. */
+        subscribe(callback) {
+            if (closedError)
+                return () => { };
+            listeners.add(callback);
+            return () => {
+                listeners.delete(callback);
+            };
+        },
+        /**
+         * Register a close listener. If the provider is already closed, the
+         * callback fires immediately with the stored error.
+         **/
+        subscribeClose(callback) {
+            if (closedError) {
+                callback(closedError);
+                return () => { };
+            }
+            closeListeners.add(callback);
+            return () => {
+                closeListeners.delete(callback);
+            };
+        },
+    };
+}
+/**
+ * Create a provider for the child side of an iframe `postMessage` channel.
+ *
+ * `target` is the `Window` the provider posts to (typically `window.parent`);
+ * `hostOrigin` is the pinned `targetOrigin` for outbound frames and the
+ * required `event.origin` of inbound frames. The provider only delivers
+ * frames whose `event.source === target` and `event.origin === hostOrigin`,
+ * so it cannot be coerced by an unrelated frame parent.
+ **/
+export function createIframeProvider(options) {
+    const base = createBaseProvider();
+    const { target, hostOrigin } = options;
+    const onMessage = (event) => {
+        if (event.source !== target)
+            return;
+        if (event.origin !== hostOrigin)
+            return;
+        if (!(event.data instanceof Uint8Array))
+            return;
+        base.deliver(event.data);
+    };
+    window.addEventListener("message", onMessage);
+    base.onClose(() => window.removeEventListener("message", onMessage));
+    return {
+        postMessage(message) {
+            const error = base.closed();
+            if (error)
+                throw error;
+            try {
+                target.postMessage(message, hostOrigin);
+            }
+            catch (error) {
+                base.close(error);
+                throw toError(error);
+            }
+        },
+        subscribe: base.subscribe,
+        subscribeClose: base.subscribeClose,
+        dispose() {
+            base.close(new Error("iframe provider disposed"));
+        },
+    };
+}
 /**
  * Create a provider from a web or Electron `MessagePort`.
  **/
 export function createMessagePortProvider(port) {
+    const base = createBaseProvider();
     let resolvedPort = null;
-    let closedError = null;
     const pending = [];
-    const listeners = [];
-    const closeListeners = [];
-    /**
-     * Notify close listeners once and drop queued outbound messages.
-     **/
-    function notifyClose(error) {
-        const nextError = error instanceof Error ? error : new Error(String(error));
-        if (closedError) {
-            return;
-        }
-        closedError = nextError;
-        pending.length = 0;
-        for (const listener of [...closeListeners]) {
-            listener(nextError);
-        }
-    }
     void Promise.resolve(port)
         .then((p) => {
-        if (closedError) {
+        if (base.closed()) {
             try {
                 p.close();
             }
@@ -154,85 +265,53 @@ export function createMessagePortProvider(port) {
         }
         resolvedPort = p;
         p.onmessage = (event) => {
-            const data = event.data;
-            if (!(data instanceof Uint8Array))
-                return;
-            for (const listener of [...listeners])
-                listener(data);
+            if (event.data instanceof Uint8Array)
+                base.deliver(event.data);
         };
         if ("onmessageerror" in p) {
             p.onmessageerror = () => {
-                notifyClose(new Error("message port closed unexpectedly"));
+                base.close(new Error("message port closed unexpectedly"));
             };
         }
         p.start();
         for (const msg of pending)
             p.postMessage(msg);
         pending.length = 0;
+        base.onClose(() => {
+            try {
+                p.close();
+            }
+            catch {
+                // ignore duplicate close during shutdown
+            }
+        });
     })
         .catch((error) => {
-        notifyClose(error);
+        base.close(error);
     });
     return {
-        /**
-         * Send bytes through the resolved port or queue them until it resolves.
-         **/
         postMessage(message) {
-            if (closedError) {
-                throw closedError;
-            }
+            const error = base.closed();
+            if (error)
+                throw error;
             if (resolvedPort) {
                 try {
                     resolvedPort.postMessage(message);
                 }
                 catch (error) {
-                    notifyClose(error);
-                    throw error instanceof Error ? error : new Error(String(error));
+                    base.close(error);
+                    throw toError(error);
                 }
             }
             else {
                 pending.push(message);
             }
         },
-        /**
-         * Register an inbound message listener.
-         **/
-        subscribe(callback) {
-            listeners.push(callback);
-            return () => {
-                const idx = listeners.indexOf(callback);
-                if (idx >= 0)
-                    listeners.splice(idx, 1);
-            };
-        },
-        /**
-         * Register a close listener.
-         **/
-        subscribeClose(callback) {
-            if (closedError) {
-                callback(closedError);
-                return () => { };
-            }
-            closeListeners.push(callback);
-            return () => {
-                const idx = closeListeners.indexOf(callback);
-                if (idx >= 0)
-                    closeListeners.splice(idx, 1);
-            };
-        },
-        /**
-         * Dispose the provider and close the port if it has resolved.
-         **/
+        subscribe: base.subscribe,
+        subscribeClose: base.subscribeClose,
         dispose() {
-            notifyClose(new Error("message port provider disposed"));
-            try {
-                resolvedPort?.close();
-            }
-            catch {
-                // ignore duplicate close during shutdown
-            }
-            listeners.length = 0;
-            closeListeners.length = 0;
+            base.close(new Error("message port provider disposed"));
+            pending.length = 0;
         },
     };
 }

package/dist/well-known-chains.d.ts

@@ -0,0 +1,13 @@
+/** Well-known chain descriptors. Each chain is its own `export const` so that
+ * bundlers can tree-shake the ones a consumer does not import. */
+import type { HexString } from "./scale.js";
+export interface WellKnownChain {
+    readonly name: string;
+    readonly network: "Mainnet" | "Testnet";
+    readonly genesis: HexString;
+}
+export declare const PASEO_NEXT_V2_ASSET_HUB: {
+    readonly name: "Paseo Next v2 Hub";
+    readonly network: "Testnet";
+    readonly genesis: "0xbf0488dbe9daa1de1c08c5f743e26fdc2a4ecd74cf87dd1b4b1eeb99ae4ef19f";
+};

package/dist/well-known-chains.js

@@ -0,0 +1,7 @@
+/** Well-known chain descriptors. Each chain is its own `export const` so that
+ * bundlers can tree-shake the ones a consumer does not import. */
+export const PASEO_NEXT_V2_ASSET_HUB = {
+    name: "Paseo Next v2 Hub",
+    network: "Testnet",
+    genesis: "0xbf0488dbe9daa1de1c08c5f743e26fdc2a4ecd74cf87dd1b4b1eeb99ae4ef19f",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/truapi",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "TrUAPI TypeScript transport, SCALE codecs, and generated API client",
   "license": "MIT",
   "author": "Parity Technologies <admin@parity.io>",
@@ -19,6 +19,7 @@
     "LICENSE"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -26,6 +27,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./scale": {
+      "types": "./dist/scale.d.ts",
+      "import": "./dist/scale.js"
+    },
+    "./wire-table": {
+      "types": "./dist/generated/wire-table.d.ts",
+      "import": "./dist/generated/wire-table.js"
+    },
     "./playground/services": {
       "types": "./dist/playground/codegen/services.d.ts",
       "import": "./dist/playground/codegen/services.js"
@@ -33,17 +42,30 @@
     "./playground/services-types": {
       "types": "./dist/playground/services-types.d.ts",
       "import": "./dist/playground/services-types.js"
+    },
+    "./playground/codegen/truapi-dts": {
+      "types": "./dist/playground/codegen/truapi-dts.d.ts",
+      "import": "./dist/playground/codegen/truapi-dts.js"
+    },
+    "./explorer/data-types": {
+      "types": "./dist/explorer/data-types.d.ts",
+      "import": "./dist/explorer/data-types.js"
+    },
+    "./explorer/types": {
+      "types": "./dist/explorer/codegen/types.d.ts",
+      "import": "./dist/explorer/codegen/types.js"
+    },
+    "./explorer/versions": {
+      "types": "./dist/explorer/versions.d.ts",
+      "import": "./dist/explorer/versions.js"
     }
   },
   "scripts": {
     "ensure-generated": "./scripts/ensure-generated.sh",
     "build": "tsc",
     "prebuild": "npm run ensure-generated",
-    "prepare": "npm run build",
-    "codegen": "cargo run -p truapi-codegen -- --input ../../../target/doc/truapi.json --output src/generated --playground-output src/playground --client-examples-output test/generated/examples",
-    "typecheck": "npm run build && npm run typecheck:examples",
-    "pretypecheck:examples": "npm run ensure-generated",
-    "typecheck:examples": "tsc -p tsconfig.examples.json",
+    "codegen": "cargo run -p truapi-codegen -- --input ../../../target/doc/truapi.json --output src/generated --playground-output src/playground --explorer-output src/explorer",
+    "typecheck": "npm run build",
     "pretest": "npm run ensure-generated",
     "test": "for f in test/*.test.mjs; do echo \"=== $f ===\" && bun \"$f\" || exit 1; done"
   },