arcade-js

@arcadeai/arcadejs is the official TypeScript and JavaScript client for the Arcade API, the platform Arcade AI provides for running and authorizing tools that AI agents call. Generated from Arcade’s OpenAPI spec via Stainless, it wraps tool execution, tool authorization, chat completions, worker management, and admin operations behind a single typed client, so agent developers can call client.tools.execute() or client.chat.completions.create() without hand-rolling HTTP requests, retries, or pagination.

The library ships with zero runtime dependencies, built-in retry and timeout handling, auto-pagination helpers, configurable logging, and full TypeScript types for every request and response shape, making it a drop-in foundation for Node.js, Deno, Bun, Cloudflare Workers, and browser-based agent applications that need to talk to Arcade’s hosted tool-calling infrastructure.

What You Get

• Typed clients for every Arcade resource — tools, chat completions, auth, workers, admin, and health checks — with full request/response TypeScript types.
• Built-in tool execution and authorization flows (client.tools.execute, client.tools.authorize) for letting agents call external tools like Gmail or Slack through Arcade.
• Automatic retries with exponential backoff, configurable timeouts, and auto-pagination via for-await-of over list endpoints.
• Zero runtime dependencies, with support for Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge, and browsers out of the box.

Common Use Cases

• Executing a registered Arcade tool (e.g. Google.ListEmails) from an agent backend and handling the authorization flow when a user needs to grant access first.
• Building a chat-based agent that calls client.chat.completions.create() against Arcade-hosted models with tool-calling support.
• Managing Arcade workers and user connections from an admin dashboard via the admin and workers resource clients.
• Iterating through paginated tool or worker listings using the built-in auto-pagination helpers instead of manually tracking page cursors.

Under The Hood

Architecture The client is organized as a central Arcade class (src/client.ts) that composes typed resource classes — Tools, Chat, Auth, Admin, Workers, Health — each extending a shared APIResource base (src/core/resource.ts) that just holds a reference back to the parent client for making requests. Requests flow through a shared request pipeline (buildHeaders, FinalRequestOptions, the internal fetch shim in src/internal/shims) that centralizes header construction, retries, and response parsing, so every resource method ultimately funnels through the same HTTP layer rather than each resource reimplementing request logic. List-returning endpoints return an AbstractPage/OffsetPageResponse (src/core/pagination.ts) that supports both for-await-of iteration and manual hasNextPage/getNextPage control, keeping pagination consistent across tools, workers, and admin listings. This is boilerplate-heavy, Stainless-generated code (nearly every file carries a “File generated from our OpenAPI spec” header) rather than hand-authored architecture, but the layering is clean: resources never talk to fetch directly, they all go through the shared client core.

Tech Stack Written in TypeScript 5.8 with zero runtime dependencies — a deliberate design choice typical of Stainless-generated SDKs to avoid supply-chain bloat and dependency conflicts in consumers’ projects. It targets a wide runtime matrix (Node.js 20+, Deno, Bun, Cloudflare Workers, Vercel Edge, and browsers) by relying on the global fetch API and platform-detection shims (src/internal/detect-platform.ts) rather than Node-specific HTTP libraries. Build tooling is pnpm-based with a custom build script producing dual CJS/ESM output (tsc-multi, package.json exports map for both import and require), and Zod is used as a devDependency for optional runtime schema helpers exposed under a lib subpath rather than as a hard dependency.

Code Quality Tests live under tests/, organized to mirror the resource structure (tests/api-resources/tools, chat, admin) plus lower-level tests for internals like header building, query stringification, and multipart form handling. The suite runs on Jest with ts-jest/swc for fast TypeScript transforms, and CI (.github/workflows/ci.yml) runs a dedicated lint job that type-checks the codebase in addition to running tests. Error handling is explicit and typed: a class hierarchy under src/core/error.ts (APIError, BadRequestError, AuthenticationError, RateLimitError, etc.) maps HTTP status codes to specific error subclasses so callers can catch by type rather than parsing status codes themselves. ESLint enforces unused-import removal and blocks self-referential package imports, and Prettier formatting is CI-checked.

API Design The public surface favors a small, discoverable set of resource namespaces (client.tools, client.chat, client.auth, client.admin, client.workers) over a single flat method list, and every request/response shape ships with TypeScript types importable alongside the client (e.g. Arcade.Chat.CompletionCreateParams). Escape hatches are deliberately built in — client.get/post for undocumented endpoints, @ts-expect-error patterns for undocumented params, and .asResponse()/.withResponse() for raw fetch Response access — so the generated client doesn’t box consumers in when the API surface gets ahead of the SDK. Getting started requires minimal boilerplate: a single Arcade({ apiKey }) constructor call, with the API key defaulting to an environment variable, before any resource method can be called.