@avallon-labs/sdk

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

Installation

npm install @avallon-labs/sdk

For React/SWR hooks:

npm install @avallon-labs/sdk swr react

Usage

Configure

import { configure } from "@avallon-labs/sdk";

configure({
  baseUrl: "https://api.avallon.ai",
  apiKey: "your-api-key",
  // OR for user auth:
  getAccessToken: () => localStorage.getItem("access_token"),
});

Response Envelope

Endpoints return the API's { data, message } envelope verbatim — the payload is on data. Paginated endpoints add meta.total so you can page without a second request. (204 endpoints return nothing, and getPartnerJwks returns a standards-compliant JWKS, so neither is enveloped.)

const { data, meta } = await listArtifacts({ count: 25, offset: 50 });
console.log(`showing ${data.length} of ${meta.total}`);

API Calls (Plain Fetch)

import { listVoiceAgents, createVoiceAgent } from "@avallon-labs/sdk";

// List agents
const { data } = await listVoiceAgents();
console.log(data.agents);

// Create agent
const { data: created } = await createVoiceAgent({ agent_name: "My Agent" });

API Calls (React SWR Hooks)

import { useListVoiceAgents, useCreateVoiceAgent } from "@avallon-labs/sdk";

function AgentsList() {
  const { data, error, isLoading } = useListVoiceAgents();

  if (isLoading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return <ul>{data.data.agents.map(a => <li key={a.id}>{a.agent_name}</li>)}</ul>;
}

function CreateAgent() {
  const { trigger, isMutating } = useCreateVoiceAgent();

  return (
    <button onClick={() => trigger({ agent_name: "New Agent" })} disabled={isMutating}>
      Create
    </button>
  );
}

OAuth Flow

import { startOAuthFlow, getStoredVerifier, clearStoredVerifier, signIn } from "@avallon-labs/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 signIn({
  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;
localStorage.setItem("access_token", access_token);
configure({ getAccessToken: () => localStorage.getItem("access_token") });

Error Handling

import { AvallonError } from "@avallon-labs/sdk";

try {
  await createVoiceAgent({ 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