GearN TypeScript Client SDK

SDK TypeScript client cho GearN Server.

GNNetwork là entrypoint duy nhất ở tầng public API. Sau init(), toàn bộ thao tác đi qua các nhóm API tĩnh, gồm: GNNetwork.authenticate, GNNetwork.masterPlayer, GNNetwork.gamePlayer, GNNetwork.characterPlayer, GNNetwork.group, GNNetwork.inventory, GNNetwork.storeInventory, GNNetwork.content, GNNetwork.multiplayer, GNNetwork.cloudScript, GNNetwork.dashboard.

AI / code assistant: đọc docs/AI_CHEATSHEET.md trước (one-page), rồi docs/RULES.md cho rule chi tiết (route, permission, self/other-self, socket, error). Machine-readable manifest: docs/ai-manifest.json.

Package publish: @xmobitea/gn-typescript-client. Rule canonical: docs/RULES.md.

1. Yêu cầu

• Node.js ≥ 20.
• Custom DTO có decorator: bật experimentalDecorators + emitDecoratorMetadata trong tsconfig.json.

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

2. Cài đặt

npm install @xmobitea/gn-typescript-client

3. Cách SDK hoạt động

Flow chuẩn:

1. Tạo GNServerSettings.

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,
  logType: LogType.Error,
  secretKey: "<secret-key>",
  gameId: "<game-id>",
});

2. Gọi GNNetwork.init(settings) đúng 1 lần khi app chạy lần đầu tiên.

GNNetwork.init(settings);

3. Gọi API qua GNNetwork.*.

const infoRequestParam = new AuthenticateModels.InfoRequestParam();
infoRequestParam.countryCode = true;
infoRequestParam.displayName = true;

const loginRequest = new AuthenticateModels.LoginByCustomIdRequestData();
loginRequest.customId = "a custom id, store this custom id and use it to login next time";
loginRequest.createPlayerIfNotExists = true;
loginRequest.infoRequestParam = infoRequestParam;

const loginByCustomIdResponse = await GNNetwork.authenticate.loginByCustomIdAsync(loginRequest);

if (loginByCustomIdResponse.returnCode != ReturnCode.Ok || loginByCustomIdResponse.errorCode != ErrorCode.Ok) {
  console.log("login by custom id failed because the returnCode is " + loginByCustomIdResponse.returnCode + ", errorCode is " + loginByCustomIdResponse.errorCode);
  return;
}

console.log("Your userId: " + loginByCustomIdResponse.responseData.userId);
console.log("Your countryCode: " + loginByCustomIdResponse.responseData.infoResponseParameters.countryCode);
console.log("Your displayName: " + loginByCustomIdResponse.responseData.infoResponseParameters.displayName);

4. Nếu app cần realtime, sau khi đã có authToken → GNNetwork.connectSocket(), đồng thời GearN Server phải settings options.socketAppSettings.enable = true.
5. Socket auto-auth nếu token đã cache; chỉ GNNetwork.sendRequestAuthSocket() thủ công khi cần re-auth.

11 API group public:

• GNNetwork.authenticate — player login/register/refresh. Guide.
• GNNetwork.masterPlayer — master player account/profile/identity. Guide.
• GNNetwork.gamePlayer — game player gameplay/profile/friend/group/character. Guide.
• GNNetwork.characterPlayer — character-level (trong trường hợp 1 game player có nhiều nhân vật nhỏ) gameplay/social. Guide.
• GNNetwork.group — group metadata/member/message/currency. Guide.
• GNNetwork.inventory — inventory item metadata, statistics, log. Guide.
• GNNetwork.storeInventory — store catalog, buy/present, receipt validation. Guide.
• GNNetwork.content — content config, file upload/download metadata, small game asset, avatar asset. Guide.
• GNNetwork.multiplayer — matchmaking ticket, handle matchmaking trận đấu (HTTP, không socket). Guide.
• GNNetwork.cloudScript — CloudScript publish/version/execute, khi cần phải phối hợp các function lại với nhau, hoặc cần để server validate, cần phải viết cloudScript code từ GearN Dashboard. Guide.
• GNNetwork.dashboard — admin login + quản trị game/secret/analytics, không nên sử dụng nếu code game client. Guide.

4. Khởi tạo cơ bản

import {
  GNNetwork,
  GNServerSettings,
  LogType,
  MessageType,
} from "@xmobitea/gn-typescript-client";

const settings = new GNServerSettings();
settings.config({
  serverAddress: "127.0.0.1",          // GearN Server host / IP
  serverPort: 2202,                    // HTTP port, dựa vào options.applicationSettings.port và options.httpAppSettings.enable của GearN Server
  serverSocketPort: 2901,              // Socket port, dựa vào options.applicationSettings.socketPort của GearN Server
  useSsl: false,                       // true khi public endpoint dùng HTTPS, nếu useSsl thì setup serverPort và serverSocketPort thành -1, đồng thời serverAddress là url hợp lệ
  useSocket: true,                     // client muốn sử dụng socket để nhận các gói tin chủ động từ phía GearN Server, dựa vào options.socketAppSettings.enable của GearN Server
  useHttp: true,                       // luôn luôn là true, dựa vào options.httpAppSettings.enable của GearN Server
  defaultTimeoutInSeconds: 20,         // default timeout tính bằng giây, thời gian để timeout tính từ lúc bắt đầu gửi OperationRequest và chờ OperationResponse từ phía server, nếu vượt quá thời gian này, 1 mã lỗi ReturnCode.OperationTimeout sẽ được trả về
  messageType: MessageType.MsgPack,    // browser client sẽ tự fallback JSON cho HTTP, sử dụng msgPack giúp gói tin nhỏ nhẹ hơn nếu là client hoặc server, tăng tỉ lệ gửi thành công và tránh mất nhiều bandwidth, băng thông, dựa vào options.httpAppSettings.enablePostViaMsgPack và options.httpAppSettings.enablePostViaJson của GearN Server
  sendRate: 20,                        // tỉ lệ gửi OperationRequest mỗi giây, 20 có nghĩa là gửi 20 OperationRequest mỗi giây
  reconnectDelay: 5000,                // khi sử dụng socket, reconnectDelay socket io
  pingInterval: 20000,                 // khi sử dụng socket, pingInterval socket io
  pingTimeout: 20000,                  // khi sử dụng socket, pingTimeout socket io
  secretKey: "secret-key",             // secretKey để có thể dùng client này, lấy từ GearN Dashboard tab Settings/SecretInfo, lựa chọn secretKey với các Permission Rules phù hợp
  gameId: "game-id",                   // game id dành cho secretKey trong settings này hoặc override lại để chọn đúng game environment phù hợp, lấy từ GearN Dashboard từ tab Settings/SecretInfo
  logType: LogType.All,                // console log ra tất cả vấn đề thuộc loại nào
});

GNNetwork.init(settings);

Full field schema: docs/reference/CONFIG.md. Rule route / permission / self / other-self: docs/RULES.md.

5. Quick start: login bằng custom device id

import {
  GNNetwork,
  AuthenticateModels,
  ReturnCode,
  ErrorCode,
} from "@xmobitea/gn-typescript-client";

const infoRequest = new AuthenticateModels.InfoRequestParam();
infoRequest.displayName = true;
infoRequest.avatar = true;
infoRequest.playerDatas = true;

const request = new AuthenticateModels.LoginByCustomDeviceIdRequestData();
request.customDeviceId = "device-000001";
request.createPlayerIfNotExists = true;
request.infoRequestParam = infoRequest;

const res = await GNNetwork.authenticate.loginByCustomDeviceIdAsync(request);

if (res.returnCode !== ReturnCode.Ok) throw new Error(res.debugMessage);
if (res.errorCode  !== ErrorCode.Ok)  throw new Error(`Business error: ${res.errorCode}`);

console.log("userId",    res.responseData.userId);
console.log("userId",    GNNetwork.getAuthenticateStatus().getUserId());
console.log("authToken", res.responseData.authToken);
console.log("authToken", GNNetwork.getAuthenticateStatus().getAuthToken());
console.log("player",    res.responseData);

6. Login bằng account

import {
  GNNetwork,
  AuthenticateModels,
  ReturnCode,
  ErrorCode,
} from "@xmobitea/gn-typescript-client";

const infoRequest = new AuthenticateModels.InfoRequestParam();
infoRequest.displayName = true;
infoRequest.playerStatistics = true;

const request = new AuthenticateModels.LoginByAccountRequestData();
request.username = "player001";
request.password = "12345678";
request.infoRequestParam = infoRequest;

const res = await GNNetwork.authenticate.loginByAccountAsync(request);
if (res.returnCode !== ReturnCode.Ok) throw new Error(res.debugMessage);
if (res.errorCode  !== ErrorCode.Ok)  throw new Error(`Business error: ${res.errorCode}`);

7. Socket

import { GNNetwork } from "@xmobitea/gn-typescript-client";

// Subscribe TRƯỚC connect để không miss event ngay sau handshake
GNNetwork.subscriberOnConnectHandler(() => {
  console.log("socket connected", GNNetwork.getSocketSId());
});

GNNetwork.subscriberOnDisconnectHandler(() => {
  console.log("socket disconnected");
});

GNNetwork.setOnEventHandler((event) => {
  console.log("eventCode", event.getEventCode());
  console.log("parameters", event.getParameters()?.toData());
});

// Gọi sau khi đã login HTTP thành công
GNNetwork.connectSocket();

Re-auth thủ công (nếu socket connect trước token hoặc token vừa đổi):

if (GNNetwork.isSocketConnected() && GNNetwork.getAuthenticateStatus().getAuthToken()) {
  GNNetwork.sendRequestAuthSocket();
}

Helper:

• GNNetwork.isSocketConnected() — trạng thái socket session id.
• GNNetwork.getPing() — ping trung bình từ active transport.
• GNNetwork.syncTs() — sync local estimate server timestamp.

Realtime event handler (6 handler, subscribe bằng gán static onUpdate): docs/reference/EVENTS.md.

8. Dashboard / admin login

DashboardApi public wrapper đi RequestRole.Client. Sau loginByAdminAccountAsync, backend resolve admin context từ authToken.

import {
  GNNetwork,
  DashboardModels,
  ReturnCode,
  ErrorCode,
} from "@xmobitea/gn-typescript-client";

const request = new DashboardModels.LoginByAdminAccountRequestData();
request.username = "gnadmin";
request.password = "123456";

const res = await GNNetwork.dashboard.loginByAdminAccountAsync(request);
if (res.returnCode !== ReturnCode.Ok) throw new Error(res.debugMessage);
if (res.errorCode  !== ErrorCode.Ok)  throw new Error(`Business error: ${res.errorCode}`);

Rule chi tiết DashboardApi: docs/guides/DASHBOARD.md.

9. Method signature

Signature đầy đủ + bảng override param (overrideAuthToken, overrideSecretKey, customTags, timeout): docs/RULES.md § 8.

10. Response model

Typed response có 5 public field (không getter): returnCode, errorCode, invalidMembers, debugMessage, responseData. Pattern check 2 tầng + full table ReturnCode/ErrorCode: docs/reference/ERROR_HANDLING.md.

11. Auth state, gameId, health check, upload

// Auth state
GNNetwork.getAuthenticateStatus().getAuthToken();
GNNetwork.getAuthenticateStatus().getUserId();

// trong trường hợp secret key có thể dùng cho game id nào cũng được, trường hợp muốn dùng riêng cho game id xác định thì sử dụng hàm này
GNNetwork.getGNServerSettings().setGameId("your-game-id");

// Health check
await GNNetwork.healthCheckAsync();

// Auth info
await GNNetwork.getAuthInfoAsync("some-auth-token");

// Upload file (cần authToken hợp lệ)
const bytes = new Uint8Array([1, 2, 3, 4]);
await GNNetwork.uploadFileAsync("file-001", bytes, "demo.bin", "application/octet-stream");

// Download URL từ download token
GNNetwork.getDownloadFileUrl("download-token-from-server");

12. Advanced: ConverterService cho custom DTO

ConverterService là helper public để convert object typed có decorator ↔ GNHashtable / GNArray. Flow SDK bình thường không cần gọi tay (vì GNNetwork.init() đã tự init converter).

Chỉ dùng khi tự define DTO có decorator:

import {
  ConverterService,
  StringDataMember,
  NumberDataMember,
  BooleanDataMember,
  GNArrayDataMember,
  GNHashtableDataMember,
  DataMember,
  GNHashtable,
} from "@xmobitea/gn-typescript-client";

class ProfileStats {
  @NumberDataMember({ code: "level", defaultValue: 1, mustInt: true }) level: number;
  @NumberDataMember({ code: "power", defaultValue: 0 }) power: number;
}

class CustomProfile {
  @StringDataMember({ code: "displayName", mustNonNull: true }) displayName: string;
  @NumberDataMember({ code: "age", isOptional: true, minValue: 0, mustInt: true }) age?: number;
  @BooleanDataMember({ code: "isVip", defaultValue: false }) isVip: boolean;
  @GNHashtableDataMember({ code: "stats" }) stats: ProfileStats;
  @DataMember({ code: "metadata", isOptional: true }) metadata?: any;
}

const source = GNHashtable.builder()
  .add("displayName", "Player 01")
  .add("age", 20)
  .add("isVip", true)
  .add("stats", GNHashtable.builder().add("level", 12).add("power", 3456).build())
  .build();

const profile = ConverterService.deserializeObject(source, CustomProfile) as CustomProfile;
const serialized = ConverterService.serializeObject(profile, CustomProfile);

Rule:

• Dùng GNNetwork.* bình thường: không cần ConverterService.
• Tự build custom DTO: dùng deserializeObject / serializeObject / deserializeArray / serializeArray.
• GNArrayDataMember với element typed: luôn truyền elementCls.
• DataMember generic cho payload động: data có thể là raw GNHashtable / GNArray, gọi .toData() để lấy plain object.
• Không gọi ConverterService.init() tay nếu đã GNNetwork.init().

13. Custom operation

Low-level API để bọc operation chưa expose:

import {
  GNNetwork,
  CustomOperationRequestAbstract,
  CustomOperationResponseAbstract,
  RequestRole,
  RequestType,
  OperationCode,
  ParameterCode,
  StringDataMember,
} from "@xmobitea/gn-typescript-client";

class ExampleRequestData {
  @StringDataMember({ code: ParameterCode.Key, mustNonNull: true }) public key: string;
}

class ExampleResponseData {
  @StringDataMember({ code: ParameterCode.Value, isOptional: true }) public value?: string;
}

class ExampleRequest extends CustomOperationRequestAbstract<ExampleRequestData> {
  protected override operationCode: string = OperationCode.GetCustomData;
  protected override requestType: RequestType = RequestType.CharacterPlayer;
  protected override role: RequestRole = RequestRole.Client;

  constructor(requestData: ExampleRequestData, timeout: number) {
    super(requestData, timeout);
    this.requestDataCls = ExampleRequestData;
  }
}

class ExampleResponse extends CustomOperationResponseAbstract<ExampleResponseData> {
  constructor() {
    super();
    this.responseDataCls = ExampleResponseData;
  }
}

const requestData = new ExampleRequestData();
requestData.key = "tutorial";

const res = await GNNetwork.sendViaHttpTRequestTResponseAsync(
  new ExampleRequest(requestData, 20),
  null,
  null,
  null,
  ExampleResponse,
);

14. Browser / Node / Cocos

• Detect platform: GNSupport.getPlatformType().
• Browser + HTTP + MsgPack → SDK auto-fallback JSON.
• Cocos Creator: giữ 2 flag TS decorator nếu có custom DTO. Integration guide.

15. Build & publish

npm run test
npm run build:node       # CommonJS cho Node
npm run build:udm        # UMD
npm run build:minudm     # UMD minified
npm run build:cocos      # Cocos
npm run build            # tất cả output chính

16. Lỗi hay gặp

Full checklist + anti-patterns: docs/RULES.md § 10. Return/error code table: docs/reference/ERROR_HANDLING.md.

17. File tham khảo trong repo

• Entry public API: src/runtime/GNNetwork.ts
• Export surface: src/index.ts
• Local debug: index.js

18. TL;DR

1. GNNetwork.init(settings) 1 lần.
2. Mọi call qua GNNetwork.*.
3. Check returnCode trước, errorCode sau.
4. Socket: login HTTP → connectSocket(); chỉ sendRequestAuthSocket() khi cần re-auth thủ công.
5. Rule chi tiết → docs/RULES.md.