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

package/src/ApiClient/WebSocketClient/normalize.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 {
+  AuthenticatedEvent,
+  BalanceUpdateEvent,
+  Balances,
+  ChangeNetworkEvent,
+  ToastMessageEvent
+} from './events';
+import {
+  RawAuthenticated,
+  RawBalanceUpdate,
+  RawBalanceV1Tokens,
+  RawBalanceV2Tokens,
+  RawChangeNetwork,
+  RawToastMessage
+} from './wireTypes';
+
+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 } : {})
+  };
+}

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,63 @@
+/**
+ * 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;
+}

package/src/ApiClient/index.ts

@@ -0,0 +1,134 @@
+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 _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._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;
+  }
+
+  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.disconnect();
+    this._socket.removeAllListeners();
+    this._auth.removeAllListeners();
+    this.removeAllListeners();
+    this._auth.clear();
+  }
+}
+
+export default ApiClient;

package/src/index.ts

@@ -0,0 +1,141 @@
+import AccountApi from './Account';
+import { AccountSnapshot, Balances, MeData } from './Account/types';
+import ApiClient, { ApiError, ApiErrorResponse, ApiResponse } from './ApiClient';
+import { SupernetType } from './ApiClient/WebSocketClient/types';
+import {
+  AuthenticatedEvent,
+  BalanceUpdateEvent,
+  ChangeNetworkEvent,
+  ConnectedEvent,
+  DisconnectedEvent,
+  ToastMessageEvent
+} from './ApiClient/WebSocketClient/events';
+import { DefaultLogger, Logger, LogLevel } from './lib/DefaultLogger';
+import { ApiKeyAuthManager, AuthStorage, TokenAuthData, TokenAuthManager } from './lib/AuthManager';
+import ErrorData from './types/ErrorData';
+import { TokenType } from './types/token';
+import { LIB_VERSION } from './version';
+
+export type {
+  AccountSnapshot,
+  ApiErrorResponse,
+  ApiResponse,
+  AuthenticatedEvent,
+  AuthStorage,
+  Balances,
+  BalanceUpdateEvent,
+  ChangeNetworkEvent,
+  ConnectedEvent,
+  DisconnectedEvent,
+  ErrorData,
+  Logger,
+  LogLevel,
+  MeData,
+  SupernetType,
+  ToastMessageEvent,
+  TokenAuthData,
+  TokenType
+};
+export { ApiError, ApiKeyAuthManager, LIB_VERSION };
+
+export interface SogniClientConfig {
+  /** Unique application ID. Multiple connections with the same ID will be rejected by the server. */
+  appId: string;
+  /** Optional source label for server-side attribution. */
+  appSource?: string;
+  /** Override the default REST API endpoint. Internal use. */
+  restEndpoint?: string;
+  /** Override the default WebSocket endpoint. Internal use. */
+  socketEndpoint?: string;
+  /** Which Supernet to connect to. Defaults to 'fast'. */
+  network?: SupernetType;
+  /** Connect to testnet instead of mainnet. */
+  testnet?: boolean;
+  /** API key for authentication. When provided, the client uses API key auth. */
+  apiKey?: string;
+  /** Authentication type. Defaults to 'token'. Forced to 'apiKey' when apiKey is provided. */
+  authType?: 'token' | 'apiKey';
+  /** Logger instance. Defaults to a console-backed logger at logLevel. */
+  logger?: Logger;
+  /** Log level for the default logger. Ignored if a custom logger is provided. */
+  logLevel?: LogLevel;
+  /** Custom storage adapter for token persistence. Defaults to expo-secure-store. */
+  authStorage?: AuthStorage;
+  /** Disable the WebSocket connection. Most APIs will not work without it. */
+  disableSocket?: boolean;
+}
+
+function assertCryptoPolyfill(): void {
+  if (
+    typeof globalThis.crypto === 'undefined' ||
+    typeof globalThis.crypto.getRandomValues !== 'function'
+  ) {
+    throw new Error(
+      "@sogni-ai/expo-client requires crypto.getRandomValues. Add `import 'expo-standard-web-crypto/polyfill'` at your app entry point (e.g. app/_layout.tsx). See README for details."
+    );
+  }
+}
+
+export class SogniClient {
+  apiClient: ApiClient;
+  account: AccountApi;
+
+  private constructor(client: ApiClient) {
+    this.apiClient = client;
+    this.account = new AccountApi(client);
+  }
+
+  get isAuthenticated(): boolean {
+    return this.apiClient.isAuthenticated;
+  }
+
+  /**
+   * For token-based auth, restore a session from refresh+access tokens.
+   * Typically called once at app startup; the SDK also auto-restores from
+   * secure storage in `create()`, so this is only needed when migrating
+   * tokens from another source.
+   */
+  async setTokens(tokens: TokenAuthData): Promise<void> {
+    const auth = this.apiClient.auth;
+    if (!(auth instanceof TokenAuthManager)) {
+      throw new Error('setTokens can only be used with token authentication');
+    }
+    await auth.authenticate(tokens);
+  }
+
+  /** Disconnect and tear down resources. Instance should not be reused after dispose(). */
+  dispose() {
+    this.apiClient.dispose();
+  }
+
+  static async create(config: SogniClientConfig): Promise<SogniClient> {
+    assertCryptoPolyfill();
+
+    const restEndpoint = config.restEndpoint || 'https://api.sogni.ai';
+    const socketEndpoint = config.socketEndpoint || 'wss://socket.sogni.ai';
+    const network: SupernetType = config.network || 'fast';
+    const logger = config.logger || new DefaultLogger(config.logLevel || 'warn');
+    const authType: 'token' | 'apiKey' = config.apiKey ? 'apiKey' : config.authType || 'token';
+
+    const apiClient = new ApiClient({
+      baseUrl: restEndpoint,
+      socketUrl: socketEndpoint,
+      appId: config.appId,
+      appSource: config.appSource,
+      networkType: network,
+      authType,
+      logger,
+      authStorage: config.authStorage,
+      disableSocket: config.disableSocket
+    });
+
+    if (config.apiKey) {
+      const auth = apiClient.auth as ApiKeyAuthManager;
+      await auth.authenticate(config.apiKey);
+    } else if (apiClient.auth instanceof TokenAuthManager) {
+      await apiClient.auth.restore();
+    }
+
+    return new SogniClient(apiClient);
+  }
+}

package/src/lib/AuthManager/ApiKeyAuthManager.ts

@@ -0,0 +1,52 @@
+import AuthManagerBase from './AuthManagerBase';
+import { Logger } from '../DefaultLogger';
+import { SocketAuthData } from '../../ApiClient/WebSocketClient/types';
+
+class ApiKeyAuthManager extends AuthManagerBase<string | null> {
+  private _apiKey?: string;
+
+  constructor(logger: Logger) {
+    super(logger);
+  }
+
+  get isAuthenticated() {
+    return !!this._apiKey;
+  }
+
+  async authenticate(apiKey: string): Promise<void> {
+    if (this._apiKey === apiKey) {
+      return;
+    }
+    this._apiKey = apiKey;
+    this.emit('updated', true);
+  }
+
+  clear() {
+    if (!this._apiKey) {
+      return;
+    }
+    this._apiKey = undefined;
+    this.emit('updated', false);
+  }
+
+  async backup(): Promise<string | null> {
+    return this._apiKey || null;
+  }
+
+  async authenticateRequest(options: RequestInit): Promise<RequestInit> {
+    if (!this._apiKey) {
+      return options;
+    }
+    return {
+      ...options,
+      headers: { ...options.headers, 'api-key': this._apiKey }
+    };
+  }
+
+  async socketAuth(): Promise<SocketAuthData> {
+    if (!this._apiKey) return {};
+    return { queryParams: { apiKey: this._apiKey } };
+  }
+}
+
+export default ApiKeyAuthManager;

package/src/lib/AuthManager/AuthManagerBase.ts

@@ -0,0 +1,35 @@
+import { Logger } from '../DefaultLogger';
+import TypedEventEmitter from '../TypedEventEmitter';
+import { SocketAuthData } from '../../ApiClient/WebSocketClient/types';
+
+interface AuthManagerEvents {
+  updated: boolean;
+}
+
+abstract class AuthManagerBase<AuthData = never> extends TypedEventEmitter<AuthManagerEvents> {
+  protected _logger: Logger;
+
+  constructor(logger: Logger) {
+    super();
+    this._logger = logger;
+  }
+
+  abstract get isAuthenticated(): boolean;
+
+  abstract authenticateRequest(option: RequestInit): Promise<RequestInit>;
+
+  /**
+   * Describe how to authenticate the WebSocket upgrade request. May return
+   * headers (preferred for JWT tokens), query params (preferred for API keys),
+   * or both. Empty object means unauthenticated.
+   */
+  abstract socketAuth(): Promise<SocketAuthData>;
+
+  abstract backup(): Promise<AuthData>;
+
+  abstract authenticate(data: AuthData): Promise<void>;
+
+  abstract clear(): void;
+}
+
+export default AuthManagerBase;

package/src/lib/AuthManager/AuthStorage.ts

@@ -0,0 +1,21 @@
+import * as SecureStore from 'expo-secure-store';
+
+export interface AuthStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+export class ExpoSecureStorage implements AuthStorage {
+  async getItem(key: string): Promise<string | null> {
+    return SecureStore.getItemAsync(key);
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    await SecureStore.setItemAsync(key, value);
+  }
+
+  async removeItem(key: string): Promise<void> {
+    await SecureStore.deleteItemAsync(key);
+  }
+}