@naturali/sdk 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @naturali/sdk
+
+TypeScript SDK for the [naturali.ai](https://naturali.ai) API, generated from
+its [OpenAPI specs](../../api/openapi/).
+
+```bash
+pnpm add @naturali/sdk
+```
+
+## Usage
+
+```ts
+import { NaturaliClient } from '@naturali/sdk';
+
+const naturali = new NaturaliClient({
+  baseUrl: 'https://api.naturali.ai',
+  token: process.env.NATURALI_TOKEN, // nat_sk_… or a session access JWT
+});
+
+const { data, error } = await naturali.agents.listAgents({
+  path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
+  query: { limit: 10 },
+});
+
+if (error) {
+  // The platform's error envelope, typed: { error: { code, message, details } }
+  console.error(error);
+} else {
+  console.log(data.data);
+}
+```
+
+A method never throws on a non-2xx response — it resolves to `{ data, error }`,
+so the machine-readable `code` (`approval_required`, `budget_exceeded`,
+`access_denied`, …) is available as typed data.
+
+## Options
+
+| Option | Purpose |
+| --- | --- |
+| `baseUrl` | API **origin** — operation paths already carry `/v1`, so pass `https://api.naturali.ai`, not `…/v1`. Defaults to `''` (same origin), which is what a browser app wants. |
+| `token` | Sent as `Authorization: Bearer …`. Accepts a `nat_sk_…` API key or a session access JWT. |
+| `headers` | Merged last, so it can override the header above or add your own. |
+
+There is no `project` option: a project-scoped operation takes `project_id` in
+its path, and that is the only thing the API authorizes against.
+
+## Call shape
+
+Each resource property mirrors a generated service class, with the configured
+HTTP client already bound. Arguments follow the spec's own structure and
+**snake_case** field names:
+
+```ts
+await naturali.sessions.addSessionMessage({
+  path: { project_id, agent_id, session_id },
+  body: { message: 'What is the capital of France?' },
+});
+
+await naturali.knowledge.queryKnowledgeCollection({
+  path: { project_id, collection_id },
+  body: { query: 'refund policy', limit: 5 },
+});
+```
+
+Resources: `agents`, `apiKeys`, `auth`, `channels`, `contacts`, `generations`,
+`knowledge`, `models`, `projects`, `providers`, `sessions`, `tools`, `traces`.
+
+`naturali.http` exposes the underlying client for interceptors or a one-off
+request (`naturali.http.get({ url: '/health' })`).
+
+## Types
+
+Every schema in the specs is exported as a type:
+
+```ts
+import type { Agent, AgentCreate, ErrorResponse } from '@naturali/sdk';
+```
+
+`created_at` / `updated_at` are handed to callers as `Date` objects; everything
+else matches the wire shape exactly.
+
+## Generation
+
+`src/generated/` is build output — never edit it, and never commit it. It is
+rebuilt from `api/openapi/v1/*.yaml` by `pnpm generate`, which `typecheck`,
+`test` and `build` all run first. See [`../README.md`](../README.md) for the
+pipeline.
+
+The only hand-written source is `src/naturaliClient.ts`.