@hasagi/schema 0.7.0 → 0.7.1

package/README.md

@@ -0,0 +1,46 @@
+# @hasagi/schema
+
+The schema / type-generation toolkit behind Hasagi. It reads the League of Legends client's own API
+description (the LCU "help" schema, exposed by a running client), builds an OpenAPI v3 (swagger)
+document from it, and generates the TypeScript definitions that power typed LCU requests and events.
+
+This is the engine used by the [`@hasagi/cli`](https://www.npmjs.com/package/@hasagi/cli) `schema`
+command and the generated types shipped in
+[`@hasagi/core/types`](https://www.npmjs.com/package/@hasagi/core) and
+[`@hasagi/types`](https://www.npmjs.com/package/@hasagi/types).
+
+> Most users don't need this package directly — use `hasagi schema` (from `@hasagi/cli`) to generate
+> types, or just consume the pre-generated types. Use `@hasagi/schema` only if you're building your
+> own generation pipeline.
+
+## Installation
+
+```bash
+npm install @hasagi/schema
+```
+
+## API
+
+```ts
+import { getExtendedHelp, getSwagger, getTypeScript } from "@hasagi/schema";
+
+// 1. Fetch and normalize the LCU help schema (requires a running League client).
+const xhelp = await getExtendedHelp();
+
+// 2. Build an OpenAPI v3 (swagger) document.
+const swagger = await getSwagger(xhelp);
+
+// 3. Generate the TypeScript definitions.
+const { lcuTypes, lcuEndpoints, lcuEvents } = await getTypeScript(swagger, xhelp /*, namespace? */);
+```
+
+- **`getExtendedHelp()`** — retrieves and normalizes the LCU's API description from a running client.
+- **`getSwagger(xhelp)`** — produces an OpenAPI v3 schema object (with helpers for generating types).
+- **`getTypeScript(swagger, xhelp, namespace?)`** — returns the generated `lcuTypes`, `lcuEndpoints`
+  and `lcuEvents` source strings. Pass a `namespace` to wrap the generated types.
+
+## Disclaimer
+
+Hasagi is not endorsed by Riot Games and does not reflect the views or opinions of Riot Games or
+anyone officially involved in producing or managing Riot Games properties. Riot Games and all
+associated properties are trademarks or registered trademarks of Riot Games, Inc.

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@hasagi/schema",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "keywords": [
     "hasagi"
   ],
   "author": "dysolix",
   "license": "MIT",
   "dependencies": {
-    "@hasagi/core": "^0.6.3",
-    "axios": "^1.7.9"
+    "@hasagi/core": "^0.7.0",
+    "axios": "^1.17.0"
   },
   "exports": {
     ".": "./index.js"
@@ -17,6 +17,6 @@
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dysolix/hasagi-schema.git"
+    "url": "git+https://github.com/dysolix/hasagi-schema.git"
   }
 }

package/generate-openapi-v3.d.ts

@@ -1,3 +0,0 @@
-import { ExtendedHelp } from "./types.js";
-import { OpenAPIObject } from "./open-api-types.js";
-export declare function generateOpenAPIv3(schema: ExtendedHelp): Promise<OpenAPIObject>;

package/generate-openapi-v3.js

@@ -1,243 +0,0 @@
-import HasagiLiteClient from "@hasagi/core";
-function getRootType(input) {
-    const isObject = input.fields.length > 0;
-    const isEnum = input.values.length > 0;
-    const required = [];
-    const properties = {};
-    input.fields.forEach(f => {
-        if (properties[f.name] !== undefined) {
-            console.log(`Duplicate field '${f.name}' in type '${input.name}'`);
-            return;
-        }
-        properties[f.name] = getType(f);
-        if (!f.optional)
-            required.push(f.name);
-    });
-    return {
-        type: isEnum ? "string" : "object",
-        description: input.description,
-        properties: isObject ? properties : undefined,
-        enum: isEnum ? input.values.sort((v1, v2) => v2.value - v1.value).map(v => v.name) : undefined,
-        additionalProperties: !isObject && !isEnum,
-        required: required.length > 0 ? required : undefined
-    };
-}
-function getType(input) {
-    const type = typeof input === "string" ? input : input.type.type;
-    switch (type) {
-        case "string":
-            return { type: "string" };
-        case "uint8":
-        case "uint16":
-        case "uint32":
-        case "uint64":
-            return { type: "integer", format: type, minimum: 0 };
-        case "int8":
-        case "int16":
-        case "int32":
-        case "int64":
-            return { type: "integer", format: type };
-        case "bool":
-            return { type: "boolean" };
-        case "double":
-        case "float":
-            return { type: "number", format: type };
-        case "vector":
-            return { type: "array", items: getType(input.type.elementType) };
-        case "map": {
-            return { type: "object", additionalProperties: getType(input.type.elementType) };
-        }
-        case "object":
-            return { type: "object", additionalProperties: true };
-        case "":
-            return undefined;
-        default:
-            return { $ref: `#/components/schemas/${type}` };
-    }
-}
-export async function generateOpenAPIv3(schema) {
-    const client = new HasagiLiteClient();
-    await client.connect();
-    const region = await client.request({ method: "get", url: "/riotclient/region-locale" });
-    const { version } = await client.request({ method: "get", url: "/system/v1/builds" });
-    const functionsWithMissingData = [];
-    const openAPISchema = {
-        openapi: "3.0.0",
-        info: {
-            title: "LCU SCHEMA",
-            description: "",
-            version
-        },
-        components: { schemas: {} },
-        paths: {}
-    };
-    let tags = [];
-    schema.types.forEach(type => openAPISchema.components.schemas[type.name] = getRootType(type));
-    schema.functions.forEach(func => {
-        if (func.overridden) {
-            functionsWithMissingData.push(func.name);
-        }
-        if (func.method === null || func.path === null) {
-            console.log(`Function '${func.name}' does not have a http method or path.`);
-            return;
-        }
-        openAPISchema.paths[func.path] = openAPISchema.paths[func.path] ?? {};
-        const operation = endpointToOperation(func, openAPISchema);
-        // @ts-expect-error
-        openAPISchema.paths[func.path][func.method.toLowerCase()] = operation;
-    });
-    let tagCount = {};
-    Object.entries(openAPISchema.paths).forEach(([path, methods]) => {
-        Object.values(methods).forEach((operation) => {
-            operation.tags?.forEach(tag => tagCount[tag] = (tagCount[tag] ?? 0) + 1);
-        });
-    });
-    Object.entries(openAPISchema.paths).forEach(([path, methods]) => {
-        Object.values(methods).forEach((operation) => {
-            operation.tags = operation.tags?.filter(tag => tagCount[tag] > 1 || tag.startsWith("Plugin")) ?? [];
-            if ((operation.tags?.length ?? 0) < 1) {
-                operation.tags = [path.split("/")[1]];
-            }
-            if (operation.tags.length === 0)
-                operation.tags.push("other");
-            operation.tags = operation.tags.map(tag => tag.startsWith("Plugin") ? tag : tag.toLowerCase());
-        });
-    });
-    tagCount = {};
-    Object.entries(openAPISchema.paths).forEach(([path, methods]) => {
-        Object.values(methods).forEach((operation) => {
-            operation.tags?.forEach(tag => tagCount[tag] = (tagCount[tag] ?? 0) + 1);
-        });
-    });
-    Object.entries(openAPISchema.paths).forEach(([path, methods]) => {
-        Object.values(methods).forEach((operation) => {
-            operation.tags = operation.tags?.filter(tag => tagCount[tag] > 1 || tag.startsWith("Plugin")) ?? [];
-            if (operation.tags.length === 0)
-                operation.tags.push("other");
-            operation.tags = operation.tags
-                .map(tag => tag.startsWith("Plugin") ? tag : tag.toLowerCase())
-                .map(tag => tag.replace("$", ""));
-            tags.push(...operation.tags.filter(tag => !tags.includes(tag)));
-        });
-    });
-    openAPISchema.tags = tags.map(tag => {
-        return {
-            name: tag
-        };
-    }).sort((t1, t2) => {
-        if (t1.name.includes("Plugin") && !t2.name.includes("Plugin"))
-            return 1;
-        if (!t1.name.includes("Plugin") && t2.name.includes("Plugin"))
-            return -1;
-        if (t1.name.includes("Plugin") && t2.name.includes("Plugin")) {
-            if (t1.name.includes("Plugin lol") && !t2.name.includes("Plugin lol"))
-                return 1;
-            if (!t1.name.includes("Plugin lol") && t2.name.includes("Plugin lol"))
-                return -1;
-        }
-        if (t1.name == "other" && t2.name != "other")
-            return 1;
-        if (t1.name != "other" && t2.name == "other")
-            return -1;
-        return t1.name.localeCompare(t2.name);
-    });
-    let i = 1;
-    openAPISchema.info.description =
-        `
-Auto-generated using LCU's /help endpoint.
-The following endpoints are not entirely auto-generated because their /help response is missing necessary fields:
-
-${functionsWithMissingData.map(func => `${i++}.\t${func}`).join("\n")}
-
-### Disclaimer
-
-dysolix.dev is not endorsed by Riot Games and does not reflect the views or opinions of Riot Games or anyone officially involved in producing or managing Riot Games properties. 
-Riot Games and all associated properties are trademarks or registered trademarks of Riot Games, Inc`;
-    return openAPISchema;
-}
-function endpointToOperation(endpoint, schema) {
-    let parameters = undefined;
-    let response = { description: "Success response" };
-    let requestBody = undefined;
-    parameters = endpoint.pathParams?.map(param => {
-        const p = endpoint.arguments.find(arg => arg.name.replace("+", "") === param.replace("+", ""));
-        return {
-            in: "path",
-            name: param,
-            required: true,
-            schema: p === undefined ? { type: "string" } : getType(p)
-        };
-    }) ?? [];
-    const nonPathParam = endpoint.arguments.slice(endpoint.pathParams?.length ?? 0);
-    if (nonPathParam.length > 1) {
-        //console.log(`Endpoint '${endpoint.name}' has more than one non-path parameter.`)
-        nonPathParam.forEach(arg => {
-            parameters.push({
-                in: "query",
-                name: arg.name,
-                schema: getType(arg),
-                required: !arg.optional
-            });
-        });
-    }
-    else if (endpoint.method === "GET" || endpoint.method === "DELETE" || endpoint.method === "HEAD" || endpoint.method === "OPTIONS" || endpoint.method === "TRACE") {
-        const params = endpoint.arguments.slice(parameters.length).flatMap(arg => {
-            const type = getType(arg);
-            if ("$ref" in type) {
-                const schemaObject = schema.components.schemas[type.$ref.split("/").at(-1)];
-                if (schemaObject.properties)
-                    return Object.entries(schemaObject.properties).map(entry => {
-                        return {
-                            in: "query",
-                            name: entry[0],
-                            type: entry[1],
-                        };
-                    });
-                return {
-                    in: "query",
-                    schema: type,
-                    name: arg.name
-                };
-            }
-            else {
-                return {
-                    in: "query",
-                    required: !arg.optional,
-                    name: arg.name,
-                    schema: getType(arg)
-                };
-            }
-        });
-        parameters.push(...params);
-    }
-    else {
-        const bodyType = endpoint.arguments.slice(parameters.length).at(0);
-        if (bodyType)
-            requestBody = {
-                content: {
-                    "application/json": {
-                        schema: getType(bodyType)
-                    }
-                }
-            };
-    }
-    const returnType = getType({ type: endpoint.returns });
-    response = returnType !== undefined ? { content: { "application/json": { schema: returnType } }, description: "Success response" } : { description: "Success response" };
-    const tags = [];
-    if (endpoint.path?.startsWith("/lol-"))
-        tags.push("Plugin " + endpoint.path.split("/")[1]);
-    else if (endpoint.path?.startsWith("/{plugin}"))
-        tags.push("Plugin Asset Serving");
-    else
-        tags.push(endpoint.path.split("/")[1]);
-    return {
-        operationId: endpoint.name,
-        description: endpoint.description,
-        tags: endpoint.tags.filter(tag => !["Plugins", "$remoting-binding-module"].includes(tag)),
-        parameters,
-        requestBody,
-        responses: {
-            "2XX": response
-        },
-    };
-}