kyro-connect 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,242 @@
+# kyro-connect
+
+Universal SDK for [Kyro CMS](https://kyro.dev). Type-safe client for any platform — Node.js, browser, Deno, Bun.
+
+```bash
+npm install kyro-connect
+```
+
+---
+
+## Quick Start
+
+### 1. Generate types
+
+```bash
+npx kyro-codegen --url http://localhost:4321/api --api-key kyro_xxx
+```
+
+Fetches your CMS schema and generates `kyro.generated.d.ts` with full type definitions for every collection, global, and procedure.
+
+### 2. Use the client
+
+```ts
+import { createClient } from "kyro-connect";
+import type { AppRouter } from "./kyro.generated";
+
+const api = createClient<AppRouter>({
+  url: "http://localhost:4321/api/trpc",
+  apiKey: "kyro_xxx",
+});
+```
+
+---
+
+## API
+
+### `createClient(options)`
+
+Creates a proxy-based client for your Kyro CMS tRPC endpoint.
+
+```ts
+const api = createClient<AppRouter>({
+  url: "http://localhost:4321/api/trpc",
+  apiKey: "kyro_xxx",
+  fetch: globalThis.fetch,
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | — | Base URL of the tRPC endpoint |
+| `apiKey` | `string` | — | API key for authenticated requests |
+| `fetch` | `typeof globalThis.fetch` | `globalThis.fetch` | Custom fetch implementation |
+
+#### Query procedures (GET)
+
+```ts
+const { docs } = await api["posts"].find({ page: 1, limit: 10 });
+// docs: Post[]
+
+const post = await api["posts"].findByID({ id: "abc123" });
+// post: Post
+
+const { totalDocs } = await api["posts"].count({
+  where: { status: { equals: "published" } },
+});
+// totalDocs: number
+```
+
+#### Mutation procedures (POST)
+
+```ts
+const { doc } = await api["posts"].create({
+  data: { title: "Hello", slug: "hello" },
+});
+// doc: Post
+
+const { doc } = await api["posts"].update({
+  id: "abc",
+  data: { title: "Updated" },
+});
+// doc: Post
+
+const { doc, message } = await api["posts"].delete({ id: "abc" });
+// doc: Post, message: string
+```
+
+#### Globals
+
+```ts
+const settings = await api["_globals_site-settings"].get();
+// settings: SiteSettingsGlobal
+
+await api["_globals_site-settings"].update({
+  data: { siteName: "New Name" },
+});
+```
+
+---
+
+## Codegen
+
+### CLI
+
+```bash
+# Basic
+npx kyro-codegen --url http://localhost:4321/api --api-key kyro_xxx
+
+# Custom output path
+npx kyro-codegen --url http://localhost:4321/api --api-key kyro_xxx --output src/types/kyro.d.ts
+```
+
+### Generated types
+
+Running codegen produces `kyro.generated.d.ts` containing:
+
+- **Doc types** — TypeScript interfaces for each collection and global, derived from field definitions
+- **Input types** — typed inputs for every procedure (`PostsFindInput`, `PostsCreateInput`, etc.)
+- **Output types** — typed outputs for every procedure (`PostsFindOutput`, etc.)
+- **AppRouter** — mapped type linking all collection/global procedures to their input/output types
+
+### Slugs with hyphens
+
+Use bracket notation when accessing collections with hyphens in their slug:
+
+```ts
+const data = await api["my-collection"].find({ page: 1 });
+```
+
+### Without codegen
+
+The client works without types — everything is `any`:
+
+```ts
+const api = createClient({ url: "...", apiKey: "..." });
+const posts = await api.posts.find({ page: 1 });
+// posts: any
+```
+
+---
+
+## Transport
+
+### Request format
+
+| Procedure type | HTTP method | URL | Body |
+|---|---|---|---|
+| `find`, `findByID`, `count` | GET | `/api/trpc/{slug}.{proc}?input={json}` | — |
+| `create`, `update`, `delete` | POST | `/api/trpc/{slug}.{proc}` | JSON body |
+
+### Authentication
+
+API key is sent as the `x-api-key` header on every request. If the server session cookie is already present (browser environment), the `apiKey` option can be omitted.
+
+---
+
+## Errors
+
+### `KyroConnectError`
+
+Thrown when the server responds with a non-2xx status code.
+
+```ts
+import { createClient, KyroConnectError } from "kyro-connect";
+
+try {
+  await api["posts"].find({ page: 1 });
+} catch (err) {
+  if (err instanceof KyroConnectError) {
+    console.error(err.message); // Server error message
+    console.error(err.status);  // HTTP status code
+    console.error(err.code);    // tRPC error code
+  }
+}
+```
+
+### Error scenarios
+
+| Scenario | Error type | Cause |
+|---|---|---|
+| Network failure | `TypeError` | DNS, connection refused, timeout |
+| Server error response | `KyroConnectError` | 4xx or 5xx status with JSON body |
+| Invalid response body | `SyntaxError` | Non-JSON response |
+| Access denied | `KyroConnectError` with `status: 403` | Missing or invalid API key |
+| Not found | `KyroConnectError` with `status: 404` | Collection or document not found |
+
+---
+
+## Platform support
+
+| Platform | Native fetch | Status |
+|---|---|---|
+| Node.js 18+ | ✅ | Full support |
+| Browser | ✅ | Full support |
+| Deno | ✅ | Full support |
+| Bun | ✅ | Full support |
+| Cloudflare Workers | ✅ | Full support |
+| Vercel Edge Runtime | ✅ | Full support |
+| Node.js 16-17 | ⚠️ | Requires polyfill or `--experimental-fetch` |
+
+---
+
+## TypeScript configuration
+
+Ensure the generated types are visible to the TypeScript compiler:
+
+```json
+// tsconfig.json
+{
+  "include": ["src", "kyro.generated.d.ts"]
+}
+```
+
+Or place `kyro.generated.d.ts` inside your `src/` directory.
+
+---
+
+## Development
+
+```bash
+git clone <repo>
+cd packages/kyro-connect
+pnpm install
+pnpm build
+```
+
+### Local testing
+
+```bash
+# Link the package globally
+pnpm link --global
+
+# In your consumer project
+pnpm link kyro-connect
+npx kyro-codegen --url http://localhost:4321/api --api-key kyro_xxx
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kyro-connect",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Universal SDK for Kyro CMS. Type-safe client + codegen for any platform.",
   "type": "module",
   "exports": {