@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/dist/runtime/networking/socket/NetworkingSocketPeerBase.d.ts

@@ -4,43 +4,241 @@ import { GNHashtable } from "./../../common/GNData";
 import { RequestRole } from "./../../constant/enumType/RequestRole";
 import { RequestType } from "./../../constant/enumType/RequestType";
 import { OperationRequest } from "./../../entity/OperationRequest";
+/**
+ * Inbound socket frame buffered between the transport callback and the
+ * SDK service-loop tick.
+ *
+ * The socket transport receives data on its own callback thread; rather
+ * than decoding and dispatching synchronously the raw payload is queued
+ * here so that all SDK-visible work happens on the
+ * {@link ServiceUpdate} tick, which simplifies error handling and lets
+ * the application reason about callback ordering.
+ */
 export declare class SocketPacket {
+    /**
+     * Raw payload as delivered by the underlying socket.io client —
+     * either an `ArrayBuffer` / `Uint8Array` (MsgPack) or a plain
+     * decoded object (JSON).
+     */
     obj: any;
+    /**
+     * `true` when {@link obj} is a MessagePack byte buffer that
+     * still needs decoding via {@link MessagePackConverterService},
+     * `false` when it is already a plain JS object.
+     */
     isMsgPack: boolean;
+    /**
+     * @param obj       Raw payload from the socket callback.
+     * @param isMsgPack Whether the payload is MessagePack-encoded.
+     */
     constructor(obj: any, isMsgPack: boolean);
 }
+/**
+ * Transport-agnostic skeleton shared by every concrete socket
+ * implementation.
+ *
+ * Owns the lifecycle handlers (connect / disconnect callbacks),
+ * buffered response / event queues and the JSON / MessagePack decode
+ * loop driven by {@link service}. Concrete subclasses such as
+ * {@link NetworkingPeerSocketIOClient} only need to:
+ * - implement {@link reInitNewSocket} so the underlying socket.io
+ *   client is created;
+ * - override {@link emit} to write outbound frames;
+ * - override {@link sendRequestAuthSocket} when their wire protocol
+ *   requires an explicit auth frame after connect;
+ * - push inbound frames into {@link responsePacketLst} /
+ *   {@link eventPacketLst} from the transport's own callbacks.
+ *
+ * Decoding policy: every frame is decoded on the SDK service tick
+ * inside a try/catch. A decode failure logs through
+ * {@link GNDebug.logException} and is swallowed — the SDK does not
+ * propagate decode failures to the application because they would
+ * almost always be unhandleable noise.
+ */
 export declare abstract class NetworkingSocketPeerBase {
+    /** Reconnect backoff in milliseconds (from server settings). */
     protected reconnectDelay: number;
+    /** Heartbeat interval in milliseconds. */
     protected pingInterval: number;
+    /** Heartbeat timeout in milliseconds. */
     protected pingTimeout: number;
+    /** socket.io session id; empty string when disconnected. */
     clientId: string;
+    /**
+     * Current connection state mirror. Maintained by the concrete
+     * subclass — true between `connect` and `disconnect`.
+     */
     isWsConnected: boolean;
+    /**
+     * Inbound response frames queued for decoding on the next
+     * service tick. Concrete subclasses push raw frames here from
+     * the socket callbacks; {@link service} drains the queue.
+     */
     protected responsePacketLst: SocketPacket[];
+    /** Inbound event frames queued for decoding on the next service tick. */
     protected eventPacketLst: SocketPacket[];
+    /** Absolute base URL handed to the underlying socket.io client. */
     protected url: string;
+    /** Callback receiving decoded events. */
     private _onEventHandler;
+    /** Callback receiving decoded responses. */
     private _onResponseHandler;
+    /**
+     * One-shot connect callback handed in via {@link connect}. Cleared
+     * after firing once so that the next reconnect does not re-fire
+     * the same callback.
+     */
     private _onSocketConnect;
+    /** One-shot disconnect callback handed in via {@link close}. */
     private _onSocketDisconnect;
+    /** Multi-subscriber list of connect callbacks. */
     private _onConnectHandler;
+    /** Multi-subscriber list of disconnect callbacks. */
     private _onDisconnectHandler;
     constructor();
+    /**
+     * Stores socket configuration and resets the inbound buffers.
+     *
+     * Called by {@link SocketPeer.initGNSocketObject} just before
+     * {@link reInitNewSocket} builds the underlying socket.io client.
+     *
+     * @param url            Absolute base URL produced by
+     *                       {@link GNServerSettings.getSocketUrl}.
+     * @param reconnectDelay Reconnect backoff in milliseconds.
+     * @param pingInterval   Heartbeat interval in milliseconds.
+     * @param pingTimeout    Heartbeat timeout in milliseconds.
+     */
     init(url: string, reconnectDelay: number, pingInterval: number, pingTimeout: number): void;
+    /**
+     * Captures a one-shot connect callback. The concrete subclass is
+     * expected to dial the socket and call {@link onConnectHandler}
+     * once the underlying client reports `connect`.
+     *
+     * @param _onSocketConnect Optional callback. Pass `null` to skip
+     *                         the one-shot notification while still
+     *                         opening the socket.
+     */
     connect(_onSocketConnect: Action0): void;
+    /**
+     * Captures a one-shot disconnect callback. The concrete subclass
+     * is expected to tear down the socket and call
+     * {@link onDisconnectHandler}.
+     */
     close(_onSocketDisconnect: Action0): void;
+    /**
+     * Sends an explicit auth frame so the backend can associate the
+     * socket session with a user.
+     *
+     * Default implementation is a no-op — concrete subclasses such as
+     * {@link NetworkingPeerSocketIOClient} override this with the
+     * wire-format-specific frame.
+     */
     sendRequestAuthSocket(): void;
+    /**
+     * Public send entry point. Forwards the frame to {@link emit};
+     * exists as a hook for future cross-cutting behaviour
+     * (compression, telemetry).
+     */
     send(requestType: RequestType, role: RequestRole, operationRequest: OperationRequest, authToken: string, secretKey: string, customTags: GNHashtable, gameId: string): void;
+    /**
+     * Subclass hook that performs the actual socket emit.
+     *
+     * Override on each concrete socket implementation. The default
+     * no-op exists so the abstract class can still be instantiated
+     * during partial implementations / mocking in tests.
+     */
     protected emit(requestType: RequestType, role: RequestRole, operationRequest: OperationRequest, authToken: string, secretKey: string, customTags: GNHashtable, gameId: string): void;
+    /**
+     * Subclass hook for (re)building the underlying socket.io client.
+     *
+     * Called once from {@link SocketPeer.initGNSocketObject} during
+     * SDK startup. The default no-op exists so the abstract class
+     * still works in tests; production code uses
+     * {@link NetworkingPeerSocketIOClient.reInitNewSocket}.
+     */
     reInitNewSocket(): void;
+    /**
+     * Adds a callback to the multi-subscriber connect channel.
+     *
+     * Use a stable function reference so the matching
+     * {@link removeOnConnectHandler} can find and remove it.
+     */
     setOnConnectHandler(_onConnectHandler: Action0): void;
+    /**
+     * Adds a callback to the multi-subscriber disconnect channel.
+     */
     setOnDisconnectHandler(_onDisconnectHandler: Action0): void;
+    /**
+     * Removes a previously registered connect callback. No-op when
+     * the function reference is not currently subscribed.
+     */
     removeOnConnectHandler(_onConnectHandler: Action0): void;
+    /**
+     * Removes a previously registered disconnect callback.
+     */
     removeOnDisconnectHandler(_onDisconnectHandler: Action0): void;
+    /**
+     * Concrete subclasses call this after the underlying transport
+     * reports `connect`.
+     *
+     * Sequence:
+     * 1. Fan out to every subscriber registered through
+     *    {@link setOnConnectHandler}.
+     * 2. When a cached auth token exists, send the auth frame so the
+     *    backend can associate the new session with the user without
+     *    waiting for the next request.
+     * 3. Resolve the one-shot {@link _onSocketConnect} callback and
+     *    clear it so the next reconnect starts fresh.
+     */
     onConnectHandler(): void;
+    /**
+     * Concrete subclasses call this after the underlying transport
+     * reports `disconnect`.
+     *
+     * Fans out to every subscriber on the disconnect channel and
+     * resolves the one-shot {@link _onSocketDisconnect} callback.
+     */
     onDisconnectHandler(): void;
+    /**
+     * Replaces the single-slot raw event callback used by the SDK.
+     *
+     * The SDK installs its own dispatch routine through this slot
+     * during {@link SocketPeer.initGNSocketObject}; application code
+     * uses {@link GNNetwork.setOnEventHandler} for the
+     * higher-level typed event channel instead.
+     */
     setOnEventHandler(_onEventHandler: Action1<GNHashtable>): void;
+    /**
+     * Routes a decoded event to the registered handler. Skipped
+     * silently when no handler is set.
+     */
     onEventHandler(obj: GNHashtable): void;
+    /**
+     * Replaces the single-slot raw response callback used by the SDK.
+     *
+     * Bound during {@link SocketPeer.initGNSocketObject} to the
+     * shared {@link PeerBase.onResponseHandler} machinery.
+     */
     setOnResponseHandler(_onResponseHandler: Action1<GNHashtable>): void;
+    /**
+     * Routes a decoded response to the registered handler.
+     */
     onResponseHandler(obj: GNHashtable): void;
+    /**
+     * Drains the inbound response and event buffers on the current
+     * service tick.
+     *
+     * For each queued packet the helper:
+     * - decodes the raw payload (MsgPack via
+     *   {@link MessagePackConverterService.deserialize}, or pass
+     *   through for JSON);
+     * - wraps the result in a {@link GNHashtable};
+     * - dispatches to the matching response / event handler.
+     *
+     * Decode failures are logged via
+     * {@link GNDebug.logException} and swallowed so a malformed frame
+     * cannot stall the service loop. After processing each list is
+     * truncated to length 0 (cheaper than allocating a fresh array).
+     */
     service(): void;
 }

package/dist/runtime/networking/socket/SocketPeer.d.ts

@@ -5,25 +5,180 @@ import { OperationEvent } from "./../../entity/OperationEvent";
 import { IServerEventHandler } from "./../handler/IServerEventHandler";
 import { OperationPending } from "./../OperationPending";
 import { PeerBase } from "./../PeerBase";
+/**
+ * High-level socket peer used by {@link NetworkingPeer} and ultimately
+ * by {@link GNNetwork}.
+ *
+ * Bridges the queue / timeout machinery in {@link PeerBase} with the
+ * socket-specific transport in {@link NetworkingSocketPeerBase} (the
+ * concrete client today is {@link NetworkingPeerSocketIOClient}).
+ *
+ * Responsibilities:
+ * - Build and configure the underlying socket.io client during
+ *   {@link initGNSocketObject}, then mirror the response / event
+ *   callbacks back into this class.
+ * - Maintain a per-event-code dispatch table populated from every
+ *   class registered through `@IServerEventHandler.registerEvent`,
+ *   plus a runtime-add path via {@link subscriberAServerEventHandler}.
+ * - Forward connect / disconnect / event subscriptions to the
+ *   transport.
+ * - Override {@link send} to log the outbound frame and apply the
+ *   default timeout fallback before delegating to the transport.
+ */
 export declare class SocketPeer extends PeerBase {
+    /** Concrete low-level socket.io client. */
     private networkingSocketPeerBase;
+    /**
+     * Per-event-code dispatch table. Each entry is the ordered list
+     * of handler instances that registered against the matching
+     * event code.
+     */
     private serverEventHandlersDict;
+    /**
+     * Single-slot raw observer that receives every decoded event.
+     * Replaced through {@link setOnEventHandler}; coexists with the
+     * typed dispatch table.
+     */
     private _onEventHandler;
+    /**
+     * Returns the socket.io session id assigned at connect time, or
+     * an empty string when disconnected.
+     */
     getClientId(): string;
+    /**
+     * Returns whether the underlying socket.io client is in the
+     * connected state.
+     */
     isConnected(): boolean;
+    /**
+     * Pushes the cached auth token through the socket auth frame.
+     * Delegates to the transport implementation.
+     */
     sendRequestAuthSocket(): void;
+    /**
+     * Walks every constructor registered through
+     * {@link IServerEventHandler.registerEvent} and instantiates one
+     * handler instance per registered class.
+     *
+     * Why one per class: the registry stores **classes** to keep the
+     * decorator API ergonomic; `SocketPeer` materialises one instance
+     * per class on init so each handler can hold its own state if
+     * needed. Multiple registrations against the same event code are
+     * preserved — they are dispatched in registration order.
+     */
     private subscriberServerEventHandler;
+    /**
+     * Adds a runtime-built handler instance to the dispatch table.
+     *
+     * Used by {@link GNNetwork.subscriberServerEventHandler} when an
+     * application registers a handler that does not use the
+     * decorator-based registry.
+     */
     subscriberAServerEventHandler(serverEventHandler: IServerEventHandler): void;
+    /**
+     * Builds the underlying socket.io client and wires the
+     * response / event callbacks back into this class.
+     *
+     * Lifecycle:
+     * 1. Validate the global server settings.
+     * 2. Capture the `useSocket` flag into {@link isUse} so the queue
+     *    short-circuits when the socket transport is disabled.
+     * 3. Instantiate {@link NetworkingPeerSocketIOClient} and call
+     *    `init` + `reInitNewSocket` so the underlying client is
+     *    fully configured.
+     * 4. Bind the transport's response / event callbacks to
+     *    {@link onResponseHandler} (inherited from
+     *    {@link PeerBase}) and {@link onEventHandler} on this
+     *    class.
+     * 5. Materialise every decorator-registered server event handler
+     *    via {@link subscriberServerEventHandler}.
+     *
+     * @throws Error when the global server settings are missing.
+     */
     initGNSocketObject(): void;
+    /**
+     * Forwards a connect callback to the underlying transport's
+     * multi-subscriber list. See
+     * {@link GNNetwork.subscriberOnConnectHandler}.
+     */
     setOnConnectHandler(_onConnectHandler: Action0): void;
+    /**
+     * Forwards a disconnect callback to the underlying transport's
+     * multi-subscriber list. See
+     * {@link GNNetwork.subscriberOnDisconnectHandler}.
+     */
     setOnDisconnectHandler(_onDisconnectHandler: Action0): void;
+    /**
+     * Removes a connect callback from the underlying transport.
+     * No-op when the reference is not currently subscribed.
+     */
     removeOnConnectHandler(_onConnectHandler: Action0): void;
+    /**
+     * Removes a disconnect callback from the underlying transport.
+     * No-op when the reference is not currently subscribed.
+     */
     removeOnDisconnectHandler(_onDisconnectHandler: Action0): void;
+    /**
+     * Opens the underlying socket connection. The optional callback
+     * is fired once after the next successful connect.
+     */
     connect(_onSocketConnect: Action0): void;
+    /**
+     * Closes the underlying socket connection. The optional callback
+     * is fired once after the next observed disconnect.
+     */
     disconnect(_onSocketDisconnect: Action0): void;
+    /**
+     * Replaces the single-slot raw event observer. This is the
+     * callback {@link GNNetwork.setOnEventHandler} ultimately writes
+     * into.
+     */
     setOnEventHandler(_onEventHandler: Action1<OperationEvent>): void;
+    /**
+     * Sends a queued operation through the underlying transport.
+     *
+     * Substitutes the SDK-wide
+     * {@link OperationRequest.defaultTimeOut} sentinel with the
+     * configured `defaultTimeoutInSeconds` so the timeout sweep on
+     * {@link PeerBase.service} uses the real value rather than the
+     * sentinel. Then chains into `super.send(...)` so the in-flight
+     * map records the request id, logs the outbound frame, and
+     * finally delegates to
+     * {@link NetworkingSocketPeerBase.send}.
+     */
     send(operationPending: OperationPending): void;
+    /**
+     * Logs a diagnostic line whenever the queue accepts a new
+     * pending entry. The actual queueing is performed by
+     * {@link PeerBase.enqueue}; this override only adds telemetry.
+     */
     protected onEnqueue(operationPending: OperationPending): void;
+    /**
+     * Decodes a raw event payload, fans it out to subscribers and
+     * logs the dispatch.
+     *
+     * Steps:
+     * 1. Read `EventCode` and the `Parameters` sub-table from the
+     *    raw frame, producing a typed {@link OperationEvent}.
+     * 2. Log a `[GN Socket EVENT]` diagnostic line.
+     * 3. Invoke the single-slot raw observer when registered.
+     * 4. Look up the typed handler list for the event code and
+     *    invoke each registered handler in order.
+     *
+     * Unrecognised event codes (no handler registered) are silently
+     * dropped after the raw-observer call.
+     */
     onEventHandler(obj: GNHashtable): void;
+    /**
+     * Drives one tick of the peer.
+     *
+     * Order matters:
+     * 1. {@link PeerBase.service} runs first so timeouts are swept
+     *    and at most one queued request is dispatched.
+     * 2. The transport's own service hook drains any inbound packet
+     *    buffers (response + event). This split ensures the SDK
+     *    response handler sees responses for requests it just
+     *    dispatched on the same tick.
+     */
     service(): void;
 }

package/dist/runtime/typescript/ServiceUpdate.d.ts

@@ -1,8 +1,54 @@
 import { NetworkingPeer } from "./../networking/NetworkingPeer";
+/**
+ * Fixed-rate driver loop that ticks the shared {@link NetworkingPeer}.
+ *
+ * The SDK has no event loop of its own — every transport relies on
+ * a periodic `service()` call to drain queued requests, sweep
+ * timeouts, and decode buffered inbound packets. This class wires a
+ * `setInterval` to that `service()` method so the work happens
+ * automatically on the host runtime's timer.
+ *
+ * Lifecycle:
+ * - {@link GNNetwork.initGNSocketObject} constructs one instance,
+ *   binds {@link peer}, and calls {@link run}.
+ * - The interval fires every 50 ms (20 Hz). The cadence is
+ *   intentionally faster than the configured `sendRate` so the
+ *   queue stays responsive when the rate cap allows multiple
+ *   sends per second.
+ * - {@link stop} can be used in tests to halt the loop without
+ *   tearing down the peer; production code never calls it.
+ */
 export declare class ServiceUpdate {
+    /**
+     * Active interval handle. `null` when the loop is stopped.
+     */
     private intervalId;
+    /**
+     * Bound peer to service on every tick. Set by the caller before
+     * {@link run} is invoked.
+     */
     peer: NetworkingPeer;
+    /**
+     * Starts the 50 ms service loop. Idempotent — calling `run`
+     * while a loop is already active is a no-op so the SDK
+     * bootstrap path can be defensive without leaking timers.
+     */
     run(): void;
+    /**
+     * Stops the service loop and clears the interval handle.
+     *
+     * Mainly useful in test setups that want to control SDK
+     * timing manually. The SDK itself does not call this — the
+     * loop is intended to run for the lifetime of the JS realm.
+     */
     stop(): void;
+    /**
+     * Per-tick callback. Defers everything to
+     * {@link NetworkingPeer.service}, which in turn ticks both
+     * transports.
+     *
+     * Skips silently when {@link peer} is unbound so a partially
+     * constructed `ServiceUpdate` cannot crash the timer.
+     */
     private update;
 }

package/docs/AI_CHEATSHEET.md

@@ -0,0 +1,211 @@
+# AI Cheatsheet
+
+One-page reference cho AI agent / code assistant. Đọc file này trước, đào sâu khi cần.
+
+> Package: `@xmobitea/gn-typescript-client` · Entry point: `GNNetwork` (static class) · Stack: HTTP + WebSocket realtime.
+
+---
+
+## 1. Mandatory pattern (sao chép & dùng)
+
+```ts
+import { GNNetwork, GNServerSettings, ReturnCode, ErrorCode, MessageType, LogType } from "@xmobitea/gn-typescript-client";
+
+const settings = new GNServerSettings();
+settings.config({
+  serverAddress: "api.example.com",
+  serverPort: 443,
+  serverSocketPort: 443,
+  useSsl: true,
+  useSocket: true,
+  useHttp: true,
+  defaultTimeoutInSeconds: 20,
+  messageType: MessageType.MsgPack,
+  sendRate: 20,
+  reconnectDelay: 5000,
+  pingInterval: 20000,
+  pingTimeout: 20000,
+  secretKey: "<secret-key>",
+  gameId: "<game-id>",
+  logType: LogType.Error,
+});
+
+// Bootstrap — gọi 1 lần, idempotent
+GNNetwork.init(settings);
+
+// Mọi call: 2-tier check
+const res = await GNNetwork.<group>.<method>Async(req);
+if (res.returnCode !== ReturnCode.Ok) return; // transport / permission
+if (res.errorCode  !== ErrorCode.Ok)  return; // business
+useResult(res.responseData);
+```
+
+`Ok === 1` ở **cả** `ReturnCode` và `ErrorCode`. **KHÔNG** giả định `Ok === 0`.
+
+---
+
+## 2. Decision tree: tôi cần làm gì?
+
+| Tôi muốn... | Mở file |
+|---|---|
+| Login / register / refresh token | [guides/AUTHENTICATE.md](guides/AUTHENTICATE.md) · [reference/API_AUTHENTICATE.md](reference/API_AUTHENTICATE.md) |
+| MasterPlayer account chung nhiều game: identity, external link/unlink, profile, statistics, currencies, player data, email/push, segment/tag/ban | [guides/MASTER_PLAYER.md](guides/MASTER_PLAYER.md) · [reference/API_MASTER_PLAYER.md](reference/API_MASTER_PLAYER.md) |
+| GamePlayer account theo game environment (`dev`/`live` hoặc custom): profile, friends, groups, inventory owner, online status, statistics/currencies/data | [guides/GAME_PLAYER.md](guides/GAME_PLAYER.md) · [reference/API_GAME_PLAYER.md](reference/API_GAME_PLAYER.md) |
+| CharacterPlayer nhân vật thuộc GamePlayer: profile riêng, statistics/currencies/data, friends/groups/inventory owner theo character | [guides/CHARACTER_PLAYER.md](guides/CHARACTER_PLAYER.md) · [reference/API_CHARACTER_PLAYER.md](reference/API_CHARACTER_PLAYER.md) |
+| Inventory item: query, owner, amount, statistics | [guides/INVENTORY.md](guides/INVENTORY.md) · [reference/API_INVENTORY.md](reference/API_INVENTORY.md) |
+| Group metadata, member, message, group inventory | [guides/GROUP.md](guides/GROUP.md) · [reference/API_GROUP.md](reference/API_GROUP.md) |
+| Store catalog, buy, present, validate receipt | [guides/STORE_INVENTORY.md](guides/STORE_INVENTORY.md) · [reference/API_STORE_INVENTORY.md](reference/API_STORE_INVENTORY.md) |
+| Matchmaking ticket / queue / match query | [guides/MULTIPLAYER.md](guides/MULTIPLAYER.md) · [reference/API_MULTIPLAYER.md](reference/API_MULTIPLAYER.md) |
+| Content config + upload/download file metadata | [guides/CONTENT.md](guides/CONTENT.md) · [reference/API_CONTENT.md](reference/API_CONTENT.md) |
+| CloudScript: publish version, execute function | [guides/CLOUDSCRIPT.md](guides/CLOUDSCRIPT.md) · [reference/API_CLOUDSCRIPT.md](reference/API_CLOUDSCRIPT.md) |
+| Admin login, secret/maintenance/analytics | [guides/DASHBOARD.md](guides/DASHBOARD.md) · [reference/API_DASHBOARD.md](reference/API_DASHBOARD.md) |
+| Realtime event (friend, group, message) | [reference/EVENTS.md](reference/EVENTS.md) |
+| Tra DTO field theo class | [reference/DTO_INDEX.md](reference/DTO_INDEX.md) (grep) hoặc [reference/dto/](reference/dto/) |
+| Enum value numeric | [reference/ENUMS.md](reference/ENUMS.md) |
+| Config field của `GNServerSettings` | [reference/CONFIG.md](reference/CONFIG.md) |
+| Permission flag / `OperationNotAllow` | [reference/PERMISSION_RULES.md](reference/PERMISSION_RULES.md) · [RULES.md § 6](RULES.md#6-permission-flags) |
+| Cách check error / retry / debug | [reference/ERROR_HANDLING.md](reference/ERROR_HANDLING.md) |
+| Scenario end-to-end (16 case) | [COOKBOOK.md](COOKBOOK.md) |
+| Rule chung (route, permission, self/other-self, socket) | [RULES.md](RULES.md) |
+| Machine-readable manifest cho tooling | [ai-manifest.json](ai-manifest.json) |
+
+---
+
+## Glossary bắt buộc
+
+| Thuật ngữ | Nghĩa |
+|---|---|
+| `route` | Trust boundary của caller: client, server, hoặc admin. |
+| `self` | Target thuộc user đang authenticate. |
+| `other-self` | Target không thuộc user đang authenticate nhưng vẫn gọi qua route client. |
+| `otherSelfEnable` | Tên permission flag trong backend config. Dùng spelling này trong code/docs. |
+| `secretKey` | Key cấu hình permission per operation. Sai/thiếu secret trả `SecretInvalid`; secret đúng nhưng thiếu flag trả `OperationNotAllow`. |
+
+---
+
+## 3. Route decision (1 phút)
+
+Route = **trust boundary của caller**, KHÔNG phải target ownership.
+
+```
+Code chạy ở đâu?
+├─ App / browser của player           → GNNetwork.<group>           (Client)
+├─ Trusted backend (game server,       → GNNetwork.<group>.server    (Server)
+│  worker, webhook, internal svc)
+└─ Backoffice / GM tool / dashboard    → GNNetwork.<group>.admin     (Admin)
+
+Ngoại lệ: DashboardApi public wrapper vẫn đi RequestRole.Client; backend resolve admin từ authToken sau loginByAdminAccountAsync.
+```
+
+`self / other-self` chỉ áp dụng trên route `client`:
+- `MasterPlayer` / `GamePlayer`: `self` = `userId` trong request trùng `userId` đã authenticate (hoặc bỏ trống).
+- `CharacterPlayer` / `Inventory` / `Group`: `self` = entity thuộc ownership của user đang authenticate.
+- `Content` / `StoreInventory` / `Multiplayer` / `CloudScript`: không có ownership rõ ràng — không ép self/other-self.
+
+---
+
+## 4. Method signature mọi API
+
+```ts
+// Callback form
+GNNetwork.<group>.<method>(requestData, onResponse?, overrideAuthToken?, overrideSecretKey?, customTags?, timeout?);
+
+// Async form (preferred)
+const res = await GNNetwork.<group>.<method>Async(requestData, overrideAuthToken?, overrideSecretKey?, customTags?, timeout?);
+```
+
+| Param | Khi nào cần |
+|---|---|
+| `overrideAuthToken` | Impersonate / multi-session / admin gọi trên user khác |
+| `overrideSecretKey` | Override secret cho 1 request, ví dụ tool migration |
+| `customTags` | Trace id, build version, A/B tag — backend có thể log/route |
+| `timeout` | Override default per-request (giây) |
+
+Trong code copy-paste, build `requestData` bằng DTO class public:
+
+```ts
+const request = new <Group>Models.<Method>RequestData();
+request.someField = value;
+const res = await GNNetwork.<group>.<method>Async(request);
+```
+
+Không dùng object literal rồi cast sang `RequestData`. Chi tiết: [RULES.md § 8.1](RULES.md#81-build-request-dto-trong-code-copy-paste).
+
+Response field public (KHÔNG phải getter): `returnCode`, `errorCode`, `invalidMembers`, `debugMessage`, `responseData`.
+
+---
+
+## 5. Socket flow
+
+```
+1. Login HTTP (authenticate.loginByXxxAsync) — SDK cache authToken vào StorageService
+2. GNNetwork.connectSocket()                  — SDK auto-auth socket nếu authToken đã có
+3. (chỉ khi socket connect TRƯỚC token, hoặc token vừa đổi)
+   GNNetwork.sendRequestAuthSocket()          — re-auth thủ công, không reconnect
+```
+
+Hook trước khi connect:
+
+```ts
+GNNetwork.subscriberOnConnectHandler(() => { /* socket up */ });
+GNNetwork.subscriberOnDisconnectHandler(() => { /* socket down */ });
+GNNetwork.setOnEventHandler((event) => { /* raw event */ });
+
+// Realtime handler — gán static field; cleanup bằng no-op hoặc wrapper dispatcher
+OnGroupMessageUpdateEventHandler.onUpdate = (payload) => { ... };
+OnGroupMessageUpdateEventHandler.onUpdate = () => {};
+```
+
+Realtime KHÔNG tự chạy chỉ vì đã gọi HTTP (friend/group/...). Phải subscribe handler liệt kê trong [reference/EVENTS.md](reference/EVENTS.md).
+
+---
+
+## 6. Top 5 pitfalls (phải tránh)
+
+1. **Tưởng success là `0`** → `Ok === 1` cả 2 tầng.
+2. **Skip tầng `returnCode`, đọc thẳng `errorCode`** → khi `returnCode !== Ok`, `errorCode` + `responseData` không đáng tin.
+3. **Dùng getter `res.getReturnCode()`** → typed response dùng PUBLIC FIELDS.
+4. **Dùng `.server` / `.admin` từ frontend để vượt permission** → trust boundary leak.
+5. **`OperationNotAllow` = thiếu secret** → SAI. Secret hợp lệ nhưng permission rule cấm. Check route + flag.
+
+18 anti-patterns đầy đủ + cột "Triệu chứng / Fix": [RULES.md § 10](RULES.md#10-anti-patterns--pitfalls).
+
+---
+
+## 7. Diagnose `ReturnCode` (nhanh)
+
+| Code | Nghĩa | Fix |
+|---|---|---|
+| `Ok` | Sang tầng `errorCode` | — |
+| `OperationTimeout` | Network/backend chậm | Retry với backoff nếu idempotent |
+| `OperationNotAllow` | Permission rule cấm | Check route + permission flag (KHÔNG retry) |
+| `InternalServerError` | Backend exception | Báo ops, có thể retry 1 lần |
+| `OperationInvalid` | Operation không tồn tại với role hiện tại | Đang gọi sai namespace, sai `RequestType`/`RequestRole` |
+| `InvalidRequestParameters` | Field invalid | Đọc `res.invalidMembers` để biết field nào |
+| `OperationNotAuthorized` | Không auth với target | Check `authToken` còn hợp lệ |
+| `MaxCCUReject` | Vượt CCU limit | Backoff retry |
+| `MaxRequestReject` | Rate limit | Exponential backoff |
+| `MaxSizeRequestReject` | Payload quá to | Paginate / split |
+| `SecretInvalid` | Secret sai/thiếu/không khớp game | Fix `GNServerSettings` (KHÔNG retry) |
+
+So sánh bằng enum symbol, không hardcode số. Giá trị numeric: [reference/ENUMS.md](reference/ENUMS.md). Full table + `ErrorCode`: [reference/ERROR_HANDLING.md](reference/ERROR_HANDLING.md).
+
+Gặp `OperationNotAllow` — decision tree + code fallback: [COOKBOOK Scenario 16](COOKBOOK.md#scenario-16-diagnose-operationnotallow). Mapping route → flag cần: [RULES § 6.1](RULES.md#61-mapping-route-target--required-flag).
+
+---
+
+## 8. Khi nào ĐƯỢC đọc `src/`
+
+- Đang sửa chính SDK
+- Verify behavior nội bộ chưa được docs cover
+- Tích hợp package: **chỉ** dùng `AGENTS.md + docs + dist/*.d.ts`. Không bám `src/` cho integration code.
+
+---
+
+## 9. Liên kết quan trọng
+
+- Single-source-of-truth rules: [RULES.md](RULES.md)
+- AI entry guide chi tiết: [../AGENTS.md](../AGENTS.md)
+- Machine manifest: [ai-manifest.json](ai-manifest.json)
+- Concatenated bundle (optional, generated artifact): [llms-full.txt](llms-full.txt). Không dùng file này làm nguồn thắng khi nó mâu thuẫn với source docs.
+- llmstxt.org index: [../llms.txt](../llms.txt)