@sogni-ai/sogni-client 4.2.0-alpha.2 → 4.2.0-alpha.21

package/src/Account/index.ts

@@ -133,7 +133,15 @@ class AccountApi extends ApiGroup {
    * @internal
    */
   async create(
-    { username, email, password, subscribe, turnstileToken, referralCode }: AccountCreateParams,
+    {
+      username,
+      email,
+      password,
+      subscribe,
+      turnstileToken,
+      referralCode,
+      appSource
+    }: AccountCreateParams,
     rememberMe = false
   ): Promise<AccountCreateData> {
     const wallet = this.getWallet(username, password);
@@ -146,9 +154,11 @@ class AccountApi extends ApiGroup {
       walletAddress: wallet.address,
       turnstileToken
     };
+    const resolvedAppSource = appSource?.trim() || this.client.appSource;
     const signature = await this.eip712.signTypedData(wallet, 'signup', { ...payload, nonce });
     const res = await this.client.rest.post<ApiResponse<AccountCreateData>>('/v1/account/create', {
       ...payload,
+      ...(resolvedAppSource ? { appSource: resolvedAppSource } : {}),
       referralCode,
       signature,
       rememberMe
@@ -175,17 +185,26 @@ class AccountApi extends ApiGroup {
    * @param password
    * @param rememberMe - Whether to establish a long-lived session. Default is false. Only
    * applicable for cookie-based authentication.
+   * @param appSource - Optional client app/source label for login attribution. Defaults to the
+   * SogniClient connection appSource when configured.
    */
-  async login(username: string, password: string, rememberMe = false): Promise<LoginData> {
+  async login(
+    username: string,
+    password: string,
+    rememberMe = false,
+    appSource?: string
+  ): Promise<LoginData> {
     const wallet = this.getWallet(username, password);
     const nonce = await this.getNonce(wallet.address);
     const signature = await this.eip712.signTypedData(wallet, 'authentication', {
       walletAddress: wallet.address,
       nonce
     });
+    const resolvedAppSource = appSource?.trim() || this.client.appSource;
     const res = await this.client.rest.post<ApiResponse<LoginData>>('/v1/account/login', {
       walletAddress: wallet.address,
       signature,
+      ...(resolvedAppSource ? { appSource: resolvedAppSource } : {}),
       rememberMe
     });
     const auth = this.client.auth;
@@ -414,6 +433,7 @@ class AccountApi extends ApiGroup {
         tokenType: raw.tokenType,
         claimed: !!raw.claimed,
         canClaim: !!raw.canClaim,
+        cantClaimReason: raw.cantClaimReason ?? null,
         lastClaim: new Date(raw.lastClaimTimestamp * 1000),
         provider: query.provider || 'base',
         nextClaim:

package/src/Account/types.ts

@@ -11,6 +11,11 @@ export interface AccountCreateParams {
   subscribe: boolean;
   turnstileToken: string;
   referralCode?: string;
+  /**
+   * Optional client app/source label for signup attribution. Defaults to the
+   * SogniClient connection appSource when configured.
+   */
+  appSource?: string;
 }
 
 export interface AccountCreateData {
@@ -126,6 +131,7 @@ export interface RewardRaw {
   tokenType: TokenType;
   claimed: number;
   canClaim: number;
+  cantClaimReason?: 'already_claimed' | 'over_free_cap' | null;
   lastClaimTimestamp: number;
   claimResetFrequencySec: number;
 }
@@ -143,6 +149,7 @@ export interface Reward {
   tokenType: TokenType;
   claimed: boolean;
   canClaim: boolean;
+  cantClaimReason?: 'already_claimed' | 'over_free_cap' | null;
   lastClaim: Date;
   nextClaim: Date | null;
   provider?: string;

package/src/ApiClient/WebSocketClient/BrowserWebSocketClient/index.ts

@@ -6,6 +6,7 @@ import RestClient from '../../../lib/RestClient';
 import { SocketEventMap } from '../events';
 import { MessageType, SocketMessageMap } from '../messages';
 import ChannelCoordinator from './ChannelCoordinator';
+import type { SocketEventSubscriptionInput, SocketEventSubscriptions } from '../eventSubscriptions';
 
 interface SocketSend<T extends MessageType = MessageType> {
   type: 'socket-send';
@@ -25,7 +26,17 @@ interface SwitchNetwork {
   payload: SupernetType;
 }
 
-type Message = SocketConnect | SocketDisconnect | SocketSend | SwitchNetwork;
+interface SetSocketEventSubscriptions {
+  type: 'setSocketEventSubscriptions';
+  payload: SocketEventSubscriptionInput;
+}
+
+type Message =
+  | SocketConnect
+  | SocketDisconnect
+  | SocketSend
+  | SwitchNetwork
+  | SetSocketEventSubscriptions;
 
 interface EventNotification<T extends keyof SocketEventMap = keyof SocketEventMap> {
   type: 'socket-event';
@@ -70,9 +81,19 @@ class BrowserWebSocketClient extends RestClient<SocketEventMap> implements IWebS
     auth: AuthManager,
     appId: string,
     supernetType: SupernetType,
-    logger: Logger
+    logger: Logger,
+    appSource?: string,
+    socketEventSubscriptions?: SocketEventSubscriptions
   ) {
-    const socketClient = new WrappedClient(baseUrl, auth, appId, supernetType, logger);
+    const socketClient = new WrappedClient(
+      baseUrl,
+      auth,
+      appId,
+      supernetType,
+      logger,
+      appSource,
+      socketEventSubscriptions
+    );
     super(socketClient.baseUrl, auth, logger);
     this.socketClient = socketClient;
     this.appId = appId;
@@ -88,6 +109,14 @@ class BrowserWebSocketClient extends RestClient<SocketEventMap> implements IWebS
     });
     this.auth.on('updated', this.handleAuthUpdated.bind(this));
     this.socketClient.intercept(this.handleSocketEvent.bind(this));
+    // Keep this tab's WrappedClient subscription state in sync with the server's authoritative
+    // snapshot, even when this tab is currently a secondary. If we get promoted to primary, the
+    // next `connect()` will serialize the up-to-date state into the URL query string.
+    this.on('socketEventSubscriptionsUpdated', (payload) => {
+      if (payload && payload.socketEventSubscriptions) {
+        this.socketClient.socketEventSubscriptions = { ...payload.socketEventSubscriptions };
+      }
+    });
   }
 
   get isConnected() {
@@ -133,6 +162,17 @@ class BrowserWebSocketClient extends RestClient<SocketEventMap> implements IWebS
     return supernetType;
   }
 
+  async setSocketEventSubscriptions(update: SocketEventSubscriptionInput): Promise<void> {
+    await this.coordinator.isReady();
+    if (this.coordinator.isPrimary) {
+      return this.socketClient.setSocketEventSubscriptions(update);
+    }
+    return this.coordinator.sendMessage({
+      type: 'setSocketEventSubscriptions',
+      payload: update
+    });
+  }
+
   async send<T extends MessageType>(messageType: T, data: SocketMessageMap[T]): Promise<void> {
     await this.coordinator.isReady();
     if (this.coordinator.isPrimary) {
@@ -172,6 +212,10 @@ class BrowserWebSocketClient extends RestClient<SocketEventMap> implements IWebS
         await this.switchNetwork(message.payload);
         return;
       }
+      case 'setSocketEventSubscriptions': {
+        await this.socketClient.setSocketEventSubscriptions(message.payload);
+        return;
+      }
       default: {
         this._logger.error('Received unknown message type:', message);
       }

package/src/ApiClient/WebSocketClient/eventSubscriptions.ts

@@ -0,0 +1,92 @@
+import type { SocketEventName } from './events';
+
+export type SocketEventSubscriptionGroup = 'modelAvailability';
+
+export type SocketEventSubscriptionName =
+  | SocketEventName
+  | SocketEventSubscriptionGroup
+  | (string & {});
+
+export type SocketEventSubscriptions = Partial<
+  Record<SocketEventName | SocketEventSubscriptionGroup, boolean>
+> &
+  Record<string, boolean | undefined>;
+
+export interface SocketEventSubscriptionUpdate {
+  /**
+   * Replace or merge explicit event subscription flags.
+   */
+  subscriptions?: SocketEventSubscriptions;
+  /**
+   * Subscribe to one or more socket events or event groups.
+   */
+  subscribe?: SocketEventSubscriptionName | SocketEventSubscriptionName[];
+  /**
+   * Unsubscribe from one or more socket events or event groups.
+   */
+  unsubscribe?: SocketEventSubscriptionName | SocketEventSubscriptionName[];
+  /**
+   * Clear existing server-side subscription overrides before applying this update.
+   */
+  reset?: boolean;
+  /**
+   * Single-event update shorthand.
+   */
+  event?: SocketEventSubscriptionName;
+  /**
+   * Boolean value for the single-event update shorthand.
+   */
+  enabled?: boolean;
+}
+
+export type SocketEventSubscriptionInput = SocketEventSubscriptions | SocketEventSubscriptionUpdate;
+
+const UPDATE_KEYS = new Set([
+  'subscriptions',
+  'subscribe',
+  'unsubscribe',
+  'reset',
+  'event',
+  'enabled'
+]);
+
+function hasUpdateShape(input: Record<string, unknown>): boolean {
+  return Object.keys(input).some((key) => UPDATE_KEYS.has(key));
+}
+
+function normalizeSubscriptions(
+  subscriptions?: SocketEventSubscriptions
+): SocketEventSubscriptions | undefined {
+  if (!subscriptions || typeof subscriptions !== 'object') {
+    return undefined;
+  }
+
+  const normalized: SocketEventSubscriptions = {};
+  for (const [eventName, enabled] of Object.entries(subscriptions)) {
+    if (typeof enabled === 'boolean') {
+      normalized[eventName] = enabled;
+    }
+  }
+  return Object.keys(normalized).length ? normalized : undefined;
+}
+
+export function normalizeSocketEventSubscriptionUpdate(
+  input: SocketEventSubscriptionInput
+): SocketEventSubscriptionUpdate {
+  const raw = input && typeof input === 'object' ? input : {};
+  const update = hasUpdateShape(raw as Record<string, unknown>)
+    ? (raw as SocketEventSubscriptionUpdate)
+    : { subscriptions: raw as SocketEventSubscriptions };
+
+  return {
+    ...update,
+    subscriptions: normalizeSubscriptions(update.subscriptions)
+  };
+}
+
+export function serializeSocketEventSubscriptions(
+  subscriptions?: SocketEventSubscriptions
+): string | undefined {
+  const normalized = normalizeSubscriptions(subscriptions);
+  return normalized ? JSON.stringify(normalized) : undefined;
+}

package/src/ApiClient/WebSocketClient/events.ts

@@ -44,9 +44,10 @@ export type JobErrorData = {
 export type JobProgressData = {
   jobID: string;
   imgID: string;
-  hasImage: boolean;
-  step: number;
-  stepCount: number;
+  hasImage?: boolean;
+  step?: number;
+  stepCount?: number;
+  progress?: number;
 };
 
 export type JobETAData = {
@@ -58,11 +59,20 @@ export type JobETAData = {
 export type JobResultData = {
   jobID: string;
   imgID: string;
-  performedStepCount: number;
-  lastSeed: string;
-  userCanceled: boolean;
-  triggeredNSFWFilter: boolean;
+  performedStepCount?: number;
+  lastSeed?: string;
+  userCanceled?: boolean;
+  triggeredNSFWFilter?: boolean;
   resultUrl?: string;
+  resultKey?: string;
+  /**
+   * @deprecated Use `resultUrl`. Kept for older video worker/socket payload compatibility.
+   */
+  videoUrl?: string;
+  /**
+   * @deprecated Use `resultUrl`. Kept for older video worker/socket payload compatibility.
+   */
+  videoFile?: string;
 };
 
 export type JobStateData =
@@ -148,6 +158,10 @@ export type LLMJobErrorData = {
   workerName?: string;
 };
 
+export type SocketEventSubscriptionsUpdatedData = {
+  socketEventSubscriptions: Record<string, boolean | undefined>;
+};
+
 export type SocketEventMap = {
   /**
    * @event WebSocketClient#authenticated - Received after successful connection to the WebSocket server
@@ -204,6 +218,10 @@ export type SocketEventMap = {
    * @event WebSocketClient#swarmLLMModels - Available LLM models with worker counts
    */
   swarmLLMModels: Record<string, number | LLMModelInfo>;
+  /**
+   * @event WebSocketClient#socketEventSubscriptionsUpdated - Current socket event subscriptions changed
+   */
+  socketEventSubscriptionsUpdated: SocketEventSubscriptionsUpdatedData;
   /**
    * @event WebSocketClient#connected - WebSocket connection opened
    */

package/src/ApiClient/WebSocketClient/index.ts

@@ -8,6 +8,11 @@ import isNodejs from '../../lib/isNodejs';
 import { LIB_VERSION } from '../../version';
 import { Logger } from '../../lib/DefaultLogger';
 import { AuthManager } from '../../lib/AuthManager';
+import {
+  normalizeSocketEventSubscriptionUpdate,
+  serializeSocketEventSubscriptions
+} from './eventSubscriptions';
+import type { SocketEventSubscriptionInput, SocketEventSubscriptions } from './eventSubscriptions';
 
 const PROTOCOL_VERSION = '3.0.0';
 
@@ -15,7 +20,9 @@ const PING_INTERVAL = 15000;
 
 class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketClient {
   appId: string;
+  appSource?: string;
   baseUrl: string;
+  socketEventSubscriptions?: SocketEventSubscriptions;
   private socket: WebSocket | null = null;
   private _supernetType: SupernetType;
   private _pingInterval: NodeJS.Timeout | null = null;
@@ -25,7 +32,9 @@ class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketCl
     auth: AuthManager,
     appId: string,
     supernetType: SupernetType,
-    logger: Logger
+    logger: Logger,
+    appSource?: string,
+    socketEventSubscriptions?: SocketEventSubscriptions
   ) {
     const _baseUrl = new URL(baseUrl);
     switch (_baseUrl.protocol) {
@@ -42,8 +51,17 @@ class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketCl
     }
     super(_baseUrl.toString(), auth, logger);
     this.appId = appId;
+    this.appSource = appSource?.trim() || undefined;
+    this.socketEventSubscriptions = socketEventSubscriptions;
     this.baseUrl = _baseUrl.toString();
     this._supernetType = supernetType;
+    // Mirror the server's authoritative subscriptions snapshot so reconnects keep any
+    // runtime updates applied via `setSocketEventSubscriptions` after the initial connect.
+    this.on('socketEventSubscriptionsUpdated', (payload) => {
+      if (payload && payload.socketEventSubscriptions) {
+        this.socketEventSubscriptions = { ...payload.socketEventSubscriptions };
+      }
+    });
   }
 
   get supernetType(): SupernetType {
@@ -63,6 +81,15 @@ class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketCl
     const isNotSecure = url.protocol === 'http:' || url.protocol === 'ws:';
     url.protocol = isNotSecure ? 'ws:' : 'wss:';
     url.searchParams.set('appId', this.appId);
+    if (this.appSource) {
+      url.searchParams.set('appSource', this.appSource);
+    }
+    const socketEventSubscriptions = serializeSocketEventSubscriptions(
+      this.socketEventSubscriptions
+    );
+    if (socketEventSubscriptions) {
+      url.searchParams.set('socketEventSubscriptions', socketEventSubscriptions);
+    }
     url.searchParams.set('clientName', userAgent);
     url.searchParams.set('clientType', 'artist');
     //At this point 'relaxed' does not work as expected, so we use 'fast' or empty
@@ -115,6 +142,11 @@ class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketCl
     });
   }
 
+  async setSocketEventSubscriptions(update: SocketEventSubscriptionInput): Promise<void> {
+    const normalizedUpdate = normalizeSocketEventSubscriptionUpdate(update);
+    await this.send('setSocketEventSubscriptions', normalizedUpdate);
+  }
+
   /**
    * Ensure the WebSocket connection is open, waiting if necessary and throwing an error if it fails
    * @private

package/src/ApiClient/WebSocketClient/messages.ts

@@ -1,6 +1,7 @@
 import { JobRequestRaw } from '../../Projects/createJobRequestMessage';
 import { SupernetType } from './types';
 import { ChatRequestMessage } from '../../Chat/types';
+import type { SocketEventSubscriptionUpdate } from './eventSubscriptions';
 
 export interface JobErrorMessage {
   jobID: string;
@@ -14,6 +15,7 @@ export interface SocketMessageMap {
   jobError: JobErrorMessage;
   changeNetwork: SupernetType;
   llmJobRequest: ChatRequestMessage;
+  setSocketEventSubscriptions: SocketEventSubscriptionUpdate;
 }
 
 export type MessageType = keyof SocketMessageMap;

package/src/ApiClient/WebSocketClient/types.ts

@@ -1,6 +1,7 @@
 import { MessageType, SocketMessageMap } from './messages';
 import RestClient from '../../lib/RestClient';
 import { SocketEventMap } from './events';
+import type { SocketEventSubscriptionInput } from './eventSubscriptions';
 
 export type SupernetType = 'relaxed' | 'fast';
 
@@ -13,5 +14,6 @@ export interface IWebSocketClient extends RestClient<SocketEventMap> {
   connect(): Promise<void>;
   disconnect(): void;
   send<T extends MessageType>(messageType: T, data: SocketMessageMap[T]): Promise<void>;
+  setSocketEventSubscriptions(update: SocketEventSubscriptionInput): Promise<void>;
   switchNetwork(supernetType: SupernetType): Promise<SupernetType>;
 }

package/src/ApiClient/index.ts

@@ -6,6 +6,10 @@ import { ServerConnectData, ServerDisconnectData } from './WebSocketClient/event
 import { ErrorCode, isNotRecoverable } from './WebSocketClient/ErrorCode';
 import { JSONValue } from '../types/json';
 import { IWebSocketClient, SupernetType } from './WebSocketClient/types';
+import type {
+  SocketEventSubscriptionInput,
+  SocketEventSubscriptions
+} from './WebSocketClient/eventSubscriptions';
 import { Logger } from '../lib/DefaultLogger';
 import ApiKeyAuthManager from '../lib/AuthManager/ApiKeyAuthManager';
 import CookieAuthManager from '../lib/AuthManager/CookieAuthManager';
@@ -41,6 +45,8 @@ export interface ApiClientOptions {
   baseUrl: string;
   socketUrl: string;
   appId: string;
+  appSource?: string;
+  socketEventSubscriptions?: SocketEventSubscriptions;
   networkType: SupernetType;
   logger: Logger;
   authType: 'token' | 'cookies' | 'apiKey';
@@ -50,6 +56,7 @@ export interface ApiClientOptions {
 
 class ApiClient extends TypedEventEmitter<ApiClientEvents> {
   readonly appId: string;
+  readonly appSource?: string;
   readonly logger: Logger;
   private _rest: RestClient;
   private _socket: IWebSocketClient;
@@ -61,6 +68,8 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
     baseUrl,
     socketUrl,
     appId,
+    appSource,
+    socketEventSubscriptions,
     networkType,
     authType,
     logger,
@@ -69,6 +78,7 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
   }: ApiClientOptions) {
     super();
     this.appId = appId;
+    this.appSource = appSource?.trim() || undefined;
     this.logger = logger;
     if (authType === 'apiKey') {
       this._auth = new ApiKeyAuthManager(logger);
@@ -81,9 +91,25 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
     const supportMultiInstance = !isNodejs && this._auth instanceof CookieAuthManager;
     if (supportMultiInstance && multiInstance) {
       // Use coordinated WebSocket client to share single connection between tabs
-      this._socket = new BrowserWebSocketClient(socketUrl, this._auth, appId, networkType, logger);
+      this._socket = new BrowserWebSocketClient(
+        socketUrl,
+        this._auth,
+        appId,
+        networkType,
+        logger,
+        this.appSource,
+        socketEventSubscriptions
+      );
     } else {
-      this._socket = new WebSocketClient(socketUrl, this._auth, appId, networkType, logger);
+      this._socket = new WebSocketClient(
+        socketUrl,
+        this._auth,
+        appId,
+        networkType,
+        logger,
+        this.appSource,
+        socketEventSubscriptions
+      );
     }
     this._disableSocket = disableSocket;
     this._auth.on('updated', this.handleAuthUpdated.bind(this));
@@ -111,6 +137,10 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
     return !this._disableSocket;
   }
 
+  setSocketEventSubscriptions(update: SocketEventSubscriptionInput): Promise<void> {
+    return this.socket.setSocketEventSubscriptions(update);
+  }
+
   handleSocketConnect({ network }: ServerConnectData) {
     this._reconnectAttempts = WS_RECONNECT_ATTEMPTS;
     this.emit('connected', { network });