@qubic.ts/sdk 0.1.0

package/src/browser.ts

@@ -0,0 +1,43 @@
+export type { ContractsHelpers, QueryRawInput, QueryRawResult } from "./contracts.js";
+export type { SdkConfig } from "./sdk.js";
+export { createSdk } from "./sdk.js";
+export type {
+  LastProcessedTick,
+  LiveBalance,
+  QueryTransaction,
+  TickInfo,
+  TransactionsForIdentityRequest,
+  TransactionsForIdentityResponse,
+} from "./rpc/client.js";
+export type { SeedSourceInput, SendTransactionResult } from "./transactions.js";
+export type {
+  BuildSignedTransferInput,
+  SendAndConfirmInput,
+  SendTransferResult,
+} from "./transfers.js";
+export type {
+  OpenSeedVaultBrowserInput,
+  VaultStore,
+} from "./vault-browser.js";
+export {
+  createLocalStorageVaultStore,
+  createMemoryVaultStore,
+  openSeedVaultBrowser,
+} from "./vault-browser.js";
+export type {
+  OpenSeedVaultInput,
+  SeedVault,
+  VaultEntry,
+  VaultEntryEncrypted,
+  VaultExport,
+  VaultHeader,
+  VaultKdfParams,
+  VaultSummary,
+} from "./vault/types.js";
+export {
+  VaultEntryExistsError,
+  VaultEntryNotFoundError,
+  VaultError,
+  VaultInvalidPassphraseError,
+  VaultNotFoundError,
+} from "./vault/types.js";

package/src/contracts.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "bun:test";
+import { ContractQueryAbortedError, createContractHelpers } from "./contracts.js";
+import type { FetchLike } from "./http.js";
+import { createRpcClient } from "./rpc/client.js";
+
+function createQueryFetch(responses: Uint8Array[]) {
+  let calls = 0;
+  const history = { calls: 0 };
+  const fetch: FetchLike = async (...args) => {
+    const url = new URL(getUrl(args[0]));
+    const method = getMethod(args[0], args[1]);
+    if (method === "POST" && url.pathname === "/live/v1/querySmartContract") {
+      const response = responses[Math.min(calls, responses.length - 1)] ?? new Uint8Array();
+      calls++;
+      history.calls = calls;
+      return Response.json({
+        responseData: Buffer.from(response).toString("base64"),
+      });
+    }
+    return new Response("not found", { status: 404 });
+  };
+  return { fetch, history };
+}
+
+describe("contracts.queryRaw", () => {
+  it("retries when response is shorter than expected", async () => {
+    const { fetch, history } = createQueryFetch([new Uint8Array(), new Uint8Array([1, 2, 3, 4])]);
+    const rpc = createRpcClient({ baseUrl: "https://example.test", fetch });
+    const contracts = createContractHelpers({ rpc, defaultRetries: 2, defaultRetryDelayMs: 1 });
+
+    const res = await contracts.queryRaw({
+      contractIndex: 1,
+      inputType: 1,
+      inputBytes: new Uint8Array(),
+      expectedOutputSize: 4,
+      retryDelayMs: 1,
+    });
+
+    expect(res.responseBytes.length).toBe(4);
+    expect(res.attempts).toBe(2);
+    expect(history.calls).toBe(2);
+  });
+
+  it("returns immediately when no expected size is provided", async () => {
+    const { fetch, history } = createQueryFetch([new Uint8Array([9])]);
+    const rpc = createRpcClient({ baseUrl: "https://example.test", fetch });
+    const contracts = createContractHelpers({ rpc });
+
+    const res = await contracts.queryRaw({
+      contractIndex: 1,
+      inputType: 1,
+      inputBytes: new Uint8Array(),
+    });
+
+    expect(res.responseBytes.length).toBe(1);
+    expect(res.attempts).toBe(1);
+    expect(history.calls).toBe(1);
+  });
+
+  it("throws when the input signal is already aborted", async () => {
+    const { fetch, history } = createQueryFetch([new Uint8Array([1])]);
+    const rpc = createRpcClient({ baseUrl: "https://example.test", fetch });
+    const contracts = createContractHelpers({ rpc, defaultRetries: 2, defaultRetryDelayMs: 10 });
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      contracts.queryRaw({
+        contractIndex: 1,
+        inputType: 1,
+        inputBytes: new Uint8Array(),
+        expectedOutputSize: 4,
+        signal: controller.signal,
+      }),
+    ).rejects.toBeInstanceOf(ContractQueryAbortedError);
+    expect(history.calls).toBe(0);
+  });
+});
+
+function getUrl(input: Parameters<typeof fetch>[0]): string {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.toString();
+  return input.url;
+}
+
+function getMethod(input: Parameters<typeof fetch>[0], init: Parameters<typeof fetch>[1]): string {
+  if (init?.method) return init.method;
+  if (input instanceof Request) return input.method;
+  return "GET";
+}

package/src/contracts.ts

@@ -0,0 +1,140 @@
+import type { RpcClient } from "./rpc/client.js";
+
+export type ContractsHelpersConfig = Readonly<{
+  rpc: RpcClient;
+  defaultRetries?: number;
+  defaultRetryDelayMs?: number;
+}>;
+
+export type QueryRawInput = Readonly<{
+  contractIndex: bigint | number;
+  inputType: bigint | number;
+  inputBytes?: Uint8Array;
+  inputBase64?: string;
+  /** If provided, retries when response bytes are shorter than this value. */
+  expectedOutputSize?: number;
+  retries?: number;
+  retryDelayMs?: number;
+  signal?: AbortSignal;
+}>;
+
+export type QueryRawResult = Readonly<{
+  responseBytes: Uint8Array;
+  responseBase64: string;
+  attempts: number;
+}>;
+
+export type ContractsHelpers = Readonly<{
+  queryRaw(input: QueryRawInput): Promise<QueryRawResult>;
+  querySmartContract(input: {
+    contractIndex: bigint | number;
+    inputType: bigint | number;
+    input: Uint8Array | string;
+  }): Promise<{ responseBytes: Uint8Array; responseBase64: string }>;
+}>;
+
+export class ContractQueryAbortedError extends Error {
+  override name = "ContractQueryAbortedError";
+}
+
+export function createContractHelpers(config: ContractsHelpersConfig): ContractsHelpers {
+  const defaultRetries = config.defaultRetries ?? 0;
+  const defaultRetryDelayMs = config.defaultRetryDelayMs ?? 1_000;
+
+  return {
+    async querySmartContract(
+      input,
+    ): Promise<{ responseBytes: Uint8Array; responseBase64: string }> {
+      return config.rpc.live.querySmartContract(input);
+    },
+
+    async queryRaw(input: QueryRawInput): Promise<QueryRawResult> {
+      const retries = input.retries ?? defaultRetries;
+      const retryDelayMs = input.retryDelayMs ?? defaultRetryDelayMs;
+      const expectedOutputSize = input.expectedOutputSize;
+      const inputBytes =
+        input.inputBytes ?? (input.inputBase64 ? decodeBase64(input.inputBase64) : undefined);
+      if (!inputBytes) {
+        throw new TypeError("queryRaw requires inputBytes or inputBase64");
+      }
+
+      const controller = new AbortController();
+      const signals: AbortSignal[] = [controller.signal];
+      if (input.signal) signals.push(input.signal);
+      const signal = anySignal(signals);
+
+      let attempts = 0;
+      while (true) {
+        if (signal.aborted) throw new ContractQueryAbortedError("Contract query aborted");
+        attempts++;
+
+        const res = await config.rpc.live.querySmartContract({
+          contractIndex: input.contractIndex,
+          inputType: input.inputType,
+          input: inputBytes,
+        });
+
+        const shortResponse =
+          typeof expectedOutputSize === "number" &&
+          Number.isFinite(expectedOutputSize) &&
+          expectedOutputSize > 0 &&
+          res.responseBytes.length < expectedOutputSize;
+
+        if (!shortResponse || attempts > retries) {
+          return { ...res, attempts };
+        }
+
+        await sleep(retryDelayMs, signal);
+      }
+    },
+  };
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const id = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+
+    const onAbort = () => {
+      cleanup();
+      reject(new ContractQueryAbortedError("Contract query aborted"));
+    };
+
+    const cleanup = () => {
+      clearTimeout(id);
+      signal.removeEventListener("abort", onAbort);
+    };
+
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function anySignal(signals: readonly AbortSignal[]): AbortSignal {
+  if (signals.length === 0) return new AbortController().signal;
+  if (signals.length === 1) {
+    const only = signals[0];
+    if (!only) return new AbortController().signal;
+    return only;
+  }
+
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  for (const s of signals) {
+    if (s.aborted) return s;
+    s.addEventListener("abort", onAbort, { once: true });
+  }
+  return controller.signal;
+}
+
+function decodeBase64(value: string): Uint8Array {
+  if (typeof atob === "function") {
+    const bin = atob(value);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return bytes;
+  }
+  throw new Error("Base64 decoding is not available in this runtime");
+}

package/src/errors.ts

@@ -0,0 +1,15 @@
+export type ErrorContext = Readonly<Record<string, unknown>>;
+
+export class SdkError extends Error {
+  readonly code: string;
+  readonly context?: ErrorContext;
+  override readonly cause?: unknown;
+
+  constructor(code: string, message: string, context?: ErrorContext, cause?: unknown) {
+    super(message, { cause });
+    this.name = "SdkError";
+    this.code = code;
+    this.context = context;
+    this.cause = cause;
+  }
+}

package/src/http.ts

@@ -0,0 +1 @@
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;

package/src/index.ts

@@ -0,0 +1,141 @@
+export type { ErrorContext } from "./errors.js";
+export { SdkError } from "./errors.js";
+export type {
+  AssetsHelpers,
+  AssetsHelpersConfig,
+  AssetsQueryInput,
+  AssetsRequestFn,
+  ListIssuedInput,
+  ListOwnedInput,
+  ListPossessedInput,
+} from "./assets.js";
+export {
+  createAssetsHelpers,
+  isIssuanceAsset,
+  isOwnershipAsset,
+  isPossessionAsset,
+} from "./assets.js";
+export type {
+  BobClient,
+  BobClientConfig,
+  BobQuerySmartContractInput,
+  BobQuerySmartContractResult,
+} from "./bob/client.js";
+export { BobError, createBobClient } from "./bob/client.js";
+export type {
+  CloseEventLike,
+  EventLike,
+  LogCursor,
+  LogCursorStore,
+  LogStream,
+  LogStreamConfig,
+  LogStreamHandlers,
+  LogSubscription,
+  MessageEventLike,
+  WebSocketLike,
+} from "./bob/log-stream.js";
+export { createLogStream } from "./bob/log-stream.js";
+export type {
+  ContractsHelpers,
+  ContractsHelpersConfig,
+  QueryRawInput,
+  QueryRawResult,
+} from "./contracts.js";
+export { ContractQueryAbortedError, createContractHelpers } from "./contracts.js";
+export type { FetchLike } from "./http.js";
+export type { RetryConfig, RetryConfigNormalized } from "./retry.js";
+export { normalizeRetryConfig, withRetry } from "./retry.js";
+export type { SdkConfig } from "./sdk.js";
+export { createSdk } from "./sdk.js";
+export type {
+  BroadcastTransactionResult,
+  ComputorList,
+  Hits,
+  LastProcessedTick,
+  LiveBalance,
+  Pagination,
+  ProcessedTickInterval,
+  QueryTransaction,
+  Range,
+  RpcClient,
+  RpcClientConfig,
+  TickData,
+  TickInfo,
+  TransactionsForIdentityPagingInput,
+  TransactionsForIdentityRequest,
+  TransactionsForIdentityResponse,
+} from "./rpc/client.js";
+export { createRpcClient, RpcError } from "./rpc/client.js";
+export type { SuggestedTargetTickInput, TickHelpers, TickHelpersConfig } from "./tick.js";
+export { createTickHelpers } from "./tick.js";
+export type {
+  TxConfirmationHelpers,
+  TxConfirmationHelpersConfig,
+  WaitForConfirmationInput,
+} from "./tx/confirm.js";
+export {
+  createTxConfirmationHelpers,
+  TxConfirmationAbortedError,
+  TxConfirmationTimeoutError,
+  TxNotFoundError,
+} from "./tx/confirm.js";
+export type { TxHelpers, TxHelpersConfig } from "./tx/tx.js";
+export { createTxHelpers } from "./tx/tx.js";
+export type {
+  EnqueueTxInput,
+  TxQueueConfirmFn,
+  TxQueueConfig,
+  TxQueueItem,
+  TxQueueItemStatus,
+  TxQueuePolicy,
+} from "./tx/tx-queue.js";
+export { TxQueue, TxQueueError } from "./tx/tx-queue.js";
+export type {
+  BuildSignedTransactionInput,
+  BuiltTransaction,
+  SeedSourceInput,
+  SendAndConfirmTransactionInput,
+  SendTransactionReceipt,
+  SendTransactionResult,
+  TransactionHelpers,
+  TransactionHelpersConfig,
+} from "./transactions.js";
+export { createTransactionHelpers, QueuedTransactionError } from "./transactions.js";
+export type {
+  BuildSignedTransferInput,
+  SendAndConfirmInput,
+  SendTransferReceipt,
+  SendTransferResult,
+  SignedTransfer,
+  TransferHelpers,
+  TransferHelpersConfig,
+} from "./transfers.js";
+export { createTransferHelpers } from "./transfers.js";
+export type {
+  OpenSeedVaultInput,
+  Pbkdf2Hash,
+  Pbkdf2KdfParams,
+  ScryptKdfParams,
+  SeedVault,
+  VaultEntry,
+  VaultEntryEncrypted,
+  VaultExport,
+  VaultHeader,
+  VaultKdf,
+  VaultKdfParams,
+  VaultSummary,
+} from "./vault/types.js";
+export {
+  VaultEntryExistsError,
+  VaultEntryNotFoundError,
+  VaultError,
+  VaultInvalidPassphraseError,
+  VaultNotFoundError,
+} from "./vault/types.js";
+export { openSeedVault, vaultExists } from "./vault.js";
+export type { OpenSeedVaultBrowserInput, VaultStore } from "./vault-browser.js";
+export {
+  createLocalStorageVaultStore,
+  createMemoryVaultStore,
+  openSeedVaultBrowser,
+} from "./vault-browser.js";

package/src/node.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/src/retry.ts

@@ -0,0 +1,61 @@
+export type RetryConfig = Readonly<{
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  jitterMs?: number;
+  retryOnStatuses?: readonly number[];
+  retryOnMethods?: readonly string[];
+}>;
+
+export type RetryConfigNormalized = Readonly<{
+  maxRetries: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+  jitterMs: number;
+  retryOnStatuses: readonly number[];
+  retryOnMethods: readonly string[];
+}>;
+
+const DEFAULT_RETRY_STATUSES = [408, 429, 500, 502, 503, 504] as const;
+
+export function normalizeRetryConfig(input?: RetryConfig): RetryConfigNormalized {
+  return {
+    maxRetries: input?.maxRetries ?? 0,
+    baseDelayMs: input?.baseDelayMs ?? 250,
+    maxDelayMs: input?.maxDelayMs ?? 2_000,
+    jitterMs: input?.jitterMs ?? 100,
+    retryOnStatuses: input?.retryOnStatuses ?? DEFAULT_RETRY_STATUSES,
+    retryOnMethods: input?.retryOnMethods ?? ["GET", "POST"],
+  };
+}
+
+export async function withRetry<T>(
+  config: RetryConfigNormalized,
+  method: string,
+  run: () => Promise<T>,
+  shouldRetry: (error: unknown) => boolean,
+): Promise<T> {
+  let attempt = 0;
+  while (true) {
+    try {
+      return await run();
+    } catch (error) {
+      if (attempt >= config.maxRetries) throw error;
+      if (!config.retryOnMethods.includes(method)) throw error;
+      if (!shouldRetry(error)) throw error;
+      const delay = computeDelay(config, attempt);
+      await sleep(delay);
+      attempt += 1;
+    }
+  }
+}
+
+function computeDelay(config: RetryConfigNormalized, attempt: number): number {
+  const base = Math.min(config.baseDelayMs * 2 ** attempt, config.maxDelayMs);
+  const jitter = config.jitterMs > 0 ? Math.floor(Math.random() * config.jitterMs) : 0;
+  return base + jitter;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}