TypeScript SDK — `@frootai/sdk-orchard`

Programmatic access to the FAI Orchard catalog from Node.js + browser runtimes. Same 27-contract conformance guarantees as the MCP server.

ℹ️ TypeScript-first. ESM + CJS dual-published. Zero runtime deps. Under 128 KiB tarball. Python SDK at /docs/sdk/orchard-python.

§1 — Install

```bash npm install @frootai/sdk-orchard

or

pnpm add @frootai/sdk-orchard

or

yarn add @frootai/sdk-orchard ```

§2 — Quick example

```ts import { createOrchardClient } from "@frootai/sdk-orchard";

const orchard = createOrchardClient({ baseUrl: "https://api.frootai.dev", // default token: process.env.FROOTAI_TOKEN, // optional; needed for Pro+ features region: "us-east", // default });

// Search the 413-entry catalog const results = await orchard.search({ query: "rag", where: "variety:azure AND trust_badge:eval_proven", limit: 20, });

for (const r of results.items) { console.log(r.id, r.title, r.stars); }

// Show full detail of one accelerator const detail = await orchard.show({ id: "azure-search-openai-demo" }); console.log(detail.manifest); ```

§3 — API surface (TS interface)

```ts interface OrchardClient { // Tools search(opts: SearchOpts): Promise<SearchResult>; show(opts: { id: string }): Promise<AcceleratorDetail>; listSkills(opts?: ListSkillsOpts): Promise<SkillsPage>; showSkill(opts: { id: string }): Promise<SkillManifest>;

// Bushel (Pro+ entitlement required) bushel: { pull(): Promise<BushelStore>; push(local: BushelStore, opts?: { if_match?: string }): Promise<PushResult>; };

// Diagnostics whoami(): Promise<{ subject: string; tier: string; entitlements: string[] }>; version(): Promise<{ sdk: string; server: string }>; } ```

§4 — Type-safe error handling

```ts import { OrchardError, isOrchardError } from "@frootai/sdk-orchard";

try { await orchard.bushel.push(local); } catch (err) { if (isOrchardError(err) && err.code === "rate_limited") { const retryAfter = err.retryAfterSeconds; console.warn(`Rate limited; retry in ${retryAfter}s`); } else if (isOrchardError(err) && err.code === "forbidden") { console.warn("Need Pro+ entitlement for bushel sync"); } else { throw err; } } ```

Error codes: `invalid_input`, `unauthorized`, `forbidden`, `not_found`, `rate_limited`, `internal`, `payload_too_large`.

§5 — Configuration via env vars

Var	Purpose
`FROOTAI_TOKEN`	Bearer token (Pro+)
`FROOTAI_BASE_URL`	Override API base URL (default `https://api.frootai.dev\`)
`FROOTAI_REGION`	Pin region (default `us-east`)
`FROOTAI_TIMEOUT_MS`	Per-request timeout (default 30000)
`DO_NOT_TRACK`	Set to `1` to disable any optional telemetry

§6 — Cross-runtime byte-equal

The same 27 contract assertions run against this TypeScript SDK and the Python SDK. JSON shapes, error envelopes, pagination cursors, etc. are byte-equal across both — verified on every release via the conformance certificate (schema).

§7 — Bundle + tree-shaking

ESM + CJS dual-published
Tree-shakeable per-tool exports: `import { search } from "@frootai/sdk-orchard/search"`
Tarball size budget: ≤ 128 KiB enforced in CI
Zero runtime deps (the only `dependencies` block is empty)

§8 — Browser usage

The SDK works in browsers behind any modern bundler (Webpack, Vite, Rollup, esbuild). For Cloudflare Workers + Vercel Edge + Deno runtimes, use the `/edge` entrypoint:

```ts import { createOrchardClient } from "@frootai/sdk-orchard/edge"; ```

This avoids any `node:*` builtins and uses only `globalThis.fetch`.

TypeScript SDK — @frootai/sdk-orchard