@ir-kit/openapi-typescript 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ahmed Rowaihi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @ir-kit/openapi-typescript
+
+Thin programmatic wrapper around [`@hey-api/openapi-ts`](https://www.npmjs.com/package/@hey-api/openapi-ts) that exposes the same `generate()` shape as [`@ir-kit/openapi-{go,kotlin,swift}`](https://github.com/ir-kit/ir-kit). Lets the [`sdk-regen`](https://github.com/ir-kit/ir-kit/tree/main/actions/sdk-regen) GitHub Action drive a TypeScript SDK alongside the native ones — same workflow, same inputs, four targets.
+
+Part of [ir-kit](https://github.com/ir-kit/ir-kit). **No new codegen** — the entire TypeScript pipeline (types, sdk, schemas, transformers, validators, query hooks, ...) is hey-api's; this package only normalises the calling convention and the result shape.
+
+## Install
+
+```bash
+pnpm add -D @ir-kit/openapi-typescript @hey-api/openapi-ts
+```
+
+`@hey-api/openapi-ts` is a peer dep so you can pin its version (and the plugins it ships) without depending on what we happen to bundle.
+
+## Usage
+
+```ts
+import { generate } from "@ir-kit/openapi-typescript";
+
+await generate({
+  input: "openapi.yaml",
+  output: "src/client",
+});
+```
+
+The default plugin set is `["@hey-api/client-fetch", "@hey-api/typescript", "@hey-api/sdk"]` — types + SDK functions + a `fetch`-based runtime adapter. Override `plugins` for any other shape:
+
+```ts
+// types-only
+await generate({ input, output, plugins: ["@hey-api/typescript"] });
+
+// SDK + zod validators + tanstack-query hooks
+await generate({
+  input,
+  output,
+  plugins: [
+    "@hey-api/client-fetch",
+    "@hey-api/typescript",
+    "@hey-api/sdk",
+    "@hey-api/schemas",
+    "zod",
+    "@tanstack/react-query",
+  ],
+});
+```
+
+Anything else hey-api's `UserConfig` accepts (custom client config, parser transforms, dryRun, etc.) goes into `heyApi:`:
+
+```ts
+await generate({
+  input,
+  output,
+  heyApi: { dryRun: true, parser: { transforms: { enums: "javascript" } } },
+});
+```
+
+## Result shape
+
+```ts
+interface GenerateResult {
+  output: string;                  // absolute path
+  files: { path: string }[];       // relative paths under output
+}
+```
+
+Matches the result shape of `@ir-kit/openapi-go` / `-kotlin` / `-swift`, so downstream tooling (the [`sdk-regen`](https://github.com/ir-kit/ir-kit/tree/main/actions/sdk-regen) action, your own CI scripts) can iterate the four packages uniformly.
+
+## Why a wrapper
+
+We don't ship our own TypeScript codegen — hey-api already does it well, and a competing TS gen would mean rebuilding their `ts-dsl` from scratch. But the `sdk-regen` action assumes a `generate({ input, output })` shape across all targets, and hey-api's `createClient(userConfig)` is shaped slightly differently and returns `Context[]` rather than `{ files, output }`. The wrapper closes that gap in ~30 lines of code.
+
+## Limitations
+
+- **Result `files`** is collected by walking the output dir post-run. So if hey-api writes outside `output` (e.g. via custom plugin paths), those files won't be reported. The default plugins all write under `output`, so this is only a concern for advanced setups.

package/dist/generate.d.ts

@@ -0,0 +1,50 @@
+import { type UserConfig } from "@hey-api/openapi-ts";
+import type { NormalizeOptions } from "@ir-kit/openapi-core";
+export interface GenerateOptions {
+    /**
+     * Path or URL to the OpenAPI 3.x spec. Forwarded to hey-api which
+     * delegates to `@hey-api/json-schema-ref-parser` and accepts both
+     * shapes.
+     */
+    input: string;
+    /** Directory the SDK is written to (created if missing). */
+    output: string;
+    /**
+     * Override hey-api's plugin list. When omitted, defaults to
+     * `@hey-api/client-fetch` + `@hey-api/typescript` + `@hey-api/sdk`.
+     * Pass any combination of hey-api's first-party plugins (validators,
+     * Faker, TanStack Query, oRPC, etc.) or third-party plugin packages.
+     */
+    plugins?: UserConfig["plugins"];
+    /**
+     * Pass-through for any other hey-api `UserConfig` field —
+     * `parser.transforms`, `experimentalParser`, `dryRun`, custom client
+     * options, etc. Merged on top of the resolved config last, so it
+     * wins over the defaults set here.
+     */
+    heyApi?: Partial<UserConfig>;
+    /**
+     * Pre-codegen spec normalization. When enabled, the spec is bundled
+     * + normalized before being handed to hey-api as a parsed object,
+     * so all four targets share the same normalization logic.
+     */
+    normalize?: boolean | NormalizeOptions;
+}
+export interface BuiltFile {
+    /** Path relative to `output`. */
+    path: string;
+}
+export interface GenerateResult {
+    /** Absolute output directory. */
+    output: string;
+    /** Files written under `output`, relative paths. */
+    files: BuiltFile[];
+}
+/**
+ * Run hey-api's TypeScript codegen against `input`, writing the result
+ * to `output`. Thin wrapper around `createClient` that matches the
+ * `generate()` shape of `@ir-kit/openapi-{go,kotlin,swift}` so
+ * the same `sdk-regen` workflow drives all four targets uniformly.
+ */
+export declare function generate(opts: GenerateOptions): Promise<GenerateResult>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAiB7D,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAChC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;CACxC;AAED,MAAM,WAAW,SAAS;IACxB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAc7E"}

package/dist/generate.js

@@ -0,0 +1,68 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { createClient } from "@hey-api/openapi-ts";
+import { loadSpec } from "@ir-kit/openapi-tools";
+/**
+ * Default plugin set — emits a runnable client SDK ready to drop into a
+ * TypeScript project: types from schemas, the SDK functions, and the
+ * `fetch`-based runtime adapter. Consumers wanting alternative shapes
+ * (axios / ofetch / TanStack Query / zod / faker / etc.) override
+ * `plugins` with the hey-api plugin name they want; the rest of
+ * hey-api's plugin ecosystem all plugs in here unchanged.
+ */
+const DEFAULT_PLUGINS = [
+    "@hey-api/client-fetch",
+    "@hey-api/typescript",
+    "@hey-api/sdk",
+];
+/**
+ * Run hey-api's TypeScript codegen against `input`, writing the result
+ * to `output`. Thin wrapper around `createClient` that matches the
+ * `generate()` shape of `@ir-kit/openapi-{go,kotlin,swift}` so
+ * the same `sdk-regen` workflow drives all four targets uniformly.
+ */
+export async function generate(opts) {
+    const out = resolve(process.cwd(), opts.output);
+    const input = opts.normalize
+        ? await loadSpec({ input: opts.input, normalize: opts.normalize })
+        : opts.input;
+    const config = {
+        input,
+        output: out,
+        plugins: (opts.plugins ?? DEFAULT_PLUGINS),
+        ...opts.heyApi,
+    };
+    await createClient(config);
+    const files = await collectFiles(out);
+    return { output: out, files };
+}
+/**
+ * Walk `dir` recursively and return every regular file under it as a
+ * relative path. Used to surface a `GenerateResult.files` array
+ * matching what our other generators return — hey-api's
+ * `createClient` resolves to `Context[]`, not a file list, so we read
+ * the result back from disk.
+ */
+async function collectFiles(dir) {
+    const out = [];
+    await walk(dir, dir, out);
+    return out;
+}
+async function walk(base, current, out) {
+    let entries;
+    try {
+        entries = await readdir(current);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = join(current, entry);
+        const s = await stat(full);
+        if (s.isDirectory())
+            await walk(base, full, out);
+        else
+            out.push({ path: relative(base, full) });
+    }
+}
+//# sourceMappingURL=generate.js.map

package/dist/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,eAAe,GAA0B;IAC7C,uBAAuB;IACvB,qBAAqB;IACrB,cAAc;CACf,CAAC;AA6CF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAqB;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS;QAC1B,CAAC,CAAC,MAAM,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;QAClE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;IACf,MAAM,MAAM,GAAe;QACzB,KAAK;QACL,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,eAAe,CAA0B;QACnE,GAAG,IAAI,CAAC,MAAM;KACf,CAAC;IACF,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,YAAY,CAAC,GAAW;IACrC,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,MAAM,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1B,OAAO,GAAG,CAAC;AACb,CAAC;AAED,KAAK,UAAU,IAAI,CACjB,IAAY,EACZ,OAAe,EACf,GAAgB;IAEhB,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,CAAC,WAAW,EAAE;YAAE,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;;YAC5C,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { BuiltFile, GenerateOptions, GenerateResult, } from "./generate.js";
+export { generate } from "./generate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,SAAS,EACT,eAAe,EACf,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { generate } from "./generate.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@ir-kit/openapi-typescript",
+  "version": "0.1.0",
+  "description": "Thin programmatic wrapper around @hey-api/openapi-ts that ships a `generate()` matching the shape of @ir-kit/openapi-{go,kotlin,swift}, so the same sdk-regen workflow can target TypeScript clients (types + sdk + schemas + transformers + validators + ...) via hey-api's plugin pipeline.",
+  "keywords": [
+    "openapi",
+    "typescript",
+    "codegen",
+    "sdk",
+    "client",
+    "hey-api"
+  ],
+  "homepage": "https://github.com/ir-kit/ir-kit/tree/main/packages/openapi/typescript",
+  "bugs": {
+    "url": "https://github.com/ir-kit/ir-kit/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Ahmed Rowaihi",
+    "email": "ahmedrowaihi@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ir-kit/ir-kit.git",
+    "directory": "packages/openapi/typescript"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@hey-api/openapi-ts": ">=0.97.0"
+  },
+  "dependencies": {
+    "@ir-kit/openapi-core": "0.1.0",
+    "@ir-kit/openapi-tools": "0.1.0"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.97.0",
+    "@types/node": "^22",
+    "vitest": "^4.0.0",
+    "@ir-kit/tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}