@sparkvault/sdk-mobile 0.1.3

package/src/billing.ts

@@ -0,0 +1,30 @@
+import type { MobileHttpClient } from './http.js';
+
+export interface BillingBalance {
+  balance: string;
+  balance_usd?: number;
+  currency?: string;
+  monthly_spend?: string;
+  monthly_spend_usd?: number;
+  transaction_count?: number;
+  recent_transactions?: Array<{
+    type: string;
+    amount: string;
+    balance_after?: string;
+    reference_id?: string;
+    created_at: number;
+  }>;
+}
+
+export class MobileBillingClient {
+  private readonly http: MobileHttpClient;
+
+  constructor(http: MobileHttpClient) {
+    this.http = http;
+  }
+
+  async getBalance(): Promise<BillingBalance> {
+    const response = await this.http.get<BillingBalance>('/billing/balance');
+    return response.data;
+  }
+}

package/src/client.ts

@@ -0,0 +1,51 @@
+import { MobileAuthClient } from './auth.js';
+import { MobileBillingClient } from './billing.js';
+import { resolveMobileConfig, type SparkVaultMobileConfig, type ResolvedMobileConfig } from './config.js';
+import { MobileEntropyClient } from './entropy.js';
+import { MobileFoldersClient } from './folders.js';
+import { MobileHealthClient } from './health.js';
+import { MobileHttpClient, type AuthEventListener } from './http.js';
+import { MobileIngotsClient } from './ingots.js';
+import { MobilePushTokensClient } from './push-tokens.js';
+import { MobileSparksClient } from './sparks.js';
+import { MobileVaultsClient } from './vaults.js';
+
+export class SparkVaultMobile {
+  readonly config: ResolvedMobileConfig;
+  readonly auth: MobileAuthClient;
+  readonly vaults: MobileVaultsClient;
+  readonly ingots: MobileIngotsClient;
+  readonly folders: MobileFoldersClient;
+  readonly health: MobileHealthClient;
+  readonly sparks: MobileSparksClient;
+  readonly entropy: MobileEntropyClient;
+  readonly pushTokens: MobilePushTokensClient;
+  readonly billing: MobileBillingClient;
+  private readonly http: MobileHttpClient;
+
+  constructor(config: SparkVaultMobileConfig) {
+    this.config = resolveMobileConfig(config);
+    this.http = new MobileHttpClient(this.config);
+    this.auth = new MobileAuthClient(this.config, this.http);
+    this.vaults = new MobileVaultsClient(this.http);
+    this.ingots = new MobileIngotsClient(this.config, this.http);
+    this.folders = new MobileFoldersClient(this.http);
+    this.health = new MobileHealthClient(this.config);
+    this.sparks = new MobileSparksClient(this.http);
+    this.entropy = new MobileEntropyClient(this.http);
+    this.pushTokens = new MobilePushTokensClient(this.http);
+    this.billing = new MobileBillingClient(this.http);
+
+    if (this.config.preloadIdentityConfig) {
+      this.auth.preloadConfig();
+    }
+  }
+
+  onAuthEvent(listener: AuthEventListener): () => void {
+    return this.http.onAuthEvent(listener);
+  }
+}
+
+export function createSparkVaultMobileClient(config: SparkVaultMobileConfig): SparkVaultMobile {
+  return new SparkVaultMobile(config);
+}

package/src/config.ts

@@ -0,0 +1,123 @@
+import { SparkVaultValidationError } from './errors.js';
+import type {
+  FetchLike,
+  MobileFileDownloader,
+  MobileFileReader,
+  SparkVaultLogger,
+  TokenStorageAdapter,
+} from './types.js';
+
+const DEFAULT_API_BASE_URL = 'https://api.sparkvault.com/v1';
+const DEFAULT_IDENTITY_BASE_URL = 'https://api.sparkvault.com/v1/apps/identity';
+
+// Hosts that are allowed to serve backend-issued ingot download URLs.
+// Keep in sync with the sdk-js default in packages/sdk-js/src/config.ts.
+const DEFAULT_ALLOWED_DOWNLOAD_HOST_PATTERNS: RegExp[] = [
+  /(^|\.)sparkvault\.com$/i,
+  /(^|\.)(x|files|file|send|spark|by|at|db|auth)\.sv$/i,
+  /\.amazonaws\.com$/i,
+  /\.cloudfront\.net$/i,
+];
+
+const noopLogger: SparkVaultLogger = {
+  debug: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+};
+
+export interface SparkVaultMobileConfig {
+  tokenStorage: TokenStorageAdapter;
+  apiBaseUrl?: string;
+  identityBaseUrl?: string;
+  identityAccountId: string;
+  preloadIdentityConfig?: boolean;
+  userAgent?: string;
+  timeoutMs?: number;
+  fileTransferTimeoutMs?: number;
+  tusPostTimeoutMs?: number;
+  tusChunkTimeoutMs?: number;
+  tusChunkSizeBytes?: number;
+  fetch?: FetchLike;
+  fileReader?: MobileFileReader;
+  fileDownloader?: MobileFileDownloader;
+  logger?: Partial<SparkVaultLogger>;
+  allowedDownloadHostPatterns?: RegExp[];
+}
+
+export interface ResolvedMobileConfig {
+  tokenStorage: TokenStorageAdapter;
+  apiBaseUrl: string;
+  identityBaseUrl: string;
+  identityAccountId: string;
+  preloadIdentityConfig: boolean;
+  userAgent: string;
+  timeoutMs: number;
+  fileTransferTimeoutMs: number;
+  tusPostTimeoutMs: number;
+  tusChunkTimeoutMs: number;
+  tusChunkSizeBytes: number;
+  fetch: FetchLike;
+  fileReader?: MobileFileReader;
+  fileDownloader?: MobileFileDownloader;
+  logger: SparkVaultLogger;
+  allowedDownloadHostPatterns: RegExp[];
+}
+
+function normalizeBaseUrl(url: string, field: string): string {
+  if (!url || typeof url !== 'string') {
+    throw new SparkVaultValidationError(`${field} must be a non-empty string`, { field });
+  }
+  return url.replace(/\/+$/, '');
+}
+
+function defaultFetch(url: string, options?: RequestInit): Promise<Response> {
+  if (typeof fetch !== 'function') {
+    throw new SparkVaultValidationError('A fetch implementation is required in this runtime');
+  }
+  return fetch(url, options);
+}
+
+export function resolveMobileConfig(config: SparkVaultMobileConfig): ResolvedMobileConfig {
+  if (!config.tokenStorage) {
+    throw new SparkVaultValidationError('tokenStorage is required', { field: 'tokenStorage' });
+  }
+
+  const identityAccountId = config.identityAccountId;
+  if (!identityAccountId || typeof identityAccountId !== 'string') {
+    throw new SparkVaultValidationError('identityAccountId is required', {
+      field: 'identityAccountId',
+      received: identityAccountId,
+    });
+  }
+
+  if (!identityAccountId.startsWith('acc_')) {
+    throw new SparkVaultValidationError('identityAccountId must start with "acc_"', {
+      field: 'identityAccountId',
+      received: identityAccountId,
+    });
+  }
+
+  return {
+    tokenStorage: config.tokenStorage,
+    apiBaseUrl: normalizeBaseUrl(config.apiBaseUrl ?? DEFAULT_API_BASE_URL, 'apiBaseUrl'),
+    identityBaseUrl: normalizeBaseUrl(config.identityBaseUrl ?? DEFAULT_IDENTITY_BASE_URL, 'identityBaseUrl'),
+    identityAccountId,
+    preloadIdentityConfig: config.preloadIdentityConfig ?? true,
+    userAgent: config.userAgent ?? 'SparkVaultMobileSDK/0.1.0',
+    timeoutMs: config.timeoutMs ?? 30000,
+    fileTransferTimeoutMs: config.fileTransferTimeoutMs ?? 300000,
+    tusPostTimeoutMs: config.tusPostTimeoutMs ?? 30000,
+    tusChunkTimeoutMs: config.tusChunkTimeoutMs ?? 120000,
+    tusChunkSizeBytes: config.tusChunkSizeBytes ?? 5 * 1024 * 1024,
+    fetch: config.fetch ?? defaultFetch,
+    fileReader: config.fileReader,
+    fileDownloader: config.fileDownloader,
+    logger: { ...noopLogger, ...config.logger },
+    allowedDownloadHostPatterns: config.allowedDownloadHostPatterns ?? DEFAULT_ALLOWED_DOWNLOAD_HOST_PATTERNS,
+  };
+}
+
+export function identityUrl(config: ResolvedMobileConfig, path: string): string {
+  return `${config.identityBaseUrl}/${config.identityAccountId}${path}`;
+}

package/src/encoding.ts

@@ -0,0 +1,150 @@
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const BASE64_LOOKUP = new Map<string, number>(
+  Array.from(BASE64_ALPHABET).map((char, index) => [char, index])
+);
+
+export function utf8ToBytes(value: string): Uint8Array {
+  const bytes: number[] = [];
+
+  for (let i = 0; i < value.length; i++) {
+    let codePoint = value.charCodeAt(i);
+
+    if (codePoint >= 0xd800 && codePoint <= 0xdbff && i + 1 < value.length) {
+      const next = value.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        codePoint = 0x10000 + ((codePoint - 0xd800) << 10) + (next - 0xdc00);
+        i++;
+      }
+    }
+
+    if (codePoint <= 0x7f) {
+      bytes.push(codePoint);
+    } else if (codePoint <= 0x7ff) {
+      bytes.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+    } else if (codePoint <= 0xffff) {
+      bytes.push(
+        0xe0 | (codePoint >> 12),
+        0x80 | ((codePoint >> 6) & 0x3f),
+        0x80 | (codePoint & 0x3f)
+      );
+    } else {
+      bytes.push(
+        0xf0 | (codePoint >> 18),
+        0x80 | ((codePoint >> 12) & 0x3f),
+        0x80 | ((codePoint >> 6) & 0x3f),
+        0x80 | (codePoint & 0x3f)
+      );
+    }
+  }
+
+  return new Uint8Array(bytes);
+}
+
+export function base64EncodeUtf8(value: string): string {
+  return bytesToBase64(utf8ToBytes(value));
+}
+
+export function bytesToUtf8(bytes: Uint8Array): string {
+  let output = '';
+  let i = 0;
+
+  while (i < bytes.length) {
+    const byte1 = bytes[i++];
+    if (byte1 < 0x80) {
+      output += String.fromCharCode(byte1);
+      continue;
+    }
+
+    if (byte1 >= 0xc0 && byte1 < 0xe0) {
+      const byte2 = bytes[i++];
+      output += String.fromCharCode(((byte1 & 0x1f) << 6) | (byte2 & 0x3f));
+      continue;
+    }
+
+    if (byte1 >= 0xe0 && byte1 < 0xf0) {
+      const byte2 = bytes[i++];
+      const byte3 = bytes[i++];
+      output += String.fromCharCode(
+        ((byte1 & 0x0f) << 12) |
+        ((byte2 & 0x3f) << 6) |
+        (byte3 & 0x3f)
+      );
+      continue;
+    }
+
+    const byte2 = bytes[i++];
+    const byte3 = bytes[i++];
+    const byte4 = bytes[i++];
+    const codePoint = (
+      ((byte1 & 0x07) << 18) |
+      ((byte2 & 0x3f) << 12) |
+      ((byte3 & 0x3f) << 6) |
+      (byte4 & 0x3f)
+    ) - 0x10000;
+    output += String.fromCharCode(
+      0xd800 + (codePoint >> 10),
+      0xdc00 + (codePoint & 0x3ff)
+    );
+  }
+
+  return output;
+}
+
+export function base64UrlToBytes(value: string): Uint8Array {
+  return base64ToBytes(value);
+}
+
+export function base64UrlToUtf8(value: string): string {
+  return bytesToUtf8(base64UrlToBytes(value));
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let output = '';
+
+  for (let i = 0; i < bytes.length; i += 3) {
+    const byte1 = bytes[i];
+    const byte2 = bytes[i + 1] ?? 0;
+    const byte3 = bytes[i + 2] ?? 0;
+    const triplet = (byte1 << 16) | (byte2 << 8) | byte3;
+
+    output += BASE64_ALPHABET[(triplet >> 18) & 0x3f];
+    output += BASE64_ALPHABET[(triplet >> 12) & 0x3f];
+    output += i + 1 < bytes.length ? BASE64_ALPHABET[(triplet >> 6) & 0x3f] : '=';
+    output += i + 2 < bytes.length ? BASE64_ALPHABET[triplet & 0x3f] : '=';
+  }
+
+  return output;
+}
+
+export function base64ToBytes(value: string): Uint8Array {
+  const sanitized = value.replace(/\s/g, '').replace(/-/g, '+').replace(/_/g, '/');
+  if (sanitized.length % 4 === 1) {
+    throw new Error('Invalid base64 input');
+  }
+
+  const padded = sanitized.padEnd(Math.ceil(sanitized.length / 4) * 4, '=');
+  const bytes: number[] = [];
+
+  for (let i = 0; i < padded.length; i += 4) {
+    const c1 = padded[i];
+    const c2 = padded[i + 1];
+    const c3 = padded[i + 2];
+    const c4 = padded[i + 3];
+
+    const v1 = BASE64_LOOKUP.get(c1);
+    const v2 = BASE64_LOOKUP.get(c2);
+    const v3 = c3 === '=' ? 0 : BASE64_LOOKUP.get(c3);
+    const v4 = c4 === '=' ? 0 : BASE64_LOOKUP.get(c4);
+
+    if (v1 === undefined || v2 === undefined || v3 === undefined || v4 === undefined) {
+      throw new Error('Invalid base64 input');
+    }
+
+    const triplet = (v1 << 18) | (v2 << 12) | (v3 << 6) | v4;
+    bytes.push((triplet >> 16) & 0xff);
+    if (c3 !== '=') bytes.push((triplet >> 8) & 0xff);
+    if (c4 !== '=') bytes.push(triplet & 0xff);
+  }
+
+  return new Uint8Array(bytes);
+}

package/src/entropy.ts

@@ -0,0 +1,56 @@
+import { base64ToBytes } from './encoding.js';
+import { SparkVaultMobileError, SparkVaultValidationError } from './errors.js';
+import type { MobileHttpClient } from './http.js';
+
+export type EntropyFormat = 'hex' | 'base64' | 'bytes' | 'uuid';
+
+export interface GenerateEntropyOptions {
+  bytes: number;
+  format?: EntropyFormat;
+}
+
+export interface EntropyResponse {
+  value: string;
+  num_bytes: number;
+  format?: EntropyFormat;
+}
+
+export class MobileEntropyClient {
+  private readonly http: MobileHttpClient;
+
+  constructor(http: MobileHttpClient) {
+    this.http = http;
+  }
+
+  async generate(options: GenerateEntropyOptions): Promise<EntropyResponse> {
+    this.validateByteCount(options.bytes);
+    const response = await this.http.post<EntropyResponse>('/entropy/generate', {
+      num_bytes: options.bytes,
+      format: options.format ?? 'base64',
+    });
+    return response.data;
+  }
+
+  async generateBytes(bytes: number): Promise<Uint8Array> {
+    const response = await this.generate({ bytes, format: 'base64' });
+    if (typeof response.value !== 'string' || response.value.length === 0) {
+      throw new SparkVaultMobileError('Entropy endpoint returned no value');
+    }
+
+    const entropy = base64ToBytes(response.value);
+    if (entropy.length !== bytes) {
+      throw new SparkVaultMobileError(`Entropy length mismatch: expected ${bytes}, got ${entropy.length}`);
+    }
+
+    return entropy;
+  }
+
+  private validateByteCount(bytes: number): void {
+    if (!Number.isInteger(bytes) || bytes < 1 || bytes > 1024) {
+      throw new SparkVaultValidationError('Entropy byte count must be an integer from 1 to 1024', {
+        field: 'bytes',
+        received: bytes,
+      });
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,110 @@
+import type { ApiMeta } from './types.js';
+
+export class SparkVaultMobileError extends Error {
+  readonly code: string | number;
+  readonly statusCode?: number;
+  readonly details?: Record<string, unknown>;
+  readonly meta?: ApiMeta;
+
+  constructor(
+    message: string,
+    options: {
+      code?: string | number;
+      statusCode?: number;
+      details?: Record<string, unknown>;
+      meta?: ApiMeta;
+    } = {}
+  ) {
+    super(message);
+    this.name = 'SparkVaultMobileError';
+    this.code = options.code ?? 'sparkvault_error';
+    this.statusCode = options.statusCode;
+    this.details = options.details;
+    this.meta = options.meta;
+    Object.setPrototypeOf(this, SparkVaultMobileError.prototype);
+  }
+}
+
+export class SparkVaultValidationError extends SparkVaultMobileError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, { code: 'validation_error', statusCode: 400, details });
+    this.name = 'SparkVaultValidationError';
+    Object.setPrototypeOf(this, SparkVaultValidationError.prototype);
+  }
+}
+
+export class SparkVaultAuthenticationError extends SparkVaultMobileError {
+  constructor(message = 'Authentication required', details?: Record<string, unknown>) {
+    super(message, { code: 'authentication_error', statusCode: 401, details });
+    this.name = 'SparkVaultAuthenticationError';
+    Object.setPrototypeOf(this, SparkVaultAuthenticationError.prototype);
+  }
+}
+
+export class SparkVaultAuthorizationError extends SparkVaultMobileError {
+  constructor(message = 'Forbidden', details?: Record<string, unknown>) {
+    super(message, { code: 'authorization_error', statusCode: 403, details });
+    this.name = 'SparkVaultAuthorizationError';
+    Object.setPrototypeOf(this, SparkVaultAuthorizationError.prototype);
+  }
+}
+
+export class SparkVaultNetworkError extends SparkVaultMobileError {
+  constructor(message = 'Network request failed', details?: Record<string, unknown>) {
+    super(message, { code: 'network_error', details });
+    this.name = 'SparkVaultNetworkError';
+    Object.setPrototypeOf(this, SparkVaultNetworkError.prototype);
+  }
+}
+
+export class SparkVaultTimeoutError extends SparkVaultMobileError {
+  constructor(message = 'Request timed out') {
+    super(message, { code: 'timeout_error', statusCode: 408 });
+    this.name = 'SparkVaultTimeoutError';
+    Object.setPrototypeOf(this, SparkVaultTimeoutError.prototype);
+  }
+}
+
+export class TusUploadError extends SparkVaultMobileError {
+  readonly cause: Error | null;
+  readonly filename: string | null;
+  readonly fileSize: number | null;
+  readonly phase: 'create' | 'upload' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
+
+  constructor(
+    message: string,
+    options: {
+      cause?: Error | null;
+      httpStatus?: number | null;
+      filename?: string | null;
+      fileSize?: number | null;
+      phase?: TusUploadError['phase'];
+    } = {}
+  ) {
+    super(message, {
+      code: options.httpStatus ?? 'tus_upload_error',
+      statusCode: options.httpStatus ?? undefined,
+    });
+    this.name = 'TusUploadError';
+    this.cause = options.cause ?? null;
+    this.filename = options.filename ?? null;
+    this.fileSize = options.fileSize ?? null;
+    this.phase = options.phase ?? 'unknown';
+    Object.setPrototypeOf(this, TusUploadError.prototype);
+  }
+
+  static fromError(
+    error: Error,
+    context: { filename?: string; fileSize?: number; phase?: TusUploadError['phase'] }
+  ): TusUploadError {
+    const statusMatch = error.message.match(/(\d{3})/);
+    const httpStatus = statusMatch ? parseInt(statusMatch[1], 10) : null;
+    return new TusUploadError(error.message, {
+      cause: error,
+      httpStatus,
+      filename: context.filename,
+      fileSize: context.fileSize,
+      phase: context.phase ?? 'unknown',
+    });
+  }
+}

package/src/folders.ts

@@ -0,0 +1,76 @@
+import type { MobileHttpClient } from './http.js';
+import type {
+  CreateFolderRequest,
+  Folder,
+  FolderBreadcrumbItem,
+  ListFoldersResponse,
+  UpdateFolderRequest,
+} from './types.js';
+import { validateFolderId, validateIngotId, validateVaultId } from './validation.js';
+
+export class MobileFoldersClient {
+  private readonly http: MobileHttpClient;
+
+  constructor(http: MobileHttpClient) {
+    this.http = http;
+  }
+
+  async list(vaultId: string, vat: string): Promise<ListFoldersResponse> {
+    validateVaultId(vaultId);
+    const response = await this.http.get<ListFoldersResponse>(`/vaults/${vaultId}/folders`, { vat });
+    return response.data;
+  }
+
+  async get(vaultId: string, folderId: string, vat: string): Promise<Folder> {
+    validateVaultId(vaultId);
+    validateFolderId(folderId);
+    const response = await this.http.get<Folder>(`/vaults/${vaultId}/folders/${folderId}`, { vat });
+    return response.data;
+  }
+
+  async getBreadcrumb(vaultId: string, folderId: string, vat: string): Promise<FolderBreadcrumbItem[]> {
+    validateVaultId(vaultId);
+    validateFolderId(folderId);
+    const response = await this.http.get<{ breadcrumb: FolderBreadcrumbItem[] }>(
+      `/vaults/${vaultId}/folders/${folderId}/breadcrumb`,
+      { vat }
+    );
+    return response.data.breadcrumb;
+  }
+
+  async create(vaultId: string, vat: string, data: CreateFolderRequest): Promise<Folder> {
+    validateVaultId(vaultId);
+    const response = await this.http.post<Folder>(`/vaults/${vaultId}/folders`, data, { vat });
+    return response.data;
+  }
+
+  async update(vaultId: string, folderId: string, vat: string, data: UpdateFolderRequest): Promise<Folder> {
+    validateVaultId(vaultId);
+    validateFolderId(folderId);
+    const response = await this.http.patch<Folder>(`/vaults/${vaultId}/folders/${folderId}`, data, { vat });
+    return response.data;
+  }
+
+  async move(vaultId: string, folderId: string, vat: string, newParentId: string | null): Promise<Folder> {
+    return this.update(vaultId, folderId, vat, { parent_id: newParentId });
+  }
+
+  async togglePin(vaultId: string, folderId: string, vat: string, pinned: boolean): Promise<Folder> {
+    return this.update(vaultId, folderId, vat, { pinned });
+  }
+
+  async delete(vaultId: string, folderId: string, vat: string): Promise<void> {
+    validateVaultId(vaultId);
+    validateFolderId(folderId);
+    await this.http.delete(`/vaults/${vaultId}/folders/${folderId}`, { vat });
+  }
+
+  async moveIngot(vaultId: string, ingotId: string, vat: string, folderId: string | null): Promise<void> {
+    validateVaultId(vaultId);
+    validateIngotId(ingotId);
+    if (folderId !== null) {
+      validateFolderId(folderId);
+    }
+    await this.http.patch(`/vaults/${vaultId}/ingots/${ingotId}`, { folder_id: folderId }, { vat });
+  }
+}

package/src/health.ts

@@ -0,0 +1,81 @@
+import type { ResolvedMobileConfig } from './config.js';
+
+export interface HealthCheckOptions {
+  timeoutMs?: number;
+}
+
+export interface HealthCheckResult {
+  online: boolean;
+  status: string;
+  httpStatus?: number;
+  checkedAt: number;
+  error?: string;
+}
+
+export class MobileHealthClient {
+  private readonly config: ResolvedMobileConfig;
+
+  constructor(config: ResolvedMobileConfig) {
+    this.config = config;
+  }
+
+  async check(options: HealthCheckOptions = {}): Promise<HealthCheckResult> {
+    const checkedAt = Math.floor(Date.now() / 1000);
+
+    try {
+      const response = await this.config.fetch(this.healthUrl(), {
+        method: 'GET',
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': this.config.userAgent,
+        },
+        timeoutMs: options.timeoutMs ?? this.config.timeoutMs,
+      });
+
+      return {
+        online: response.ok,
+        status: response.ok ? await this.readStatus(response) : 'unhealthy',
+        httpStatus: response.status,
+        checkedAt,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.config.logger.debug('Health check failed', { error: message });
+      return {
+        online: false,
+        status: 'unreachable',
+        checkedAt,
+        error: message,
+      };
+    }
+  }
+
+  async isOnline(options: HealthCheckOptions = {}): Promise<boolean> {
+    const result = await this.check(options);
+    return result.online;
+  }
+
+  private healthUrl(): string {
+    return `${this.config.apiBaseUrl.replace(/\/v1$/, '')}/health`;
+  }
+
+  private async readStatus(response: Response): Promise<string> {
+    try {
+      const body = await response.json();
+      const data = typeof body === 'object' && body !== null && 'data' in body
+        ? (body as { data?: unknown }).data
+        : body;
+
+      if (typeof data === 'object' && data !== null) {
+        const status = (data as { status?: unknown }).status;
+        if (typeof status === 'string' && status) {
+          return status;
+        }
+      }
+    } catch {
+      return response.ok ? 'healthy' : 'unhealthy';
+    }
+
+    return response.ok ? 'healthy' : 'unhealthy';
+  }
+}