@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/llms.txt

@@ -0,0 +1,47 @@
+# GearN TypeScript Client SDK
+
+> TypeScript SDK cho GearN backend: authenticate, realtime socket, player/inventory/group/multiplayer/cloudscript APIs. Package: `@xmobitea/gn-typescript-client`. Entrypoint: static class `GNNetwork`. Cài: `npm install @xmobitea/gn-typescript-client`.
+
+Rule canonical: [docs/RULES.md](docs/RULES.md). Đọc trước khi sinh code.
+
+## Start here
+
+- [docs/AI_CHEATSHEET.md](docs/AI_CHEATSHEET.md): one-page reference (decision tree, mandatory pattern, top pitfalls)
+- [docs/RULES.md](docs/RULES.md): single source of truth cho route, permission, self/other-self, socket, error
+- [AGENTS.md](AGENTS.md): full AI entry guide
+- [docs/ai-manifest.json](docs/ai-manifest.json): machine-readable manifest (schemaVersion=3)
+
+## Reference
+
+- [docs/reference/API_INDEX.md](docs/reference/API_INDEX.md): 11 API group, 945 public async methods (bảng method → DTO → response class)
+- [docs/reference/DTO_INDEX.md](docs/reference/DTO_INDEX.md): 2506 DTO, grep target (đừng load full)
+- [docs/reference/dto/](docs/reference/dto/): DTO field-level theo từng domain
+- [docs/reference/ENUMS.md](docs/reference/ENUMS.md): giá trị numeric của mọi enum
+- [docs/reference/CONFIG.md](docs/reference/CONFIG.md): schema `GNServerSettings`
+- [docs/reference/PERMISSION_RULES.md](docs/reference/PERMISSION_RULES.md): permission route/target/flag offline
+- [docs/reference/EVENTS.md](docs/reference/EVENTS.md): 6 realtime event handler
+- [docs/reference/ERROR_HANDLING.md](docs/reference/ERROR_HANDLING.md): pattern check `ReturnCode` + `ErrorCode`
+
+## Cookbook
+
+- [docs/COOKBOOK.md](docs/COOKBOOK.md): 16 scenario end-to-end (init, login, socket, matchmaking, store, cloudscript, cleanup, diagnose permission)
+
+## Guides (per domain)
+
+- [docs/guides/AUTHENTICATE.md](docs/guides/AUTHENTICATE.md)
+- [docs/guides/MASTER_PLAYER.md](docs/guides/MASTER_PLAYER.md)
+- [docs/guides/GAME_PLAYER.md](docs/guides/GAME_PLAYER.md)
+- [docs/guides/CHARACTER_PLAYER.md](docs/guides/CHARACTER_PLAYER.md)
+- [docs/guides/INVENTORY.md](docs/guides/INVENTORY.md)
+- [docs/guides/GROUP.md](docs/guides/GROUP.md)
+- [docs/guides/STORE_INVENTORY.md](docs/guides/STORE_INVENTORY.md)
+- [docs/guides/MULTIPLAYER.md](docs/guides/MULTIPLAYER.md)
+- [docs/guides/CONTENT.md](docs/guides/CONTENT.md)
+- [docs/guides/CLOUDSCRIPT.md](docs/guides/CLOUDSCRIPT.md)
+- [docs/guides/DASHBOARD.md](docs/guides/DASHBOARD.md)
+- [docs/guides/COCOS_CREATOR_INTEGRATION.md](docs/guides/COCOS_CREATOR_INTEGRATION.md)
+
+## Optional
+
+- [README.MD](README.MD): full package README
+- [docs/llms-full.txt](docs/llms-full.txt): optional generated-bundle placeholder; source docs above always win

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "@xmobitea/gn-typescript-client",
-  "version": "2.6.13",
+  "version": "2.6.14",
   "description": "GearN Typescript Client SDK by XmobiTea (Pro)",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
+  "files": [
+    "dist",
+    "docs",
+    "README.MD",
+    "LICENSE",
+    "AGENTS.md",
+    "llms.txt"
+  ],
   "scripts": {
     "dev": "rm -rf ./dist && npm run build:node && npm run debug",
     "debug": "node index.js",
     "test": "mocha -r ts-node/register ./test/**/*.test.ts",
+    "docs:validate": "node scripts/validate-ai-docs.mjs",
     "build:node": "webpack --config webpack.config.mjs --mode production --stats-modules",
     "build:udm": "webpack --config webpack.config.udm.mjs --mode production --stats-modules",
     "build:minudm": "webpack --config webpack.config.min.udm.mjs --mode production --stats-modules",
     "build": "rm -rf ./dist && npm run build:node && npm run build:udm && npm run build:minudm",
-    "build:withoutwebpack": "rm -rf ./dist && tsc",
+    "build:tsc": "rm -rf ./dist && tsc",
     "build:cocos": "rm -rf ./dist && webpack --config webpack.config.cocos.mjs --mode production --stats-modules",
     "push": "npm run build && npm publish && git push"
   },
@@ -63,4 +72,4 @@
   "engines": {
     "node": ">=20.0.0"
   }
-}
+}

package/GNServerSettings.debug.json

@@ -1,21 +0,0 @@
-{
-    "name": "debug",
-    "options": {
-        "serverAddress": "127.0.0.1",
-        "serverPort": 2202,
-        "serverSocketPort": 2901,
-        "useSsl": false,
-        "useSocket": true,
-        "useHttp": true,
-        "defaultTimeoutInSeconds": 20,
-        "messageType": 2,
-        "sendRate": 20,
-        "reconnectDelay": 5000,
-        "pingInterval": 20000,
-        "pingTimeout": 20000,
-        "logType": 4,
-        "adminSecretKey": "",
-        "serverSecretKey": "",
-        "clientSecretKey": ""
-    }
-}

package/docs/COCOS_CREATOR_INTEGRATION.md

@@ -1,116 +0,0 @@
-# GearN SDK - Cocos Creator 3.x Integration Guide
-
-## Overview
-
-GearN TypeScript SDK hỗ trợ đầy đủ Cocos Creator 3.x thông qua npm package.
-
-## Installation
-
-### 1. Cài đặt qua npm
-
-Trong thư mục project Cocos Creator của bạn:
-
-```bash
-npm install @xmobitea/gn-typescript-client
-```
-
-### 2. TypeScript Configuration
-
-Đảm bảo `tsconfig.json` của Cocos Creator project có cài đặt tương thích:
-
-```json
-{
-  "compilerOptions": {
-    "esModuleInterop": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
-```
-
-## Basic Usage
-
-### Initialize SDK
-
-```typescript
-import { GNNetwork, GNServerSettings, LogType, MessageType } from '@xmobitea/gn-typescript-client';
-
-// Tạo server settings
-const settings = new GNServerSettings({
-    httpUrl: "http://your-server:8080",
-    socketUrl: "ws://your-server:8080",
-    secretKey: "your-secret-key",
-    useSocket: true,
-    useHttp: true,
-    logType: LogType.All,
-    sendRate: 30,
-    messageType: MessageType.MsgPack,
-});
-
-// Initialize
-GNNetwork.init(settings);
-```
-
-### Authentication
-
-```typescript
-// Login với Device ID
-const response = await GNNetwork.authenticate.loginDeviceIdAsync({
-    deviceId: "unique-device-id",
-    createAccount: true,
-});
-
-if (!response.hasError()) {
-    console.log("User ID:", GNNetwork.getAuthenticateStatus().getUserId());
-}
-```
-
-### Socket Connection
-
-```typescript
-// Subscribe events
-GNNetwork.subscriberOnConnectHandler(() => {
-    console.log("Connected!");
-    GNNetwork.sendRequestAuthSocket();
-});
-
-GNNetwork.subscriberOnDisconnectHandler(() => {
-    console.log("Disconnected!");
-});
-
-// Connect
-GNNetwork.connectSocket();
-```
-
-## Example Component
-
-Xem file mẫu hoàn chỉnh tại: [examples/cocos-creator/GearNExample.ts](../examples/cocos-creator/GearNExample.ts)
-
-## Platform Detection
-
-SDK tự động phát hiện Cocos Creator environment:
-
-```typescript
-import { GNSupport } from '@xmobitea/gn-typescript-client';
-
-if (GNSupport.isCocosCreator()) {
-    console.log("Running in Cocos Creator");
-}
-```
-
-## Storage
-
-SDK tự động sử dụng `cc.sys.localStorage` trong Cocos Creator để lưu auth token.
-
-## Troubleshooting
-
-### Module not found
-Đảm bảo đã chạy `npm install` trong project folder.
-
-### Build errors
-Kiểm tra `tsconfig.json` có `esModuleInterop: true`.
-
-## Support
-
-- GitHub Issues: https://github.com/XmobiTea-Family/GearN-typescript-client-sdk/issues
-- Homepage: https://gearn.net

package/examples/cocos-creator/GearNExample.ts.txt

@@ -1,176 +0,0 @@
-/**
- * GearNExample.ts - Example Cocos Creator 3.x Component using GearN SDK
- * 
- * This component demonstrates how to integrate the GearN SDK
- * with a Cocos Creator 3.x project.
- * 
- * Installation:
- * 1. npm install @xmobitea/gn-typescript-client
- * 2. Copy this file to your Cocos Creator project's scripts folder
- * 3. Attach to a Node in your scene
- */
-
-import { _decorator, Component, log, warn, error } from 'cc';
-
-// Import GearN SDK
-import {
-    GNNetwork,
-    GNServerSettings,
-    GNServerSettingsOptions,
-    LogType,
-    MessageType
-} from '@xmobitea/gn-typescript-client';
-
-const { ccclass, property } = _decorator;
-
-@ccclass('GearNExample')
-export class GearNExample extends Component {
-
-    @property({ tooltip: "GearN Server HTTP URL" })
-    httpUrl: string = "http://localhost:8080";
-
-    @property({ tooltip: "GearN Server Socket URL" })
-    socketUrl: string = "ws://localhost:8080";
-
-    @property({ tooltip: "Your Game/App Secret Key" })
-    secretKey: string = "";
-
-    @property({ tooltip: "Enable debug logging" })
-    enableDebugLog: boolean = true;
-
-    start() {
-        this.initializeGearN();
-    }
-
-    /**
-     * Initialize GearN SDK
-     */
-    private initializeGearN(): void {
-        try {
-            // Create server settings
-            const settings: GNServerSettingsOptions = {
-                httpUrl: this.httpUrl,
-                socketUrl: this.socketUrl,
-                secretKey: this.secretKey,
-                useSocket: true,
-                useHttp: true,
-                logType: this.enableDebugLog ? LogType.All : LogType.None,
-                sendRate: 30,
-                messageType: MessageType.MsgPack,
-                socketReconnectDelay: 1000,
-                socketPingInterval: 3000,
-                socketPingTimeout: 5000,
-                httpRequestTimeout: 10,
-            };
-
-            const gnServerSettings = new GNServerSettings(settings);
-
-            // Initialize GearN
-            GNNetwork.init(gnServerSettings);
-
-            log('[GearN] SDK initialized successfully!');
-            log('[GearN] Platform:', GNNetwork.getPlatform());
-
-            // Subscribe to connection events
-            this.setupConnectionHandlers();
-
-        } catch (err) {
-            error('[GearN] Failed to initialize SDK:', err);
-        }
-    }
-
-    /**
-     * Setup socket connection event handlers
-     */
-    private setupConnectionHandlers(): void {
-        GNNetwork.subscriberOnConnectHandler(() => {
-            log('[GearN] Socket connected! SID:', GNNetwork.getSocketSId());
-
-            // Authenticate after connection
-            this.onSocketConnected();
-        });
-
-        GNNetwork.subscriberOnDisconnectHandler(() => {
-            warn('[GearN] Socket disconnected!');
-        });
-    }
-
-    /**
-     * Called when socket is connected
-     */
-    private onSocketConnected(): void {
-        // Example: Send auth token if already logged in
-        const authStatus = GNNetwork.getAuthenticateStatus();
-        if (authStatus.getAuthToken()) {
-            GNNetwork.sendRequestAuthSocket();
-            log('[GearN] Auth token sent to socket');
-        }
-    }
-
-    /**
-     * Connect to socket server
-     */
-    public connectSocket(): void {
-        log('[GearN] Connecting to socket...');
-        GNNetwork.connectSocket(() => {
-            log('[GearN] Socket connection initiated');
-        });
-    }
-
-    /**
-     * Disconnect from socket server
-     */
-    public disconnectSocket(): void {
-        log('[GearN] Disconnecting from socket...');
-        GNNetwork.disconnectSocket(() => {
-            log('[GearN] Socket disconnected');
-        });
-    }
-
-    /**
-     * Example: Login with device ID
-     */
-    public async loginWithDeviceId(deviceId: string): Promise<void> {
-        try {
-            log('[GearN] Logging in with device ID:', deviceId);
-
-            const response = await GNNetwork.authenticate.loginDeviceIdAsync({
-                deviceId: deviceId,
-                createAccount: true,
-            });
-
-            if (response.hasError()) {
-                error('[GearN] Login failed:', response.getDebugMessage());
-                return;
-            }
-
-            log('[GearN] Login successful!');
-            log('[GearN] User ID:', GNNetwork.getAuthenticateStatus().getUserId());
-
-            // Connect socket after successful login
-            this.connectSocket();
-
-        } catch (err) {
-            error('[GearN] Login error:', err);
-        }
-    }
-
-    /**
-     * Example: Get server health status
-     */
-    public async checkServerHealth(): Promise<void> {
-        try {
-            const response = await GNNetwork.healthCheckAsync();
-            log('[GearN] Server health:', response);
-        } catch (err) {
-            error('[GearN] Health check failed:', err);
-        }
-    }
-
-    onDestroy() {
-        // Cleanup: disconnect socket when component is destroyed
-        if (GNNetwork.isSocketConnected()) {
-            GNNetwork.disconnectSocket();
-        }
-    }
-}

package/srcSwift/Package.swift

@@ -1,32 +0,0 @@
-// swift-tools-version: 5.7
-// The swift-tools-version declares the minimum version of Swift required to build this package.
-
-import PackageDescription
-
-let package = Package(
-    name: "GearN",
-    products: [
-        // Products define the executables and libraries a package produces, making them visible to other packages.
-        .library(
-            name: "GearN",
-            targets: ["GearN"]),
-    ],
-    dependencies: [
-        // Dependencies declare other packages that this package depends on.
-        .package(url: "https://github.com/socketio/socket.io-client-swift", from: "16.1.1"),
-    ],
-    targets: [
-        // Targets are the basic building blocks of a package, defining a module or a test suite.
-        // Targets can depend on other targets in this package and products from dependencies.
-        .target(
-            name: "GearN",
-            dependencies: [
-                .product(name: "SocketIO", package: "socket.io-client-swift")
-            ],
-            path: "Sources/GearN"),
-        .testTarget(
-            name: "GearNTests",
-            dependencies: ["GearN"],
-            path: "Tests/GearNTests"),
-    ]
-)