@avallon/sdk

TypeScript SDK for the Avallon API. Auto-generated from OpenAPI with custom auth utilities.

Installation

npm install @avallon/sdk

For React/SWR hooks:

npm install @avallon/sdk swr react

Usage

Configure

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)

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)

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

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

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

# 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