{
  "schemaVersion": 3,
  "package": {
    "name": "@xmobitea/gn-typescript-client",
    "entryPoint": "GNNetwork",
    "installCommand": "npm install @xmobitea/gn-typescript-client",
    "typesEntry": "dist/index.d.ts",
    "runtimeEntry": "dist/index.js"
  },
  "docs": {
    "readingOrderForAi": [
      "docs/AI_CHEATSHEET.md",
      "docs/RULES.md",
      "docs/ai-manifest.json",
      "docs/reference/API_INDEX.md",
      "docs/reference/ERROR_HANDLING.md",
      "docs/reference/CONFIG.md",
      "docs/reference/EVENTS.md",
      "docs/reference/ENUMS.md",
      "docs/COOKBOOK.md"
    ],
    "entryPoints": {
      "cheatsheet": "docs/AI_CHEATSHEET.md",
      "rules": "docs/RULES.md",
      "agentGuide": "AGENTS.md",
      "llmstxtIndex": "llms.txt",
      "fullBundle": "docs/llms-full.txt"
    },
    "reference": {
      "apiIndex": "docs/reference/API_INDEX.md",
      "dtoIndex": "docs/reference/DTO_INDEX.md",
      "dtoDirectory": "docs/reference/dto",
      "enums": "docs/reference/ENUMS.md",
      "config": "docs/reference/CONFIG.md",
      "events": "docs/reference/EVENTS.md",
      "errorHandling": "docs/reference/ERROR_HANDLING.md",
      "permissionRules": "docs/reference/PERMISSION_RULES.md"
    },
    "cookbook": "docs/COOKBOOK.md",
    "guidesDirectory": "docs/guides",
    "guidanceForAiConsumer": [
      "đọc docs/AI_CHEATSHEET.md trước (one-page) để biết file nào cần mở tiếp",
      "đọc docs/RULES.md cho rule cross-cutting (route, permission, self/other-self, socket, error)",
      "tra method signature qua docs/reference/API_<GROUP>.md",
      "tra DTO field qua docs/reference/dto/<DOMAIN>.md hoặc grep DTO_INDEX.md (2506 rows, đừng load full)",
      "tra enum value numeric qua docs/reference/ENUMS.md",
      "scenario end-to-end xem docs/COOKBOOK.md (16 scenarios)",
      "chỉ fall back đọc dist/*.d.ts khi câu hỏi nằm ngoài scope docs",
      "docs/llms-full.txt là generated bundle optional; không dùng làm source thắng khi mâu thuẫn với source docs"
    ]
  },
  "globalRules": {
    "preferAsyncAwait": true,
    "requireInitBeforeAnyApiCall": true,
    "initMethod": "GNNetwork.init(settings)",
    "initStrategy": "once_per_app_session",
    "repeatInitBehavior": "ignored",
    "successCodeCheckOrder": [
      "returnCode",
      "errorCode"
    ],
    "successCodes": {
      "returnCodeOk": 1,
      "errorCodeOk": 1
    },
    "doNotAssumeSuccessIsZero": true,
    "doNotReadSrcForNormalPackageUsage": true,
    "responseFieldAccess": "public_fields_not_getters"
  },
  "returnCodeMeanings": {
    "Ok": "success, sang tầng errorCode để check business",
    "OperationTimeout": "timeout từ SDK hoặc backend; retry với backoff nếu operation idempotent",
    "OperationNotAllow": "secretKey hợp lệ nhưng permission rules không cho phép operation trong target context; check route + flag self/other/server/admin",
    "InternalServerError": "backend exception; có thể retry 1 lần rồi escalate",
    "OperationInvalid": "operation code không tồn tại hoặc không hợp lệ với request type/role",
    "InvalidRequestParameters": "request shape sai; đọc res.invalidMembers",
    "OperationNotAuthorized": "caller chưa auth; refresh token hoặc re-login",
    "MaxCCUReject": "vượt CCU limit; backoff retry",
    "MaxRequestReject": "rate limit; exponential backoff",
    "MaxSizeRequestReject": "payload vượt size; paginate hoặc split",
    "SecretInvalid": "secretKey sai, thiếu, hoặc không khớp game; KHÔNG retry, fix config"
  },
  "routing": {
    "principle": "trust_boundary",
    "client": "code chạy trong app hoặc player client",
    "server": "code chạy trong trusted backend như game server, internal service, worker, cron hoặc webhook backend",
    "admin": "code chạy trong backoffice, dashboard, GM tool, migration tool hoặc vận hành dữ liệu",
    "rules": [
      "không chọn server hoặc admin chỉ vì target không thuộc user hiện tại",
      "không dùng namespace server hoặc admin từ app client chỉ để vượt permission",
      "không suy diễn route chỉ từ việc request có hay không có userId"
    ]
  },
  "permissionRules": {
    "authoritativeDoc": "docs/reference/PERMISSION_RULES.md",
    "externalReference": "https://docs.gearn.net/permissionRules",
    "note": "Backend GearN Server/dashboard là runtime source-of-truth per-operation. Trong repo, dùng docs/reference/PERMISSION_RULES.md và docs/reference/API_<GROUP>.md để lấy operation name và mapping flag; externalReference chỉ là mirror khi cần đối chiếu online.",
    "selfOtherSelfOnlyApplyOnClientRoute": true,
    "flags": {
      "selfEnable": "cho phép thực thi trên chính tài nguyên thuộc user đã authenticate",
      "otherSelfEnable": "cho phép thực thi trên tài nguyên không thuộc user đã authenticate",
      "serverSelfEnable": "cho phép thực thi qua route server",
      "adminSelfEnable": "cho phép thực thi qua route admin"
    },
    "routeToFlagMapping": [
      { "callerNamespace": "GNNetwork.<group>.<method>()",        "route": "client", "target": "self",       "requiredFlag": "selfEnable" },
      { "callerNamespace": "GNNetwork.<group>.<method>(otherId)", "route": "client", "target": "other-self", "requiredFlag": "otherSelfEnable" },
      { "callerNamespace": "GNNetwork.<group>.server.<method>()", "route": "server", "target": "*",          "requiredFlag": "serverSelfEnable" },
      { "callerNamespace": "GNNetwork.<group>.admin.<method>()",  "route": "admin",  "target": "*",          "requiredFlag": "adminSelfEnable" }
    ],
    "configOwnership": {
      "configuredBy": "backend_admin_on_gearn_dashboard",
      "configGranularity": "per secretKey x per operation x per flag",
      "clientCanChange": false,
      "recommendedActionOnOperationNotAllow": [
        "dùng secretKey khác qua GNServerSettings.secretKey",
        "truyền overrideSecretKey per-request",
        "yêu cầu backend admin bật flag cho secret hiện tại trong GearN Dashboard"
      ]
    },
    "selfSemantics": {
      "masterPlayerAndGamePlayer": "target userId trùng userId đã authenticate thành công",
      "characterPlayerInventoryGroup": "entity target thuộc ownership của GamePlayer có userId trùng userId đã authenticate",
      "domainsWithoutClearOwnership": [
        "ContentApi",
        "StoreInventoryApi",
        "MultiplayerApi",
        "CloudScriptApi"
      ]
    },
    "operationNotAllowChecklist": [
      "xác định route đang gọi: client hay .server hay .admin",
      "xác định target self hay other-self theo self-semantics của domain",
      "tra routeToFlagMapping ra flag cần",
      "check secretKey active có flag đó cho operation này không (xem backend dashboard hoặc hỏi admin)",
      "nếu không có: dùng secret khác, overrideSecretKey, hoặc yêu cầu backend admin bật flag trong GearN Dashboard",
      "KHÔNG retry - đây là config fix"
    ],
    "diagnoseWorkflow": "docs/COOKBOOK.md#scenario-16-diagnose-operationnotallow"
  },
  "authAndSocket": {
    "flow": [
      "login hoặc refresh token qua HTTP",
      "sau khi SDK đã có authToken, nếu cần realtime thì gọi GNNetwork.connectSocket()",
      "nếu socket connect khi token đã có trong cache, SDK sẽ tự auth socket",
      "chỉ gọi GNNetwork.sendRequestAuthSocket() khi cần re-auth thủ công"
    ],
    "rules": [
      "không gộp auth socket với auth HTTP",
      "không bắt buộc gọi tay sendRequestAuthSocket sau mọi lần connectSocket",
      "nếu socket connect trước khi token xuất hiện hoặc token vừa đổi và không muốn reconnect thì mới gọi sendRequestAuthSocket"
    ]
  },
  "dashboardSpecialCase": {
    "apiGroup": "DashboardApi",
    "publicWrapperRequestRole": "Client",
    "backendAuthBehavior": "sau loginByAdminAccountAsync thành công, backend middleware resolve secret context và quyền admin riêng từ authToken",
    "emptyPublicNamespaces": [
      "GNNetwork.dashboard.server",
      "GNNetwork.dashboard.admin"
    ]
  },
  "enums": {
    "docPath": "docs/reference/ENUMS.md",
    "list": [
      { "name": "ReturnCode", "anchor": "returncode", "okValue": 1, "role": "transport" },
      { "name": "ErrorCode", "anchor": "errorcode", "okValue": 1, "role": "domain" },
      { "name": "RequestRole", "anchor": "requestrole" },
      { "name": "RequestType", "anchor": "requesttype" },
      { "name": "MessageType", "anchor": "messagetype" },
      { "name": "PostType", "anchor": "posttype" },
      { "name": "LogType", "anchor": "logtype" },
      { "name": "FriendStatus", "anchor": "friendstatus" },
      { "name": "GroupStatus", "anchor": "groupstatus" },
      { "name": "GoogleLoginType", "anchor": "googlelogintype" },
      { "name": "InvalidMemberType", "anchor": "invalidmembertype" },
      { "name": "ItemType", "anchor": "itemtype" },
      { "name": "OwnerType", "anchor": "ownertype" },
      { "name": "PushPlatformType", "anchor": "pushplatformtype" },
      { "name": "MatchmakingMemberStatus", "anchor": "matchmakingmemberstatus" },
      { "name": "MatchmakingTicketStatus", "anchor": "matchmakingticketstatus" },
      { "name": "MatchStatus", "anchor": "matchstatus" },
      { "name": "ExecuteResponseStatus", "anchor": "executeresponsestatus" },
      { "name": "StoreItemType", "anchor": "storeitemtype" },
      { "name": "StoreReceiveType", "anchor": "storereceivetype" },
      { "name": "PermissionDataItem", "anchor": "permissiondataitem" },
      { "name": "FieldDataType", "anchor": "fielddatatype" }
    ]
  },
  "events": {
    "docPath": "docs/reference/EVENTS.md",
    "subscribePattern": "<Handler>.onUpdate = (payload) => { … }",
    "unsubscribePattern": "<Handler>.onUpdate = () => {}",
    "prerequisite": "socket connected + authenticated",
    "subscribeOrder": "subscribe trước khi gọi GNNetwork.connectSocket() để không bỏ lỡ event ngay sau handshake",
    "list": [
      {
        "name": "OnGroupMessageUpdateEventHandler",
        "payloadClass": "GroupMessageUpdate",
        "anchor": "ongroupmessageupdateeventhandler",
        "scope": "Group",
        "payloadKeys": ["groupMessages", "groupId", "characterId?"]
      },
      {
        "name": "OnGroupMemberUpdateEventHandler",
        "payloadClass": "GroupMemberUpdate",
        "anchor": "ongroupmemberupdateeventhandler",
        "scope": "Group",
        "payloadKeys": ["members", "groupId"]
      },
      {
        "name": "OnGamePlayerFriendUpdateEventHandler",
        "payloadClass": "GamePlayerFriendUpdate",
        "anchor": "ongameplayerfriendupdateeventhandler",
        "scope": "GamePlayer",
        "payloadKeys": ["playerFriends", "characterId?"]
      },
      {
        "name": "OnGamePlayerGroupUpdateEventHandler",
        "payloadClass": "GamePlayerGroupUpdate",
        "anchor": "ongameplayergroupupdateeventhandler",
        "scope": "GamePlayer",
        "payloadKeys": ["playerGroups", "characterId?"]
      },
      {
        "name": "OnCharacterPlayerFriendUpdateEventHandler",
        "payloadClass": "CharacterPlayerFriendUpdate",
        "anchor": "oncharacterplayerfriendupdateeventhandler",
        "scope": "CharacterPlayer",
        "payloadKeys": ["playerFriends", "characterId"]
      },
      {
        "name": "OnCharacterPlayerGroupUpdateEventHandler",
        "payloadClass": "CharacterPlayerGroupUpdate",
        "anchor": "oncharacterplayergroupupdateeventhandler",
        "scope": "CharacterPlayer",
        "payloadKeys": ["playerGroups", "characterId"]
      }
    ]
  },
  "configSchema": {
    "docPath": "docs/reference/CONFIG.md",
    "class": "GNServerSettingsOptions",
    "ctorUsage": "const settings = new GNServerSettings(); settings.config({ serverAddress, serverPort, gameId, secretKey, ... }); GNNetwork.init(settings)",
    "fields": [
      { "name": "serverAddress", "type": "string", "default": "127.0.0.1" },
      { "name": "serverPort", "type": "number", "default": 2202, "unit": "port" },
      { "name": "serverSocketPort", "type": "number", "default": 2901, "unit": "port" },
      { "name": "useSsl", "type": "boolean", "default": false },
      { "name": "useSocket", "type": "boolean", "default": true },
      { "name": "useHttp", "type": "boolean", "default": true },
      { "name": "defaultTimeoutInSeconds", "type": "number", "default": 20, "unit": "seconds" },
      { "name": "messageType", "type": "MessageType", "default": "MsgPack" },
      { "name": "sendRate", "type": "number", "default": 20, "unit": "messages_per_second" },
      { "name": "reconnectDelay", "type": "number", "default": 5000, "unit": "milliseconds" },
      { "name": "pingInterval", "type": "number", "default": 20000, "unit": "milliseconds" },
      { "name": "pingTimeout", "type": "number", "default": 20000, "unit": "milliseconds" },
      { "name": "secretKey", "type": "string" },
      { "name": "gameId", "type": "string" },
      { "name": "logType", "type": "LogType", "default": "All" }
    ],
    "runtimeOnlySetters": [
      { "name": "useReverseProxy", "setter": "settings.setUseReverseProxy(true)", "default": false }
    ]
  },
  "errorHandling": {
    "docPath": "docs/reference/ERROR_HANDLING.md",
    "responseFieldAccess": "public_fields",
    "responseFields": ["returnCode", "errorCode", "invalidMembers", "debugMessage", "responseData"],
    "checkOrder": [
      "if (res.returnCode !== ReturnCode.Ok) return;",
      "if (res.errorCode !== ErrorCode.Ok) return;",
      "useResult(res.responseData);"
    ],
    "okValue": 1,
    "warning": "Typed response (mọi *Async() và callback form) dùng PUBLIC FIELDS, KHÔNG phải getter. Low-level OperationResponse (raw transport) mới dùng getReturnCode() etc."
  },
  "scenarios": {
    "docPath": "docs/COOKBOOK.md",
    "list": [
      { "id": 1, "title": "Init SDK + bootstrap tối thiểu", "anchor": "scenario-1-init-sdk--bootstrap-tối-thiểu", "apis": ["GNNetwork.init"] },
      { "id": 2, "title": "Login by account + retrieve profile", "anchor": "scenario-2-login-by-account--retrieve-profile", "apis": ["GNNetwork.authenticate.loginByAccountAsync"] },
      { "id": 3, "title": "Refresh token và persist session", "anchor": "scenario-3-refresh-token-và-persist-session", "apis": ["GNNetwork.authenticate.refreshAuthTokenAsync"] },
      { "id": 4, "title": "Login by social (Google/Apple/Facebook)", "anchor": "scenario-4-login-by-social-googleapplefacebook", "apis": ["GNNetwork.authenticate.loginByGoogleAsync", "GNNetwork.authenticate.loginByAppleAsync", "GNNetwork.authenticate.loginByFacebookAsync"] },
      { "id": 5, "title": "Connect socket + handle reconnect", "anchor": "scenario-5-connect-socket--handle-reconnect", "apis": ["GNNetwork.connectSocket", "GNNetwork.subscriberOnConnectHandler"] },
      { "id": 6, "title": "Subscribe friend updates", "anchor": "scenario-6-subscribe-friend-updates", "events": ["OnGamePlayerFriendUpdateEventHandler"] },
      { "id": 7, "title": "Subscribe + send group message", "anchor": "scenario-7-subscribe--send-group-message", "events": ["OnGroupMessageUpdateEventHandler"], "apis": ["GNNetwork.group.sendGroupMessageAsync"] },
      { "id": 8, "title": "Group member lifecycle + realtime update", "anchor": "scenario-8-group-member-lifecycle-join--leave--kick--realtime-update", "events": ["OnGroupMemberUpdateEventHandler"], "apis": ["GNNetwork.gamePlayer.joinGroupAsync", "GNNetwork.gamePlayer.leaveGroupAsync", "GNNetwork.group.server.removeMemberAsync"] },
      { "id": 9, "title": "Matchmaking ticket flow", "anchor": "scenario-9-matchmaking-ticket-flow", "apis": ["GNNetwork.multiplayer.createMatchmakingTicketAsync", "GNNetwork.multiplayer.getMatchmakingTicketAsync", "GNNetwork.multiplayer.cancelMatchmakingTicketAsync"] },
      { "id": 10, "title": "Inventory query + grant item (server role)", "anchor": "scenario-10-inventory-query--grant-item-server-role", "apis": ["GNNetwork.gamePlayer.getPlayerInventoryAsync", "GNNetwork.gamePlayer.server.createPlayerItemAsync"] },
      { "id": 11, "title": "Store list → purchase → validate receipt", "anchor": "scenario-11-store-list-catalog--purchase--validate-receipt", "apis": ["GNNetwork.storeInventory.getStoreItemsWithTagAsync", "GNNetwork.storeInventory.buyStoreItemAsync", "GNNetwork.storeInventory.server.validateGooglePlayStoreReceiptAsync"] },
      { "id": 12, "title": "CloudScript execute + customTags", "anchor": "scenario-12-cloudscript-execute-function--customtags", "apis": ["GNNetwork.cloudScript.executeFunctionAsync"] },
      { "id": 13, "title": "Override authToken / secret", "anchor": "scenario-13-override-authtoken--secret-impersonate-cross-role" },
      { "id": 14, "title": "Admin login qua DashboardApi", "anchor": "scenario-14-admin-login-qua-dashboardapi", "apis": ["GNNetwork.dashboard.loginByAdminAccountAsync"] },
      { "id": 15, "title": "Cleanup & shutdown flow", "anchor": "scenario-15-cleanup--shutdown-flow", "apis": ["GNNetwork.disconnectSocket"] },
      { "id": 16, "title": "Diagnose OperationNotAllow", "anchor": "scenario-16-diagnose-operationnotallow", "apis": ["GNNetwork.inventory.admin.setAmountAsync"] }
    ]
  },
  "apiGroups": [
    {
      "name": "AuthenticateApi",
      "guideDoc": "docs/guides/AUTHENTICATE.md",
      "referenceDoc": "docs/reference/API_AUTHENTICATE.md",
      "dtoDoc": "docs/reference/dto/AUTHENTICATE.md",
      "apiDts": "dist/runtime/GNNetworkAuthenticateApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/AuthenticateModels.d.ts",
        "dist/runtime/entity/models/AuthenticateRequestModels.d.ts",
        "dist/runtime/entity/models/AuthenticateResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 18,
      "routes": [
        {
          "namespace": "GNNetwork.authenticate",
          "requestRole": "Client",
          "useWhen": "login player, register account, refresh auth token"
        }
      ],
      "emptyNamespaces": [
        "GNNetwork.authenticate.server",
        "GNNetwork.authenticate.admin"
      ],
      "permissionRuleDoc": "docs/reference/API_AUTHENTICATE.md",
      "recommendedSecretPermissions": {
        "client": "otherSelfEnable cho các method login/register (login luôn là acting-on-unauth-user)",
        "server": "serverSelfEnable nếu backend cần issue token cho user cụ thể",
        "admin": "adminSelfEnable nếu dashboard cần impersonate/provision tài khoản"
      }
    },
    {
      "name": "DashboardApi",
      "guideDoc": "docs/guides/DASHBOARD.md",
      "referenceDoc": "docs/reference/API_DASHBOARD.md",
      "dtoDoc": "docs/reference/dto/DASHBOARD.md",
      "apiDts": "dist/runtime/GNNetworkDashboardApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/DashboardModels.d.ts",
        "dist/runtime/entity/models/DashboardRequestModels.d.ts",
        "dist/runtime/entity/models/DashboardResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 26,
      "routes": [
        {
          "namespace": "GNNetwork.dashboard",
          "requestRole": "Client",
          "useWhen": "dashboard, analytics, secret, maintenance, admin login",
          "specialCase": "backend resolve admin context từ authToken sau login admin"
        }
      ],
      "emptyNamespaces": [
        "GNNetwork.dashboard.server",
        "GNNetwork.dashboard.admin"
      ],
      "permissionRuleDoc": "docs/reference/API_DASHBOARD.md",
      "recommendedSecretPermissions": {
        "client": "secretKey bootstrap chỉ cần cho phép loginByAdminAccount; sau login backend tự resolve quyền admin từ authToken"
      }
    },
    {
      "name": "ContentApi",
      "guideDoc": "docs/guides/CONTENT.md",
      "referenceDoc": "docs/reference/API_CONTENT.md",
      "dtoDoc": "docs/reference/dto/CONTENT.md",
      "apiDts": "dist/runtime/GNNetworkContentApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/ContentModels.d.ts",
        "dist/runtime/entity/models/ContentRequestModels.d.ts",
        "dist/runtime/entity/models/ContentResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 21,
      "routes": [
        {
          "namespace": "GNNetwork.content",
          "requestRole": "Client",
          "useWhen": "content config hoặc file metadata từ app hoặc player side"
        },
        {
          "namespace": "GNNetwork.content.server",
          "requestRole": "Server",
          "useWhen": "trusted backend hoặc worker xử lý content hoặc file metadata"
        },
        {
          "namespace": "GNNetwork.content.admin",
          "requestRole": "Admin",
          "useWhen": "dashboard hoặc backoffice quản trị content hoặc file metadata"
        }
      ],
      "permissionRuleDoc": "docs/reference/API_CONTENT.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho các method app-level query; otherSelfEnable nếu cần đọc content của user khác",
        "server": "serverSelfEnable cho trusted backend upload/download metadata",
        "admin": "adminSelfEnable cho dashboard quản trị content"
      }
    },
    {
      "name": "MultiplayerApi",
      "guideDoc": "docs/guides/MULTIPLAYER.md",
      "referenceDoc": "docs/reference/API_MULTIPLAYER.md",
      "dtoDoc": "docs/reference/dto/MULTIPLAYER.md",
      "apiDts": "dist/runtime/GNNetworkMultiplayerApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/MultiplayerModels.d.ts",
        "dist/runtime/entity/models/MultiplayerRequestModels.d.ts",
        "dist/runtime/entity/models/MultiplayerResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 30,
      "routes": [
        {
          "namespace": "GNNetwork.multiplayer",
          "requestRole": "Client",
          "useWhen": "matchmaking ticket hoặc match query gắn với auth token hiện tại"
        },
        {
          "namespace": "GNNetwork.multiplayer.server",
          "requestRole": "Server",
          "useWhen": "trusted backend thao tác ticket hoặc match của user cụ thể"
        },
        {
          "namespace": "GNNetwork.multiplayer.admin",
          "requestRole": "Admin",
          "useWhen": "ops hoặc dashboard liệt kê và quản lý ticket hoặc match"
        }
      ],
      "hardRules": [
        "không dùng socket để tạo hoặc join hoặc cancel hoặc query matchmaking ticket",
        "flow chuẩn là create hoặc join ticket rồi poll getMatchmakingTicket rồi mới getMatch"
      ],
      "permissionRuleDoc": "docs/reference/API_MULTIPLAYER.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho create/cancel ticket của chính user; otherSelfEnable nếu cần query ticket user khác",
        "server": "serverSelfEnable cho trusted backend điều phối match",
        "admin": "adminSelfEnable cho dashboard liệt kê/quản lý ticket"
      }
    },
    {
      "name": "StoreInventoryApi",
      "guideDoc": "docs/guides/STORE_INVENTORY.md",
      "referenceDoc": "docs/reference/API_STORE_INVENTORY.md",
      "dtoDoc": "docs/reference/dto/STORE_INVENTORY.md",
      "apiDts": "dist/runtime/GNNetworkStoreInventoryApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/StoreInventoryModels.d.ts",
        "dist/runtime/entity/models/StoreInventoryRequestModels.d.ts",
        "dist/runtime/entity/models/StoreInventoryResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 42,
      "routes": [
        {
          "namespace": "GNNetwork.storeInventory",
          "requestRole": "Client",
          "useWhen": "store catalog, buy, present, receipt validation cho flow app hoặc player"
        },
        {
          "namespace": "GNNetwork.storeInventory.server",
          "requestRole": "Server",
          "useWhen": "trusted backend purchase fulfillment hoặc store workflow"
        },
        {
          "namespace": "GNNetwork.storeInventory.admin",
          "requestRole": "Admin",
          "useWhen": "dashboard hoặc ops quản trị catalog hoặc log"
        }
      ],
      "permissionRuleDoc": "docs/reference/API_STORE_INVENTORY.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho buy/present/validate receipt của chính user",
        "server": "serverSelfEnable cho backend fulfillment, webhook validate receipt",
        "admin": "adminSelfEnable cho dashboard CRUD catalog, log, remove status"
      }
    },
    {
      "name": "InventoryApi",
      "guideDoc": "docs/guides/INVENTORY.md",
      "referenceDoc": "docs/reference/API_INVENTORY.md",
      "dtoDoc": "docs/reference/dto/INVENTORY.md",
      "apiDts": "dist/runtime/GNNetworkInventoryApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/InventoryModels.d.ts",
        "dist/runtime/entity/models/InventoryRequestModels.d.ts",
        "dist/runtime/entity/models/InventoryResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 102,
      "routes": [
        {
          "namespace": "GNNetwork.inventory",
          "requestRole": "Client",
          "useWhen": "player app thao tác trên item thuộc session hoặc ownership hiện tại"
        },
        {
          "namespace": "GNNetwork.inventory.server",
          "requestRole": "Server",
          "useWhen": "trusted backend xử lý item hoặc ownership hoặc statistics"
        },
        {
          "namespace": "GNNetwork.inventory.admin",
          "requestRole": "Admin",
          "useWhen": "GM tool hoặc dashboard vận hành dữ liệu inventory"
        }
      ],
      "permissionRuleDoc": "docs/reference/API_INVENTORY.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho query/statistics item của chính user; otherSelfEnable nếu xem item user khác",
        "server": "serverSelfEnable cho grant/transfer/remove item từ trusted backend",
        "admin": "adminSelfEnable cho GM tool setAmount, setOwner, setRemoveStatus"
      }
    },
    {
      "name": "GroupApi",
      "guideDoc": "docs/guides/GROUP.md",
      "referenceDoc": "docs/reference/API_GROUP.md",
      "dtoDoc": "docs/reference/dto/GROUP.md",
      "apiDts": "dist/runtime/GNNetworkGroupApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/GroupModels.d.ts",
        "dist/runtime/entity/models/GroupRequestModels.d.ts",
        "dist/runtime/entity/models/GroupResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 120,
      "routes": [
        {
          "namespace": "GNNetwork.group",
          "requestRole": "Client",
          "useWhen": "player app thao tác trên group đã tồn tại"
        },
        {
          "namespace": "GNNetwork.group.server",
          "requestRole": "Server",
          "useWhen": "trusted backend xử lý group lifecycle hoặc member hoặc message"
        },
        {
          "namespace": "GNNetwork.group.admin",
          "requestRole": "Admin",
          "useWhen": "dashboard hoặc GM tool vận hành dữ liệu group"
        }
      ],
      "realtimeHandlers": [
        "dist/runtime/networking/handler/OnGroupMessageUpdateEventHandler.d.ts",
        "dist/runtime/networking/handler/OnGroupMemberUpdateEventHandler.d.ts"
      ],
      "permissionRuleDoc": "docs/reference/API_GROUP.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho member của group đã join; otherSelfEnable cho query group khác",
        "server": "serverSelfEnable cho backend manage lifecycle, currency, message",
        "admin": "adminSelfEnable cho GM tool kick member, reset statistics, setRemoveStatus"
      }
    },
    {
      "name": "MasterPlayerApi",
      "guideDoc": "docs/guides/MASTER_PLAYER.md",
      "referenceDoc": "docs/reference/API_MASTER_PLAYER.md",
      "dtoDoc": "docs/reference/dto/MASTER_PLAYER.md",
      "apiDts": "dist/runtime/GNNetworkMasterPlayerApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/MasterPlayerModels.d.ts",
        "dist/runtime/entity/models/MasterPlayerRequestModels.d.ts",
        "dist/runtime/entity/models/MasterPlayerResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 256,
      "routes": [
        {
          "namespace": "GNNetwork.masterPlayer",
          "requestRole": "Client",
          "useWhen": "player app thao tác trên account hoặc profile của chính user hiện tại",
          "userIdBehavior": "có thể bỏ userId để target user hiện tại"
        },
        {
          "namespace": "GNNetwork.masterPlayer.server",
          "requestRole": "Server",
          "useWhen": "trusted backend xử lý account hoặc profile của player cụ thể",
          "userIdBehavior": "các flow self-target phải truyền userId rõ ràng"
        },
        {
          "namespace": "GNNetwork.masterPlayer.admin",
          "requestRole": "Admin",
          "useWhen": "dashboard hoặc GM tool vận hành dữ liệu master player",
          "userIdBehavior": "các flow self-target phải truyền userId rõ ràng"
        }
      ],
      "permissionRuleDoc": "docs/reference/API_MASTER_PLAYER.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho profile/identity/currency của chính user; otherSelfEnable cho search/leaderboard/xem user khác",
        "server": "serverSelfEnable cho backend provisioning, link/unlink identity, change currency",
        "admin": "adminSelfEnable cho GM tool ban, reset password, send push notification"
      }
    },
    {
      "name": "GamePlayerApi",
      "guideDoc": "docs/guides/GAME_PLAYER.md",
      "referenceDoc": "docs/reference/API_GAME_PLAYER.md",
      "dtoDoc": "docs/reference/dto/GAME_PLAYER.md",
      "apiDts": "dist/runtime/GNNetworkGamePlayerApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/GamePlayerModels.d.ts",
        "dist/runtime/entity/models/GamePlayerRequestModels.d.ts",
        "dist/runtime/entity/models/GamePlayerResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 156,
      "routes": [
        {
          "namespace": "GNNetwork.gamePlayer",
          "requestRole": "Client",
          "useWhen": "player app thao tác trên gameplay profile của chính user hiện tại",
          "userIdBehavior": "có thể bỏ userId để target user hiện tại"
        },
        {
          "namespace": "GNNetwork.gamePlayer.server",
          "requestRole": "Server",
          "useWhen": "trusted backend xử lý lifecycle game player của user cụ thể",
          "userIdBehavior": "các flow self-target phải truyền userId rõ ràng"
        },
        {
          "namespace": "GNNetwork.gamePlayer.admin",
          "requestRole": "Admin",
          "useWhen": "dashboard hoặc GM tool vận hành dữ liệu game player",
          "userIdBehavior": "các flow self-target phải truyền userId rõ ràng"
        }
      ],
      "realtimeHandlers": [
        "dist/runtime/networking/handler/OnGamePlayerFriendUpdateEventHandler.d.ts",
        "dist/runtime/networking/handler/OnGamePlayerGroupUpdateEventHandler.d.ts"
      ],
      "permissionRuleDoc": "docs/reference/API_GAME_PLAYER.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho gameplay profile/relation của chính user; otherSelfEnable cho friend/group query sang user khác",
        "server": "serverSelfEnable cho backend create character, change currency, manage friend/group",
        "admin": "adminSelfEnable cho GM tool"
      }
    },
    {
      "name": "CharacterPlayerApi",
      "guideDoc": "docs/guides/CHARACTER_PLAYER.md",
      "referenceDoc": "docs/reference/API_CHARACTER_PLAYER.md",
      "dtoDoc": "docs/reference/dto/CHARACTER_PLAYER.md",
      "apiDts": "dist/runtime/GNNetworkCharacterPlayerApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/CharacterPlayerModels.d.ts",
        "dist/runtime/entity/models/CharacterPlayerRequestModels.d.ts",
        "dist/runtime/entity/models/CharacterPlayerResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 159,
      "routes": [
        {
          "namespace": "GNNetwork.characterPlayer",
          "requestRole": "Client",
          "useWhen": "player app thao tác trên character cụ thể đang thuộc ownership hợp lệ",
          "targetBehavior": "gần như luôn phải truyền characterId rõ ràng"
        },
        {
          "namespace": "GNNetwork.characterPlayer.server",
          "requestRole": "Server",
          "useWhen": "trusted backend xử lý lifecycle hoặc relation của character cụ thể",
          "targetBehavior": "gần như luôn phải truyền characterId rõ ràng"
        },
        {
          "namespace": "GNNetwork.characterPlayer.admin",
          "requestRole": "Admin",
          "useWhen": "dashboard hoặc GM tool vận hành dữ liệu character",
          "targetBehavior": "gần như luôn phải truyền characterId rõ ràng"
        }
      ],
      "realtimeHandlers": [
        "dist/runtime/networking/handler/OnCharacterPlayerFriendUpdateEventHandler.d.ts",
        "dist/runtime/networking/handler/OnCharacterPlayerGroupUpdateEventHandler.d.ts"
      ],
      "permissionRuleDoc": "docs/reference/API_CHARACTER_PLAYER.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho character thuộc ownership user; otherSelfEnable cho view character khác",
        "server": "serverSelfEnable cho backend create/remove character, manage friend/group ở cấp character",
        "admin": "adminSelfEnable cho GM tool"
      }
    },
    {
      "name": "CloudScriptApi",
      "guideDoc": "docs/guides/CLOUDSCRIPT.md",
      "referenceDoc": "docs/reference/API_CLOUDSCRIPT.md",
      "dtoDoc": "docs/reference/dto/CLOUDSCRIPT.md",
      "apiDts": "dist/runtime/GNNetworkCloudScriptApi.d.ts",
      "modelDts": [
        "dist/runtime/entity/models/CloudScriptModels.d.ts",
        "dist/runtime/entity/models/CloudScriptRequestModels.d.ts",
        "dist/runtime/entity/models/CloudScriptResponseModels.d.ts"
      ],
      "transport": "http",
      "methodCount": 15,
      "routes": [
        {
          "namespace": "GNNetwork.cloudScript",
          "requestRole": "Client",
          "useWhen": "app public chỉ execute function nếu backend cho phép"
        },
        {
          "namespace": "GNNetwork.cloudScript.server",
          "requestRole": "Server",
          "useWhen": "trusted backend execute hoặc publish theo workflow backend"
        },
        {
          "namespace": "GNNetwork.cloudScript.admin",
          "requestRole": "Admin",
          "useWhen": "dashboard hoặc backoffice quản trị version và live status"
        }
      ],
      "hardRules": [
        "editFunctionAsync không sửa source code, chỉ flag enabled hoặc live của version",
        "muốn đổi source code phải addFunctionAsync để tạo version mới",
        "không có public delete function hoặc hard delete version"
      ],
      "permissionRuleDoc": "docs/reference/API_CLOUDSCRIPT.md",
      "recommendedSecretPermissions": {
        "client": "selfEnable cho executeFunction nếu backend cho phép app public execute",
        "server": "serverSelfEnable cho backend execute/publish theo workflow trusted",
        "admin": "adminSelfEnable cho dashboard addFunction/editFunction/publish version"
      }
    }
  ]
}