yandex-kit-core 0.1.0

package/dist/generated/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./errors.js";
+export * from "./registry.js";
+export * from "./client.js";
+export * from "./validate.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./errors.js";
+export * from "./registry.js";
+export * from "./client.js";
+export * from "./validate.js";

package/dist/registry.d.ts

@@ -0,0 +1,34 @@
+export interface RegistryQueryParam {
+    name: string;
+    required: boolean;
+    type: string;
+    enum?: string[] | null;
+    minimum?: number | null;
+    maximum?: number | null;
+    default?: unknown;
+    descriptionRu?: string | null;
+}
+export interface RegistryOp {
+    id: string;
+    method: string;
+    path: string;
+    tag: string;
+    summaryRu: string;
+    descriptionRu?: string | null;
+    pathParams: string[];
+    queryParams: RegistryQueryParam[];
+    requestContentType?: string | null;
+    requestSchemaRef?: string | null;
+    responseSchemaRef?: string | null;
+    paginated: boolean;
+    itemsProp?: string | null;
+}
+export interface Registry {
+    specTitle: string;
+    specVersion: string;
+    opsCount: number;
+    ops: Record<string, RegistryOp>;
+}
+export declare function getRegistry(): Registry;
+export declare function getOp(operationId: string): RegistryOp;
+export declare function loadSpec(): any;

package/dist/registry.js

@@ -0,0 +1,22 @@
+/**
+ * Access to the generated operation registry (generated/registry.json) and
+ * the bundled OpenAPI spec (generated/spec.json). Both are loaded lazily via
+ * readFileSync (no JSON import attributes — node 20 compat) and cached.
+ */
+import { readFileSync } from "node:fs";
+let cachedRegistry;
+let cachedSpec;
+export function getRegistry() {
+    cachedRegistry ??= JSON.parse(readFileSync(new URL("./generated/registry.json", import.meta.url), "utf8"));
+    return cachedRegistry;
+}
+export function getOp(operationId) {
+    const op = getRegistry().ops[operationId];
+    if (!op)
+        throw new Error(`Unknown operationId: ${operationId}`);
+    return op;
+}
+export function loadSpec() {
+    cachedSpec ??= JSON.parse(readFileSync(new URL("./generated/spec.json", import.meta.url), "utf8"));
+    return cachedSpec;
+}

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+export declare function validateRequestBody(operationId: string, body: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+export declare function resolveOperationSchema(operationId: string): {
+    request?: unknown;
+    response?: unknown;
+};

package/dist/validate.js

@@ -0,0 +1,133 @@
+/**
+ * Request-body validation (Ajv) and schema resolution helpers driven by the
+ * generated operation registry and the bundled OpenAPI spec.
+ */
+import AjvImport, { Ajv as AjvNamed } from "ajv";
+import { getOp, loadSpec } from "./registry.js";
+// ajv v8 is CJS; depending on the loader the class may sit on the named
+// export, the default export, or `.default` of the default export.
+const AjvClass = AjvNamed ??
+    AjvImport.default ??
+    AjvImport;
+const REF_DEPTH_CAP = 30;
+let ajvInstance;
+let transformedSchemas;
+const validatorCache = new Map();
+/**
+ * OpenAPI 3.0 `nullable: true` is not JSON Schema; rewrite it into a type
+ * union with "null" (and extend enums) so Ajv validates it correctly.
+ */
+function transformNullable(node) {
+    if (Array.isArray(node))
+        return node.map(transformNullable);
+    if (node === null || typeof node !== "object")
+        return node;
+    const src = node;
+    const out = {};
+    for (const [key, value] of Object.entries(src)) {
+        // Only drop the OpenAPI keyword; a property literally named "nullable"
+        // inside a `properties` map holds an object, not a boolean.
+        if (key === "nullable" && typeof value === "boolean")
+            continue;
+        out[key] = transformNullable(value);
+    }
+    if (src.nullable === true) {
+        if (typeof out.type === "string")
+            out.type = [out.type, "null"];
+        else if (Array.isArray(out.type)) {
+            if (!out.type.includes("null"))
+                out.type = [...out.type, "null"];
+        }
+        else {
+            // No sibling `type` (allOf/$ref form, e.g. {allOf:[{$ref:X}],nullable:true}):
+            // widening `type` is impossible, so wrap the whole schema instead.
+            return { anyOf: [{ type: "null" }, out] };
+        }
+        if (Array.isArray(out.enum) && !out.enum.includes(null)) {
+            out.enum = [...out.enum, null];
+        }
+    }
+    return out;
+}
+function getTransformedSchemas() {
+    transformedSchemas ??= transformNullable(loadSpec().components?.schemas ?? {});
+    return transformedSchemas;
+}
+function getAjv() {
+    ajvInstance ??= new AjvClass({
+        strict: false,
+        allErrors: true,
+        validateFormats: false,
+    });
+    return ajvInstance;
+}
+function getValidator(operationId, schemaRef) {
+    const cached = validatorCache.get(operationId);
+    if (cached)
+        return cached;
+    // Wrap the ref together with all (nullable-transformed) component schemas
+    // so internal "#/components/schemas/X" pointers resolve locally.
+    const validate = getAjv().compile({
+        $ref: schemaRef,
+        components: { schemas: getTransformedSchemas() },
+    });
+    validatorCache.set(operationId, validate);
+    return validate;
+}
+export function validateRequestBody(operationId, body) {
+    const op = getOp(operationId);
+    if (!op.requestSchemaRef)
+        return { valid: true, errors: [] };
+    const validate = getValidator(operationId, op.requestSchemaRef);
+    if (validate(body))
+        return { valid: true, errors: [] };
+    const errors = (validate.errors ?? []).map((e) => `${e.instancePath || "(root)"}: ${e.message ?? "invalid"}`);
+    return { valid: false, errors };
+}
+function resolveRefTarget(ref) {
+    if (!ref.startsWith("#/")) {
+        throw new Error(`Unsupported external $ref: ${ref}`);
+    }
+    let node = loadSpec();
+    for (const rawSegment of ref.slice(2).split("/")) {
+        const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~");
+        node = node?.[segment];
+        if (node === undefined)
+            throw new Error(`Unresolvable $ref: ${ref}`);
+    }
+    return node;
+}
+/**
+ * Inline every $ref. A ref already being expanded on the current branch (or
+ * expansion beyond the depth cap) is replaced with {"$circular": "<ref>"}.
+ */
+function deref(node, refStack) {
+    if (Array.isArray(node))
+        return node.map((item) => deref(item, refStack));
+    if (node === null || typeof node !== "object")
+        return node;
+    const src = node;
+    if (typeof src.$ref === "string") {
+        const ref = src.$ref;
+        if (refStack.includes(ref) || refStack.length >= REF_DEPTH_CAP) {
+            return { $circular: ref };
+        }
+        return deref(resolveRefTarget(ref), [...refStack, ref]);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(src)) {
+        out[key] = deref(value, refStack);
+    }
+    return out;
+}
+export function resolveOperationSchema(operationId) {
+    const op = getOp(operationId);
+    const result = {};
+    if (op.requestSchemaRef) {
+        result.request = deref({ $ref: op.requestSchemaRef }, []);
+    }
+    if (op.responseSchemaRef) {
+        result.response = deref({ $ref: op.responseSchemaRef }, []);
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "yandex-kit-core",
+  "version": "0.1.0",
+  "description": "Typed client for the Yandex KIT API, driven by the official OpenAPI spec",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && mkdir -p dist/generated && cp src/generated/*.json dist/generated/",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "test": "node --import tsx --test $(find src -name '*.test.ts')",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "yandex",
+    "kit",
+    "e-commerce",
+    "api-client",
+    "openapi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ztemerbekov/a1-yandex-kit-skills.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/ztemerbekov/a1-yandex-kit-skills#readme",
+  "bugs": {
+    "url": "https://github.com/ztemerbekov/a1-yandex-kit-skills/issues"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  }
+}