@useragent-kit/sdk 0.0.0 → 0.0.1

package/dist/guest/navigate.js

@@ -0,0 +1,169 @@
+import { binaryBridgeUnavailableError, hostRejectedError, invalidArgumentError, timeoutError, } from "../errors.js";
+/**
+ * Navigate the host to a `dot://` URL via the SCALE binary bridge.
+ *
+ * This uses `window.__HOST_API_PORT__` directly — the same binary bridge that
+ * the host-api WASM module uses — with a minimal SCALE encoder for the
+ * NavigateTo request (tag 6, per `host-api/src/protocol.rs`).
+ *
+ * @example
+ * ```ts
+ * import { navigateTo } from "@polkadot-apps/product-sdk";
+ *
+ * await navigateTo("dot://settings");
+ * await navigateTo("dot://chat.dot/room/general");
+ * ```
+ */
+/** Timeout for host response before cleaning up the listener (ms). */
+const NAVIGATE_TIMEOUT_MS = 10000;
+/** Tag constants from host-api/src/protocol.rs lines 25-26. */
+const TAG_NAVIGATE_TO_REQ = 6;
+const TAG_NAVIGATE_TO_RESP = 7;
+/** Wrapping request ID counter. Stays within safe compact encoding range. */
+let nextRequestId = 1;
+const MAX_REQUEST_ID = 2 ** 30;
+// ── SCALE compact codec ───────────────────────────────────────────────
+// Mirrors host-api/src/codec.rs encode_compact_u32 / decode_compact_u32.
+/** @internal Decode a SCALE compact integer, returning value and bytes consumed. */
+export function decodeCompact(bytes, offset) {
+    if (offset >= bytes.length) {
+        throw new RangeError("decodeCompact: unexpected end of input");
+    }
+    const first = bytes[offset];
+    const mode = first & 0x03;
+    if (mode === 0) {
+        return { value: first >>> 2, bytesRead: 1 };
+    }
+    else if (mode === 1) {
+        if (offset + 1 >= bytes.length) {
+            throw new RangeError("decodeCompact: unexpected end of input (mode 1)");
+        }
+        const value = (((bytes[offset + 1] << 8) | first) >>> 2) & 0x3fff;
+        return { value, bytesRead: 2 };
+    }
+    else {
+        if (offset + 3 >= bytes.length) {
+            throw new RangeError("decodeCompact: unexpected end of input (mode 2)");
+        }
+        const v32 = ((bytes[offset + 3] << 24) | (bytes[offset + 2] << 16) | (bytes[offset + 1] << 8) | first) >>>
+            0;
+        const value = v32 >>> 2;
+        return { value, bytesRead: 4 };
+    }
+}
+/** @internal Encode a u32 in SCALE compact form. */
+export function encodeCompact(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RangeError(`encodeCompact: invalid value ${value}`);
+    }
+    if (value < 64) {
+        return new Uint8Array([value << 2]);
+    }
+    else if (value < 16384) {
+        const v = (value << 2) | 1;
+        return new Uint8Array([v & 0xff, (v >> 8) & 0xff]);
+    }
+    else if (value < 0x40000000) {
+        const v = (value << 2) | 2;
+        return new Uint8Array([v & 0xff, (v >> 8) & 0xff, (v >> 16) & 0xff, (v >> 24) & 0xff]);
+    }
+    else {
+        throw new RangeError(`encodeCompact: value ${value} exceeds 30-bit compact range`);
+    }
+}
+/** @internal Encode a SCALE string (compact length + UTF-8 bytes). */
+export function encodeString(s) {
+    const utf8 = new TextEncoder().encode(s);
+    const len = encodeCompact(utf8.length);
+    const out = new Uint8Array(len.length + utf8.length);
+    out.set(len);
+    out.set(utf8, len.length);
+    return out;
+}
+// ── navigateTo ────────────────────────────────────────────────────────
+/**
+ * Navigate the host to a URL.
+ *
+ * Resolves when the host acknowledges the navigation. Rejects if the port is
+ * unavailable, the host returns an error, or the request times out.
+ */
+export function navigateTo(url) {
+    return new Promise((resolve, reject) => {
+        if (!url) {
+            reject(invalidArgumentError("navigateTo: url must not be empty"));
+            return;
+        }
+        const port = window.__HOST_API_PORT__;
+        if (!port) {
+            reject(binaryBridgeUnavailableError());
+            return;
+        }
+        // Wrapping request ID.
+        if (nextRequestId >= MAX_REQUEST_ID)
+            nextRequestId = 1;
+        const requestId = `nav-${nextRequestId++}`;
+        const reqIdBytes = encodeString(requestId);
+        const urlBytes = encodeString(url);
+        // Wire format: [requestId: SCALE String][tag: u8 = 6][version: u8 = 0][url: SCALE String]
+        const msg = new Uint8Array(reqIdBytes.length + 1 + 1 + urlBytes.length);
+        let offset = 0;
+        msg.set(reqIdBytes, offset);
+        offset += reqIdBytes.length;
+        msg[offset++] = TAG_NAVIGATE_TO_REQ;
+        msg[offset++] = 0; // version tag
+        msg.set(urlBytes, offset);
+        function cleanup() {
+            port.removeEventListener("message", handler);
+            clearTimeout(timer);
+        }
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(timeoutError("navigateTo timed out"));
+        }, NAVIGATE_TIMEOUT_MS);
+        const handler = (event) => {
+            const data = event.data;
+            if (!(data instanceof ArrayBuffer))
+                return;
+            const bytes = new Uint8Array(data);
+            // Decode response requestId to match.
+            let pos = 0;
+            try {
+                const { value: respIdLen, bytesRead } = decodeCompact(bytes, pos);
+                pos += bytesRead;
+                if (pos + respIdLen > bytes.length)
+                    return;
+                const respId = new TextDecoder().decode(bytes.slice(pos, pos + respIdLen));
+                pos += respIdLen;
+                if (respId !== requestId)
+                    return;
+                if (pos >= bytes.length)
+                    return;
+                const tag = bytes[pos++];
+                if (tag !== TAG_NAVIGATE_TO_RESP)
+                    return;
+                // Need version byte + result byte.
+                if (pos + 2 > bytes.length) {
+                    cleanup();
+                    reject(hostRejectedError("navigateTo: truncated response"));
+                    return;
+                }
+                pos++; // version byte
+                const result = bytes[pos];
+                cleanup();
+                if (result === 0) {
+                    resolve();
+                }
+                else {
+                    reject(hostRejectedError("navigateTo rejected by host"));
+                }
+            }
+            catch {
+                // Decode error on a non-matching message — skip it.
+            }
+        };
+        port.start();
+        port.addEventListener("message", handler);
+        port.postMessage(msg.buffer);
+    });
+}
+//# sourceMappingURL=navigate.js.map

package/dist/guest/navigate.js.map

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

package/dist/guest/statements.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Typed wrapper for host statement push events.
+ *
+ * @example
+ * ```ts
+ * import { statements } from "@polkadot-apps/product-sdk";
+ *
+ * const unsub = statements.onStatement((payload) => {
+ *   console.log("New statement:", payload);
+ * });
+ * // later: unsub();
+ * ```
+ */
+import type { HostEventMap } from "./types.js";
+type Unsub = () => void;
+export declare function onStatement(cb: (payload: HostEventMap["statement"]) => void): Unsub;
+export {};
+//# sourceMappingURL=statements.d.ts.map

package/dist/guest/statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.d.ts","sourceRoot":"","sources":["../../src/guest/statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,YAAY,CAAC;AAU3D,KAAK,KAAK,GAAG,MAAM,IAAI,CAAC;AAExB,wBAAgB,WAAW,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,GAAG,KAAK,CAInF"}

package/dist/guest/statements.js

@@ -0,0 +1,26 @@
+/**
+ * Typed wrapper for host statement push events.
+ *
+ * @example
+ * ```ts
+ * import { statements } from "@polkadot-apps/product-sdk";
+ *
+ * const unsub = statements.onStatement((payload) => {
+ *   console.log("New statement:", payload);
+ * });
+ * // later: unsub();
+ * ```
+ */
+import { hostRuntimeUnavailableError } from "../errors.js";
+function getHost() {
+    if (!window.host) {
+        throw hostRuntimeUnavailableError("Host runtime");
+    }
+    return window.host;
+}
+export function onStatement(cb) {
+    const host = getHost();
+    host.on("statement", cb);
+    return () => host.off("statement", cb);
+}
+//# sourceMappingURL=statements.js.map

package/dist/guest/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../../src/guest/statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAE3D,SAAS,OAAO;IACd,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,2BAA2B,CAAC,cAAc,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAID,MAAM,UAAU,WAAW,CAAC,EAAgD;IAC1E,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACzB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/guest/telemetry.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Guest-side telemetry — runs inside sandboxed product iframes.
+ *
+ * Reads `window.__HOST_TRACE_CONTEXT__` (injected by the host at mount time)
+ * and posts Segment-shaped analytics events + performance timing events back
+ * to the host via postMessage. The host's analytics router then forwards
+ * events to per-product backend adapters.
+ *
+ * When `sampled` is false (or no trace context is present), all calls are
+ * no-ops — zero overhead for unsampled sessions.
+ *
+ * @example
+ * ```ts
+ * import { track, identify, recordSpan } from "@polkadot-apps/product-sdk/guest/telemetry";
+ *
+ * identify("5F3sa2TJ...");
+ * track("tx_submitted", { chain: "polkadot", amount: 10 });
+ *
+ * const start = performance.now();
+ * await doExpensiveWork();
+ * recordSpan("expensive_work", start, performance.now() - start);
+ * ```
+ */
+/** Shape of window.__HOST_TRACE_CONTEXT__ injected by the host. */
+interface HostTraceContext {
+    readonly traceId: string;
+    readonly parentSpanId: string;
+    readonly sampled: boolean;
+    readonly productId?: string;
+}
+declare global {
+    interface Window {
+        __HOST_TRACE_CONTEXT__?: HostTraceContext;
+    }
+}
+/**
+ * Record a user action (Segment `track` call).
+ *
+ * No-op when the session is not sampled.
+ *
+ * @param event - Action name (e.g. "wallet_connected", "tx_submitted").
+ * @param properties - Arbitrary properties describing the action.
+ */
+export declare function track(event: string, properties?: Record<string, unknown>): void;
+/**
+ * Associate a user identity (Segment `identify` call).
+ *
+ * Products should only pass the user's public wallet address or an
+ * anonymous ID — never PII like email or real name.
+ *
+ * No-op when the session is not sampled.
+ *
+ * @param userId - User identifier (wallet address or anonymous ID).
+ * @param traits - Traits describing the user.
+ */
+export declare function identify(userId: string, traits?: Record<string, unknown>): void;
+/**
+ * Record a page/screen view (Segment `page` call).
+ *
+ * No-op when the session is not sampled.
+ *
+ * @param name - Page or screen name.
+ * @param properties - Additional page properties.
+ */
+export declare function page(name: string, properties?: Record<string, unknown>): void;
+/**
+ * Record a performance timing span (bridges to the host's OTel trace tree).
+ *
+ * Use this to wrap expensive operations so they appear in the host's
+ * distributed traces alongside Rust-side spans.
+ *
+ * No-op when the session is not sampled.
+ *
+ * @param name - Span name (e.g. "product.rpc_call", "product.render").
+ * @param startMs - Start time from `performance.now()`.
+ * @param durationMs - Duration in milliseconds.
+ * @param attributes - Key-value attributes for the span.
+ *
+ * @example
+ * ```ts
+ * const t0 = performance.now();
+ * const result = await api.query();
+ * recordSpan("api_query", t0, performance.now() - t0, { endpoint: "/balance" });
+ * ```
+ */
+export declare function recordSpan(name: string, startMs: number, durationMs: number, attributes?: Record<string, string | number | boolean>): void;
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/guest/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/guest/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,mEAAmE;AACnE,UAAU,gBAAgB;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;KAC3C;CACF;AA0ED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAU/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAU/E;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAU7E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,IAAI,CAeN"}

package/dist/guest/telemetry.js

@@ -0,0 +1,184 @@
+/**
+ * Guest-side telemetry — runs inside sandboxed product iframes.
+ *
+ * Reads `window.__HOST_TRACE_CONTEXT__` (injected by the host at mount time)
+ * and posts Segment-shaped analytics events + performance timing events back
+ * to the host via postMessage. The host's analytics router then forwards
+ * events to per-product backend adapters.
+ *
+ * When `sampled` is false (or no trace context is present), all calls are
+ * no-ops — zero overhead for unsampled sessions.
+ *
+ * @example
+ * ```ts
+ * import { track, identify, recordSpan } from "@polkadot-apps/product-sdk/guest/telemetry";
+ *
+ * identify("5F3sa2TJ...");
+ * track("tx_submitted", { chain: "polkadot", amount: 10 });
+ *
+ * const start = performance.now();
+ * await doExpensiveWork();
+ * recordSpan("expensive_work", start, performance.now() - start);
+ * ```
+ */
+function getTraceContext() {
+    try {
+        const ctx = window.__HOST_TRACE_CONTEXT__;
+        if (ctx &&
+            typeof ctx.traceId === "string" &&
+            typeof ctx.parentSpanId === "string" &&
+            typeof ctx.sampled === "boolean") {
+            return ctx;
+        }
+    }
+    catch {
+        // window may not be available (SSR/test).
+    }
+    return null;
+}
+function isSampled() {
+    return getTraceContext()?.sampled === true;
+}
+// ---------------------------------------------------------------------------
+// Span ID generation
+// ---------------------------------------------------------------------------
+/** Generate a random 16-char hex span ID. */
+function randomSpanId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+// ---------------------------------------------------------------------------
+// postMessage sender
+// ---------------------------------------------------------------------------
+function postAnalytics(event) {
+    try {
+        parent.postMessage({ type: "host-analytics", event }, "*");
+    }
+    catch {
+        // Silently swallow — postMessage may fail if parent is gone.
+    }
+}
+function makeContext() {
+    const ctx = getTraceContext();
+    const base = {
+        app: { productId: getProductId() },
+    };
+    if (ctx) {
+        base["trace"] = { traceId: ctx.traceId, spanId: ctx.parentSpanId };
+    }
+    return base;
+}
+/**
+ * Best-effort product ID extraction.
+ * Reads from the host-injected trace context first; falls back to
+ * document.title, then "unknown".
+ */
+function getProductId() {
+    try {
+        return getTraceContext()?.productId || document.title || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API (Segment-shaped)
+// ---------------------------------------------------------------------------
+/**
+ * Record a user action (Segment `track` call).
+ *
+ * No-op when the session is not sampled.
+ *
+ * @param event - Action name (e.g. "wallet_connected", "tx_submitted").
+ * @param properties - Arbitrary properties describing the action.
+ */
+export function track(event, properties) {
+    if (!isSampled())
+        return;
+    postAnalytics({
+        type: "track",
+        event,
+        properties,
+        timestamp: new Date().toISOString(),
+        context: makeContext(),
+    });
+}
+/**
+ * Associate a user identity (Segment `identify` call).
+ *
+ * Products should only pass the user's public wallet address or an
+ * anonymous ID — never PII like email or real name.
+ *
+ * No-op when the session is not sampled.
+ *
+ * @param userId - User identifier (wallet address or anonymous ID).
+ * @param traits - Traits describing the user.
+ */
+export function identify(userId, traits) {
+    if (!isSampled())
+        return;
+    postAnalytics({
+        type: "identify",
+        userId,
+        traits,
+        timestamp: new Date().toISOString(),
+        context: makeContext(),
+    });
+}
+/**
+ * Record a page/screen view (Segment `page` call).
+ *
+ * No-op when the session is not sampled.
+ *
+ * @param name - Page or screen name.
+ * @param properties - Additional page properties.
+ */
+export function page(name, properties) {
+    if (!isSampled())
+        return;
+    postAnalytics({
+        type: "page",
+        name,
+        properties,
+        timestamp: new Date().toISOString(),
+        context: makeContext(),
+    });
+}
+/**
+ * Record a performance timing span (bridges to the host's OTel trace tree).
+ *
+ * Use this to wrap expensive operations so they appear in the host's
+ * distributed traces alongside Rust-side spans.
+ *
+ * No-op when the session is not sampled.
+ *
+ * @param name - Span name (e.g. "product.rpc_call", "product.render").
+ * @param startMs - Start time from `performance.now()`.
+ * @param durationMs - Duration in milliseconds.
+ * @param attributes - Key-value attributes for the span.
+ *
+ * @example
+ * ```ts
+ * const t0 = performance.now();
+ * const result = await api.query();
+ * recordSpan("api_query", t0, performance.now() - t0, { endpoint: "/balance" });
+ * ```
+ */
+export function recordSpan(name, startMs, durationMs, attributes) {
+    if (!isSampled())
+        return;
+    const ctx = getTraceContext();
+    postAnalytics({
+        type: "timing",
+        name,
+        startMs,
+        durationMs,
+        spanId: randomSpanId(),
+        parentSpanId: ctx?.parentSpanId ?? "0000000000000000",
+        attributes,
+        timestamp: new Date().toISOString(),
+        context: makeContext(),
+    });
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/guest/telemetry.js.map

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