@sogni-ai/expo-client 1.0.0-alpha.10

package/src/ApiClient/WebSocketClient/normalize.ts

@@ -0,0 +1,287 @@
+/**
+ * The ONLY place where wire-level message shapes are translated into clean
+ * public types. Every quirk in the sogni-socket protocol gets masked here so
+ * the rest of the SDK and downstream apps never see them.
+ *
+ * Authoritative wire source:
+ *   ../sogni-socket/controllers/jobsController.js
+ *   ../sogni-socket/controllers/websocketsController.js
+ *
+ * Known quirks masked (catalog grows as later phases add events):
+ *   - `jobID` on the wire is actually the PROJECT id (Phase 3)
+ *   - `imgID` on the wire is actually the JOB id (Phase 3)
+ *   - `error_message` is snake_case in an otherwise camelCase API (Phase 3)
+ *   - `balanceUpdate` arrives in two shapes (v1 flat, v2 nested) — always
+ *     normalized to v2 here.
+ *   - `authenticated.tokens` similarly v1/v2 — normalized to v2.
+ */
+
+import {
+  ArtistCancelConfirmationEvent,
+  AuthenticatedEvent,
+  BalanceUpdateEvent,
+  Balances,
+  ChangeNetworkEvent,
+  ChatErrorEvent,
+  ChatResultEvent,
+  ChatTokensEvent,
+  JobErrorEvent,
+  JobETAEvent,
+  JobInitiatingModelEvent,
+  JobLifecycleCompletedEvent,
+  JobProgressEvent,
+  JobResultEvent,
+  JobStartedEvent,
+  SwarmLLMModelsEvent,
+  ToastMessageEvent
+} from './events';
+import { LLMModelInfo } from '../../Chat/types';
+import {
+  RawArtistCancelConfirmation,
+  RawAuthenticated,
+  RawBalanceUpdate,
+  RawBalanceV1Tokens,
+  RawBalanceV2Tokens,
+  RawChangeNetwork,
+  RawJobError,
+  RawJobETA,
+  RawJobProgress,
+  RawJobResult,
+  RawJobState,
+  RawJobTokens,
+  RawLLMJobError,
+  RawLLMJobResult,
+  RawSwarmLLMModels,
+  RawToastMessage
+} from './wireTypes';
+import { JobErrorReason } from '../../Projects/types';
+
+function isV2Tokens(t: RawBalanceUpdate): t is RawBalanceV2Tokens {
+  return (
+    typeof t === 'object' && t !== null && 'sogni' in t && 'spark' in (t as RawBalanceV2Tokens)
+  );
+}
+
+function normalizeBalanceTokens(raw: RawBalanceUpdate): Balances {
+  if (isV2Tokens(raw)) {
+    return {
+      sogni: {
+        settled: String(raw.sogni.settled ?? '0'),
+        credit: String(raw.sogni.credit ?? '0'),
+        debit: String(raw.sogni.debit ?? '0'),
+        net: String(raw.sogni.net ?? '0')
+      },
+      spark: {
+        settled: String(raw.spark.settled ?? '0'),
+        credit: String(raw.spark.credit ?? '0'),
+        debit: String(raw.spark.debit ?? '0'),
+        net: String(raw.spark.net ?? '0'),
+        premiumCredit: String(raw.spark.premiumCredit ?? '0')
+      }
+    };
+  }
+  // v1 → synthesize v2 wrapper with empty spark
+  const v1 = raw as RawBalanceV1Tokens;
+  return {
+    sogni: {
+      settled: String(v1.settled ?? '0'),
+      credit: String(v1.credit ?? '0'),
+      debit: String(v1.debit ?? '0'),
+      net: String(v1.net ?? '0')
+    },
+    spark: {
+      settled: '0',
+      credit: '0',
+      debit: '0',
+      net: '0',
+      premiumCredit: '0'
+    }
+  };
+}
+
+export function normalizeAuthenticated(raw: RawAuthenticated): AuthenticatedEvent {
+  return {
+    username: raw.username,
+    walletAddress: raw.address,
+    balance: normalizeBalanceTokens(raw.tokens),
+    isMainnet: !!raw.isMainnet,
+    accountWasMigrated: !!raw.accountWasMigrated,
+    hasUnclaimedAirdrop: !!raw.hasUnclaimedAirdrop,
+    firstLoginAfterMigration: !!raw.firstLoginAfterMigration
+  };
+}
+
+export function normalizeBalanceUpdate(raw: RawBalanceUpdate): BalanceUpdateEvent {
+  return { balance: normalizeBalanceTokens(raw) };
+}
+
+export function normalizeChangeNetwork(raw: RawChangeNetwork): ChangeNetworkEvent {
+  return { network: raw.network };
+}
+
+export function normalizeToastMessage(raw: RawToastMessage): ToastMessageEvent {
+  return {
+    level: raw.type,
+    message: raw.message,
+    ...(raw.stickyID ? { stickyID: raw.stickyID } : {})
+  };
+}
+
+/* ============================================================================
+ * Project / job lifecycle normalizers.
+ *   - wire `jobID` -> `projectId` (uppercased on both sides)
+ *   - wire `imgID` -> `jobId`
+ *   - wire `error_message` -> `errorMessage`
+ *   - mixed casing on error reasons normalized to one spelling, with the raw
+ *     code preserved in `rawCode` for forward compat
+ * ========================================================================== */
+
+const upper = (s: string | undefined | null) => (s ? s.toUpperCase() : null);
+
+export type NormalizedJobState =
+  | { kind: 'jobStarted'; event: JobStartedEvent }
+  | { kind: 'jobInitiatingModel'; event: JobInitiatingModelEvent }
+  | { kind: 'jobLifecycleCompleted'; event: JobLifecycleCompletedEvent };
+
+/** Split the composite jobState message into distinct typed events. */
+export function normalizeJobState(raw: RawJobState): NormalizedJobState | null {
+  const projectId = upper(raw.jobID);
+  if (!projectId) return null;
+  const jobId = upper(raw.imgID);
+  switch (raw.type) {
+    case 'jobStarted':
+      return {
+        kind: 'jobStarted',
+        event: { projectId, jobId, workerName: raw.workerName ?? null }
+      };
+    case 'initiatingModel':
+      return { kind: 'jobInitiatingModel', event: { projectId, jobId } };
+    case 'jobCompleted':
+      return { kind: 'jobLifecycleCompleted', event: { projectId, jobId } };
+    default:
+      return null;
+  }
+}
+
+export function normalizeJobProgress(raw: RawJobProgress): JobProgressEvent | null {
+  const projectId = upper(raw.jobID);
+  const jobId = upper(raw.imgID);
+  if (!projectId || !jobId) return null;
+  const stepCount = Math.max(0, raw.stepCount ?? 0);
+  const step = Math.max(0, raw.step ?? 0);
+  const progress = stepCount > 0 ? Math.min(1, step / stepCount) : 0;
+  return { projectId, jobId, progress, step, stepCount };
+}
+
+export function normalizeJobResult(raw: RawJobResult): JobResultEvent | null {
+  const projectId = upper(raw.jobID);
+  const jobId = upper(raw.imgID);
+  if (!projectId || !jobId) return null;
+  return {
+    projectId,
+    jobId,
+    seed: raw.lastSeed,
+    performedStepCount: raw.performedStepCount,
+    userCanceled: !!raw.userCanceled,
+    triggeredNSFWFilter: !!raw.triggeredNSFWFilter
+  };
+}
+
+const ERROR_REASON_MAP: Record<string, JobErrorReason> = {
+  serverRestarting: 'serverRestarting',
+  workerDisconnected: 'workerDisconnected',
+  jobTimedOut: 'jobTimedOut',
+  artistCanceled: 'artistCanceled',
+  workerCancelled: 'workerCanceled',
+  workerCanceled: 'workerCanceled',
+  sensitiveContent: 'sensitiveContent',
+  imgUploadFailure: 'imgUploadFailure',
+  imgDownloadFailure: 'imgDownloadFailure'
+};
+
+export function normalizeJobError(raw: RawJobError): JobErrorEvent | null {
+  const projectId = upper(raw.jobID);
+  if (!projectId) return null;
+  return {
+    projectId,
+    jobId: upper(raw.imgID),
+    reason: ERROR_REASON_MAP[raw.error] ?? 'unknown',
+    rawCode: raw.error,
+    message: raw.error_message,
+    source: raw.isFromWorker ? 'worker' : 'server'
+  };
+}
+
+export function normalizeJobETA(raw: RawJobETA): JobETAEvent | null {
+  const projectId = upper(raw.jobID);
+  const jobId = upper(raw.imgID);
+  if (!projectId || !jobId) return null;
+  return { projectId, jobId, etaSeconds: Number(raw.etaSeconds ?? 0) };
+}
+
+export function normalizeArtistCancelConfirmation(
+  raw: RawArtistCancelConfirmation
+): ArtistCancelConfirmationEvent | null {
+  const projectId = upper(raw.jobID);
+  if (!projectId) return null;
+  return {
+    projectId,
+    didCancel: !!raw.didCancel,
+    ...(raw.error_message ? { errorMessage: raw.error_message } : {})
+  };
+}
+
+/* === LLM (chat) ===
+ * Chat jobs have only one ID (the completion's jobID — no project/job hierarchy).
+ * We just rename to camelCase. */
+
+export function normalizeChatTokens(raw: RawJobTokens): ChatTokensEvent | null {
+  const jobId = upper(raw.jobID);
+  if (!jobId) return null;
+  return {
+    jobId,
+    content: raw.content ?? '',
+    role: raw.role,
+    finishReason: raw.finishReason ?? null,
+    usage: raw.usage,
+    tool_calls: raw.tool_calls
+  };
+}
+
+export function normalizeChatResult(raw: RawLLMJobResult): ChatResultEvent | null {
+  const jobId = upper(raw.jobID);
+  if (!jobId) return null;
+  return {
+    jobId,
+    usage: raw.usage,
+    timeTaken: raw.timeTaken,
+    ...(raw.workerName ? { workerName: raw.workerName } : {})
+  };
+}
+
+export function normalizeChatError(raw: RawLLMJobError): ChatErrorEvent | null {
+  const jobId = upper(raw.jobID);
+  if (!jobId) return null;
+  return {
+    jobId,
+    rawCode: raw.error,
+    message: raw.error_message,
+    ...(raw.workerName ? { workerName: raw.workerName } : {})
+  };
+}
+
+export function normalizeSwarmLLMModels(raw: RawSwarmLLMModels): SwarmLLMModelsEvent {
+  const models: Record<string, LLMModelInfo> = {};
+  for (const [modelId, value] of Object.entries(raw || {})) {
+    if (typeof value === 'number') {
+      models[modelId] = { workers: value };
+    } else if (value && typeof value === 'object') {
+      models[modelId] = {
+        workers: value.workers ?? 0,
+        ...(value.displayName ? { displayName: value.displayName } : {}),
+        ...(value.contextLength ? { contextLength: value.contextLength } : {})
+      };
+    }
+  }
+  return { models };
+}

package/src/ApiClient/WebSocketClient/types.ts

@@ -0,0 +1,10 @@
+export type SupernetType = 'fast' | 'relaxed';
+
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
+
+export interface SocketAuthData {
+  /** Headers sent in the WebSocket upgrade request. */
+  headers?: Record<string, string>;
+  /** Query string parameters appended to the WebSocket URL. */
+  queryParams?: Record<string, string>;
+}

package/src/ApiClient/WebSocketClient/wireTypes.ts

@@ -0,0 +1,183 @@
+/**
+ * Wire-level message shapes as the sogni-socket server sends them.
+ * These are NOT exposed to consumers. They are translated into clean public
+ * types by `normalize.ts`.
+ *
+ * Authoritative source: ../sogni-socket/controllers/jobsController.js and
+ * ../sogni-socket/controllers/websocketsController.js.
+ */
+
+/** Envelope wrapping all socket messages in both directions. */
+export interface RawSocketEnvelope {
+  type: string;
+  /** base64-encoded JSON.stringify(payload) */
+  data: string;
+}
+
+/** `authenticated` event — sent right after the server upgrades a connection. */
+export interface RawAuthenticated {
+  id: string;
+  clientType: string;
+  username: string;
+  address: string;
+  SID: number;
+  clientSID: number;
+  addressSID: number;
+  balanceVersion?: 1 | 2;
+  /** v1: BigNumber/string; v2: { sogni, spark } */
+  tokens: RawBalanceV1Tokens | RawBalanceV2Tokens;
+  activeProjects: string[];
+  unclaimedCompletedProjects: string[];
+  isMainnet: boolean;
+  accountWasMigrated: boolean;
+  hasUnclaimedAirdrop: boolean;
+  firstLoginAfterMigration: boolean;
+}
+
+export interface RawBalanceV1Tokens {
+  settled: string;
+  credit: string;
+  debit: string;
+  net: string;
+}
+
+export interface RawBalanceV2Tokens {
+  sogni: RawBalanceV1Tokens & { premiumCredit?: string };
+  spark: RawBalanceV1Tokens & { premiumCredit?: string };
+}
+
+/** `balanceUpdate` event — fired when the user's balance changes. */
+export type RawBalanceUpdate = RawBalanceV1Tokens | RawBalanceV2Tokens;
+
+/** `changeNetwork` event — confirms a network switch. */
+export interface RawChangeNetwork {
+  network: 'fast' | 'relaxed';
+}
+
+/** `toastMessage` event — server-initiated UI message. */
+export interface RawToastMessage {
+  type: 'info' | 'success' | 'warning' | 'error';
+  message: string;
+  autoClose?: number;
+  stickyID?: string;
+}
+
+/* ============================================================================
+ * Project / job lifecycle events. ALL of these use:
+ *   - `jobID` (uppercase) to mean the PROJECT id
+ *   - `imgID` (uppercase) to mean the JOB id (one image within the project)
+ * `normalize.ts` masks this so the rest of the SDK never sees the rename.
+ * ========================================================================== */
+
+/** `jobState` event — composite. `type` field carries the actual sub-state. */
+export interface RawJobState {
+  jobID: string;
+  imgID?: string;
+  type: 'jobStarted' | 'initiatingModel' | 'jobCompleted';
+  workerName?: string;
+  queuePosition?: number;
+}
+
+/** `jobProgress` event — fine-grained step/stepCount progress. */
+export interface RawJobProgress {
+  jobID: string;
+  imgID: string;
+  step: number;
+  stepCount: number;
+  /** Optional preview image bytes — ignored in this SDK. */
+  currentImages?: unknown[];
+}
+
+/**
+ * `jobResult` event — terminal result for one job in a project.
+ * Note that `userCanceled` and `triggeredNSFWFilter` flags signal failure paths
+ * even though the message type is "result". Normalize splits these out.
+ */
+export interface RawJobResult {
+  jobID: string;
+  imgID: string;
+  lastSeed: number;
+  userCanceled: boolean;
+  triggeredNSFWFilter: boolean;
+  performedStepCount: number;
+  interval?: number;
+  itsPerSecond?: number;
+  timings?: Record<string, number>;
+}
+
+/** `jobError` event. */
+export interface RawJobError {
+  jobID: string;
+  imgID?: string;
+  error: string;
+  error_message: string;
+  isFromWorker: boolean;
+}
+
+/** `jobETA` event — server's running estimate of remaining seconds. */
+export interface RawJobETA {
+  jobID: string;
+  imgID: string;
+  etaSeconds: number;
+}
+
+/** `artistCancelConfirmation` — sent after the artist requests a project cancel. */
+export interface RawArtistCancelConfirmation {
+  jobID: string;
+  didCancel: boolean;
+  error_message?: string;
+}
+
+/* ============================================================================
+ * LLM (chat) events. Unlike image/video projects, chat jobs only have a single
+ * job ID — there's no project/job hierarchy. The wire `jobID` here is the
+ * completion identifier used to route streaming tokens back to the caller.
+ * ========================================================================== */
+
+export interface RawToolCallDelta {
+  index: number;
+  id?: string;
+  type?: 'function';
+  function?: { name?: string; arguments?: string };
+}
+
+/** `jobTokens` — streaming chunk from an LLM completion. */
+export interface RawJobTokens {
+  jobID: string;
+  content?: string;
+  role?: string;
+  finishReason?: string | null;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens?: number;
+  };
+  tool_calls?: RawToolCallDelta[];
+}
+
+/** `llmJobResult` — terminal result for an LLM completion. */
+export interface RawLLMJobResult {
+  jobID: string;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens?: number;
+  };
+  timeTaken: number;
+  workerName?: string;
+  cost?: unknown;
+}
+
+/** `llmJobError` — terminal error for an LLM completion. */
+export interface RawLLMJobError {
+  jobID: string;
+  error: string;
+  error_message: string;
+  workerName?: string;
+}
+
+/** `swarmLLMModels` — available LLM models on the active network. */
+export type RawSwarmLLMModels = Record<
+  string,
+  number | { workers: number; displayName?: string; contextLength?: number }
+>;

package/src/ApiClient/index.ts

@@ -0,0 +1,147 @@
+import RestClient from '../lib/RestClient';
+import TypedEventEmitter from '../lib/TypedEventEmitter';
+import { JSONValue } from '../types/json';
+import { Logger } from '../lib/DefaultLogger';
+import { ApiKeyAuthManager, AuthManager, AuthStorage, TokenAuthManager } from '../lib/AuthManager';
+import WebSocketClient from './WebSocketClient';
+import { SupernetType } from './WebSocketClient/types';
+import { ConnectedEvent, DisconnectedEvent } from './WebSocketClient/events';
+
+export interface ApiResponse<D = JSONValue> {
+  status: 'success';
+  data: D;
+}
+
+export interface ApiErrorResponse {
+  status: 'error';
+  message: string;
+  errorCode: number;
+}
+
+export class ApiError extends Error {
+  status: number;
+  payload: ApiErrorResponse;
+  constructor(status: number, payload: ApiErrorResponse) {
+    super(payload.message);
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+interface ApiClientEvents {
+  authUpdated: boolean;
+  connected: ConnectedEvent;
+  disconnected: DisconnectedEvent;
+}
+
+export interface ApiClientOptions {
+  baseUrl: string;
+  socketUrl: string;
+  appId: string;
+  appSource?: string;
+  networkType: SupernetType;
+  logger: Logger;
+  authType: 'token' | 'apiKey';
+  authStorage?: AuthStorage;
+  disableSocket?: boolean;
+}
+
+class ApiClient extends TypedEventEmitter<ApiClientEvents> {
+  readonly appId: string;
+  readonly appSource?: string;
+  readonly logger: Logger;
+  private _rest: RestClient;
+  private _socketRest: RestClient;
+  private _auth: AuthManager;
+  private _socket: WebSocketClient;
+  private _disableSocket: boolean;
+
+  constructor({
+    baseUrl,
+    socketUrl,
+    appId,
+    appSource,
+    networkType,
+    authType,
+    logger,
+    authStorage,
+    disableSocket = false
+  }: ApiClientOptions) {
+    super();
+    this.appId = appId;
+    this.appSource = appSource?.trim() || undefined;
+    this.logger = logger;
+    this._disableSocket = disableSocket;
+    if (authType === 'apiKey') {
+      this._auth = new ApiKeyAuthManager(logger);
+    } else {
+      this._auth = new TokenAuthManager(baseUrl, logger, authStorage);
+    }
+    this._rest = new RestClient(baseUrl, this._auth, logger);
+    this._socketRest = new RestClient(normalizeHttpUrl(socketUrl), this._auth, logger);
+    this._socket = new WebSocketClient(
+      socketUrl,
+      this._auth,
+      appId,
+      networkType,
+      logger,
+      this.appSource
+    );
+    this._auth.on('updated', (isAuthenticated) => {
+      this.emit('authUpdated', isAuthenticated);
+      this._handleAuthUpdated(isAuthenticated);
+    });
+    this._socket.on('connected', (e) => this.emit('connected', e));
+    this._socket.on('disconnected', (e) => this.emit('disconnected', e));
+  }
+
+  get isAuthenticated(): boolean {
+    return this._auth.isAuthenticated;
+  }
+
+  get auth(): AuthManager {
+    return this._auth;
+  }
+
+  get rest(): RestClient {
+    return this._rest;
+  }
+
+  /** REST client bound to the socket server URL (used for model lists, image upload/download URLs, etc.). */
+  get socketRest(): RestClient {
+    return this._socketRest;
+  }
+
+  get socket(): WebSocketClient {
+    return this._socket;
+  }
+
+  get socketEnabled(): boolean {
+    return !this._disableSocket;
+  }
+
+  private _handleAuthUpdated(isAuthenticated: boolean) {
+    if (this._disableSocket) return;
+    if (isAuthenticated && !this._socket.isConnected) {
+      void this._socket.connect();
+    } else if (!isAuthenticated && this._socket.isConnected) {
+      this._socket.disconnect();
+    }
+  }
+
+  dispose() {
+    this._socket.dispose();
+    this._auth.removeAllListeners();
+    this.removeAllListeners();
+    this._auth.clear();
+  }
+}
+
+function normalizeHttpUrl(url: string): string {
+  const u = new URL(url);
+  if (u.protocol === 'http:' || u.protocol === 'ws:') u.protocol = 'http:';
+  else u.protocol = 'https:';
+  return u.toString();
+}
+
+export default ApiClient;