@accelbyte/codegen 0.0.0-dev-20240828032938

package/.eslintrc.json

@@ -0,0 +1,6 @@
+{
+  "plugins": ["unused-imports"],
+  "rules": {
+    "unused-imports/no-unused-imports": "error"
+  }
+}

package/LICENSE

@@ -0,0 +1,19 @@
+AccelByte Development Code License
+
+This development code license agreement (“Agreement”) is between you and AccelByte, Inc. ("AccelByte"), and governs your use of the library, sample code or other software that is accompanied by this license (the "Licensed Software"). By using the Licensed Software, you agree to be bound by the terms of this Agreement. If you do not agree to the terms of this Agreement, do not use the Licensed Software.
+
+1. License Grant. AccelByte hereby grants you a revocable, non-exclusive, non-sublicensable, non-transferrable license to use the Licensed Software, solely to develop your own games that are designed to operate on the AccelByte platform (available under a separate agreement), and solely as needed to enable that operation.
+
+2. Restrictions. Except as expressly permitted in this Agreement, you may not: (a) copy, modify, or create derivative works of the Licensed Software; (b) distribute, sublicense, lease, rent, loan, or otherwise transfer the Licensed Software or any rights granted under this Agreement; (c) reverse engineer, decompile, or disassemble the Licensed Software; or (d) make the functionality of the Licensed Software available to any third party.
+
+3. Termination. This Agreement will remain in effect until terminated by you or AccelByte. AccelByte may terminate this Agreement at any time for any reason. Upon termination of this Agreement, you must cease all use of the Licensed Software and destroy all copies of the Licensed Software in your possession or control.
+
+4. Proprietary Rights. The Licensed Software is owned and copyrighted by AccelByte. Your license to use the Licensed Software does not grant you any right, title, or interest in or to the Licensed Software, except for the limited rights expressly granted in this Agreement.
+
+5. Disclaimer of Warranties. THE LICENSED SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, ACCELBYTE DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+6. Limitation of Liability. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL ACCELBYTE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR ANY OTHER DAMAGES OF ANY KIND, ARISING FROM OR RELATED TO THIS AGREEMENT OR THE SDK, WHETHER IN CONTRACT, TORT, OR OTHERWISE, EVEN IF ACCELBYTE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. Governing Law. This Agreement will be governed by and construed in accordance with the laws of the state of Washington in the United States of America, without regard to its conflict of law provisions.
+
+8. Contact Information. If you have any questions about this Agreement, please contact AccelByte at: hello@accelbyte.io. Last updated: October 26, 2022

package/PATCHING.md

@@ -0,0 +1,137 @@
+# Code Generator Patching
+
+This document outlines the steps required when patching an Open API specs.
+
+## JSON Patch
+
+Inside the directory `packages/od-codegen/src/swaggers`, there are also JSON Patch that will patch the Swagger document. The patches will adjust the endpoints so that it will produce the proper functions to match the actual backend service. 
+We use https://github.com/Starcounter-Jack/JSON-Patch library that follow https://jsonpatch.com/ format
+
+### Operations
+
+#### Add
+```
+{ "op": "add", "path": "/biscuits/1", "value": { "name": "Ginger Nut" } }
+```
+Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array.
+
+#### Remove
+```
+{ "op": "remove", "path": "/biscuits" }
+```
+Removes a value from an object or array.
+```
+{ "op": "remove", "path": "/biscuits/0" }
+```
+Removes the first element of the array at biscuits (or just removes the “0” key if biscuits is an object)
+
+#### Replace
+```
+{ "op": "replace", "path": "/biscuits/0/name", "value": "Chocolate Digestive" }
+```
+Replaces a value. Equivalent to a “remove” followed by an “add”.
+
+#### Copy
+```
+{ "op": "copy", "from": "/biscuits/0", "path": "/best_biscuit" }
+```
+Copies a value from one location to another within the JSON document. Both from and path are JSON Pointers.
+
+#### Move
+```
+{ "op": "move", "from": "/biscuits", "path": "/cookies" }
+```
+Moves a value from one location to the other. Both from and path are JSON Pointers.
+
+#### Test
+```
+{ "op": "test", "path": "/best_biscuit/name", "value": "Choco Leibniz" }
+```
+Tests that the specified value is set in the document. If the test fails, then the patch as a whole should not apply.
+
+### Example
+For example, take a look at the this object
+```oauthmodel.TokenResponseV3": {
+   "required": [
+    "access_token",
+    "refresh_token",
+    "expires_in",
+    "token_type",
+    "roles",
+    "permissions",
+    "bans",
+    "user_id",
+    "display_name",
+    "namespace",
+    "namespace_roles",
+    "refresh_expires_in",
+    "scope",
+    "xuid"
+   ],
+   // ...
+}
+```
+
+This definition says that `TokenResponseV3` will always give out `xuid`. Yet at the moment, that property shouldn't always appear in the current IAM and the Swagger JSON is mistakenly written that way. If we kept the `xuid` property there, the response validation in the TypeScript SDK will throw error and say the response missed the `xuid` property. Therefore, the JSON Patches are created, and it looks like this
+
+```
+  {
+    "op": "remove",
+    "path": "/definitions/oauthmodel.TokenResponseV3/required/13"
+  }
+  ```
+
+#### NOTE
+Be careful if we want to use remove multiple array the results will be different from what is expected because at the first opportunity it will change the array order
+
+for example the original json:
+```
+"required": [
+  "validateOnly",
+  "code",
+  "contactType",
+  "languageTag"
+]
+```
+
+what we expect:
+```
+"required": [
+  "code",
+  "languageTag"
+]
+```
+
+patch:
+```
+{
+  "op": "remove",
+  "path": "/required/0"
+},
+{
+  "op": "remove",
+  "path": "/required/2"
+}
+```
+
+result:
+```
+"required": [
+  "code",
+  "contactType"
+]
+```
+
+So instead of doing multiple removes on array it's better to use replace operation
+
+patch: 
+```
+{
+  "op": "replace",
+  "path": "/required",
+  "value": [
+    "code",
+    "languageTag"
+  ]
+}
+```

package/README.md

@@ -0,0 +1,111 @@
+# AccelByte TypeScript SDK Code Generator
+
+AccelByte Code Generator is a CLI tool that facilitates creating an AccelByte TypeScript SDK from AccelByte OpenAPI definitions.
+
+## CLI
+This codegen build a CLI called `accelbyte-codegen` that will be used to generate code from given config.
+
+```
+Commands:  
+accelbyte-codegen download-swaggers  Download swaggers JSON files  
+accelbyte-codegen generate-code      Generate code based on downloaded swagger
+files
+
+Options:
+--version           Show version number                                         [boolean]  
+--config            Config file providing backend services URL.                 [string] [required]  
+--swaggersOutput    Output path for downloaded swaggers JSON files.             [string] [required]  
+--output            Output path for generated code. Required for generate-code  [string]  
+--admin             Only generate /admin endpoints.                             [boolean] [default: false]  
+--help              Show help                                                   [boolean]  
+```
+
+### Config file
+Provide swaggers url you wish to generate, store it in .json format file.
+
+```
+[
+  ["iam", "Iam", "iam.json", "https://example.com/iam/apidocs/api.json"]
+]
+```
+
+## How to Generate
+
+**Step 1: Set Up Your Node.js Environment** Make sure you have Node.js and npm (Node Package Manager) installed on your system. You can download and install them from the official website: https://nodejs.org/en/ 
+
+__*It is recommended__ to use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install Node.js so you can switch between Node versions more easily 
+
+**Step 2: Create a New Node.js Project (if needed)** If you are starting a new project, create a new directory and initialize it as a Node.js project. You can do this using the following commands: 
+```
+mkdir my-project
+cd my-project
+npm init
+```
+Follow the prompts to set up your project's package.json file.
+
+**Step 3: Install the Package** To use `@accelbyte/codegen`, you need to install it as a dependency for your project. Run the following command within your project directory:
+```
+npm install @accelbyte/codegen
+# Or, with yarn:
+yarn add @accelbyte/codegen
+```
+**Step 4: Configure the Package** Check the documentation or the README of the package for specific configuration instructions. 
+  1.	Prepare The `CHANGELOG.md` file, create the Changelog file in the root project with `CHANGELOG.md` file name.
+  2.	Prepare Config file, Provide the swaggers URL you wish to generate with the format of an Array of array detailed services, so we can add multiple services at the same time, by adding an Array of detailed services into `Config.json` Array like this:
+```
+[
+  [serviceName, aliasName, swaggerFileOutput, swaggerURL],
+  [serviceName2, aliasName2, swaggerFileOutput2, swaggerURL2],
+  ...
+]
+```
+and then store it in .json format file (we suggest placing the file in the root directory). example:
+```
+[
+  ["iam", "Iam", "iam.json", "https://example.com/iam/apidocs/api.json"]
+]
+```
+for the Accelbyte Demo environment, this will look like this
+```
+[
+  ["iam", "Iam", "iam.json", "https://demo.accelbyte.io/iam/apidocs/api.json"]
+]
+```
+
+**Step 5: Download Swagger Files** download the swagger file to the project by executing this command
+```
+npm exec -- accelbyte-codegen download-swaggers --config ./config.json --swaggersOutput ./swaggers
+# Or, with yarn:
+yarn accelbyte-codegen download-swaggers --config ./config.json --swaggersOutput ./swaggers
+```
+*note: please adjust the `--config` flag with the path of config.json file that was already set up before, and please specify the swagger output directory by using `--swaggersOutput` flag.
+
+**Step 6: Generate Code from Swagger Files** after the swagger file has already been downloaded we can proceed to generating TypeScript SDK code from the Swagger File using this command : 
+```
+npm exec -- accelbyte-codegen generate-code --config ./config.json --swaggersOutput ./swaggers --output ./sdk
+```
+*note: please adjust the `--config` flag with the path of config.json file that was already set up before, and please specify for the swagger output directory by using `--swaggersOutput` flag, and the directory output of generated SDK using `--output` flag.
+if it is successful the result will look like this, and the WebSDK code should be generated under the/sdk directory
+
+```
+----------
+Generating API: { title: 'justice-iam-service', version: '7.4.0' }
+!!!! Missing x-version ...
+COMPLETED
+----------
+```
+
+**Step 7: Prettify the files (Optional)** 
+
+To prettify the code file using the prettier tool, please install the plugin first by doing this:
+```
+npm install prettier 
+# Or, with yarn:
+yarn add prettier
+```
+after installing, execute prettier as below
+```
+npm exec prettier --write swaggers/*.json && prettier --write sdk/**/*
+# Or, with yarn:
+yarn prettier --write swaggers/*.json && prettier --write sdk/**/*
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@accelbyte/codegen",
+  "version": "0.0.0-dev-20240828032938",
+  "author": "AccelByte Inc",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "dist/accelbyte-codegen.js",
+  "module": "dist/accelbyte-codegen.mjs",
+  "scripts": {
+    "build": "tsup && yarn set-permissions",
+    "set-permissions": "cd dist && ls *.* && chmod 700 *.* || echo 'No matching files'",
+    "prettier": "prettier --write sdk/.",
+    "test": "vitest run --testTimeout=15000",
+    "test:watch": "vitest",
+    "clean": "npx rimraf dist && npx rimraf node_modules"
+  },
+  "bin": {
+    "accelbyte-codegen": "dist/accelbyte-codegen.js"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "10.1.0",
+    "axios": "1.3.6",
+    "eslint": "8.56.0",
+    "eslint-plugin-unused-imports": "3.0.0",
+    "fast-json-patch": "3.1.1",
+    "lodash": "4.17.21",
+    "rimraf": "4.1.2",
+    "semver": "7.5.4",
+    "swagger-parser": "10.0.3",
+    "validator": "13.7.0",
+    "yargs": "17.6.2",
+    "zod": "3.17.3"
+  },
+  "devDependencies": {
+    "@types/node": "22.3.0",
+    "@types/yargs": "17.0.14",
+    "tsup": "8.2.4",
+    "vitest": "2.0.5"
+  }
+}

package/scripts/generate-test-resources.mjs

@@ -0,0 +1,105 @@
+// @ts-check
+import fs from 'fs/promises'
+import path from 'path'
+
+// The objective of this script is so that we could trim down the IAM Swagger.
+// We want to test our Swagger parser and generator, in some ways so that we could be sure
+// that when we do something, nothing breaks.
+//
+// And having the entire IAM Swagger JSON might be overkill.
+// Hence, wh at we're doing in the `INCLUDED_ENDPOINTS` is that, we want to make sure
+// to cover the scenarios. For example, function naming, deprecated endpoints exclusion.
+const PATH_TO_IAM_SAMPLE = 'src/helpers/test-resources/swagger-iam-sample.json'
+
+const INCLUDED_ENDPOINTS = [
+  // These are deprecated endpoints, should be automatically excluded.
+  '/iam/bans',
+  '/iam/roles',
+  // These are the normal ones.
+  '/iam/v3/admin/bans',
+  '/iam/v3/admin/roles',
+  '/iam/v3/admin/users/me',
+  '/iam/v3/public/users/me',
+  '/iam/v3/admin/namespaces/{namespace}/clients/{clientId}/permissions/{resource}/{action}',
+  // For array definitions test.
+  '/iam/v3/admin/namespaces/{namespace}/users/{userId}/platforms/justice'
+]
+
+async function main() {
+  const content = await fs.readFile(path.join(process.cwd(), PATH_TO_IAM_SAMPLE), 'utf-8')
+  const json = JSON.parse(content)
+
+  const newPaths = {}
+  const modelsSet = new Set()
+  const newDefinitions = {}
+
+  for (const key in json.paths) {
+    // Only include the endpoints set above.
+    if (INCLUDED_ENDPOINTS.includes(key)) {
+      newPaths[key] = json.paths[key]
+
+      for (const methodKey in json.paths[key]) {
+        const { parameters = [], responses = {} } = json.paths[key][methodKey]
+
+        // Get the request body schema, if any.
+        for (const parameter of parameters) {
+          const { schema } = parameter
+          if (!schema) continue
+
+          const ref = getEffectiveRef(schema)
+          if (ref) modelsSet.add(ref)
+        }
+
+        // Get the resposne body schema, if any.
+        for (const responseStatus in responses) {
+          const { schema } = responses[responseStatus]
+          if (!schema) continue
+
+          const ref = getEffectiveRef(schema)
+          if (ref) modelsSet.add(ref)
+        }
+      }
+    }
+  }
+
+  for (const model of modelsSet) {
+    // Recursively add definitions (including definitions inside definitions).
+    recursivelyAddToNewDefinitions(newDefinitions, json.definitions, model)
+  }
+
+  json.paths = newPaths
+  json.definitions = newDefinitions
+
+  // Re-write the old Swagger into the new Swagger.
+  await fs.writeFile(PATH_TO_IAM_SAMPLE, JSON.stringify(json, null, 2), 'utf-8')
+}
+
+main()
+
+// Helper functions.
+function getEffectiveRef(schema) {
+  let ref = schema['$ref']
+  if (!ref) {
+    ref = schema.items?.['$ref']
+  }
+
+  return ref?.slice('#/definitions/'.length)
+}
+
+function recursivelyAddToNewDefinitions(newDefinitions, definitions, modelName) {
+  // Store the definition in the new definitions.
+  const currentDefinition = definitions[modelName]
+  newDefinitions[modelName] = currentDefinition
+
+  // From the definition, check the properties.
+  // See if they have "nested" definitions, so we can traverse them recursively.
+  for (const propertyKey in currentDefinition.properties) {
+    const propertySchema = currentDefinition.properties[propertyKey]
+    const ref = getEffectiveRef(propertySchema)
+
+    if (ref) {
+      newDefinitions[ref] = definitions[ref]
+      recursivelyAddToNewDefinitions(newDefinitions, definitions, ref)
+    }
+  }
+}

package/scripts/get-swaggers-configs.mjs

@@ -0,0 +1,54 @@
+import fs, { readFileSync, writeFileSync } from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+/* node ./packages/codegen/scripts/get-swaggers-configs.mjs */
+
+const rootDir = path.resolve(path.join(__dirname, '../../'))
+
+function findSwaggerFiles(dir) {
+  const files = fs.readdirSync(dir)
+  const swaggerFiles = []
+
+  files.forEach(file => {
+    const filePath = path.join(dir, file)
+    const stat = fs.statSync(filePath)
+
+    if (stat.isDirectory() && file.startsWith('sdk-')) {
+      const swaggerPath = path.join(filePath, 'swaggers.json')
+      if (fs.existsSync(swaggerPath)) {
+        swaggerFiles.push(swaggerPath)
+      }
+    }
+  })
+
+  return swaggerFiles
+}
+
+function parseSwaggerFiles(swaggerFiles) {
+  const result = {}
+
+  swaggerFiles.forEach(swaggerPath => {
+    const dirName = swaggerPath.match(/\/(sdk-[^\/]*)\//)?.[1]
+    const content = JSON.parse(readFileSync(swaggerPath, 'utf8'))
+
+    result[dirName] = content[0]
+  })
+
+  return result
+}
+
+function writeSwaggersConfigToFile(data) {
+  const filePath = path.resolve('./packages/codegen/src/helpers/test-resources/swaggersConfig.ts')
+  const fileContent = `const swaggersConfig = ${JSON.stringify(data, null, 2)};\n\nexport default swaggersConfig;\n`
+
+  writeFileSync(filePath, fileContent, 'utf8')
+  console.log(`swaggersConfig.js file created successfully at ${filePath}`)
+}
+
+const swaggerFiles = findSwaggerFiles(rootDir)
+const parsedData = parseSwaggerFiles(swaggerFiles)
+writeSwaggersConfigToFile(parsedData)