@xmobitea/gn-typescript-client 2.6.13-tsc → 2.6.14

package/dist/runtime/GNNetwork.d.ts

@@ -27,66 +27,750 @@ import { CloudScriptApi } from "./GNNetworkCloudScriptApi";
 import { GetAuthInfoResponse } from "./entity/response/GetAuthInfoResponse";
 import { UploadFileResponse } from "./entity/response/UploadFileResponse";
 import { HealthCheckResponse } from "./entity/response/HealthCheckResponse";
+/**
+ * Static facade that owns the entire GearN client SDK runtime state.
+ *
+ * Application code never instantiates `GNNetwork` directly — it calls
+ * {@link init} once with a populated {@link GNServerSettings} and then
+ * issues operations through the static API namespaces ({@link authenticate},
+ * {@link characterPlayer}, {@link group}, ...) or the low-level
+ * `sendVia*` helpers.
+ *
+ * Responsibility:
+ * - Owns the shared {@link NetworkingPeer} that bundles the HTTP and
+ *   socket transports.
+ * - Persists the auth token and user id through {@link StorageService} so
+ *   that a page reload or process restart automatically resumes the
+ *   previous session.
+ * - Exposes typed helpers for arbitrary `OperationRequest` /
+ *   `OperationResponse` pairs (`sendViaSocketTRequestTResponse`,
+ *   `sendViaHttpTRequestTResponse`) used internally by the generated
+ *   `*Api` wrappers.
+ * - Surfaces realtime hooks: socket connect / disconnect callbacks plus
+ *   typed {@link IServerEventHandler} subscription.
+ *
+ * Threading model:
+ * - JavaScript is single-threaded so all members are safe to access from
+ *   any callback. The `service()` loop driven by {@link ServiceUpdate}
+ *   uses `setInterval`-style scheduling and shares no synchronisation
+ *   primitives with caller code.
+ *
+ * Initialisation contract:
+ * - {@link init} is idempotent — calling it twice logs a warning and
+ *   returns without re-initialising. There is no `dispose()` counterpart;
+ *   the static state lives for the lifetime of the JS realm.
+ * - All static API namespaces ({@link authenticate}, {@link group}, ...)
+ *   are `undefined` until `init()` finishes. Accessing them earlier will
+ *   throw `TypeError`.
+ */
 export declare class GNNetwork {
+    /**
+     * Storage key used by {@link StorageService} to persist the most
+     * recent successful auth token.
+     *
+     * The key is intentionally namespaced (`[GearN]_` prefix) so that an
+     * application embedding multiple SDKs into the same browser
+     * `localStorage` cannot collide with GearN entries.
+     */
     static readonly AUTH_TOKEN_KEY = "[GearN]_AUTH_TOKEN_KEY";
+    /**
+     * Storage key used by {@link StorageService} to persist the user id
+     * that was bound to the cached auth token.
+     *
+     * Restored together with {@link AUTH_TOKEN_KEY} during {@link init}
+     * so the SDK can hydrate `getAuthenticateStatus().getUserId()`
+     * without an extra round trip.
+     */
     static readonly USER_ID_KEY = "[GearN]_USER_ID_KEY";
-    static readonly GAME_ID_KEY = "[GearN]_GAME_ID_KEY";
+    /**
+     * Active runtime configuration. Populated by {@link init} and treated
+     * as the single source of truth for URLs, transport tuning and the
+     * configured `secretKey` / `gameId`.
+     *
+     * Remains `null` before `init()` runs, which is also the sentinel
+     * used to make `init()` idempotent.
+     */
     private static gnServerSettings;
+    /**
+     * Returns the shared {@link GNServerSettings} instance owned by the
+     * SDK.
+     *
+     * Useful for inspecting URLs / tuning values at runtime, or for
+     * mutating them on the fly through the dedicated `set*` accessors of
+     * `GNServerSettings`.
+     *
+     * @returns The active settings instance, or `undefined` when called
+     *          before {@link init}.
+     */
     static getGNServerSettings(): GNServerSettings;
+    /**
+     * Shared low-level networking peer. Instantiated by
+     * {@link initGNSocketObject} and never replaced. Owns both the HTTP
+     * peer ({@link HttpPeer}) and the socket peer ({@link SocketPeer}).
+     *
+     * Marked `public` only because the `*Api` wrappers and integration
+     * tests need to reach the underlying transports directly. Application
+     * code should normally go through the typed helpers or domain APIs
+     * instead of touching this object.
+     */
     static peer: NetworkingPeer;
+    /**
+     * Returns the averaged transport latency in milliseconds across every
+     * transport currently marked as `isUsing()`.
+     *
+     * The transports compute their own ping using a sliding window of the
+     * last 10 successful round trips (see {@link PeerBase.addPing}). When
+     * both HTTP and socket transports are active, this method returns
+     * their unweighted arithmetic mean.
+     *
+     * @returns Average latency in milliseconds, or `-1` when neither
+     *          transport is enabled or no successful request has produced
+     *          a measurement yet.
+     */
     static getPing(): number;
+    /**
+     * Returns the socket session id assigned by the socket.io server.
+     *
+     * The session id is non-empty only after the socket has completed its
+     * connect handshake — use {@link isSocketConnected} for a boolean
+     * connection check.
+     *
+     * @returns Current socket id, or `""` (empty string) when the SDK is
+     *          not initialised or the socket is not connected.
+     */
     static getSocketSId(): string;
+    /**
+     * Pushes the cached auth token to the socket channel.
+     *
+     * Required after a fresh socket connect because the socket.io session
+     * has no concept of HTTP cookies — the backend needs the explicit
+     * auth frame to associate the socket with a user. Most callers do not
+     * need to invoke this manually because the SDK fires it from its own
+     * connect handler when an auth token is present.
+     *
+     * @throws TypeError when called before {@link init} has populated
+     *         {@link peer}.
+     */
     static sendRequestAuthSocket(): void;
+    /**
+     * Returns whether the socket transport currently holds a non-empty
+     * session id.
+     *
+     * Implementation detail: this checks the cached
+     * {@link getSocketSId} string rather than asking the underlying
+     * socket.io client directly. The two stay in sync because the SDK
+     * clears the cached id on disconnect.
+     *
+     * @returns `true` while the socket has an active session, `false`
+     *          when uninitialised or disconnected.
+     */
     static isSocketConnected(): boolean;
+    /**
+     * Returns the SDK's best estimate of the current server clock in
+     * **milliseconds since epoch**.
+     *
+     * After at least one successful response the peer rebases the local
+     * `Date.now()` against the latest server timestamp it has observed
+     * (see {@link PeerBase.onResponseHandler} and
+     * {@link NetworkingPeer.setServerTimeMilliseconds}). Until then this
+     * method falls back to the local `Date.now()` so caller code can use
+     * it without a null check.
+     *
+     * @returns Estimated server timestamp. Always defined, never `null`.
+     */
     static getServerTimestamp(): number;
+    /**
+     * Returns the shared cache of auth-related state (auth token + user
+     * id) tracked by the networking peer.
+     *
+     * @returns The shared {@link AuthenticateStatus} instance. Mutating
+     *          its fields directly bypasses {@link StorageService} — for
+     *          a persisted update prefer
+     *          {@link setNewAuthenticateStatus}.
+     *
+     * @throws TypeError when called before {@link init}.
+     */
     static getAuthenticateStatus(): AuthenticateStatus;
-    static getGameId(): string;
+    /**
+     * Returns a string describing the runtime detected by
+     * {@link GNSupport}.
+     *
+     * Possible return values: `"browser"`, `"nodejs"`, `"cocos"`. Useful
+     * for switching between platform-specific code paths in higher-level
+     * application code (analytics SDKs, file pickers, ...).
+     *
+     * @returns Detected platform identifier.
+     */
     static getPlatform(): string;
+    /**
+     * Authentication API namespace — login, register and refresh-token
+     * operations executed over HTTP with `RequestRole.Client`.
+     *
+     * Instantiated during {@link init}. The wrapper also exposes
+     * `.server` and `.admin` sub-namespaces for symmetry, but those are
+     * currently empty for the Authenticate domain.
+     */
     static authenticate: AuthenticateApi;
+    /**
+     * Character-player API namespace — gameplay-tier player operations:
+     * profile, social graph (friends, groups), tags, currencies and
+     * statistics scoped to a single in-game character. Executed over HTTP.
+     */
     static characterPlayer: CharacterPlayerApi;
+    /**
+     * Content API namespace — file metadata, upload-token and
+     * download-token operations. Pair the typed responses with
+     * {@link uploadFile} and {@link getDownloadFileUrl} for the actual
+     * binary transfer.
+     */
     static content: ContentApi;
+    /**
+     * Dashboard / admin API namespace.
+     *
+     * The backend resolves admin-vs-client privileges from the auth token
+     * itself, so the same wrapper exposes both the data-access methods
+     * used by tools and the admin operations that need an
+     * `AdminAccount`-issued token.
+     */
     static dashboard: DashboardApi;
+    /**
+     * Game-player API namespace — account-level player profile, identity
+     * link / unlink, friend graph, group membership and notifications
+     * scoped to the master player record.
+     */
     static gamePlayer: GamePlayerApi;
+    /**
+     * Group API namespace — group metadata, member roles, message wall,
+     * group currencies and group statistics.
+     */
     static group: GroupApi;
+    /**
+     * Inventory API namespace — item metadata, ownership ledger,
+     * per-owner amounts, item statistics and audit log.
+     */
     static inventory: InventoryApi;
+    /**
+     * Master-player API namespace — account / identity / profile
+     * operations bound to the global master player record (one per
+     * GearN account).
+     */
     static masterPlayer: MasterPlayerApi;
+    /**
+     * Store API namespace — catalog browsing, purchase, gift, receipt
+     * validation and audit operations.
+     */
     static storeInventory: StoreInventoryApi;
+    /**
+     * Multiplayer API namespace — matchmaking ticket lifecycle and
+     * match-history queries.
+     */
     static multiplayer: MultiplayerApi;
+    /**
+     * CloudScript API namespace — backend-hosted script execute, publish
+     * and version-management operations.
+     */
     static cloudScript: CloudScriptApi;
+    /**
+     * Boots every static piece of SDK state.
+     *
+     * Steps performed in order:
+     * 1. Reject second invocations — when {@link gnServerSettings} is
+     *    already populated the call logs a warning and returns. This makes
+     *    the method safe to invoke from multiple bootstrap paths in the
+     *    host application.
+     * 2. Initialise the lookup tables and platform detection helpers
+     *    ({@link GNSupport}, {@link CodeHelper},
+     *    {@link ConverterService}). These must run before any model
+     *    serialises or any code reads `getPlatform()`.
+     * 3. Cache the supplied settings, configure {@link GNDebug} from them
+     *    and emit the SDK banner including {@link getClientSdkVersion}.
+     * 4. Build the shared {@link NetworkingPeer} via
+     *    {@link initGNSocketObject} and start the {@link ServiceUpdate}
+     *    loop that drives the queue and timeout machinery.
+     * 5. Hydrate {@link AuthenticateStatus} from the persisted
+     *    `[GearN]_AUTH_TOKEN_KEY` and `[GearN]_USER_ID_KEY` entries so a
+     *    process restart can resume the prior session without an explicit
+     *    re-login.
+     * 6. Instantiate every public `*Api` namespace.
+     *
+     * @param gnServerSettings Configured runtime parameters. The SDK
+     *                         keeps a live reference to this object — do
+     *                         not mutate it concurrently from another
+     *                         thread (in browsers there is none, in
+     *                         Node.js use the dedicated `set*` accessors
+     *                         and avoid worker-thread sharing).
+     */
     static init(gnServerSettings: GNServerSettings): void;
+    /**
+     * Persists a new auth-token / user-id pair to {@link StorageService}
+     * and reflects the change into the shared {@link AuthenticateStatus}.
+     *
+     * Used after operations that mint or rotate a token outside the
+     * normal login flow — e.g. server-issued auth handoff, custom
+     * delegated-auth integrations, or a manual restore from a known good
+     * snapshot.
+     *
+     * The normal login flows do **not** need this helper because
+     * {@link PeerBase.onResponseHandler} already updates both the cache
+     * and storage every time a successful response includes an
+     * `authToken` / `userId` field.
+     *
+     * @param authenticateStatus Source of the new values. Only its
+     *                           `getAuthToken()` and `getUserId()` are
+     *                           inspected; the object itself is not
+     *                           retained.
+     */
     static setNewAuthenticateStatus(authenticateStatus: AuthenticateStatus): void;
-    static setGameId(gameId: string): void;
+    /**
+     * Returns the public SDK version string.
+     *
+     * Reflects the {@link VERSION} constant declared at the top of this
+     * file. Useful when reporting bugs to GearN support — include the
+     * version in any issue you file.
+     *
+     * @returns Semantic-version-like string (e.g. `"2.6"`).
+     */
     static getClientSdkVersion(): string;
+    /**
+     * Legacy hook from the original Unity client SDK.
+     *
+     * The Unity SDK loaded its `GNServerSettings` from a Resources asset
+     * which the editor menu helped author. The TypeScript SDK accepts the
+     * settings object as a constructor argument to {@link init} instead,
+     * so this method does nothing — it remains so future SDK ports can
+     * reuse the same `init()` call sequence without diverging from the
+     * original.
+     */
     private static initServerSettings;
+    /**
+     * Configures {@link GNDebug} from the active {@link GNServerSettings}.
+     *
+     * Asserts that {@link gnServerSettings} has been populated — failing
+     * loudly here is intentional because every later call relies on the
+     * settings reference being valid.
+     *
+     * @throws Error when {@link gnServerSettings} is `null`.
+     */
     private static initGNDebug;
+    /**
+     * Builds the shared {@link NetworkingPeer} and starts the
+     * {@link ServiceUpdate} loop.
+     *
+     * The service loop ticks at a fixed interval and calls
+     * `peer.service()` on every tick, which lets the HTTP and socket
+     * peers (a) drain their pending queues at the configured `sendRate`
+     * and (b) detect timed-out in-flight operations.
+     *
+     * Called exactly once from {@link init}; never invoked again because
+     * the peer reference and the service loop are designed to live for
+     * the lifetime of the JS realm.
+     */
     private static initGNSocketObject;
+    /**
+     * Sends a low-level {@link OperationRequest} through the socket
+     * transport.
+     *
+     * This is the rawest entry point — most application code should use
+     * the typed `sendViaSocketTRequestTResponse` helper or the domain
+     * `*Api` wrappers instead. Use this method only when you already have
+     * a hand-built `OperationRequest` (custom op-codes, replay tooling,
+     * advanced testing) and explicitly want the socket transport.
+     *
+     * The peer fills the `authToken` and `secretKey` slots from the
+     * shared {@link AuthenticateStatus} / {@link GNServerSettings} when
+     * the corresponding override parameter is `null`, and always attaches
+     * the configured `gameId` from `GNServerSettings.getGameId()`.
+     *
+     * @param requestType        Logical request category (Authenticate /
+     *                           CharacterPlayer / ...). Embedded in the
+     *                           socket frame and used by the backend to
+     *                           pick the correct handler.
+     * @param role               `RequestRole.Client`, `Server` or `Admin`.
+     *                           Determines which permission table the
+     *                           backend evaluates against the auth token.
+     * @param request            Pre-built request payload — the peer
+     *                           assigns a `requestId` when the existing
+     *                           value is `-1` so the response can be
+     *                           correlated.
+     * @param onResponse         Optional callback fired with the resolved
+     *                           {@link OperationResponse}. Pass `null`
+     *                           for fire-and-forget semantics; the SDK
+     *                           still tracks timeouts but the result is
+     *                           dropped.
+     * @param overrideAuthToken  Use a one-shot auth token instead of the
+     *                           cached one. Pass `null` to use the cache.
+     * @param overrideSecretKey  Use a one-shot secret key instead of the
+     *                           configured one. Pass `null` for the
+     *                           default.
+     * @param customTags         Optional bag of routing / telemetry tags
+     *                           merged into the outbound payload.
+     */
     static sendViaSocket(requestType: RequestType, role: RequestRole, request: OperationRequest, onResponse: Action1<OperationResponse>, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable): void;
+    /**
+     * Promise-based wrapper around {@link sendViaSocket}.
+     *
+     * The promise always resolves (it never rejects). On a transport
+     * error or timeout the resolved {@link OperationResponse} carries a
+     * non-zero `returnCode` that callers should check via
+     * `response.hasError()`.
+     *
+     * @returns Promise of the typed response.
+     */
     static sendViaSocketAsync(requestType: RequestType, role: RequestRole, request: OperationRequest, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable): Promise<OperationResponse>;
+    /**
+     * Sends a low-level {@link OperationRequest} through the HTTP
+     * transport.
+     *
+     * Mirror of {@link sendViaSocket}. See that method's documentation
+     * for the parameter contract — the only behavioural difference is
+     * the choice of transport, which determines which queue the request
+     * is enqueued into and which serializer is used (JSON over Axios for
+     * HTTP, MsgPack/JSON over socket.io for the socket peer).
+     *
+     * Prefer HTTP for request/response operations that do not require
+     * realtime push, and the socket peer for low-latency or
+     * server-initiated traffic.
+     *
+     * @param requestType        See {@link sendViaSocket}.
+     * @param role               See {@link sendViaSocket}.
+     * @param request            See {@link sendViaSocket}.
+     * @param onResponse         See {@link sendViaSocket}.
+     * @param overrideAuthToken  See {@link sendViaSocket}.
+     * @param overrideSecretKey  See {@link sendViaSocket}.
+     * @param customTags         See {@link sendViaSocket}.
+     */
     static sendViaHttp(requestType: RequestType, role: RequestRole, request: OperationRequest, onResponse: Action1<OperationResponse>, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable): void;
+    /**
+     * Promise-based wrapper around {@link sendViaHttp}.
+     *
+     * Same resolution contract as {@link sendViaSocketAsync}: always
+     * resolves; transport errors and timeouts surface through
+     * `response.hasError()`.
+     *
+     * @returns Promise of the typed response.
+     */
     static sendViaHttpAsync(requestType: RequestType, role: RequestRole, request: OperationRequest, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable): Promise<OperationResponse>;
+    /**
+     * Sends a typed {@link CustomOperationRequest} through the socket
+     * transport and deserialises the response into the supplied
+     * {@link CustomOperationResponse} subclass.
+     *
+     * Used internally by every generated `*Api` wrapper. Application
+     * code reaches for it directly when implementing a custom request
+     * type that does not yet have a wrapper.
+     *
+     * @param request                       Source request — its
+     *                                      `getRequestType()`,
+     *                                      `getRole()` and `build()` are
+     *                                      called to obtain the wire
+     *                                      payload.
+     * @param onResponse                    Optional typed callback.
+     * @param overrideAuthToken             Optional one-shot auth token.
+     * @param overrideSecretKey             Optional one-shot secret key.
+     * @param customTags                    Optional routing tags.
+     * @param customOperationResponseCls    Concrete response class — the
+     *                                      SDK instantiates it via
+     *                                      `new customOperationResponseCls()`
+     *                                      and calls
+     *                                      `setupOperationResponse(...)`
+     *                                      on the result.
+     */
     static sendViaSocketTRequestTResponse<TRequest extends CustomOperationRequest, TResponse extends CustomOperationResponse>(request: TRequest, onResponse: Action1<TResponse>, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable, customOperationResponseCls: Constructor<TResponse>): void;
+    /**
+     * Promise-based wrapper around
+     * {@link sendViaSocketTRequestTResponse}.
+     *
+     * @returns Promise of the typed response.
+     */
     static sendViaSocketTRequestTResponseAsync<TRequest extends CustomOperationRequest, TResponse extends CustomOperationResponse>(request: TRequest, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable, customOperationResponseCls: Constructor<TResponse>): Promise<TResponse>;
+    /**
+     * Sends a typed {@link CustomOperationRequest} through the HTTP
+     * transport.
+     *
+     * Same contract as {@link sendViaSocketTRequestTResponse} but routes
+     * the request through Axios instead of socket.io. This is the
+     * helper invoked by every method on the generated `*Api` classes.
+     */
     static sendViaHttpTRequestTResponse<TRequest extends CustomOperationRequest, TResponse extends CustomOperationResponse>(request: TRequest, onResponse: Action1<TResponse>, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable, customOperationResponseCls: Constructor<TResponse>): void;
+    /**
+     * Promise-based wrapper around
+     * {@link sendViaHttpTRequestTResponse}.
+     *
+     * @returns Promise of the typed response.
+     */
     static sendViaHttpTRequestTResponseAsync<TRequest extends CustomOperationRequest, TResponse extends CustomOperationResponse>(request: TRequest, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable, customOperationResponseCls: Constructor<TResponse>): Promise<TResponse>;
+    /**
+     * Sends a low-level {@link OperationRequest} through the socket
+     * transport but deserialises the result into a typed
+     * {@link CustomOperationResponse} subclass.
+     *
+     * Use this when your call site has a hand-built `OperationRequest`
+     * (already encoded with the right `operationCode` and parameters)
+     * but still wants the convenience of a typed response object.
+     *
+     * The callback is **not** invoked when the underlying transport
+     * yields a `null` response — this matches the historical behaviour
+     * the Unity SDK relied on. Wrap the call in a timeout watchdog if
+     * you need a guaranteed final notification.
+     *
+     * @param requestType                See {@link sendViaSocket}.
+     * @param role                       See {@link sendViaSocket}.
+     * @param request                    See {@link sendViaSocket}.
+     * @param onResponse                 Optional typed callback. Pass
+     *                                   `null` for fire-and-forget.
+     * @param overrideAuthToken          Optional one-shot auth token.
+     * @param overrideSecretKey          Optional one-shot secret key.
+     * @param customTags                 Optional routing tags.
+     * @param customOperationResponseCls Concrete response class.
+     */
     static sendViaSocketTResponse<TResponse extends CustomOperationResponse>(requestType: RequestType, role: RequestRole, request: OperationRequest, onResponse: Action1<TResponse>, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable, customOperationResponseCls: Constructor<TResponse>): void;
+    /**
+     * Promise-based wrapper around {@link sendViaSocketTResponse}.
+     *
+     * Like the underlying method, the promise never rejects but may stay
+     * pending forever if the transport drops the response without
+     * triggering a timeout. Pair with `Promise.race` against an
+     * application-side timer when that matters.
+     *
+     * @returns Promise of the typed response.
+     */
     static sendViaSocketTResponseAsync<TResponse extends CustomOperationResponse>(requestType: RequestType, role: RequestRole, request: OperationRequest, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable, customOperationResponseCls: Constructor<TResponse>): Promise<TResponse>;
+    /**
+     * Sends a low-level {@link OperationRequest} through the HTTP
+     * transport and deserialises the result into a typed
+     * {@link CustomOperationResponse} subclass.
+     *
+     * HTTP mirror of {@link sendViaSocketTResponse}. Same `null` short
+     * circuit applies: when the transport yields a `null` response the
+     * callback is not invoked.
+     *
+     * @param requestType                See {@link sendViaSocket}.
+     * @param role                       See {@link sendViaSocket}.
+     * @param request                    See {@link sendViaSocket}.
+     * @param onResponse                 Optional typed callback.
+     * @param overrideAuthToken          Optional one-shot auth token.
+     * @param overrideSecretKey          Optional one-shot secret key.
+     * @param customTags                 Optional routing tags.
+     * @param customOperationResponseCls Concrete response class.
+     */
     static sendViaHttpTResponse<TResponse extends CustomOperationResponse>(requestType: RequestType, role: RequestRole, request: OperationRequest, onResponse: Action1<TResponse>, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable, customOperationResponseCls: Constructor<TResponse>): void;
+    /**
+     * Promise-based wrapper around {@link sendViaHttpTResponse}.
+     *
+     * @returns Promise of the typed response.
+     */
     static sendViaHttpTResponseAsync<TResponse extends CustomOperationResponse>(requestType: RequestType, role: RequestRole, request: OperationRequest, overrideAuthToken: string, overrideSecretKey: string, customTags: GNHashtable, customOperationResponseCls: Constructor<TResponse>): Promise<TResponse>;
+    /**
+     * Opens the socket transport.
+     *
+     * Triggers the underlying socket.io client to dial the configured
+     * URL using the SSL / port settings active at the time of the call.
+     * Subsequent connect notifications fire on every callback registered
+     * through {@link subscriberOnConnectHandler}.
+     *
+     * @param _onSocketConnect Optional callback invoked once the socket
+     *                         finishes its connect handshake. Pass
+     *                         `null` (default) when other connect hooks
+     *                         are sufficient.
+     */
     static connectSocket(_onSocketConnect?: Action0): void;
+    /**
+     * Closes the socket transport.
+     *
+     * Sends the disconnect frame, drops every pending socket-bound
+     * operation in the queue, and triggers every callback registered
+     * through {@link subscriberOnDisconnectHandler}.
+     *
+     * @param _onSocketDisconnect Optional callback invoked once the
+     *                            socket reports `disconnect`.
+     */
     static disconnectSocket(_onSocketDisconnect?: Action0): void;
+    /**
+     * Replaces the raw event callback that observes every incoming
+     * server event.
+     *
+     * Only one raw observer is installed at a time — calling this method
+     * again overwrites the previous handler. For non-destructive
+     * subscriptions use {@link subscriberServerEventHandler} with a
+     * dedicated typed handler.
+     *
+     * @param _onEventHandler Receiver invoked with every decoded
+     *                        {@link OperationEvent} as it arrives. Pass
+     *                        `null` to clear the slot.
+     */
     static setOnEventHandler(_onEventHandler: Action1<OperationEvent>): void;
+    /**
+     * Adds a callback to the multi-subscriber socket-connect channel.
+     *
+     * Unlike {@link setOnEventHandler}, the connect / disconnect channel
+     * accumulates subscribers — every registered callback is invoked in
+     * registration order on the next connect.
+     *
+     * @param _onConnectHandler Function to add. Use a stable reference
+     *                          so that {@link unscriberOnConnectHandler}
+     *                          can remove it later.
+     */
     static subscriberOnConnectHandler(_onConnectHandler: Action0): void;
+    /**
+     * Adds a callback to the multi-subscriber socket-disconnect channel.
+     *
+     * @param _onDisconnectHandler Function to add. Must be the same
+     *                             reference that will later be passed to
+     *                             {@link unsubscriberOnDisconnectHandler}.
+     */
     static subscriberOnDisconnectHandler(_onDisconnectHandler: Action0): void;
+    /**
+     * Removes a previously registered socket-connect callback.
+     *
+     * No-op when the supplied function reference is not currently
+     * subscribed.
+     *
+     * @param _onConnectHandler The exact reference originally passed to
+     *                          {@link subscriberOnConnectHandler}.
+     */
     static unscriberOnConnectHandler(_onConnectHandler: Action0): void;
+    /**
+     * Removes a previously registered socket-disconnect callback.
+     *
+     * No-op when the supplied function reference is not currently
+     * subscribed.
+     *
+     * @param _onDisconnectHandler The exact reference originally passed
+     *                             to
+     *                             {@link subscriberOnDisconnectHandler}.
+     */
     static unsubscriberOnDisconnectHandler(_onDisconnectHandler: Action0): void;
+    /**
+     * Registers a typed {@link IServerEventHandler} so the SDK can
+     * dispatch the matching server event to it automatically.
+     *
+     * The handler must implement `IServerEventHandler` and is usually
+     * decorated with `@IServerEventHandler.registerEvent` so that it is
+     * picked up at module-load time. This helper exists for the cases
+     * where a handler is constructed dynamically and therefore needs to
+     * be subscribed at runtime.
+     *
+     * Multiple handlers may register against the same `EventCode`; they
+     * are invoked in registration order whenever a matching event is
+     * received from the socket.
+     *
+     * @param serverEventHandler Concrete handler instance.
+     */
     static subscriberServerEventHandler(serverEventHandler: IServerEventHandler): void;
+    /**
+     * Triggers the timestamp endpoint and refreshes the local server
+     * clock estimate.
+     *
+     * The SDK already calls this internally when the server includes a
+     * `ts` field in any successful response (see
+     * {@link PeerBase.onResponseHandler}). Manual invocations are useful
+     * after long idle periods or before issuing a time-sensitive request
+     * such as receipt validation.
+     *
+     * @param onResponse Optional callback receiving the new server
+     *                   timestamp in milliseconds since epoch.
+     */
     static syncTs(onResponse?: Action1<number>): void;
+    /**
+     * Promise-based wrapper around {@link syncTs}.
+     *
+     * @returns Promise of the freshly observed server timestamp in
+     *          milliseconds since epoch.
+     */
     static syncTsAsync(): Promise<number>;
+    /**
+     * Calls the auth-info endpoint to inspect the player record bound to
+     * an arbitrary auth token without affecting the cached session.
+     *
+     * Useful for tools (admin dashboards, diagnostics) that need to
+     * resolve a token without logging in as the corresponding user.
+     *
+     * @param authToken  Token to inspect. Does **not** replace the
+     *                   cached auth token used by other requests.
+     * @param onResponse Optional callback receiving the typed
+     *                   {@link GetAuthInfoResponse}.
+     */
     static getAuthInfo(authToken: string, onResponse?: Action1<GetAuthInfoResponse>): void;
+    /**
+     * Promise-based wrapper around {@link getAuthInfo}.
+     *
+     * @returns Promise of the typed auth-info response.
+     */
     static getAuthInfoAsync(authToken: string): Promise<GetAuthInfoResponse>;
+    /**
+     * Calls the health-check endpoint.
+     *
+     * Useful for warm-up probes, health dashboards or as a simple ping
+     * to confirm that the configured base URL is reachable. The endpoint
+     * does **not** require an auth token.
+     *
+     * @param onResponse Optional callback receiving the typed
+     *                   {@link HealthCheckResponse}.
+     */
     static healthCheck(onResponse?: Action1<HealthCheckResponse>): void;
+    /**
+     * Promise-based wrapper around {@link healthCheck}.
+     *
+     * @returns Promise of the typed health-check response.
+     */
     static healthCheckAsync(): Promise<HealthCheckResponse>;
+    /**
+     * Uploads a file using the authenticated multipart endpoint.
+     *
+     * Expected flow:
+     * 1. Call `GNNetwork.content.createNewFileUploadInfo(...)` (or the
+     *    matching async variant). The backend reserves a slot and
+     *    returns a `fileId`.
+     * 2. Pass that `fileId` plus the binary payload into this method.
+     *    The SDK uses the cached auth token automatically (it does not
+     *    accept an override here).
+     * 3. Inspect `response.uploadCommitted` (or equivalent field) before
+     *    treating the upload as durable.
+     *
+     * Browser caveat: `content` is sent as a `Blob`, so very large
+     * payloads may be subject to host-runtime memory limits. Chunked
+     * uploads are not supported by this endpoint — use the dashboard /
+     * server SDK for files larger than ~50 MB.
+     *
+     * @param fileId     Identifier returned by `content.createNewFileUploadInfo*`.
+     * @param content    Binary payload to upload.
+     * @param filename   Display name written into the multipart envelope.
+     * @param mimetype   Content-Type for the file part. Affects the
+     *                   `Content-Type` header on the file blob only;
+     *                   the multipart envelope itself remains
+     *                   `multipart/form-data`.
+     * @param onResponse Optional callback receiving the typed
+     *                   {@link UploadFileResponse}.
+     */
     static uploadFile(fileId: string, content: Uint8Array, filename: string, mimetype: string, onResponse?: Action1<UploadFileResponse>): void;
+    /**
+     * Promise-based wrapper around {@link uploadFile}.
+     *
+     * @returns Promise of the typed upload response.
+     */
     static uploadFileAsync(fileId: string, content: Uint8Array, filename: string, mimetype: string): Promise<UploadFileResponse>;
+    /**
+     * Builds the absolute download URL for a previously issued download
+     * token.
+     *
+     * Expected flow:
+     * 1. Call `GNNetwork.content.requestDownloadFileUploadInfo(...)` to
+     *    obtain a short-lived `downloadToken` for the target file.
+     * 2. Pass that token into this helper to get the absolute URL.
+     * 3. Hand the URL to the host runtime's preferred download
+     *    primitive (`<a download>`, `fetch(...)`, Cocos `assetManager`,
+     *    Node.js `http.get`, ...).
+     *
+     * The returned URL embeds the token directly — treat it as
+     * sensitive and avoid logging it.
+     *
+     * @param downloadToken Short-lived token returned by
+     *                      `content.requestDownloadFileUploadInfo*`.
+     * @returns Absolute URL of the form
+     *          `<httpUrl>/download/<downloadToken>`.
+     *
+     * @throws TypeError when called before {@link init} (the SDK has no
+     *         settings to pull the base URL from).
+     */
     static getDownloadFileUrl(downloadToken: string): string;
 }