@macula-io/ts 0.17.0 → 0.18.0

package/dist/wire.d.ts

@@ -0,0 +1,53 @@
+/** A payload, restricted to what macula's wire CBOR carries: no boolean and
+ * no undefined. Encode true/false as 1/0 yourself; a JS boolean reaching the
+ * wire is exactly the mistake this type makes impossible at compile time.
+ *
+ * Bytes have no native JSON shape. Going IN, write them as an object whose
+ * ONLY key is "$bytes", holding standard padded base64: `{"$bytes": "AQID"}`
+ * is the three bytes 01 02 03. A plain string is always text. Coming OUT,
+ * bytes are a "0x"-prefixed lowercase hex string by default, or the same
+ * tagged object when you ask for `bytes: "tagged"` (see BytesOutput). */
+export type JsonValue = string | number | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** How bytes in a result, a request, an event or a record reach JavaScript:
+ * "hex" (the default) or "tagged" ({"$bytes": "<base64>"}). */
+export type BytesOutput = "hex" | "tagged";
+/** BytesOutput as the integer the native layer takes. */
+export declare function bytesModeFor(bytes: BytesOutput | undefined): number;
+/** A 32-byte id (a node_id, a realm id, a record key): 64 hex characters or
+ * 32 bytes. */
+export type Id = string | Uint8Array;
+/** An Id as the 32 bytes the native layer takes. */
+export declare function id32(id: Id, what?: string): Uint8Array;
+/** 32 bytes as lowercase hex. */
+export declare function hex(bytes: Uint8Array): string;
+/** A provider's own ERROR for a call: `handler_error` with the handler's
+ * text, `temporary_relay_failure` for a handler that crashed,
+ * `unknown_next_peer` for a procedure it does not serve, or an admission
+ * refusal (`expired`, `request_copy`, `caller_quota`, ...). */
+export declare class ProviderError extends Error {
+    readonly code: string;
+    readonly detail: string;
+    constructor(code: string, detail: string);
+}
+/** A station's signed relay error for a call: it could not relay it, e.g.
+ * `unknown_next_peer` for a provider it cannot reach. */
+export declare class RelayError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/** A stream ended by a STREAM_ERROR: the peer's, a relay error from the
+ * station (`relay`), or this side's own (e.g. `resource_exhausted`). */
+export declare class StreamError extends Error {
+    readonly code: string;
+    readonly detail: string;
+    readonly relay: boolean;
+    constructor(code: string, detail: string, relay: boolean);
+}
+/** The error the native layer rejects a call with, as the class it names:
+ * "provider_error:<code>:<detail>" and "relay_error:<code>" (cabi's
+ * callError), any other text as a plain Error. */
+export declare function callError(e: unknown): Error;
+/** How long a call waits, in milliseconds, when not told: macula's 5 s. */
+export declare const DEFAULT_CALL_TIMEOUT_MS = 5000;

package/dist/wire.js

@@ -0,0 +1,79 @@
+// The shapes every part of the API shares: payload values, ids, and the
+// errors a call or a stream ends with.
+/** BytesOutput as the integer the native layer takes. */
+export function bytesModeFor(bytes) {
+    if (bytes === undefined || bytes === "hex")
+        return 0;
+    if (bytes === "tagged")
+        return 1;
+    throw new Error(`macula-ts: bytes must be "hex" or "tagged", got ${JSON.stringify(bytes)}`);
+}
+/** An Id as the 32 bytes the native layer takes. */
+export function id32(id, what = "id") {
+    if (typeof id === "string") {
+        if (!/^[0-9a-fA-F]{64}$/.test(id))
+            throw new Error(`macula-ts: ${what} must be 64 hex characters`);
+        return Uint8Array.from(Buffer.from(id, "hex"));
+    }
+    if (id.length !== 32)
+        throw new Error(`macula-ts: ${what} must be 32 bytes, got ${id.length}`);
+    return id;
+}
+/** 32 bytes as lowercase hex. */
+export function hex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+/** A provider's own ERROR for a call: `handler_error` with the handler's
+ * text, `temporary_relay_failure` for a handler that crashed,
+ * `unknown_next_peer` for a procedure it does not serve, or an admission
+ * refusal (`expired`, `request_copy`, `caller_quota`, ...). */
+export class ProviderError extends Error {
+    code;
+    detail;
+    constructor(code, detail) {
+        super(`macula-ts: the provider answered ${code}${detail ? `: ${detail}` : ""}`);
+        this.code = code;
+        this.detail = detail;
+        this.name = "ProviderError";
+    }
+}
+/** A station's signed relay error for a call: it could not relay it, e.g.
+ * `unknown_next_peer` for a provider it cannot reach. */
+export class RelayError extends Error {
+    code;
+    constructor(code) {
+        super(`macula-ts: the station could not relay the call: ${code}`);
+        this.code = code;
+        this.name = "RelayError";
+    }
+}
+/** A stream ended by a STREAM_ERROR: the peer's, a relay error from the
+ * station (`relay`), or this side's own (e.g. `resource_exhausted`). */
+export class StreamError extends Error {
+    code;
+    detail;
+    relay;
+    constructor(code, detail, relay) {
+        super(`macula-ts: stream error ${code}${detail ? `: ${detail}` : ""}`);
+        this.code = code;
+        this.detail = detail;
+        this.relay = relay;
+        this.name = "StreamError";
+    }
+}
+/** The error the native layer rejects a call with, as the class it names:
+ * "provider_error:<code>:<detail>" and "relay_error:<code>" (cabi's
+ * callError), any other text as a plain Error. */
+export function callError(e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const provider = /^provider_error:([^:]*):([\s\S]*)$/.exec(message);
+    if (provider)
+        return new ProviderError(provider[1] ?? "", provider[2] ?? "");
+    const relay = /^relay_error:(.*)$/.exec(message);
+    if (relay)
+        return new RelayError(relay[1] ?? "");
+    return e instanceof Error ? e : new Error(message);
+}
+/** How long a call waits, in milliseconds, when not told: macula's 5 s. */
+export const DEFAULT_CALL_TIMEOUT_MS = 5_000;
+//# sourceMappingURL=wire.js.map

package/dist/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macula-io/ts",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "TypeScript SDK for the Macula mesh (FFI over macula-go)",
   "license": "Apache-2.0",
   "keywords": [
@@ -45,9 +45,10 @@
     "build:addon:dev": "npm run build:go && node-gyp rebuild",
     "build:prebuilds": "npm run build:go && prebuildify --napi --strip && npm pkg delete scripts.install",
     "build": "npm run build:addon:dev && tsc",
-    "test": "vitest run",
-    "test:live": "MACULA_TS_LIVE=1 vitest run src/session.live.test.ts src/rpc.live.test.ts src/dht.live.test.ts src/pubsub.live.test.ts src/content.live.test.ts src/ucan.live.test.ts src/directdial.live.test.ts src/pool.live.test.ts",
-    "typecheck": "tsc --noEmit"
+    "test": "npm run build:teststation && vitest run",
+    "test:live": "MACULA_TS_LIVE=1 vitest run src/fleet.live.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build:teststation": "cd cabi && go build -trimpath -buildvcs=false -o ../build/teststation ./cmd/teststation"
   },
   "dependencies": {
     "node-addon-api": "^8.9.2",