@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/dist/runtime/helper/EnumUtility.d.ts

@@ -1,6 +1,69 @@
+/**
+ * Generic helper for parsing and formatting TypeScript enums.
+ *
+ * Background: TypeScript compiles a numeric enum into an object that
+ * carries **both** the forward (`name → value`) and the reverse
+ * (`value → name`) mappings. The reverse-mapping entries make
+ * `Object.keys(MyEnum)` noisy when the caller only wants the human
+ * readable member names. This utility centralises the
+ * `isNaN(Number(key))` filter so call sites can ignore the
+ * implementation detail, and it caches the filtered key list per
+ * enum type for repeated lookups.
+ *
+ * Used by debug log tooling and by application code that needs to
+ * convert between an enum value and its display name (e.g. the
+ * `getCodeName` helpers in {@link CodeHelper}).
+ */
 export declare class EnumUtility {
+    /**
+     * Per-enum cache of human-readable member names. The cache key
+     * is the enum object itself (not its name), so two distinct
+     * enums sharing the same numeric values still get independent
+     * entries.
+     */
     private static enumKeyCache;
+    /**
+     * Returns the cached list of human-readable member names for
+     * `enumType`, building the list on first access.
+     *
+     * Filters out the numeric reverse-mapping keys produced by
+     * `Object.keys` on a numeric enum. Caching avoids re-filtering
+     * on every call.
+     */
     private static getEnumKeys;
+    /**
+     * Resolves a string member name to the matching enum value.
+     *
+     * Two lookup paths:
+     * - **Case-sensitive** (default): a direct property lookup with
+     *   the `value in enumType` guard so unknown names cleanly
+     *   return `null`.
+     * - **Case-insensitive**: walk the cached member-name list
+     *   uppercase-comparing against the input. Slower but tolerant
+     *   to mixed-case input from external sources (URLs, config
+     *   files).
+     *
+     * @param enumType   Enum object (e.g. `MyEnum`). The signature
+     *                   `Record<string, number | string>` covers
+     *                   both numeric and string enums.
+     * @param value      Display name to resolve.
+     * @param ignoreCase Set to `true` to allow mixed-case input.
+     *                   Defaults to `false` (case-sensitive).
+     * @returns          The enum value, or `null` when the name is
+     *                   unknown.
+     */
     static parse<T extends Record<string, number | string>>(enumType: T, value: string, ignoreCase?: boolean): T[keyof T];
+    /**
+     * Returns the human-readable name corresponding to `value`.
+     *
+     * Walks the cached member list and finds the first entry whose
+     * value matches. For numeric enums this is essentially a
+     * convenient wrapper around the enum's reverse mapping — the
+     * helper exists so the same call site works against string
+     * enums too (which do **not** have reverse mappings).
+     *
+     * @returns The member name, or `null` when no member maps to
+     *          `value`.
+     */
     static toString<T extends Record<string, number | string>>(enumType: T, value: T[keyof T]): string;
 }

package/dist/runtime/helper/GNSupport.d.ts

@@ -1,24 +1,84 @@
+/**
+ * Discrete identifiers returned by {@link GNSupport.getPlatformType}.
+ *
+ * The string union is intentionally narrow — the SDK only branches
+ * on these three values:
+ * - `"cocos"` — the host runtime exposes the Cocos `cc` global with
+ *   `cc.sys`. Detected before the browser check because the Cocos
+ *   web build also exposes `window`.
+ * - `"browser"` — the host exposes `window` but no Cocos `cc`
+ *   global (vanilla browser, Electron renderer, embedded WebView).
+ * - `"nodejs"` — neither of the above (Node.js, edge runtimes).
+ */
 type PlatformType = "cocos" | "browser" | "nodejs";
+/**
+ * Detects the host runtime once during {@link GNNetwork.init} and
+ * exposes the result through small static accessors.
+ *
+ * Used for branching across runtime-specific code paths:
+ * - {@link StorageService} picks between `cc.sys.localStorage`,
+ *   `window.localStorage` and the npm `store` package.
+ * - {@link HttpPeer} downgrades MsgPack HTTP requests to JSON in
+ *   browsers because the browser HTTP path cannot reliably
+ *   consume a MsgPack response across vendors.
+ * - {@link NetworkingPeerAxiosRequest} only emits the custom
+ *   `User-Agent` / `Content-Length` headers from Node.js because
+ *   browsers refuse to let JavaScript override them.
+ *
+ * Detection runs exactly once because the runtime cannot change
+ * mid-process; the cached values are accessed via the boolean
+ * helpers without re-running the checks.
+ */
 export declare class GNSupport {
+    /** Cached `_platformType === "browser"` flag. */
     private static _isBrowser;
+    /** Cached `_platformType === "cocos"` flag. */
     private static _isCocosCreator;
+    /** Cached platform identifier. */
     private static _platformType;
+    /**
+     * Init guard so {@link init} is idempotent — the SDK calls it
+     * from {@link GNNetwork.init} but defensive call sites may
+     * also invoke it.
+     */
     private static _initialized;
+    /**
+     * Detects the runtime environment and caches the result.
+     *
+     * Detection order matters: Cocos must come first because the
+     * Cocos web build still exposes `window`. Once `cc.sys` is
+     * present we treat the host as Cocos even if `window` is also
+     * defined.
+     *
+     * Safe to call multiple times — the {@link _initialized} guard
+     * makes the second call a no-op.
+     */
     static init(): void;
     /**
-     * Check if running in standard browser environment
+     * Returns whether the host runtime exposes a `window` global.
+     *
+     * Note that this returns `true` for both vanilla browsers and
+     * the Cocos web build — when you need to distinguish those two
+     * cases use {@link isCocosCreator} or
+     * {@link getPlatformType} instead.
      */
     static isBrowser(): boolean;
     /**
-     * Check if running in Cocos Creator 3.x environment
+     * Returns whether the host runtime is Cocos Creator (detected
+     * via the `cc.sys` global).
      */
     static isCocosCreator(): boolean;
     /**
-     * Check if running in Node.js environment
+     * Returns whether the host runtime is Node.js (or any other
+     * environment that exposes neither `window` nor `cc.sys`).
      */
     static isNodeJS(): boolean;
     /**
-     * Get the current platform type
+     * Returns the cached {@link PlatformType} discriminator.
+     *
+     * Useful for `switch` statements that need to handle the three
+     * runtimes distinctly — see {@link StorageService.getString}
+     * for the canonical example.
      */
     static getPlatformType(): PlatformType;
 }

package/dist/runtime/helper/GNUtils.d.ts

@@ -1,10 +1,64 @@
 import { GenericModels } from "./../entity/models/GenericModels";
+/**
+ * Convenience converters that turn the array-shaped collections
+ * returned by the GearN API into `Map<string, T>` lookups keyed by
+ * the most common business identifier.
+ *
+ * The SDK transports always deliver collections as arrays so the
+ * wire format stays JSON / MsgPack friendly. Application code
+ * usually wants O(1) lookup by id; wrapping each call site in a
+ * small `for` loop is repetitive, so this helper centralises the
+ * conversion.
+ *
+ * Each method returns `null` when the input is `null` so the call
+ * site can chain it after a typed response without a separate
+ * null-check (`GNUtils.toFriendDictionary(response.getResponseData()?.playerFriends)`).
+ */
 export declare class GNUtils {
+    /**
+     * Indexes a {@link GenericModels.DataItem} array by its
+     * `key` field.
+     *
+     * Useful for player-data / custom-data responses where the
+     * application normally needs to look up entries by key. Later
+     * duplicates with the same key win, mirroring `Map.set`'s
+     * default behaviour.
+     *
+     * @param datas Source array, or `null`.
+     * @returns A keyed map, or `null` when `datas` is `null`.
+     */
     static toDatasDictionary(datas: Array<GenericModels.DataItem>): Map<string, GenericModels.DataItem>;
+    /**
+     * Indexes a {@link GenericModels.TagItem} array by its `key`
+     * field. Used for player / character tag responses.
+     */
     static toTagsDictionary(tags: Array<GenericModels.TagItem>): Map<string, GenericModels.TagItem>;
+    /**
+     * Indexes a {@link GenericModels.CurrencyItem} array by its
+     * `key` field. Used for player / group currency responses.
+     */
     static toCurrenciesDictionary(currencies: Array<GenericModels.CurrencyItem>): Map<string, GenericModels.CurrencyItem>;
+    /**
+     * Indexes a {@link GenericModels.StatisticsItem} array by its
+     * `key` field. Used for player / group statistic responses.
+     */
     static toStatisticsDictionary(statistics: Array<GenericModels.StatisticsItem>): Map<string, GenericModels.StatisticsItem>;
+    /**
+     * Indexes a {@link GenericModels.InventoryItem} array by its
+     * `itemId` field — the unique inventory ledger entry id, not
+     * the catalog identifier. To bucket by catalog id instead,
+     * write a custom loop using the `classId` field.
+     */
     static toInventoriesDictionary(inventories: Array<GenericModels.InventoryItem>): Map<string, GenericModels.InventoryItem>;
+    /**
+     * Indexes a {@link GenericModels.GroupItem} array by its
+     * `groupId` field. Used for player-group lookup responses.
+     */
     static toGroupDictionary(groups: Array<GenericModels.GroupItem>): Map<string, GenericModels.GroupItem>;
+    /**
+     * Indexes a {@link GenericModels.FriendItem} array by its
+     * `friendId` field. Used for player-friend lookup responses
+     * and to drive social UIs that need O(1) presence checks.
+     */
     static toFriendDictionary(friends: Array<GenericModels.FriendItem>): Map<string, GenericModels.FriendItem>;
 }

package/dist/runtime/helper/MessagePackConverterService.d.ts

@@ -1,4 +1,52 @@
+/**
+ * Thin wrapper around the `@msgpack/msgpack` codec.
+ *
+ * Used by both transports for binary wire-format serialisation:
+ * - {@link NetworkingPeerSocketIOClient.emit} encodes outbound socket
+ *   frames when {@link MessageType.MsgPack} is selected.
+ * - {@link NetworkingSocketPeerBase.service} decodes inbound socket
+ *   frames flagged as MsgPack via {@link SocketPacket.isMsgPack}.
+ * - {@link NetworkingPeerAxiosRequest.postRequestAxios} encodes the
+ *   HTTP request body when MsgPack is selected (Node.js / Cocos
+ *   only — browser HTTP is downgraded to JSON inside
+ *   {@link HttpPeer.send}).
+ * - {@link HttpPeer.onSendOperationRequestResponse} decodes
+ *   non-JSON HTTP response bodies via {@link deserialize}.
+ *
+ * The wrapper exists so the SDK does not import the codec directly
+ * from every call site; centralising the import also makes it
+ * trivial to swap the underlying library if a future port needs a
+ * different MsgPack implementation.
+ */
 export declare class MessagePackConverterService {
+    /**
+     * Encodes any JSON-compatible value into a MessagePack byte
+     * buffer.
+     *
+     * The codec accepts the same value space as `JSON.stringify`
+     * (objects, arrays, numbers, strings, booleans, `null`) plus a
+     * few extras such as `Uint8Array` (encoded as the MsgPack
+     * `bin` type). Cyclic graphs throw — the SDK never builds them
+     * because every payload originates from
+     * {@link GNHashtable.toData} / {@link GNArray.toData} which
+     * produce a tree.
+     *
+     * @param tObj Value to encode. Pass the result of
+     *             `gnHashtable.toData()` for SDK request payloads.
+     * @returns MessagePack-encoded bytes ready for transmission.
+     */
     static serialize<T>(tObj: T): Uint8Array;
+    /**
+     * Decodes a MessagePack byte buffer into a plain JavaScript
+     * value.
+     *
+     * The result is cast to `T` for caller convenience; the runtime
+     * shape always reflects what the codec actually decoded
+     * (typically a plain object that the SDK feeds into
+     * {@link GNHashtable.builder}).
+     *
+     * @param data Bytes received from the transport.
+     * @returns Decoded value cast to `T`.
+     */
     static deserialize<T>(data: Uint8Array): T;
 }

package/dist/runtime/helper/OperationHelper.d.ts

@@ -1,7 +1,58 @@
 import { RequestRole } from "./../constant/enumType/RequestRole";
 import { RequestType } from "./../constant/enumType/RequestType";
 import { OperationRequest } from "./../entity/OperationRequest";
+/**
+ * Wire-shape encoder for outbound socket frames.
+ *
+ * The GearN socket protocol expects an array (not a JSON object) so
+ * that the most common case — request + response correlation —
+ * survives MsgPack encoding without paying the per-key overhead of
+ * the map type. {@link toSocketData} builds that array.
+ *
+ * The corresponding HTTP path uses a different shape (typed JSON
+ * body keyed by parameter codes) and is **not** produced through
+ * this helper; the Axios call inside {@link HttpPeer} talks
+ * directly to {@link GNHashtable.toData}.
+ */
 export declare class OperationHelper {
+    /**
+     * Builds the wire-format array sent over the socket.
+     *
+     * Layout produced:
+     * - Index 0: request-type display name (e.g. `"authenticate"`).
+     * - Index 1: request-role display name (e.g. `"client"`).
+     * - Index 2: operation code string from
+     *   {@link OperationCode}.
+     * - Index 3: parameter bag dumped via
+     *   {@link GNHashtable.toData}, or `null` when the request has
+     *   no parameters.
+     * - Index 4 (only when `requestId !== -1`): request id used by
+     *   the backend to correlate the response. Omitted entirely
+     *   for fire-and-forget calls.
+     *
+     * The display-name conversions go through {@link CodeHelper}
+     * which produces the lowercased-first-letter form the backend
+     * expects (e.g. `RequestType.Authenticate` → `"authenticate"`).
+     *
+     * @param requestType Logical request category.
+     * @param role        Permission scope.
+     * @param request     Pre-built request to encode.
+     * @returns           Array ready to be MsgPack-encoded /
+     *                    JSON-stringified by the caller.
+     */
     static toSocketData(requestType: RequestType, role: RequestRole, request: OperationRequest): any;
+    /**
+     * Reserved for future HTTP payload conversion.
+     *
+     * The current HTTP path bypasses this helper because the
+     * payload it sends is already shaped exactly like the inner
+     * `GNHashtable` (the operation code, request type and role go
+     * into the URL instead of the body). The method exists so a
+     * future protocol revision that needs HTTP-side restructuring
+     * has a natural home for the new logic without changing the
+     * call sites.
+     *
+     * Always returns `null` today.
+     */
     static toHttpData(requestType: RequestType, role: RequestRole, request: OperationRequest): any;
 }

package/dist/runtime/helper/StorageService.d.ts

@@ -1,18 +1,58 @@
 /**
- * StorageService - Cross-platform storage abstraction for GearN SDK
- * Supports: Browser localStorage, Node.js, Cocos Creator 3.x
+ * Cross-platform key/value persistence used by the SDK.
+ *
+ * Used by:
+ * - {@link GNNetwork.init} to hydrate the cached
+ *   {@link AuthenticateStatus} from `[GearN]_AUTH_TOKEN_KEY` and
+ *   `[GearN]_USER_ID_KEY` so a process restart resumes the
+ *   previous session.
+ * - {@link PeerBase.onResponseHandler} to mirror a fresh auth
+ *   token / user id onto disk every time a successful response
+ *   carries the matching parameters.
+ *
+ * Backend selection follows {@link GNSupport.getPlatformType}:
+ * - **`"cocos"`**: `cc.sys.localStorage` (Cocos Creator's own
+ *   wrapper around the platform storage).
+ * - **`"browser"`**: `window.localStorage`.
+ * - **`"nodejs"`**: the `store` npm package, which picks the best
+ *   available backend (file system, SQLite, ...).
+ *
+ * Failure handling: every method runs inside `try/catch` and logs
+ * via `console.warn` on failure rather than throwing, because
+ * storage failures (quota exceeded, permissions denied, missing
+ * primitives in old Cocos builds) should not crash the SDK
+ * bootstrap path.
  */
 export declare class StorageService {
     /**
-     * Get a value from storage
-     * @param key Storage key
-     * @param defaultValue Default value if key doesn't exist
+     * Reads a previously persisted string.
+     *
+     * @param key          Storage key (e.g.
+     *                     `GNNetwork.AUTH_TOKEN_KEY`).
+     * @param defaultValue Value returned when the key is absent or
+     *                     storage access throws. Defaults to `""`
+     *                     so callers can use the result without a
+     *                     null check.
+     * @returns            Stored value, or `defaultValue` when the
+     *                     key is missing / storage fails.
+     *
+     * Implementation note: the return type is `any` because the
+     * Node.js path delegates to the `store` package's typed
+     * accessor which already handles the default value internally.
+     * Treat the result as `string` at call sites.
      */
     static getString(key: string, defaultValue?: string): any;
     /**
-     * Set a value in storage
-     * @param key Storage key
-     * @param value Value to store
+     * Persists a string under `key`.
+     *
+     * Storage failures are swallowed and logged via `console.warn`
+     * — most call sites ({@link PeerBase.onResponseHandler}) want
+     * the SDK to keep working even when persistence is denied
+     * (private-mode browsers, full disk on Cocos device builds).
+     *
+     * @param key   Storage key.
+     * @param value Value to persist. Pass `""` to clear the slot
+     *              (the SDK uses this when explicitly logging out).
      */
     static setString(key: string, value: string): void;
 }

package/dist/runtime/logger/GNDebug.d.ts

@@ -1,15 +1,132 @@
+/**
+ * Hierarchical log verbosity levels consumed by {@link GNDebug}.
+ *
+ * The values are deliberately ordered so that a higher number includes every
+ * lower level. The numeric ordering is what {@link GNDebug.log},
+ * {@link GNDebug.logError}, {@link GNDebug.logWarning} and
+ * {@link GNDebug.logException} compare against, which yields the following
+ * inclusion table:
+ *
+ * | Configured LogType | Exception | Error | Warning | Verbose `log()` |
+ * |--------------------|:---------:|:-----:|:-------:|:---------------:|
+ * | `Off`     (0)      |     -     |   -   |    -    |        -        |
+ * | `Exception` (1)    |     X     |   -   |    -    |        -        |
+ * | `Error`   (2)      |     X     |   X   |    -    |        -        |
+ * | `Warning` (3)      |     X     |   X   |    X    |        -        |
+ * | `All`     (4)      |     X     |   X   |    X    |        X        |
+ *
+ * The default level used by the SDK is whatever `GNServerSettings.getLogType()`
+ * returns — `LogType.All` until the application overrides it.
+ */
 export declare enum LogType {
+    /** Suppress every category of log output. */
     Off = 0,
+    /** Allow only `logException` calls to reach the console. */
     Exception = 1,
+    /** Allow exceptions plus errors. */
     Error = 2,
+    /** Allow exceptions, errors and warnings. */
     Warning = 3,
+    /** Allow every category, including verbose `log` traces from the transports. */
     All = 4
 }
+/**
+ * Static logging facade used by every internal SDK module.
+ *
+ * The class is a thin level-gated wrapper around `console.log`,
+ * `console.warn` and `console.error`. It is intentionally global so that
+ * networking code, helpers and converters can all emit log lines without
+ * having to thread a logger reference through every call.
+ *
+ * Lifecycle:
+ * - The level is uninitialised until `GNNetwork.init()` calls
+ *   {@link setLogType} with the value from
+ *   `GNServerSettings.getLogType()`. Until that point any call to the
+ *   `log*` methods will compare against `undefined` and therefore log
+ *   nothing — be aware of this when adding code that runs before init.
+ * - The level can be updated at runtime by calling {@link setLogType} again,
+ *   which takes effect on the very next call.
+ *
+ * Output destination:
+ * - Always `console.*` of the host runtime (browser DevTools, Node.js stdout
+ *   / stderr, or the Cocos Creator log panel). The SDK does not write to a
+ *   file or remote sink — wiring custom log shipping is the application's
+ *   responsibility.
+ *
+ * Thread-safety / concurrency:
+ * - JavaScript is single-threaded so no synchronisation is required around
+ *   `_logType`. Mutations from inside event handlers are visible immediately.
+ */
 export declare class GNDebug {
+    /**
+     * Currently configured maximum verbosity level.
+     *
+     * Stays `undefined` until {@link setLogType} is called for the first
+     * time, which is why the level comparisons in the `log*` helpers below
+     * use `>=` against the requested category instead of relying on a
+     * default value here.
+     */
     private static _logType;
+    /**
+     * Replaces the global log verbosity level.
+     *
+     * Effect is immediate; the next call to any of the `log*` helpers uses
+     * the new value. Passing {@link LogType.Off} silences the SDK
+     * completely until a higher level is restored.
+     *
+     * @param logType New level to apply. Higher values include all lower
+     *                categories (see the inclusion table on {@link LogType}).
+     */
     static setLogType(logType: LogType): void;
+    /**
+     * Writes a verbose trace line.
+     *
+     * Used by the transports to surface every queued/sent/received frame
+     * (see `[GN Socket SEND]`, `[GN RECV]`, ... prefixes in the networking
+     * code) plus other low-frequency informational events like the SDK
+     * banner emitted from `GNNetwork.init()`.
+     *
+     * Only fires when the current level is {@link LogType.All}.
+     *
+     * @param message Anything the host `console.log` accepts — strings,
+     *                objects, errors, etc. The value is forwarded as-is so
+     *                custom `toString()` implementations are honoured.
+     */
     static log(message: any): void;
+    /**
+     * Writes a captured exception via `console.error`.
+     *
+     * Fires for every level except {@link LogType.Off}. Prefer this over
+     * {@link logError} when you have an actual `Error` instance because it
+     * preserves the stack trace produced by the host runtime.
+     *
+     * @param exception Error instance to print. The SDK never serialises
+     *                  the value first — passing a plain object is allowed
+     *                  but loses the formatted stack trace.
+     */
     static logException(exception: Error): void;
+    /**
+     * Writes a non-fatal warning via `console.warn`.
+     *
+     * Fires when the level is at least {@link LogType.Warning}. Used by the
+     * SDK for recoverable issues like missing storage features in
+     * {@link StorageService} or incoming events that no handler subscribed
+     * to.
+     *
+     * @param message Anything the host `console.warn` accepts.
+     */
     static logWarning(message: any): void;
+    /**
+     * Writes an error message via `console.error`.
+     *
+     * Fires when the level is at least {@link LogType.Error}. Used by the
+     * SDK whenever a request cannot be sent (`isUse === false`), an unknown
+     * `responseId` arrives, or any HTTP/socket failure surfaces from the
+     * underlying transport.
+     *
+     * @param message Anything the host `console.error` accepts. For real
+     *                exception objects prefer {@link logException} so the
+     *                stack trace is preserved.
+     */
     static logError(message: any): void;
 }

package/dist/runtime/networking/AuthenticateStatus.d.ts

@@ -1,8 +1,72 @@
+/**
+ * In-memory cache of the auth-related state shared across the SDK.
+ *
+ * Owned by {@link NetworkingPeer}; populated during {@link GNNetwork.init}
+ * from the persisted entries on {@link StorageService} (keys
+ * `[GearN]_AUTH_TOKEN_KEY` and `[GearN]_USER_ID_KEY`) and refreshed
+ * automatically by {@link PeerBase.onResponseHandler} every time a
+ * successful response carries a new `authToken` or `userId`.
+ *
+ * Lifecycle and consistency:
+ * - The instance lives for the lifetime of the JS realm; there is no
+ *   `dispose()`.
+ * - Mutations are immediately visible to every caller because
+ *   {@link NetworkingPeer.sendViaSocket} / `sendViaHttp` read the
+ *   current values right before each send.
+ * - Mutating the fields directly bypasses the persistent storage
+ *   layer. If you need a persisted update prefer
+ *   {@link GNNetwork.setNewAuthenticateStatus}, which writes through
+ *   to both {@link StorageService} and this cache.
+ */
 export declare class AuthenticateStatus {
+    /**
+     * Cached auth token used as the default value sent with every
+     * authenticated request when the caller does not pass an explicit
+     * override.
+     */
     private authToken;
+    /**
+     * Cached user id resolved from the most recent successful auth
+     * response. Updated together with {@link authToken} during the
+     * normal login / refresh flows.
+     */
     private userId;
+    /**
+     * Returns the cached auth token.
+     *
+     * @returns Token string, or an empty string when no successful
+     *          login has happened yet (and storage held no prior
+     *          value).
+     */
     getAuthToken(): string;
+    /**
+     * Updates the cached auth token in memory only.
+     *
+     * Called automatically by the response handler when a successful
+     * response carries a fresh `authToken`. Application code should
+     * normally use {@link GNNetwork.setNewAuthenticateStatus} so that
+     * the change is also written to {@link StorageService}.
+     *
+     * @param authToken New token. Pass `""` to clear the cached value
+     *                  without persisting; pass via the public helper
+     *                  if you also want the persisted entry cleared.
+     */
     setAuthToken(authToken: string): void;
+    /**
+     * Returns the cached user id.
+     *
+     * @returns User id string, or an empty string when no successful
+     *          login has happened yet.
+     */
     getUserId(): string;
+    /**
+     * Updates the cached user id in memory only.
+     *
+     * Same caveat as {@link setAuthToken}: bypasses
+     * {@link StorageService}. Use
+     * {@link GNNetwork.setNewAuthenticateStatus} for a persisted update.
+     *
+     * @param userId New user id.
+     */
     setUserId(userId: string): void;
 }