@qubic.ts/sdk 0.1.0

package/src/bob/client.ts

@@ -0,0 +1,393 @@
+import { SdkError } from "../errors.js";
+import type { FetchLike } from "../http.js";
+import { normalizeRetryConfig, type RetryConfig, withRetry } from "../retry.js";
+
+export type BobClientConfig = Readonly<{
+  /** Base URL for QubicBob (default: http://localhost:40420). */
+  baseUrl?: string;
+  fetch?: FetchLike;
+  headers?: Readonly<Record<string, string>>;
+  retry?: RetryConfig;
+  onRequest?: (info: Readonly<{ url: string; method: string; body?: unknown }>) => void;
+  onResponse?: (
+    info: Readonly<{
+      url: string;
+      method: string;
+      status: number;
+      ok: boolean;
+      durationMs: number;
+    }>,
+  ) => void;
+  onError?: (error: BobError) => void;
+}>;
+
+export class BobError extends SdkError {
+  override name = "BobError";
+
+  constructor(
+    code: string,
+    message: string,
+    readonly details: Readonly<{
+      url: string;
+      method: string;
+      status?: number;
+      statusText?: string;
+      bodyText?: string;
+    }>,
+    cause?: unknown,
+  ) {
+    super(code, message, details, cause);
+  }
+}
+
+export type BobQuerySmartContractInput = Readonly<{
+  nonce?: number;
+  scIndex: number;
+  funcNumber: number;
+  dataHex?: string;
+  dataBytes?: Uint8Array;
+}>;
+
+export type BobQuerySmartContractResult = Readonly<{
+  nonce: number;
+  pending: boolean;
+  dataHex?: string;
+  message?: string;
+}>;
+
+export type BobClient = Readonly<{
+  status(): Promise<unknown>;
+  balance(identity: string): Promise<unknown>;
+  asset(input: {
+    identity: string;
+    issuer: string;
+    assetName: string;
+    manageSCIndex: number;
+  }): Promise<unknown>;
+  epochInfo(epoch: number): Promise<unknown>;
+  tx(hash: string): Promise<unknown>;
+  logRange(input: { epoch: number; fromId: number; toId: number }): Promise<unknown>;
+  tick(tickNumber: number): Promise<unknown>;
+  findLog(input: {
+    fromTick: number;
+    toTick: number;
+    scIndex: number;
+    logType: number;
+    topic1: string;
+    topic2: string;
+    topic3: string;
+  }): Promise<unknown>;
+  getLogCustom(input: {
+    epoch: number;
+    tick: number;
+    scIndex: number;
+    logType: number;
+    topic1: string;
+    topic2: string;
+    topic3: string;
+  }): Promise<unknown>;
+  querySmartContract(input: BobQuerySmartContractInput): Promise<BobQuerySmartContractResult>;
+  broadcastTransaction(input: { dataHex?: string; dataBytes?: Uint8Array }): Promise<unknown>;
+  getQuTransfersForIdentity(input: {
+    fromTick: number;
+    toTick: number;
+    identity: string;
+  }): Promise<unknown>;
+  getAssetTransfersForIdentity(input: {
+    fromTick: number;
+    toTick: number;
+    identity: string;
+    assetIssuer: string;
+    assetName: string;
+  }): Promise<unknown>;
+  getAllAssetTransfers(input: {
+    fromTick: number;
+    toTick: number;
+    assetIssuer: string;
+    assetName: string;
+  }): Promise<unknown>;
+}>;
+
+export function createBobClient(config: BobClientConfig = {}): BobClient {
+  const baseUrl = ensureTrailingSlash(config.baseUrl ?? "http://localhost:40420");
+  const base = new URL(baseUrl);
+  const doFetch = config.fetch ?? fetch;
+  const retryConfig = normalizeRetryConfig(config.retry);
+
+  const requestJson = async (method: string, url: URL, body?: unknown): Promise<unknown> => {
+    return withRetry(
+      retryConfig,
+      method,
+      async () => {
+        const start = Date.now();
+        const headers: Record<string, string> = {
+          accept: "application/json",
+          ...config.headers,
+        };
+        let bodyText: string | undefined;
+        if (body !== undefined) {
+          headers["content-type"] = "application/json";
+          bodyText = JSON.stringify(body);
+        }
+
+        try {
+          config.onRequest?.({ url: url.toString(), method, body });
+          const res = await doFetch(url, {
+            method,
+            headers,
+            body: bodyText,
+          });
+          config.onResponse?.({
+            url: url.toString(),
+            method,
+            status: res.status,
+            ok: res.ok,
+            durationMs: Date.now() - start,
+          });
+
+          const text = await res.text();
+          if (!res.ok) {
+            const error = new BobError(
+              "bob_request_failed",
+              `QubicBob request failed: ${res.status} ${res.statusText}`,
+              {
+                url: url.toString(),
+                method,
+                status: res.status,
+                statusText: res.statusText,
+                bodyText: text || undefined,
+              },
+            );
+            config.onError?.(error);
+            throw error;
+          }
+
+          if (text.length === 0) return null;
+          try {
+            return JSON.parse(text) as unknown;
+          } catch {
+            const error = new BobError("bob_invalid_json", "QubicBob response was not valid JSON", {
+              url: url.toString(),
+              method,
+              status: res.status,
+              statusText: res.statusText,
+              bodyText: text || undefined,
+            });
+            config.onError?.(error);
+            throw error;
+          }
+        } catch (error) {
+          if (error instanceof BobError) throw error;
+          const wrapped = new BobError(
+            "bob_fetch_error",
+            "QubicBob fetch failed",
+            {
+              url: url.toString(),
+              method,
+            },
+            error,
+          );
+          config.onError?.(wrapped);
+          throw wrapped;
+        }
+      },
+      (error) => shouldRetryBob(error, retryConfig),
+    );
+  };
+
+  return {
+    async status(): Promise<unknown> {
+      const url = new URL("status", base);
+      return requestJson("GET", url);
+    },
+
+    async balance(identity: string): Promise<unknown> {
+      const url = new URL(`balance/${encodeURIComponent(identity)}`, base);
+      return requestJson("GET", url);
+    },
+
+    async asset(input): Promise<unknown> {
+      const url = new URL(
+        `asset/${encodeURIComponent(input.identity)}/${encodeURIComponent(
+          input.issuer,
+        )}/${encodeURIComponent(input.assetName)}/${input.manageSCIndex}`,
+        base,
+      );
+      return requestJson("GET", url);
+    },
+
+    async epochInfo(epoch: number): Promise<unknown> {
+      const url = new URL(`epochinfo/${epoch}`, base);
+      return requestJson("GET", url);
+    },
+
+    async tx(hash: string): Promise<unknown> {
+      const url = new URL(`tx/${encodeURIComponent(hash)}`, base);
+      return requestJson("GET", url);
+    },
+
+    async logRange(input): Promise<unknown> {
+      const url = new URL(`log/${input.epoch}/${input.fromId}/${input.toId}`, base);
+      return requestJson("GET", url);
+    },
+
+    async tick(tickNumber: number): Promise<unknown> {
+      const url = new URL(`tick/${tickNumber}`, base);
+      return requestJson("GET", url);
+    },
+
+    async findLog(input): Promise<unknown> {
+      const url = new URL("findLog", base);
+      return requestJson("POST", url, input);
+    },
+
+    async getLogCustom(input): Promise<unknown> {
+      const url = new URL("getlogcustom", base);
+      return requestJson("POST", url, input);
+    },
+
+    async querySmartContract(
+      input: BobQuerySmartContractInput,
+    ): Promise<BobQuerySmartContractResult> {
+      const nonce = input.nonce ?? randomUint32();
+      const dataHex = input.dataHex ?? (input.dataBytes ? toHex(input.dataBytes) : "");
+      const url = new URL("querySmartContract", base);
+
+      const headers: Record<string, string> = {
+        accept: "application/json",
+        "content-type": "application/json",
+        ...config.headers,
+      };
+      const bodyText = JSON.stringify({
+        nonce,
+        scIndex: input.scIndex,
+        funcNumber: input.funcNumber,
+        data: dataHex,
+      });
+
+      return withRetry(
+        retryConfig,
+        "POST",
+        async () => {
+          const start = Date.now();
+          config.onRequest?.({ url: url.toString(), method: "POST", body: JSON.parse(bodyText) });
+          const res = await doFetch(url, { method: "POST", headers, body: bodyText });
+          config.onResponse?.({
+            url: url.toString(),
+            method: "POST",
+            status: res.status,
+            ok: res.ok,
+            durationMs: Date.now() - start,
+          });
+          const text = await res.text();
+          let json: unknown = null;
+          if (text.length) {
+            try {
+              json = JSON.parse(text) as unknown;
+            } catch {
+              const error = new BobError(
+                "bob_invalid_json",
+                "QubicBob response was not valid JSON",
+                {
+                  url: url.toString(),
+                  method: "POST",
+                  status: res.status,
+                  statusText: res.statusText,
+                  bodyText: text || undefined,
+                },
+              );
+              config.onError?.(error);
+              throw error;
+            }
+          }
+
+          if (res.status === 202) {
+            const obj = expectObject(json);
+            return {
+              nonce,
+              pending: true,
+              message: typeof obj.message === "string" ? obj.message : "pending",
+            };
+          }
+
+          if (!res.ok) {
+            const error = new BobError(
+              "bob_request_failed",
+              `QubicBob request failed: ${res.status} ${res.statusText}`,
+              {
+                url: url.toString(),
+                method: "POST",
+                status: res.status,
+                statusText: res.statusText,
+                bodyText: text || undefined,
+              },
+            );
+            config.onError?.(error);
+            throw error;
+          }
+
+          const obj = expectObject(json);
+          return {
+            nonce,
+            pending: false,
+            dataHex: typeof obj.data === "string" ? obj.data : undefined,
+          };
+        },
+        (error) => shouldRetryBob(error, retryConfig),
+      );
+    },
+
+    async broadcastTransaction(input): Promise<unknown> {
+      const dataHex = input.dataHex ?? (input.dataBytes ? toHex(input.dataBytes) : "");
+      if (!dataHex) throw new TypeError("broadcastTransaction requires dataHex or dataBytes");
+      const url = new URL("broadcastTransaction", base);
+      return requestJson("POST", url, { data: dataHex });
+    },
+
+    async getQuTransfersForIdentity(input): Promise<unknown> {
+      const url = new URL("getQuTransfersForIdentity", base);
+      return requestJson("POST", url, input);
+    },
+
+    async getAssetTransfersForIdentity(input): Promise<unknown> {
+      const url = new URL("getAssetTransfersForIdentity", base);
+      return requestJson("POST", url, input);
+    },
+
+    async getAllAssetTransfers(input): Promise<unknown> {
+      const url = new URL("getAllAssetTransfers", base);
+      return requestJson("POST", url, input);
+    },
+  };
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function expectObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object") return {};
+  return value as Record<string, unknown>;
+}
+
+function toHex(bytes: Uint8Array): string {
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+
+function randomUint32(): number {
+  if (typeof crypto !== "undefined" && "getRandomValues" in crypto) {
+    const buf = new Uint32Array(1);
+    crypto.getRandomValues(buf);
+    return buf[0] ?? 0;
+  }
+  return Math.floor(Math.random() * 0xffff_ffff);
+}
+
+function shouldRetryBob(error: unknown, config: ReturnType<typeof normalizeRetryConfig>): boolean {
+  if (!(error instanceof BobError)) return false;
+  if (error.code === "bob_fetch_error") return true;
+  const status = error.details.status;
+  return typeof status === "number" && config.retryOnStatuses.includes(status);
+}

package/src/bob/log-stream.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "bun:test";
+import type { WebSocketLike } from "./log-stream.js";
+import { createLogStream } from "./log-stream.js";
+
+class FakeWebSocket implements WebSocketLike {
+  static instances: FakeWebSocket[] = [];
+  readonly readyState = 0;
+  onopen: ((event: Record<string, unknown>) => void) | null = null;
+  onmessage: ((event: { data: string }) => void) | null = null;
+  onerror: ((event: Record<string, unknown>) => void) | null = null;
+  onclose: ((event: { code?: number; reason?: string }) => void) | null = null;
+  sent: string[] = [];
+
+  constructor(readonly url: string) {
+    FakeWebSocket.instances.push(this);
+  }
+
+  send(data: string) {
+    this.sent.push(data);
+  }
+
+  close() {
+    this.onclose?.({});
+  }
+
+  open() {
+    this.onopen?.({});
+  }
+}
+
+describe("log stream", () => {
+  it("sends batch subscribe on open", async () => {
+    const stream = createLogStream({
+      baseUrl: "http://example.test",
+      subscriptions: [
+        { scIndex: 1, logType: 100001 },
+        { scIndex: 2, logType: 100002 },
+      ],
+      webSocketFactory: (url) => new FakeWebSocket(url),
+    });
+
+    const socket = FakeWebSocket.instances[0];
+    expect(socket).toBeDefined();
+    if (!socket) throw new Error("Missing test WebSocket instance");
+    socket.open();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    const sent = socket.sent.map((s) => JSON.parse(s));
+    expect(sent.length).toBe(1);
+    expect(sent[0]?.action).toBe("subscribe");
+    expect(Array.isArray(sent[0]?.subscriptions)).toBe(true);
+    expect(sent[0]?.subscriptions?.length).toBe(2);
+    expect(stream.socket).toBe(socket);
+  });
+});

package/src/bob/log-stream.ts

@@ -0,0 +1,241 @@
+export type LogSubscription = Readonly<{
+  scIndex: number;
+  logType: number;
+  lastTick?: number;
+  lastLogId?: number;
+}>;
+
+export type LogCursor = Readonly<{ lastTick?: number; lastLogId?: number }>;
+
+export type LogCursorStore = Readonly<{
+  get(key: string): LogCursor | Promise<LogCursor | undefined> | undefined;
+  set(key: string, cursor: LogCursor): void | Promise<void>;
+}>;
+
+export type LogStreamHandlers = Readonly<{
+  onOpen?: () => void;
+  onClose?: (event: CloseEventLike) => void;
+  onError?: (event: EventLike) => void;
+  onWelcome?: (message: Record<string, unknown>) => void;
+  onAck?: (message: Record<string, unknown>) => void;
+  onLog?: (message: Record<string, unknown>) => void;
+  onCatchUpComplete?: (message: Record<string, unknown>) => void;
+  onPong?: (message: Record<string, unknown>) => void;
+  onServerError?: (message: Record<string, unknown>) => void;
+}>;
+
+export type LogStreamConfig = LogStreamHandlers &
+  Readonly<{
+    baseUrl: string;
+    subscriptions?: readonly LogSubscription[];
+    lastTick?: number;
+    lastLogId?: number;
+    cursorStore?: LogCursorStore;
+    webSocketFactory?: (url: string) => WebSocketLike;
+    signal?: AbortSignal;
+  }>;
+
+export type LogStream = Readonly<{
+  socket: WebSocketLike;
+  subscribe(sub: LogSubscription): void;
+  subscribeMany(subs: readonly LogSubscription[], cursor?: LogCursor): void;
+  unsubscribe(sub: LogSubscription): void;
+  unsubscribeAll(): void;
+  ping(): void;
+  close(code?: number, reason?: string): void;
+}>;
+
+export function createLogStream(config: LogStreamConfig): LogStream {
+  const wsUrl = toWebSocketUrl(config.baseUrl);
+  const createSocket = config.webSocketFactory ?? defaultWebSocketFactory;
+  const socket = createSocket(wsUrl);
+
+  const pending: string[] = [];
+  let open = false;
+
+  const sendMessage = (message: Record<string, unknown>) => {
+    const text = JSON.stringify(message);
+    if (!open) {
+      pending.push(text);
+      return;
+    }
+    socket.send(text);
+  };
+
+  socket.onopen = () => {
+    open = true;
+    for (const text of pending.splice(0, pending.length)) socket.send(text);
+    config.onOpen?.();
+    if (config.subscriptions?.length) {
+      bootstrapSubscriptions(config.subscriptions);
+    }
+  };
+
+  socket.onmessage = (event) => {
+    const data = typeof event.data === "string" ? event.data : "";
+    let message: Record<string, unknown> | null = null;
+    try {
+      message = JSON.parse(data) as Record<string, unknown>;
+    } catch {
+      return;
+    }
+    if (!message) return;
+
+    const type = typeof message.type === "string" ? message.type : "";
+    if (type === "welcome") config.onWelcome?.(message);
+    else if (type === "ack") config.onAck?.(message);
+    else if (type === "log") {
+      config.onLog?.(message);
+      maybeUpdateCursor(message);
+    } else if (type === "catchUpComplete") config.onCatchUpComplete?.(message);
+    else if (type === "pong") config.onPong?.(message);
+    else if (type === "error") config.onServerError?.(message);
+  };
+
+  socket.onerror = (event) => {
+    config.onError?.(event);
+  };
+
+  socket.onclose = (event) => {
+    open = false;
+    config.onClose?.(event);
+  };
+
+  if (config.signal) {
+    if (config.signal.aborted) socket.close();
+    else config.signal.addEventListener("abort", () => socket.close(), { once: true });
+  }
+
+  const subscribe = (sub: LogSubscription) => {
+    sendMessage({
+      action: "subscribe",
+      scIndex: sub.scIndex,
+      logType: sub.logType,
+      ...(sub.lastLogId !== undefined ? { lastLogId: sub.lastLogId } : {}),
+      ...(sub.lastTick !== undefined && sub.lastLogId === undefined
+        ? { lastTick: sub.lastTick }
+        : {}),
+    });
+  };
+
+  const subscribeMany = (subs: readonly LogSubscription[], cursor?: LogCursor) => {
+    sendMessage({
+      action: "subscribe",
+      ...(cursor?.lastLogId !== undefined ? { lastLogId: cursor.lastLogId } : {}),
+      ...(cursor?.lastTick !== undefined && cursor.lastLogId === undefined
+        ? { lastTick: cursor.lastTick }
+        : {}),
+      subscriptions: subs.map((s) => ({ scIndex: s.scIndex, logType: s.logType })),
+    });
+  };
+
+  const unsubscribe = (sub: LogSubscription) => {
+    sendMessage({
+      action: "unsubscribe",
+      scIndex: sub.scIndex,
+      logType: sub.logType,
+    });
+  };
+
+  const unsubscribeAll = () => {
+    sendMessage({ action: "unsubscribeAll" });
+  };
+
+  const ping = () => {
+    sendMessage({ action: "ping" });
+  };
+
+  const close = (code?: number, reason?: string) => {
+    socket.close(code, reason);
+  };
+
+  const bootstrapSubscriptions = async (subs: readonly LogSubscription[]) => {
+    const withCursor: LogSubscription[] = [];
+    for (const s of subs) {
+      const cursor = await getCursorFor(s);
+      withCursor.push({ ...s, ...cursor });
+    }
+
+    const hasPerCursor = withCursor.some(
+      (s) => s.lastLogId !== undefined || s.lastTick !== undefined,
+    );
+    if (!hasPerCursor && withCursor.length > 1) {
+      subscribeMany(withCursor, {
+        lastLogId: config.lastLogId,
+        lastTick: config.lastTick,
+      });
+      return;
+    }
+
+    for (const sub of withCursor) subscribe(sub);
+  };
+
+  const getCursorFor = async (sub: LogSubscription): Promise<LogCursor | undefined> => {
+    if (sub.lastLogId !== undefined || sub.lastTick !== undefined) {
+      return { lastLogId: sub.lastLogId, lastTick: sub.lastTick };
+    }
+    if (!config.cursorStore) return undefined;
+    return config.cursorStore.get(cursorKey(sub.scIndex, sub.logType));
+  };
+
+  const maybeUpdateCursor = (message: Record<string, unknown>) => {
+    if (!config.cursorStore) return;
+    const scIndex = asNumber(message.scIndex);
+    const logType = asNumber(message.logType);
+    if (scIndex === undefined || logType === undefined) return;
+
+    const payload = expectObject(message.message);
+    const logId = asNumber(payload.logId ?? payload.id);
+    const tick = asNumber(payload.tick ?? payload.tickNumber);
+    if (logId === undefined && tick === undefined) return;
+
+    const cursor: LogCursor = logId !== undefined ? { lastLogId: logId } : { lastTick: tick };
+    config.cursorStore.set(cursorKey(scIndex, logType), cursor);
+  };
+
+  return { socket, subscribe, subscribeMany, unsubscribe, unsubscribeAll, ping, close };
+}
+
+function toWebSocketUrl(baseUrl: string): string {
+  const url = new URL(baseUrl);
+  const wsProtocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.protocol = wsProtocol;
+  const basePath = url.pathname.replace(/\/$/, "");
+  url.pathname = `${basePath}/ws/logs`;
+  return url.toString();
+}
+
+function cursorKey(scIndex: number, logType: number): string {
+  return `${scIndex}:${logType}`;
+}
+
+function expectObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object") return {};
+  return value as Record<string, unknown>;
+}
+
+function asNumber(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return value;
+}
+
+function defaultWebSocketFactory(url: string): WebSocketLike {
+  if (typeof WebSocket === "undefined") {
+    throw new Error("WebSocket is not available; provide webSocketFactory");
+  }
+  return new WebSocket(url) as WebSocketLike;
+}
+
+export type WebSocketLike = {
+  readonly readyState: number;
+  onopen: ((event: EventLike) => void) | null;
+  onmessage: ((event: MessageEventLike) => void) | null;
+  onerror: ((event: EventLike) => void) | null;
+  onclose: ((event: CloseEventLike) => void) | null;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+};
+
+export type EventLike = Readonly<Record<string, unknown>>;
+export type MessageEventLike = Readonly<{ data: string }>;
+export type CloseEventLike = Readonly<{ code?: number; reason?: string }>;