@avallon-labs/sdk 0.0.0-40188bf9

package/README.md

@@ -0,0 +1,135 @@
+# @avallon/sdk
+
+TypeScript SDK for the Avallon API. Auto-generated from OpenAPI with custom auth utilities.
+
+## Installation
+
+```bash
+npm install @avallon/sdk
+```
+
+For React/SWR hooks:
+```bash
+npm install @avallon/sdk swr react
+```
+
+## Usage
+
+### Configure
+
+```typescript
+import { configure } from "@avallon/sdk";
+
+configure({
+  baseUrl: "https://api.avallon.ai",
+  apiKey: "your-api-key",
+  // OR for user auth:
+  getAccessToken: () => localStorage.getItem("access_token"),
+});
+```
+
+### API Calls (Plain Fetch)
+
+```typescript
+import { listAgents, createAgent } from "@avallon/sdk";
+
+// List agents
+const response = await listAgents();
+console.log(response.data.data.agents);
+
+// Create agent
+const created = await createAgent({ agent_name: "My Agent" });
+```
+
+### API Calls (React SWR Hooks)
+
+```typescript
+import { useListAgents, useCreateAgent } from "@avallon/sdk";
+
+function AgentsList() {
+  const { data, error, isLoading } = useListAgents();
+
+  if (isLoading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+
+  return <ul>{data.data.data.agents.map(a => <li key={a.id}>{a.agent_name}</li>)}</ul>;
+}
+
+function CreateAgent() {
+  const { trigger, isMutating } = useCreateAgent();
+
+  return (
+    <button onClick={() => trigger({ agent_name: "New Agent" })} disabled={isMutating}>
+      Create
+    </button>
+  );
+}
+```
+
+### OAuth Flow
+
+```typescript
+import { startOAuthFlow, getStoredVerifier, clearStoredVerifier, postV1AuthSignIn } from "@avallon/sdk";
+
+// 1. Start OAuth (redirects user)
+const { url } = await startOAuthFlow({
+  provider: "google",
+  redirectUri: "https://app.example.com/callback",
+});
+window.location.href = url;
+
+// 2. After redirect, exchange code for tokens
+const verifier = getStoredVerifier();
+const response = await postV1AuthSignIn({
+  type: "oauth",
+  code: new URLSearchParams(location.search).get("code"),
+  verifier,
+});
+clearStoredVerifier();
+
+// 3. Store tokens and configure SDK
+const { access_token, refresh_token, expires_at } = response.data.data;
+localStorage.setItem("access_token", access_token);
+configure({ getAccessToken: () => localStorage.getItem("access_token") });
+```
+
+### Error Handling
+
+```typescript
+import { AvallonError } from "@avallon/sdk";
+
+try {
+  await createAgent({ agent_name: "" });
+} catch (e) {
+  if (e instanceof AvallonError) {
+    if (e.isValidationError()) {
+      console.log("Validation errors:", e.errors);
+    } else if (e.isUnauthorized()) {
+      // Redirect to login
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Regenerate SDK from OpenAPI (from repo root)
+npm run sdk:gen
+
+# Build
+npm run build
+```
+
+## Structure
+
+```
+src/           # Handwritten code
+  index.ts     # Main exports
+  fetcher.ts   # Fetch wrapper with auth
+  auth.ts      # OAuth PKCE utilities
+
+generated/     # Auto-generated (do not edit)
+  endpoints/   # API functions + SWR hooks
+  models/      # Request/response types
+```