@alpinedataworks/sdk

Official TypeScript/JavaScript SDK for the Alpine DataWorks Intelligence Object API.

• Zero runtime dependencies — uses the native fetch built into Node 18+ and all modern browsers
• Typed with full TypeScript (ESM, *.d.ts declarations included)
• Mirrors the Python SDK surface exactly for cross-language consistency

Installation

npm install @alpinedataworks/sdk

Node 18 or later is required (for native fetch).

Quick start

import { Client } from "@alpinedataworks/sdk";

const client = new Client({
  apiKey: "adw_gold_demo",
  // baseUrl: "http://localhost:8787/v1",  // omit for production
});

// Public endpoints (no auth required)
const health = await client.health();
console.log(health.status); // "ok"

// List intelligence products
const products = await client.listProducts({ domain: "Crypto" });

// Get a tier-projected IOM object
const iom = await client.getProduct("ADW-001");
console.log(iom.score, iom.trend);

// Agent/LLM tool shim (zero-arg async callable)
const toolFn = client.asTool("ADW-001");
const result = await toolFn(); // → IntelligenceObject

Demo API keys

| Key | Tier | Field depth | |-----|------|-------------| | adw_free_demo | Free | score, trend, freshness, methodology_version | | adw_silver_demo | Silver | + confidence, top_drivers, coverage, recommended_use | | adw_gold_demo | Gold | + source_lineage, allowed_use, /history endpoint | | adw_platinum_demo | Platinum | Everything + larger batch (100) |

API reference

new Client(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | (required) | Bearer token | | baseUrl | string | https://api.alpinedataworks.ai/v1 | Override for local dev | | timeoutMs | number | 10000 | Per-request timeout |

Methods

All methods are async and return typed responses.

Public (no auth)

| Method | Returns | Description | |--------|---------|-------------| | health() | HealthResponse | API liveness check | | sourcesHealth() | SourcesHealthResponse | Upstream data-source status | | schemas() | SchemasResponse | IOM JSON Schema definition | | validate(obj) | ValidateResponse | Validate a candidate IOM object |

Authenticated (Bearer key required)

| Method | Returns | Tier | |--------|---------|------| | listProducts(opts?) | Product[] | Free+ | | getProduct(id) | IntelligenceObject | Free+ | | getIntelligence(id) | IntelligenceObject | Free+ (alias for above) | | batch(ids) | IntelligenceObject[] | Free+ | | drivers(id) | Driver[] | Silver+ | | history(id) | HistoryPoint[] | Gold+ | | asTool(id) | () => Promise<IntelligenceObject> | Free+ |

client.rateLimit

Rate limit state from the most recent response:

{
  limit: string | null;      // X-RateLimit-Limit
  remaining: string | null;  // X-RateLimit-Remaining
  reset: string | null;      // X-RateLimit-Reset
}

Error handling

All errors thrown by the SDK extend AlpineApiError:

import {
  AlpineApiError,
  AuthError,          // 401 — invalid/missing API key
  TierForbiddenError, // 403 — tier too low
  NotFoundError,      // 404 — product not found
  RateLimitError,     // 429 — quota exceeded
  BadRequestError,    // 400 — bad request body
} from "@alpinedataworks/sdk";

try {
  const obj = await client.history("ADW-001");
} catch (err) {
  if (err instanceof TierForbiddenError) {
    console.log("Upgrade required:", err.requiredTier);
  } else if (err instanceof RateLimitError) {
    console.log("Retry after:", err.retryAfter, "seconds");
  } else if (err instanceof AlpineApiError) {
    console.log(err.code, err.statusCode, err.requestId);
  }
}

Agent/LLM tool snippet

import { Client } from "@alpinedataworks/sdk";

const client = new Client({ apiKey: process.env.ADW_API_KEY! });

// Returns a named zero-arg async function — drop it straight into any
// agent framework as a tool execute handler.
const toolFn = client.asTool("ADW-001");
// toolFn.name === "adw_tool_adw_001"

// Vercel AI SDK example:
// import { tool } from "ai";
// import { z } from "zod";
// const adwCryptoSentiment = tool({
//   description: "Alpine DataWorks crypto sentiment & volatility index",
//   parameters: z.object({}),
//   execute: client.asTool("ADW-001"),
// });

// LangChain example:
// import { Tool } from "langchain/tools";
// const adwTool = new Tool({
//   name: "adw_crypto_sentiment",
//   description: "Returns ADW-001 crypto sentiment index",
//   func: client.asTool("ADW-001"),
// });

Local development

# Build
npm run build

# Run tests against a local wrangler dev instance
bash scripts/run-tests.sh

# Run the quickstart example
ADW_BASE_URL=http://localhost:8787/v1 node --import tsx examples/quickstart.ts

Architecture notes

• Zero runtime deps: uses globalThis.fetch, AbortController, and URLSearchParams — all built into Node 18+ and browsers.
• ESM only: "type": "module" with full exports map.
• Tier projection: field presence on IntelligenceObject depends on your API key tier; optional fields are typed as T | undefined.
• Passthrough: IntelligenceObject carries an index signature [key: string]: unknown for product-specific extra fields not in the base IOM schema.