@geeqdev/geeq-sdk 0.0.1 → 0.1.1

package/src/net/transport.ts

@@ -0,0 +1,221 @@
+import { GeeqError, networkUnreachable, nodeError } from '../errors'
+
+/** A response, narrowed to what this SDK reads. A WHATWG `Response` satisfies it. */
+export interface GeeqHttpResponse {
+  readonly ok: boolean
+  readonly status: number
+  text(): Promise<string>
+}
+
+/** A request, narrowed to what this SDK sends. Assignable to `RequestInit`. */
+export interface GeeqRequestInit {
+  readonly method?: string
+  readonly headers?: Readonly<Record<string, string>>
+  readonly body?: string
+  readonly signal?: AbortSignal
+}
+
+/**
+ * How the SDK reaches a node.
+ *
+ * Deliberately a structural subset of WHATWG `fetch`, so `{ transport: fetch }`
+ * typechecks with no adapter, and so does undici with a custom dispatcher, a relative
+ * URL through a dev proxy, or a scripted array of responses in a test.
+ */
+export type GeeqTransport = (
+  url: string,
+  init?: GeeqRequestInit,
+) => Promise<GeeqHttpResponse>
+
+/**
+ * `globalThis.fetch`, resolved at call time.
+ *
+ * Never a stored reference: an unbound `fetch` throws `Illegal invocation` in a
+ * browser, and capturing it would defeat any test that swaps `globalThis.fetch` after
+ * this module is imported.
+ */
+export const defaultTransport: GeeqTransport = (url, init) =>
+  globalThis.fetch(url, init as RequestInit)
+
+export interface RequestOptions {
+  readonly transport: GeeqTransport
+  readonly timeoutMs: number
+  readonly retries: number
+  readonly headers?: Readonly<Record<string, string>> | undefined
+  readonly signal?: AbortSignal | undefined
+  readonly method?: string | undefined
+  readonly body?: string | undefined
+}
+
+/**
+ * The one failure a browser can be certain about before making a request.
+ *
+ * An https page may not load an http subresource. The browser blocks it and reports a
+ * generic network failure, so issuing the request would only turn a knowable cause into
+ * an ambiguous one.
+ */
+function assertSchemeReachable(url: string): void {
+  const location = (globalThis as { location?: { protocol?: string } }).location
+  if (location?.protocol !== 'https:') return
+
+  let scheme: string
+  try {
+    scheme = new URL(url).protocol
+  } catch {
+    return
+  }
+  if (scheme !== 'http:') return
+
+  throw networkUnreachable(
+    `This page is served over https and the node URL ${url} is http, so the browser ` +
+      'will block the request as mixed content before it is sent. Use the node\'s https ' +
+      'URL (port 2082 by default), or serve this page over http while developing.',
+  )
+}
+
+/** The four causes a browser cannot tell apart, each with what to do about it. */
+function opaqueFailureMessage(url: string): string {
+  return (
+    `Could not reach the Geeq node at ${url}. A browser reports network failures ` +
+    'opaquely, so this is one of four things: (1) the node does not answer CORS for ' +
+    'this origin — pass your own `transport` routing through a proxy you control; ' +
+    "(2) the node's TLS certificate is not trusted, which is common because nodes are " +
+    'addressed by bare IP — open the URL in a tab to see the interstitial; (3) this ' +
+    'page is https and the node is http, which browsers block; or (4) the node is down ' +
+    'or the URL is wrong.'
+  )
+}
+
+function describeCause(cause: unknown): string | undefined {
+  if (cause !== null && typeof cause === 'object') {
+    const { code } = cause as { code?: unknown }
+    if (typeof code === 'string') return code
+  }
+  return undefined
+}
+
+/** Pull the node's own `details` out of an error body without trusting its shape. */
+function nodeDetailsOf(body: string): string | undefined {
+  try {
+    const parsed: unknown = JSON.parse(body)
+    if (parsed !== null && typeof parsed === 'object') {
+      const { details, error } = parsed as { details?: unknown; error?: unknown }
+      if (typeof details === 'string' && details !== '') return details
+      // A block explorer sends its reasons as a list.
+      if (Array.isArray(details)) {
+        const joined = details.filter((item) => typeof item === 'string').join('; ')
+        if (joined !== '') return joined
+      }
+      if (typeof error === 'string' && error !== '') return error
+    }
+  } catch {
+    // Not JSON. The raw body is still the most useful thing we have.
+  }
+  return body === '' ? undefined : body.slice(0, 400)
+}
+
+/**
+ * `signal.throwIfAborted()`, written out: a polyfilled `AbortSignal` may not have it.
+ * A call rather than an inline check also keeps TypeScript from narrowing `aborted` to
+ * false for the rest of the function — it can change across an `await`.
+ */
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted === true) throw signal.reason
+}
+
+/**
+ * Make one request and return its body, mapping every failure onto a typed error.
+ *
+ * Retries only a transport failure, and only because reads are idempotent. A response
+ * that arrived is never retried: the node has decided.
+ */
+export async function requestText(url: string, options: RequestOptions): Promise<string> {
+  assertSchemeReachable(url)
+
+  const { signal } = options
+  let lastCause: unknown
+  for (let attempt = 0; attempt <= options.retries; attempt += 1) {
+    // An 'abort' listener never fires for a signal that is already aborted, so without
+    // this the request would go out anyway — and so would a retry after an abort.
+    throwIfAborted(signal)
+
+    // Composed by hand rather than with AbortSignal.any, which needs Node 20.3 and
+    // Safari 17.4 — too new for a library that supports Node 20. The caller's reason is
+    // passed on, so a fetch that honours it rejects with exactly what the caller aborted with.
+    const controller = new AbortController()
+    const onAbort = (): void => controller.abort(signal?.reason)
+    signal?.addEventListener('abort', onAbort)
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      controller.abort()
+    }, options.timeoutMs)
+
+    try {
+      const response = await options.transport(url, {
+        signal: controller.signal,
+        ...(options.method === undefined ? {} : { method: options.method }),
+        ...(options.headers === undefined ? {} : { headers: options.headers }),
+        ...(options.body === undefined ? {} : { body: options.body }),
+      })
+
+      const body = await response.text()
+      if (!response.ok) {
+        const details = nodeDetailsOf(body)
+        throw nodeError(
+          `The node at ${url} answered HTTP ${response.status}` +
+            (details === undefined ? ' with no detail.' : `: ${JSON.stringify(details)}.`),
+          response.status,
+          details,
+        )
+      }
+      return body
+    } catch (cause) {
+      if (cause instanceof GeeqError) throw cause
+
+      // A caller-driven abort is theirs to observe, not ours to relabel.
+      if (signal?.aborted === true) throw signal.reason
+
+      if (timedOut) {
+        throw networkUnreachable(
+          `The node at ${url} did not answer within ${options.timeoutMs}ms. Raise ` +
+            'timeoutMs if the node is simply slow, or try another node.',
+          cause,
+        )
+      }
+      lastCause = cause
+    } finally {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+    }
+  }
+
+  const code = describeCause(lastCause)
+  throw networkUnreachable(
+    code === undefined
+      ? opaqueFailureMessage(url)
+      : `Could not reach the Geeq node at ${url}: ${code}.`,
+    lastCause,
+  )
+}
+
+/**
+ * Wait for `promise`, or stop waiting when `signal` aborts.
+ *
+ * For a request several callers share: aborting one caller's wait must not cancel the
+ * request out from under the others, so the request runs on without any caller's signal
+ * and each caller races its own against it.
+ *
+ * @internal
+ */
+export function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (signal === undefined) return promise
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(signal.reason)
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise
+      .then(resolve, reject)
+      .finally(() => signal.removeEventListener('abort', onAbort))
+  })
+}

package/src/net/websocket.ts

@@ -0,0 +1,94 @@
+import { socketUnreachable } from '../errors'
+
+/** `readyState` of an open connection. The same number in browsers and in `ws`. */
+export const WEBSOCKET_OPEN = 1
+
+/** What a WebSocket hands its `message` listeners, narrowed to the one field read. */
+export interface GeeqWebSocketMessageEvent {
+  readonly data: unknown
+}
+
+/**
+ * A WebSocket, narrowed to what this SDK uses.
+ *
+ * Deliberately structural, like {@link GeeqTransport}: a browser `WebSocket`, Node 22's
+ * global one and the `ws` package's class all satisfy it with no adapter, and so does a
+ * scripted fake in a test. Listeners are attached with `addEventListener` rather than
+ * `onmessage` and friends because a method is compared bivariantly, which is what lets
+ * each implementation's own event types through.
+ */
+export interface GeeqWebSocketLike {
+  readonly readyState: number
+  send(data: string): void
+  close(code?: number, reason?: string): void
+  addEventListener(type: 'open', listener: (event: unknown) => void): void
+  addEventListener(type: 'message', listener: (event: GeeqWebSocketMessageEvent) => void): void
+  addEventListener(type: 'close', listener: (event: unknown) => void): void
+  addEventListener(type: 'error', listener: (event: unknown) => void): void
+}
+
+/**
+ * How the SDK opens a socket.
+ *
+ * `(url) => new WebSocket(url)` is the whole contract. Pass one to use the `ws` package on
+ * Node 20, to add headers or a TLS agent there, or to script a connection in a test.
+ */
+export type GeeqWebSocketFactory = (url: string) => GeeqWebSocketLike
+
+/**
+ * `new globalThis.WebSocket(url)`, resolved at call time.
+ *
+ * Never a stored reference, for the same reason as `defaultTransport`: a test that swaps
+ * the global after import must still be honoured. Node 20 has no global WebSocket at all,
+ * and a library that supports Node 20 cannot assume one, so its absence is reported with
+ * the one-line fix rather than as a `TypeError`.
+ */
+export const defaultWebSocketFactory: GeeqWebSocketFactory = (url) => {
+  const WebSocketClass = (globalThis as { WebSocket?: new (url: string) => GeeqWebSocketLike })
+    .WebSocket
+  if (typeof WebSocketClass !== 'function') {
+    throw socketUnreachable(
+      'This runtime has no global WebSocket — Node 20 does not, Node 22 and every browser ' +
+        'do. Pass one explicitly: `webSocket: (url) => new WebSocket(url)` with ' +
+        '`import WebSocket from "ws"`.',
+    )
+  }
+  return new WebSocketClass(url)
+}
+
+/**
+ * The one socket failure a browser can be certain about before trying.
+ *
+ * An https page may not open a `ws://` socket; the browser refuses it outright and reports
+ * nothing useful, so the handshake would only turn a knowable cause into an opaque one.
+ */
+export function assertSocketSchemeReachable(url: string): void {
+  const location = (globalThis as { location?: { protocol?: string } }).location
+  if (location?.protocol !== 'https:') return
+
+  let scheme: string
+  try {
+    scheme = new URL(url).protocol
+  } catch {
+    return
+  }
+  if (scheme !== 'ws:') return
+
+  throw socketUnreachable(
+    `This page is served over https and the socket URL ${url} is ws://, so the browser ` +
+      'will block it as mixed content before it connects. Use the node\'s wss:// URL ' +
+      '(port 2082 by default), or serve this page over http while developing.',
+  )
+}
+
+/** The causes a browser cannot tell apart when a handshake fails, with the fix for each. */
+export function opaqueSocketFailureMessage(url: string): string {
+  return (
+    `Could not open the Geeq node socket at ${url}. A browser reports a failed handshake ` +
+    'with no detail, so this is one of four things: (1) the node\'s TLS certificate is ' +
+    'not trusted, which is common because nodes are addressed by bare IP — open the ' +
+    "node's https URL in a tab to see the interstitial; (2) this page is https and the " +
+    'socket is ws://, which browsers block; (3) the URL is wrong — the path is /ws/, with ' +
+    'the trailing slash, on the same port as the HTTP API; or (4) the node is down.'
+  )
+}

package/src/runtime/bindings.ts

@@ -0,0 +1,38 @@
+/**
+ * The single place the SDK reaches into the WebAssembly engine.
+ *
+ * Every binding is imported by name and re-exported as a real identifier, never
+ * looked up by string. A string-keyed lookup here would break under any consumer
+ * minifier that renames module bindings, and it would fail silently for exactly
+ * one code path — the failure mode this indirection exists to prevent.
+ */
+export {
+  Keypair as WasmKeypair,
+  WalletAddress as WasmWalletAddress,
+  RecordType as WasmRecordType,
+  CoinType as WasmCoinType,
+  verify as wasmVerify,
+  mnemonicToSeed as wasmMnemonicToSeed,
+  generateSeedId as wasmGenerateSeedId,
+  // A proxy's account id, derived from its admin's public key and an index exactly as the
+  // Geeq wallet derives it. See src/tx/proxy.ts.
+  generateIrn as wasmGenerateIrn,
+  IrnRecordType as WasmIrnRecordType,
+  // Transaction canonicalisation. The engine cannot *build* a transaction — every
+  // transaction class it exposes has a private constructor — but it is the only
+  // thing that can turn a Cap'n Proto message into the flattened byte form the
+  // chain signs over, so structures are built with capnp and flattened here.
+  Payload as WasmPayload,
+  // Both forms of the transaction are needed and they are NOT interchangeable. The
+  // engine flattens `UserAppTxData` without the signature — that is the preimage the
+  // signature is made over — and `UserAppTx` with it, which is what the chain hashes to
+  // identify the transaction. See src/tx/attestation.ts.
+  UserAppTx as WasmUserAppTx,
+  UserAppTxData as WasmUserAppTxData,
+  // The validation-layer transaction — coin transfers — has the same two forms, but the
+  // node identifies it by the Data (signature-excluded) flatten, not the signed one.
+  // See src/tx/transfer.ts.
+  UserValTx as WasmUserValTx,
+  UserValTxData as WasmUserValTxData,
+  AttestationSubgroupData as WasmAttestationSubgroupData,
+} from '../wasm/browser/geeq_core'

package/src/runtime/init.ts

@@ -0,0 +1,49 @@
+import { GeeqError, notInitialized } from '../errors'
+import type { InitOptions } from '../types'
+import { loadWasm } from './wasm-loader.browser'
+
+let inflight: Promise<void> | null = null
+let ready = false
+
+/**
+ * Load the Geeq engine. Idempotent and single-flight: concurrent callers share one
+ * load, and repeat calls after success resolve immediately.
+ *
+ * You rarely need to call this yourself — every async entry point in the SDK awaits
+ * it first. Call it at startup if you would rather pay the cost up front.
+ */
+export function initGeeq(options: InitOptions = {}): Promise<void> {
+  if (ready) return Promise.resolve()
+
+  if (inflight === null) {
+    inflight = loadWasm(options.wasm)
+      .then(() => {
+        ready = true
+      })
+      .catch((cause: unknown) => {
+        // Clear the cached promise so a later call can retry with, say, an
+        // explicit `wasm` source rather than being stuck with the first failure.
+        inflight = null
+        throw new GeeqError(
+          'init-failed',
+          'Could not load the Geeq WebAssembly engine. If your bundler does not emit ' +
+            'geeq_core_bg.wasm automatically, pass its URL as initGeeq({ wasm }).',
+          { cause },
+        )
+      })
+  }
+
+  return inflight
+}
+
+/** True once the engine is loaded and the synchronous APIs are usable. */
+export function isGeeqReady(): boolean {
+  return ready
+}
+
+/** @internal Guard for synchronous APIs that require a loaded engine. */
+export function assertReady(what: string): void {
+  if (!ready) {
+    throw notInitialized(what)
+  }
+}

package/src/runtime/wasm-loader.browser.ts

@@ -0,0 +1,22 @@
+import initWasm from '../wasm/browser/geeq_core'
+import type { WasmSource } from '../types'
+
+/**
+ * Browser loader: finds the engine's .wasm file and starts it.
+ *
+ * If the app passes its own `source`, that is used. Otherwise it is the .wasm file
+ * that ships next to this script in `dist/browser/`.
+ *
+ * `new URL('./geeq_core_bg.wasm', import.meta.url)` means "geeq_core_bg.wasm in the
+ * same folder as this file". Keep it written exactly this way: Vite, webpack, Rollup
+ * and Parcel spot this pattern and copy the .wasm into the app's build for you.
+ *
+ * The Node build swaps this module for `wasm-loader.node.ts` at bundle time.
+ */
+export async function loadWasm(source?: WasmSource): Promise<void> {
+  const wasm = source ?? new URL('./geeq_core_bg.wasm', import.meta.url)
+
+  // `module_or_path` is the option name wasm-bindgen expects. Passing `wasm`
+  // directly instead also works, but prints a deprecation warning.
+  await initWasm({ module_or_path: wasm })
+}

package/src/runtime/wasm-loader.node.ts

@@ -0,0 +1,16 @@
+import { readFile } from 'node:fs/promises'
+import initWasm from '../wasm/browser/geeq_core'
+import type { WasmSource } from '../types'
+
+/**
+ * Node loader: same job as the browser loader, but Node's `fetch` cannot read
+ * local files, so the .wasm is read off disk here and passed in as bytes.
+ * Used by the Node build; the test suite swaps in its own stub (see jest.config.js).
+ */
+export async function loadWasm(source?: WasmSource): Promise<void> {
+  const wasm = source ?? (await readFile(new URL('./geeq_core_bg.wasm', import.meta.url)))
+
+  // `module_or_path` is the option name wasm-bindgen expects. Passing `wasm`
+  // directly instead also works, but prints a deprecation warning.
+  await initWasm({ module_or_path: wasm })
+}