@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

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

@@ -4,9 +4,92 @@ import { RequestType } from "./../constant/enumType/RequestType";
 import { Action1 } from "./../common/Action1";
 import { OperationRequest } from "./../entity/OperationRequest";
 import { OperationResponse } from "./../entity/OperationResponse";
+/**
+ * Common transport contract implemented by both the HTTP peer
+ * ({@link HttpPeer}) and the socket peer ({@link SocketPeer}).
+ *
+ * The contract is intentionally minimal: a peer must support
+ * (a) one-time initialisation, (b) enqueueing an outgoing request,
+ * (c) reporting whether it is currently enabled by configuration, and
+ * (d) being serviced from a fixed-rate driver loop. Everything beyond
+ * that — request/response correlation, timeout sweeping, ping
+ * tracking, transport-specific framing — lives in
+ * {@link PeerBase} or in the concrete subclasses.
+ *
+ * Why an interface instead of a single base class: {@link NetworkingPeer}
+ * holds two peer instances side by side (one HTTP, one socket) and
+ * needs to dispatch generic operations to whichever one matches the
+ * caller's choice. The shared type makes that dispatch well-typed
+ * without forcing the two transports to share the rest of their
+ * implementations.
+ */
 export interface IPeer {
+    /**
+     * One-shot initialisation hook.
+     *
+     * Implementations allocate their internal queues, configure the
+     * send rate from {@link GNServerSettings.getSendRate}, then call
+     * the abstract `initGNSocketObject()` step in {@link PeerBase}
+     * which lets each transport build its own low-level client
+     * (Axios for HTTP, socket.io for the socket peer).
+     *
+     * Idempotency is the implementation's responsibility — the SDK
+     * calls this exactly once per peer in
+     * {@link NetworkingPeer.initPeer}.
+     */
     initPeer(): void;
+    /**
+     * Enqueues an outgoing operation request.
+     *
+     * The peer wraps the call in an {@link OperationPending} entry,
+     * pushes it into its FIFO queue, and assigns a fresh `requestId`
+     * when the existing value is not the `-1` fire-and-forget sentinel.
+     * The actual send happens later, during the next `service()` tick
+     * that the local rate limiter allows.
+     *
+     * @param requestType         Logical request category. Embedded in
+     *                            the wire payload so the backend
+     *                            picks the right handler.
+     * @param role                `Client`, `Server` or `Admin`.
+     *                            Selects the permission set the
+     *                            backend evaluates against the auth
+     *                            token.
+     * @param operationRequest    Pre-built request to enqueue.
+     * @param onOperationResponse Optional callback. Pass `null` for
+     *                            fire-and-forget; the peer still
+     *                            tracks timeouts but discards the
+     *                            decoded response.
+     * @param authToken           Auth token for this request. The
+     *                            caller normally lets
+     *                            {@link NetworkingPeer.sendViaSocket}
+     *                            / `sendViaHttp` fill the value from
+     *                            the cached
+     *                            {@link AuthenticateStatus} when the
+     *                            override is `null`.
+     * @param secretKey           Game-specific shared secret.
+     * @param customTags          Optional bag of routing / telemetry
+     *                            tags merged into the outbound
+     *                            payload.
+     * @param gameId              Game identifier sent in the
+     *                            `Game-Id` header / equivalent
+     *                            socket frame.
+     */
     enqueue(requestType: RequestType, role: RequestRole, operationRequest: OperationRequest, onOperationResponse: Action1<OperationResponse>, authToken: string, secretKey: string, customTags: GNHashtable, gameId: string): void;
+    /**
+     * Returns whether the transport is enabled by configuration.
+     *
+     * Reflects the `useHttp` / `useSocket` switch on
+     * {@link GNServerSettings}. When `false`, every `enqueue` call is
+     * dropped with an error log.
+     */
     isUsing(): boolean;
+    /**
+     * Drives one tick of the peer's internal work loop.
+     *
+     * Each call sweeps the in-flight set for timed-out operations
+     * (every `0.1s`), then sends at most one queued request when the
+     * rate-limit timer permits. Invoked by {@link ServiceUpdate} on a
+     * fixed interval.
+     */
     service(): void;
 }

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

@@ -11,39 +11,294 @@ import { RequestRole } from "./../constant/enumType/RequestRole";
 import { GetAuthInfoResponse } from "./../entity/response/GetAuthInfoResponse";
 import { UploadFileResponse } from "./../entity/response/UploadFileResponse";
 import { HealthCheckResponse } from "./../entity/response/HealthCheckResponse";
+/**
+ * Owns one HTTP peer and one socket peer side by side, plus the
+ * shared {@link AuthenticateStatus} cache and the local server clock
+ * estimate.
+ *
+ * Sits between the {@link GNNetwork} static facade (which exposes the
+ * public API surface) and the concrete transports
+ * ({@link HttpPeer}, {@link SocketPeer}). Most methods on this class
+ * are thin dispatchers that pick the right transport, fill missing
+ * authentication / configuration values from the cached state, and
+ * forward the call.
+ *
+ * Lifecycle:
+ * - Instantiated once in {@link GNNetwork.initGNSocketObject}.
+ * - {@link initPeer} allocates both transports.
+ * - The static {@link ServiceUpdate} loop keeps calling
+ *   {@link service} on a fixed interval so the queues drain and the
+ *   timeout sweep runs.
+ * - There is no `dispose()` — the instance lives for the lifetime of
+ *   the JS realm.
+ */
 export declare class NetworkingPeer {
+    /** Sub-URI of the timestamp endpoint (`GET /ts`). */
     static readonly SYNC_TS: string;
+    /** Sub-URI of the auth-info endpoint (`GET /getAuthInfo?authToken=...`). */
     static readonly GET_AUTH_INFO: string;
+    /** Sub-URI of the health-check endpoint. */
     static readonly HEALTH_CHECK: string;
+    /** Sub-URI of the multipart upload endpoint. */
     static readonly UPLOAD_FILE: string;
+    /**
+     * Sub-URI of the download endpoint. Used by
+     * {@link GNNetwork.getDownloadFileUrl} to compose the absolute
+     * URL for a previously issued download token.
+     */
     static readonly DOWNLOAD_FILE: string;
+    /** Sub-URI of the JSON HTTP API entry point. */
     static readonly API_JSON: string;
+    /** Sub-URI of the MessagePack HTTP API entry point. */
     static readonly API_MSG_PACK: string;
+    /** Realtime / push transport ({@link SocketPeer}). */
     private socketPeer;
+    /** Request-response transport ({@link HttpPeer}). */
     private httpPeer;
+    /**
+     * Shared cache of auth token + user id. Populated during
+     * {@link initPeer} (created blank — the persisted values are
+     * loaded by {@link GNNetwork.init}) and updated automatically by
+     * {@link PeerBase.onResponseHandler} on every successful
+     * response.
+     */
     authenticateStatus: AuthenticateStatus;
-    gameId: string;
+    /**
+     * Returns the unweighted average of the active transports'
+     * sliding-window pings (in milliseconds).
+     *
+     * Skips transports that report `isUsing() === false`. Returns
+     * `-1` when neither transport is active.
+     */
     getPing(): number;
+    /**
+     * Returns the underlying socket.io session id assigned at connect
+     * time. Empty / `null` when the socket is not connected.
+     */
     getClientId(): string;
+    /**
+     * Most recent server timestamp captured from a response, in
+     * milliseconds since epoch.
+     */
     private lastCurrentServerMilliseconds;
+    /**
+     * Local `Date.now()` reading at the moment
+     * {@link lastCurrentServerMilliseconds} was captured. Used to
+     * extrapolate the current server time without a fresh round trip.
+     */
     private lastGetCurrentMilliseconds;
+    /**
+     * Records a fresh server timestamp + local timestamp pair so
+     * {@link getServerTimestamp} can extrapolate the current server
+     * time without contacting the server again.
+     *
+     * Called automatically by {@link PeerBase.onResponseHandler} when
+     * a successful response carries `ParameterCode.Ts`, plus by
+     * {@link initPeer} as a sane default. Manual callers can use
+     * {@link syncTs} to refresh the estimate explicitly.
+     *
+     * @param currentServerMilliseconds Server-side `Date.now()`-style
+     *                                  value in milliseconds since
+     *                                  epoch.
+     */
     setServerTimeMilliseconds(currentServerMilliseconds: number): void;
+    /**
+     * Returns the SDK's best estimate of the current server clock,
+     * computed as `lastCurrentServerMilliseconds + (Date.now() -
+     * lastGetCurrentMilliseconds)`.
+     *
+     * The estimate ignores clock drift and request latency so it can
+     * be off by tens of milliseconds; treat it as a coarse "server
+     * now" rather than a precise timestamp source.
+     */
     getServerTimestamp(): number;
+    /**
+     * One-time bootstrap.
+     *
+     * Steps:
+     * 1. Seed the server-time estimate with `Date.now()` so
+     *    {@link getServerTimestamp} returns a sane value before any
+     *    response has been observed.
+     * 2. Validate the global {@link GNServerSettings} singleton
+     *    (failing loudly when the SDK is used out of order).
+     * 3. Allocate the empty {@link AuthenticateStatus} cache. The
+     *    persisted values are loaded later by {@link GNNetwork.init}
+     *    after this method returns.
+     * 4. Build and initialise both the HTTP and socket peers.
+     *
+     * @throws Error when the global server settings have not been
+     *         configured yet.
+     */
     initPeer(): void;
+    /**
+     * Drives one tick on both transports.
+     *
+     * Each tick lets every peer drain at most one queued request and
+     * sweep its in-flight set for timeouts. Called repeatedly by
+     * {@link ServiceUpdate}.
+     */
     service(): void;
+    /**
+     * Queues an operation request on the socket transport.
+     *
+     * Substitutes missing authentication data with the cached values
+     * (auth token from {@link AuthenticateStatus}, secret key + game
+     * id from {@link GNServerSettings}) so caller code can pass
+     * `null` for any override it does not need.
+     *
+     * @param requestType    Logical request category.
+     * @param role           Permission scope.
+     * @param request        Pre-built request to enqueue.
+     * @param onResponse     Optional response callback.
+     * @param authToken      Optional one-shot auth token override.
+     *                       Pass `null` to use the cached token.
+     * @param secretKey      Optional one-shot secret key override.
+     *                       Pass `null` to use the configured key.
+     * @param customTags     Optional routing tags.
+     */
     sendViaSocket(requestType: RequestType, role: RequestRole, request: OperationRequest, onResponse?: Action1<OperationResponse>, authToken?: string, secretKey?: string, customTags?: GNHashtable): void;
+    /**
+     * Queues an operation request on the HTTP transport.
+     *
+     * Substitutes missing authentication data the same way
+     * {@link sendViaSocket} does. The only behavioural difference is
+     * the choice of transport.
+     */
     sendViaHttp(requestType: RequestType, role: RequestRole, request: OperationRequest, onResponse?: Action1<OperationResponse>, authToken?: string, secretKey?: string, customTags?: GNHashtable): void;
+    /**
+     * Pushes the cached auth token to the socket channel.
+     *
+     * The socket.io session has no implicit cookie / header carrier,
+     * so the backend needs an explicit auth frame to associate the
+     * socket with a user. Most callers do not need this — the SDK
+     * fires it from its own connect handler when an auth token is
+     * present.
+     */
     sendRequestAuthSocket(): void;
+    /**
+     * 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.
+     *
+     * @param _onSocketConnect Optional callback invoked once the
+     *                         socket finishes its connect handshake.
+     */
     connectSocket(_onSocketConnect: Action0): void;
+    /**
+     * Closes the socket transport.
+     *
+     * @param _onSocketDisconnect Optional callback invoked once the
+     *                            socket reports `disconnect`.
+     */
     disconnectSocket(_onSocketDisconnect: Action0): void;
+    /**
+     * Replaces the raw event observer that receives every incoming
+     * server event.
+     *
+     * Single-slot — calling this method again overwrites the previous
+     * handler. For non-destructive subscriptions register a typed
+     * {@link IServerEventHandler} via
+     * {@link subscriberServerEventHandler}.
+     */
     setOnEventHandler(_onEventHandler: Action1<OperationEvent>): void;
+    /**
+     * Adds a callback to the multi-subscriber socket-connect channel.
+     *
+     * Use a stable function reference so the matching
+     * {@link removeOnConnectHandler} can find and remove it later.
+     */
     setOnConnectHandler(_onConnectHandler: Action0): void;
+    /**
+     * Adds a callback to the multi-subscriber socket-disconnect channel.
+     */
     setOnDisconnectHandler(_onDisconnectHandler: Action0): void;
+    /**
+     * Removes a previously registered socket-connect callback. No-op
+     * when the function reference is not currently subscribed.
+     */
     removeOnConnectHandler(_onConnectHandler: Action0): void;
+    /**
+     * Removes a previously registered socket-disconnect callback.
+     * No-op when the function reference is not currently subscribed.
+     */
     removeOnDisconnectHandler(_onDisconnectHandler: Action0): void;
+    /**
+     * Registers an additional typed {@link IServerEventHandler}
+     * instance.
+     *
+     * Multiple handlers may register against the same event code;
+     * they are dispatched in registration order whenever the matching
+     * event arrives over the socket.
+     */
     subscriberServerEventHandler(serverEventHandler: IServerEventHandler): void;
+    /**
+     * Calls the timestamp endpoint over HTTP to refresh the local
+     * server-clock estimate.
+     *
+     * The endpoint returns a JSON object with a `ts` key (server
+     * milliseconds since epoch). On success, the helper invokes
+     * {@link setServerTimeMilliseconds} with the parsed value before
+     * the callback fires; on failure it falls back to `Date.now()`
+     * silently so the callback always sees a non-null value.
+     *
+     * @param onResponse Optional callback receiving the new server
+     *                   timestamp in milliseconds since epoch.
+     */
     syncTs(onResponse?: Action1<number>): void;
+    /**
+     * Inspects the player record bound to an arbitrary auth token
+     * without affecting the cached session.
+     *
+     * Routes through HTTP. The endpoint either returns
+     * `{ data: { ..., otherDatas } }` on success or `{ error: "..." }`
+     * on failure; this helper unwraps the JSON envelope and re-shapes
+     * `data.otherDatas` into a {@link GNHashtable} so the caller can
+     * use the typed accessors.
+     *
+     * @param authToken  Auth token to inspect. Sent as a query
+     *                   parameter, **not** as the active SDK
+     *                   authorisation, so the cached session is
+     *                   unaffected.
+     * @param onResponse Callback receiving the typed
+     *                   {@link GetAuthInfoResponse}. Always invoked
+     *                   with either `error` or `data` populated.
+     */
     getAuthInfo(authToken: string, onResponse: Action1<GetAuthInfoResponse>): void;
+    /**
+     * Calls the health-check endpoint over HTTP.
+     *
+     * Endpoint behaviour mirrors {@link getAuthInfo}: returns
+     * `{ data: ... }` on success or `{ error: "..." }` on failure.
+     * Useful for warm-up probes / readiness dashboards. The endpoint
+     * does not require an auth token.
+     *
+     * @param onResponse Callback receiving the typed
+     *                   {@link HealthCheckResponse}.
+     */
     healthCheck(onResponse: Action1<HealthCheckResponse>): void;
+    /**
+     * Uploads a file through the authenticated multipart endpoint.
+     *
+     * Expected flow:
+     * 1. Reserve a slot via
+     *    `GNNetwork.content.createNewFileUploadInfo(...)`. The
+     *    backend returns a `fileId`.
+     * 2. Call this method with the binary payload. The SDK uses the
+     *    cached auth token automatically — no override is accepted
+     *    here.
+     * 3. Inspect `response.error` to verify the upload was committed.
+     *
+     * @param fileId     Identifier returned by step 1.
+     * @param content    Binary payload, framed as a `Blob` /
+     *                   `multipart/form-data` part by the underlying
+     *                   Axios call.
+     * @param filename   Display filename written into the multipart
+     *                   envelope.
+     * @param mimetype   Content-Type for the file part.
+     * @param onResponse Callback receiving the typed
+     *                   {@link UploadFileResponse}. Always invoked.
+     */
     uploadFile(fileId: string, content: Uint8Array, filename: string, mimetype: string, onResponse: Action1<UploadFileResponse>): void;
 }

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

@@ -4,6 +4,33 @@ import { RequestType } from "./../constant/enumType/RequestType";
 import { Action1 } from "./../common/Action1";
 import { OperationRequest } from "./../entity/OperationRequest";
 import { OperationResponse } from "./../entity/OperationResponse";
+/**
+ * Per-request bookkeeping entry tracked by {@link PeerBase}.
+ *
+ * Lifecycle:
+ * 1. Constructed inside {@link PeerBase.enqueue} when caller code
+ *    issues a request. The constructor seeds an absolute timeout
+ *    deadline using the SDK-wide
+ *    {@link OperationRequest.defaultTimeOut} fallback, plus copies
+ *    every per-request override (auth token, secret key, custom tags,
+ *    game id) into private fields so the queue can be drained without
+ *    another lookup against the shared {@link AuthenticateStatus}.
+ * 2. Pushed into the FIFO queue. While waiting it is only inspected by
+ *    `service()` for queue ordering.
+ * 3. Sent via {@link PeerBase.send}, which calls {@link onSend} to
+ *    record the wall-clock send time and recompute the timeout
+ *    deadline using the request-specific timeout. The entry then moves
+ *    into the in-flight map keyed by `requestId` (when a callback is
+ *    registered).
+ * 4. Resolved by {@link PeerBase.onResponseHandler}, which calls
+ *    {@link onRecv} so {@link getExecuteTimerInMs} can return the
+ *    measured round-trip in milliseconds.
+ *
+ * Timeout semantics: `timeout` is an absolute `Date.now()`-style epoch
+ * milliseconds value. The 0.1s timeout sweep inside `service()` checks
+ * every in-flight pending entry against the current time and synthesises
+ * a `ReturnCode.OperationTimeout` response when it has elapsed.
+ */
 export declare class OperationPending {
     private operationRequest;
     private requestType;
@@ -16,17 +43,102 @@ export declare class OperationPending {
     private timeout;
     private firstSend;
     private secondsSend;
+    /**
+     * Captures every bit of state needed to send and later correlate
+     * the request without revisiting the shared SDK state.
+     *
+     * @param requestType         Logical request category.
+     * @param role                Permission scope evaluated by the
+     *                            backend.
+     * @param operationRequest    Pre-built request (operation code,
+     *                            parameters, request id, timeout
+     *                            override).
+     * @param onOperationResponse Optional callback. `null` makes this
+     *                            a fire-and-forget entry; the timeout
+     *                            sweep still fires but nobody is
+     *                            notified of the timeout response.
+     * @param authToken           Auth token to send with this request.
+     * @param secretKey           Game-specific shared secret.
+     * @param customTags          Routing / telemetry tags merged into
+     *                            the outbound payload.
+     * @param gameId              Game identifier for the `Game-Id`
+     *                            header.
+     */
     constructor(requestType: RequestType, role: RequestRole, operationRequest: OperationRequest, onOperationResponse: Action1<OperationResponse>, authToken: string, secretKey: string, customTags: GNHashtable, gameId: string);
+    /**
+     * Returns the logical request category recorded at enqueue time.
+     */
     getRequestType(): RequestType;
+    /**
+     * Returns the permission role recorded at enqueue time.
+     */
     getRole(): RequestRole;
+    /**
+     * Returns the auth token captured at enqueue time.
+     *
+     * The token is copied verbatim into the entry — later mutations
+     * to {@link AuthenticateStatus} do not affect already-queued
+     * pending operations.
+     */
     getAuthToken(): string;
+    /**
+     * Returns the secret key captured at enqueue time.
+     */
     getSecretKey(): string;
+    /**
+     * Returns the game id captured at enqueue time.
+     */
     getGameId(): string;
+    /**
+     * Returns the custom tags captured at enqueue time, or `null` when
+     * none were supplied.
+     */
     getCustomTags(): GNHashtable;
+    /**
+     * Marks the operation as just sent and recomputes the absolute
+     * timeout deadline using the request-specific timeout.
+     *
+     * Called from {@link PeerBase.send} immediately before the actual
+     * transport-specific dispatch. The deadline value is later read by
+     * {@link isTimeout} during the periodic timeout sweep.
+     */
     onSend(): void;
+    /**
+     * Marks the operation as resolved so the round-trip duration can
+     * be measured.
+     *
+     * Called from {@link PeerBase.onResponseHandler} when a matching
+     * response arrives. The captured timestamp is paired with
+     * {@link firstSend} by {@link getExecuteTimerInMs}.
+     */
     onRecv(): void;
+    /**
+     * Returns the round-trip duration in milliseconds.
+     *
+     * Defined as `secondsSend - firstSend`. The peer feeds half of
+     * this value into {@link PeerBase.addPing} as the per-request
+     * one-way latency measurement.
+     *
+     * @returns Duration in milliseconds, or a negative / zero value
+     *          when {@link onRecv} has not fired yet.
+     */
     getExecuteTimerInMs(): number;
+    /**
+     * Returns whether the absolute timeout deadline has elapsed.
+     *
+     * The peer's `service()` sweeps with this method every 0.1s and
+     * synthesises a `ReturnCode.OperationTimeout` response when it
+     * returns `true`.
+     */
     isTimeout(): boolean;
+    /**
+     * Returns the underlying {@link OperationRequest} captured at
+     * construction time.
+     */
     getOperationRequest(): OperationRequest;
+    /**
+     * Returns the response callback captured at construction time, or
+     * `null` for a fire-and-forget entry.
+     */
     getCallback(): Action1<OperationResponse>;
 }