@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/dist/runtime/entity/OperationRequest.d.ts

@@ -1,18 +1,126 @@
 import { GNHashtable } from "./../common/GNData";
+/**
+ * Low-level request envelope sent to the GearN backend.
+ *
+ * Carries the operation code, the optional parameter bag, the
+ * client-assigned request id used to correlate the response, and a
+ * per-request timeout. Most application code never instantiates
+ * this class directly — the typed `*Api` wrappers and
+ * `CustomOperationRequest` subclasses build it for you. Reach for
+ * the raw class only when issuing custom operations through
+ * {@link GNNetwork.sendViaSocket} / {@link GNNetwork.sendViaHttp}.
+ *
+ * Request id semantics:
+ * - The default constructor leaves the id unassigned. The peer
+ *   later sets a unique id during {@link PeerBase.enqueue} so the
+ *   response can be matched to the right callback.
+ * - Set the id to `-1` explicitly when you want a fire-and-forget
+ *   request: the peer sees the sentinel and skips both the id
+ *   assignment and the in-flight tracking, so no response will
+ *   ever resolve through the SDK callback path.
+ */
 export declare class OperationRequest {
+    /**
+     * Sentinel used by the SDK in two unrelated places:
+     *
+     * - As the **default timeout in seconds** when application code
+     *   does not pass an explicit timeout — the transport replaces
+     *   it with `GNServerSettings.getDefaultTimeoutInSeconds()` at
+     *   send time.
+     * - As the magic value `20` shared with the same default in
+     *   {@link GNServerSettings} so the two places agree by
+     *   construction.
+     */
     static readonly defaultTimeOut: number;
+    /**
+     * Operation code carried in every wire frame. Values come from
+     * {@link OperationCode}.
+     */
     private operationCode;
+    /**
+     * Client-assigned request id used to correlate the response.
+     * Stays `undefined` until {@link PeerBase.enqueue} assigns one
+     * (or remains `-1` for fire-and-forget calls).
+     */
     private requestId;
+    /** Optional parameter bag, lazily allocated on first {@link setParameter}. */
     private parameters;
+    /**
+     * Timeout in **seconds**. The {@link defaultTimeOut} sentinel
+     * is replaced with the configured default at send time.
+     */
     private timeout;
+    /**
+     * @param operationCode Operation code from
+     *                      {@link OperationCode}.
+     * @param timeout       Optional per-request timeout in seconds.
+     *                      Defaults to {@link defaultTimeOut} so
+     *                      the transport can substitute the
+     *                      configured value.
+     */
     constructor(operationCode: string, timeout?: number);
+    /**
+     * Returns the operation code embedded in the request.
+     */
     getOperationCode(): string;
+    /**
+     * Returns the request id used for response correlation.
+     *
+     * @returns Numeric id (assigned by the peer), or `-1` for
+     *          fire-and-forget requests, or `undefined` before
+     *          {@link PeerBase.enqueue} runs.
+     */
     getRequestId(): number;
+    /**
+     * Returns the parameter bag that will be serialised onto the
+     * wire, or `null` when no parameters have been added.
+     */
     getParameters(): GNHashtable;
+    /**
+     * Returns the timeout in **seconds** that will apply to the
+     * request.
+     */
     getTimeout(): number;
+    /**
+     * Replaces the request id and returns the current request for
+     * chaining.
+     *
+     * @param requestId  New id. Use `-1` to opt into the
+     *                   fire-and-forget path.
+     */
     setRequestId(requestId: number): OperationRequest;
+    /**
+     * Adds or replaces a single parameter and returns the request
+     * for chaining.
+     *
+     * Lazily allocates the underlying {@link GNHashtable} on the
+     * first call so empty requests do not pay for the container.
+     *
+     * @param key   Wire-level parameter key — usually a constant
+     *              from {@link ParameterCode}.
+     * @param value Any value accepted by
+     *              {@link GNHashtable.add} (primitives, plain
+     *              objects, arrays, nested containers).
+     */
     setParameter(key: string, value: any): OperationRequest;
+    /**
+     * Replaces the entire parameter bag and returns the request for
+     * chaining.
+     */
     setParameters(parameters: GNHashtable): OperationRequest;
+    /**
+     * Replaces the timeout (in seconds) and returns the request for
+     * chaining.
+     */
     setTimeout(timeout: number): OperationRequest;
+    /**
+     * Returns a debug-friendly summary of the request.
+     *
+     * Used by `[GN Socket SEND]` / `[GN Http SEND]` log lines. The
+     * parameters are dumped via
+     * `JSON.stringify(parameters?.toData())` so nested
+     * {@link GNHashtable} / {@link GNArray} containers are
+     * expanded into plain objects / arrays.
+     */
     toString(): string;
 }

package/dist/runtime/entity/OperationResponse.d.ts

@@ -1,5 +1,23 @@
 import { GNHashtable } from "./../common/GNData";
 import { InvalidMember } from "./InvalidMember";
+/**
+ * Low-level response container produced by the SDK transports.
+ *
+ * Built by {@link PeerBase.onResponseHandler} from the raw response
+ * payload and handed to either:
+ * - the application callback registered through
+ *   {@link GNNetwork.sendViaSocket} / `sendViaHttp` (raw consumers);
+ *   or
+ * - the typed `*OperationResponse` wrapper that
+ *   {@link GNNetwork.sendViaSocketTResponse} / `sendViaHttpTResponse`
+ *   built from the supplied response class.
+ *
+ * Validation: when the server rejects a request because of malformed
+ * parameters, it ships a list of offending keys via
+ * `invalidRequestParameters`. {@link PeerBase.onResponseHandler}
+ * decodes the inner array into typed {@link InvalidMember} entries
+ * accessible through {@link getInvalidMembers}.
+ */
 export declare class OperationResponse {
     private operationCode;
     private responseId;
@@ -7,18 +25,110 @@ export declare class OperationResponse {
     private debugMessage;
     private parameters;
     private invalidMembers;
+    /**
+     * @param operationCode Operation code that produced the
+     *                      response (mirrored from the matching
+     *                      request).
+     * @param responseId    Response id used for correlation.
+     *                      Matches the request's id assigned by
+     *                      {@link PeerBase.enqueue}.
+     */
     constructor(operationCode: string, responseId: number);
+    /**
+     * Returns the operation code carried by the response.
+     */
     getOperationCode(): string;
+    /**
+     * Returns the backend return code (from {@link ReturnCode}).
+     *
+     * Use {@link hasError} when you only need a boolean
+     * success / failure check.
+     */
     getReturnCode(): number;
+    /**
+     * Returns the deserialized response parameter bag.
+     *
+     * For a successful response this carries the operation-specific
+     * payload; for a failed response it is typically empty.
+     */
     getParameters(): GNHashtable;
+    /**
+     * Returns the response correlation id.
+     *
+     * Used internally by the in-flight tracking machinery. Most
+     * application code can ignore it.
+     */
     getResponseId(): number;
+    /**
+     * Returns the debug message attached by the backend, or `null`
+     * when none was provided.
+     *
+     * Populated mainly for failure responses — the GearN backend
+     * does not include a debug message on success.
+     */
     getDebugMessage(): string;
+    /**
+     * Returns the list of invalid request parameters reported by
+     * the backend, or `null` when none were reported.
+     *
+     * Populated only when {@link getReturnCode} equals
+     * `ReturnCode.InvalidRequestParameters`.
+     */
     getInvalidMembers(): InvalidMember[];
+    /**
+     * Returns whether the response represents a non-success outcome.
+     *
+     * @returns `true` when {@link getReturnCode} is anything other
+     *          than `ReturnCode.Ok`. Note that this is **not** the
+     *          same as a domain error
+     *          ({@link ErrorCode}) — domain errors travel inside
+     *          successful responses; check the operation-specific
+     *          response data for those.
+     */
     hasError(): boolean;
+    /**
+     * Sets the return code and returns the response for chaining.
+     *
+     * Used by {@link PeerBase.onResponseHandler}; application code
+     * does not normally call this directly.
+     */
     setReturnCode(returnCode: number): OperationResponse;
+    /**
+     * Sets the debug message and returns the response for chaining.
+     */
     setDebugMessage(debugMessage: string): OperationResponse;
+    /**
+     * Adds or replaces a single response parameter.
+     *
+     * @param k     Parameter key — usually a constant from
+     *              {@link ParameterCode}.
+     * @param value Any value accepted by {@link GNHashtable.add}.
+     * @returns     The response for chaining.
+     */
     setParameter(k: string, value: any): OperationResponse;
+    /**
+     * Replaces the entire response parameter bag.
+     *
+     * Used by {@link PeerBase.onResponseHandler} after decoding the
+     * raw payload.
+     */
     setParameters(parameters: GNHashtable): OperationResponse;
+    /**
+     * Replaces the invalid-member collection.
+     *
+     * Set by {@link PeerBase.onResponseHandler} when the raw
+     * response carries `invalidRequestParameters`.
+     */
     setInvalidMembers(invalidMembers: InvalidMember[]): OperationResponse;
+    /**
+     * Returns a debug-friendly summary of the response, used by the
+     * `[GN RECV]` log line.
+     *
+     * The format adapts to the outcome:
+     * - `Ok`: appends the parameter dump.
+     * - `InvalidRequestParameters`: appends the offending member
+     *   list.
+     * - Other failures: appends the debug message.
+     */
     toString(): string;
 }

package/dist/runtime/entity/models/AuthenticateModels.d.ts

@@ -1,12 +1,29 @@
 import { GNHashtable } from "./../../common/GNData";
 import { GenericModels } from "./GenericModels";
 import { MasterPlayerModels } from "./MasterPlayerModels";
+/**
+ * Groups reusable request and response contracts for Authenticate operations.
+ *
+ * All login and register requests in this namespace use `RequestType.Authenticate` with `RequestRole.Client`.
+ * Every login or register flow except `RefreshAuthToken` requires a non-null `infoRequestParam`.
+ */
 export declare namespace AuthenticateModels {
+    /**
+     * Defines the reusable parameter block `infoRequestParam`.
+     *
+     * This object controls which optional profile fields should be returned together with the auth response.
+     * Every boolean flag defaults to `false`, so omit fields you do not need.
+     */
     class InfoRequestParam {
+        /** Include linked external identity data. */
         external?: boolean;
+        /** Include segment assignments. */
         segments?: boolean;
+        /** Include custom data entries, optionally filtered by `customDataKeys`. */
         customDatas?: boolean;
+        /** Include display-name data. */
         displayName?: boolean;
+        /** Include avatar data. */
         avatar?: boolean;
         tsCreate?: boolean;
         tags?: boolean;
@@ -19,64 +36,110 @@ export declare namespace AuthenticateModels {
         email?: boolean;
         tsLastLogin?: boolean;
         pushNotifications?: boolean;
+        /** Filter the returned player data fields. */
         playerDataKeys?: Array<string>;
+        /** Filter the returned player currency fields. */
         playerCurrencyKeys?: Array<string>;
+        /** Filter the returned player statistics fields. */
         playerStatisticsKeys?: Array<string>;
+        /** Filter the returned custom-data fields. */
         customDataKeys?: Array<string>;
+        /** Filter the returned tags by key. */
         tagKeys?: Array<string>;
     }
+    /**
+     * Defines the request payload for `loginByAccount`.
+     *
+     * Use this flow when the player authenticates with a GearN username and password.
+     */
     class LoginByAccountRequestData {
         username: string;
         password: string;
+        /** Controls which optional profile fields should be returned together with the auth payload. */
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByAndroidDeviceId.
+     */
     class LoginByAndroidDeviceIdRequestData {
         androidDeviceId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByApple.
+     */
     class LoginByAppleRequestData {
         token: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByCustomDeviceId.
+     */
     class LoginByCustomDeviceIdRequestData {
         customDeviceId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByCustomId.
+     */
     class LoginByCustomIdRequestData {
         customId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByEditorDeviceId.
+     */
     class LoginByEditorDeviceIdRequestData {
         editorDeviceId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByFacebook.
+     */
     class LoginByFacebookRequestData {
         token: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for `loginByGenericService`.
+     *
+     * `serviceData` is provider-defined and is not constrained by a public typed schema beyond `GNHashtable`.
+     */
     class LoginByGenericServiceRequestData {
         serviceName: string;
+        /** Provider-defined payload consumed by the backend integration for `serviceName`. */
         serviceData: GNHashtable;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for `loginByGoogle`.
+     *
+     * `type` should be mapped with the public `GoogleLoginType` enum.
+     */
     class LoginByGoogleRequestData {
         token: string;
         type: number;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByGooglePlayGameService.
+     */
     class LoginByGooglePlayGameServiceRequestData {
         token: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByGameCenter.
+     */
     class LoginByGameCenterRequestData {
         playerId: string;
         name: string;
@@ -87,50 +150,102 @@ export declare namespace AuthenticateModels {
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByiOSDeviceId.
+     */
     class LoginByiOSDeviceIdRequestData {
         iOSDeviceId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByLinuxDeviceId.
+     */
     class LoginByLinuxDeviceIdRequestData {
         linuxDeviceId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByMacOSDeviceId.
+     */
     class LoginByMacOSDeviceIdRequestData {
         macOSDeviceId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByWindowsDeviceId.
+     */
     class LoginByWindowsDeviceIdRequestData {
         windowsDeviceId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for LoginByWindowsPhoneDeviceId.
+     */
     class LoginByWindowsPhoneDeviceIdRequestData {
         windowsPhoneDeviceId: string;
         createPlayerIfNotExists?: boolean;
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for `registerAccount`.
+     *
+     * This creates a GearN account and returns the same profile-style payload shape used by the normal login flows.
+     */
     class RegisterAccountRequestData {
         username: string;
         password: string;
+        /** Controls which optional profile fields should be returned together with the auth payload. */
         infoRequestParam: InfoRequestParam;
     }
+    /**
+     * Defines the request payload for `refreshAuthToken`.
+     *
+     * The request body is intentionally empty. The current auth context comes from the stored auth token
+     * or from `overrideAuthToken` passed to the API call.
+     */
     class RefreshAuthTokenRequestData {
     }
+    /**
+     * Defines the response payload returned by most login and register flows.
+     *
+     * This payload extends `MasterPlayerWithUserIdResponseData`, so it may already include profile data
+     * requested through `infoRequestParam` in addition to auth-specific fields.
+     */
     class AuthenticateResponseData extends MasterPlayerModels.MasterPlayerWithUserIdResponseData {
+        /** Indicates whether the backend created a new player as part of the login flow. */
         newlyCreated?: boolean;
+        /** Auth token to cache locally and reuse for future HTTP or socket auth flows. */
         authToken?: string;
+        /** Optional ban state returned together with the auth payload. */
         playerBan?: GenericModels.BanItem;
     }
+    /**
+     * Defines the response payload for `loginByGenericService`.
+     *
+     * This extends the normal auth response and adds an optional backend error message for the external provider flow.
+     */
     class GenericServiceAuthenticateResponseData extends AuthenticateResponseData {
+        /** Optional provider-specific error message returned by the backend integration. */
         errorMessage?: string;
     }
+    /**
+     * Defines the response payload for `refreshAuthToken`.
+     *
+     * Unlike the normal login flows, this response only returns the refreshed auth token and optional ban state.
+     */
     class RefreshAuthTokenResponseData {
+        /** Refreshed auth token that should replace the previously stored token. */
         authToken?: string;
+        /** Optional ban state returned together with the refreshed token. */
         playerBan?: GenericModels.BanItem;
     }
+    /**
+     * Defines an intentionally empty response payload.
+     */
     class EmptyResponseData {
     }
 }