kayto_ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vladislav Yemelyanov
+
+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,299 @@
+# kayto_ts
+
+🚀 Build robust API integrations faster with `kayto_ts`.
+
+- 🔒 End-to-end type safety for `method + path + params + body + response`
+- ⚡ Zero-boilerplate HTTP client generation from schema
+- 🧩 Request/response hooks for auth, tracing, and custom logic
+- ⏱️ Built-in timeout and cancellation support
+- 🛡️ Predictable, unified error model for cleaner handling
+
+## Install
+
+```bash
+bun add kayto_ts
+# alternatives:
+# npm i kayto_ts
+# pnpm add kayto_ts
+# yarn add kayto_ts
+```
+
+During install, `kayto_ts` automatically downloads `kayto` binary into local package directory: `.kayto/bin`.
+No global `kayto` install is required.
+
+## Using CLI
+
+Generate TypeScript schema from OpenAPI in one command:
+
+```bash
+bunx kayto --lang ts --input "https://example.com/openapi.json" --output "generated/schema.ts"
+```
+
+Alternatives:
+
+```bash
+npx kayto --help
+pnpm exec kayto --help
+yarn kayto --help
+```
+
+## Multiple Services
+
+If you generate one schema file per microservice, keep clients centralized in one place.
+
+```ts
+import { clientApi, type EndpointsMap } from "kayto_ts";
+import type { Endpoints as AccountsEndpoints } from "./schemas/accounts";
+import type { Endpoints as BillingEndpoints } from "./schemas/billing";
+import type { Endpoints as NotificationsEndpoints } from "./schemas/notifications";
+
+const SERVICE_URLS = {
+  accounts: "https://accounts.example.com",
+  billing: "https://billing.example.com",
+  notifications: "https://notifications.example.com",
+} as const;
+
+function createServiceClient<TEndpoints extends EndpointsMap>(baseUrl: string) {
+  return clientApi<TEndpoints>({
+    baseUrl,
+    onRequest: ({ init }) => {
+      const headers = new Headers(init.headers);
+      headers.set("authorization", `Bearer ${getAccessToken()}`);
+      init.headers = headers;
+    },
+  });
+}
+
+export const clients = {
+  accounts: createServiceClient<AccountsEndpoints>(SERVICE_URLS.accounts),
+  billing: createServiceClient<BillingEndpoints>(SERVICE_URLS.billing),
+  notifications: createServiceClient<NotificationsEndpoints>(SERVICE_URLS.notifications),
+};
+
+function getAccessToken(): string {
+  return "token";
+}
+
+// usage
+const me = await clients.accounts.get("/v1/me");
+const invoices = await clients.billing.get("/v1/invoices");
+```
+
+Suggested structure:
+- `schemas/accounts.ts`, `schemas/billing.ts`, `schemas/notifications.ts`
+- one shared `clients.ts` that exports preconfigured clients
+- app code imports only `clients` and never constructs clients ad-hoc
+
+## Quick Start (Cats API)
+
+### With `baseUrl`
+
+```ts
+import { clientApi } from "kayto_ts";
+import type { Endpoints as CatsEndpoints } from "./schemas/cats";
+
+const clientWithBaseUrl = clientApi<CatsEndpoints>({
+  baseUrl: "https://api.example.com",
+});
+```
+
+`baseUrl` applies only to relative paths.
+If you pass an absolute URL (`https://...`), it is used as-is and `baseUrl` is ignored.
+
+```ts
+import { clientApi } from "kayto_ts";
+import type { Endpoints as CatsEndpoints } from "./schemas/cats";
+
+const client = clientApi<CatsEndpoints>({
+  baseUrl: "https://api.example.com",
+});
+
+await client.get("/api/cats");
+// -> https://api.example.com/api/cats
+
+await client.get("https://other.example.com/api/cats" as "/api/cats");
+// -> https://other.example.com/api/cats
+```
+
+## Basic Requests
+
+### GET with query params
+
+```ts
+const listResult = await client.get("/api/cats", {
+  params: {
+    query: {
+      page: 1,
+      search: "british",
+    },
+  },
+});
+```
+
+### GET with path params
+
+```ts
+const oneResult = await client.get("/api/cats/{id}", {
+  params: {
+    path: {
+      id: "cat_42",
+    },
+  },
+});
+```
+
+### POST with body
+
+```ts
+const createResult = await client.post("/api/cats", {
+  body: {
+    name: "Milo",
+    age: 2,
+  },
+});
+```
+
+### Request headers
+
+```ts
+const authorizedResult = await client.get("/api/cats", {
+  headers: {
+    Authorization: "Bearer <token>",
+    "x-cats-trace-id": "trace_123",
+  },
+});
+```
+
+### DELETE with path params
+
+```ts
+const deleteResult = await client.delete("/api/cats/{id}", {
+  params: {
+    path: {
+      id: "cat_42",
+    },
+  },
+});
+```
+
+## Timeout and Cancellation
+
+### Timeout
+
+```ts
+const result = await client.get("/api/cats", {
+  timeoutMs: 5_000,
+});
+```
+
+### AbortController
+
+```ts
+const controller = new AbortController();
+
+const promise = client.get("/api/cats", {
+  signal: controller.signal,
+});
+
+controller.abort();
+
+const result = await promise;
+```
+
+## Hooks and Interceptor
+
+```ts
+import { clientApi } from "kayto_ts";
+import type { Endpoints as CatsEndpoints } from "./schemas/cats";
+
+const clientWithHooks = clientApi<CatsEndpoints>({
+  baseUrl: "https://api.example.com",
+
+  onRequest: ({ method, path, init }) => {
+    const headers = new Headers(init.headers);
+    headers.set("x-cats-trace-id", "trace_123");
+    init.headers = headers;
+
+    console.log("request", method, path);
+  },
+
+  responseInterceptor: async ({ response }) => {
+    // Example: could refresh token and retry in your own wrapper logic.
+    return response;
+  },
+
+  onResponse: ({ method, path, response, durationMs }) => {
+    console.log("response", method, path, response.status, `${durationMs}ms`);
+  },
+});
+```
+
+## Error Handling
+
+All requests return a discriminated union:
+
+- success: `{ ok: true, result, response }`
+- failure: `{ ok: false, error, response? }`
+
+`error.kind` values:
+
+- `network`
+- `timeout`
+- `aborted`
+- `http`
+- `parse`
+- `hook`
+
+You can handle errors by `kind`, but it is optional.
+You can also handle them generically via `message` / `status` / `cause` without branching by `kind`.
+
+```ts
+const result = await client.get("/api/cats");
+
+if (!result.ok) {
+  console.error("Request failed:", result.error.message);
+
+  if (result.error.status != null) {
+    console.error("HTTP status:", result.error.status);
+  }
+
+  if (result.error.cause) {
+    console.error("Cause:", result.error.cause);
+  }
+}
+```
+
+```ts
+const result = await client.get("/api/cats");
+
+if (!result.ok) {
+  switch (result.error.kind) {
+    case "timeout":
+      console.error("Cats API timeout");
+      break;
+    case "aborted":
+      console.error("Request was cancelled");
+      break;
+    case "http":
+      console.error("HTTP error", result.error.status);
+      break;
+    default:
+      console.error(result.error.message, result.error.cause);
+  }
+}
+```
+
+## Response Parsing Rules
+
+Client parses response body automatically by `content-type`:
+
+- JSON: `application/json`, `application/problem+json`, `*+json`
+- Text: `text/*`
+- Other content-types: `Blob`
+- Empty body statuses (`204`, `205`, `304`): `null`
+
+## Notes
+
+- Runtime shape validation is not built in yet (current typing is compile-time only).
+- If you need runtime validation, validate `result.result` in consumer code (ArkType/Zod/etc.).
+- Current entrypoint is `src/index.ts`.

package/bin/kayto.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { platform } from "node:os";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = dirname(__dirname);
+
+const binary = platform() === "win32" ? "kayto.exe" : "kayto";
+const binaryPath = join(rootDir, ".kayto", "bin", binary);
+
+if (!existsSync(binaryPath)) {
+  console.error("[kayto_ts] kayto binary is missing. Reinstall package: npm i kayto_ts (or bun/pnpm/yarn install)");
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error("[kayto_ts] failed to execute kayto:", result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/bun.lock

@@ -0,0 +1,26 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "kayto_ts",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
+
+    "@types/node": ["@types/node@25.3.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A=="],
+
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "kayto_ts",
+  "version": "0.1.0",
+  "description": "Type-safe HTTP client and CLI wrapper for generating and using schemas with kayto.",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "kayto": "./bin/kayto.mjs"
+  },
+  "scripts": {
+    "postinstall": "bun ./scripts/postinstall.mjs || node ./scripts/postinstall.mjs",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}