trawl-sdk 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @trawl/sdk
+
+The official TypeScript SDK for the [Trawl](https://gettrawl.com) API — extract transcripts from YouTube, podcasts, TikTok, earnings calls, SEC filings, news, and academic papers.
+
+## Install
+
+```bash
+npm install @trawl/sdk
+```
+
+## Quick Start
+
+```typescript
+import { TrawlClient } from "@trawl/sdk";
+
+const client = new TrawlClient({ apiKey: "trawl_your_key" });
+
+// Search YouTube
+const results = await client.search.youtube("machine learning", 5);
+results.results.forEach((v) => console.log(`${v.title} — ${v.channel}`));
+
+// Extract a transcript (no auth needed)
+const preview = await client.transcripts.preview("https://youtube.com/watch?v=dQw4w9WgXcQ");
+console.log(`${preview.segments.length} segments`);
+
+// Bulk download as ZIP
+const zip = await client.bulk.download(["dQw4w9WgXcQ", "9bZkp7q19f0"], "jsonl");
+```
+
+## All Resources
+
+```typescript
+const client = new TrawlClient({ apiKey: "trawl_your_key" });
+
+// YouTube
+client.search.youtube(query, maxResults?)
+client.transcripts.extract(url, language?)
+client.transcripts.preview(url)              // No auth
+client.transcripts.download(id, format?)
+client.bulk.download(videoIds, format?)       // No auth
+
+// Podcasts
+client.search.podcasts(query, maxResults?)
+client.podcasts.episodes(podcastId)
+client.podcasts.transcribe(audioUrl, options?)
+
+// Earnings
+client.earnings.search(ticker)
+client.earnings.getTranscript(ticker, year, quarter)
+
+// SEC Filings
+client.filings.search(ticker, formType?)
+
+// News
+client.news.search(query, language?, country?)
+client.news.getArticleText(url)
+
+// Papers
+client.papers.search(query, source?)
+client.papers.extract(arxivId?, doi?)
+
+// AI
+client.ai.summarize(transcriptId)
+client.ai.topics(transcriptId)
+client.ai.entities(transcriptId)
+client.ai.previewSummarize(text)            // No auth
+
+// Jobs
+client.jobs.get(jobId)
+client.jobs.list()
+```
+
+## Error Handling
+
+```typescript
+import { AuthenticationError, RateLimitError, NotFoundError } from "@trawl/sdk";
+
+try {
+  await client.transcripts.extract("invalid-url");
+} catch (e) {
+  if (e instanceof RateLimitError) {
+    console.log(`Retry after ${e.retryAfter}s`);
+  } else if (e instanceof AuthenticationError) {
+    console.log("Invalid API key");
+  }
+}
+```
+
+## TypeScript
+
+Full TypeScript support with exported interfaces:
+
+```typescript
+import type {
+  TranscriptResponse,
+  SearchResponse,
+  SearchResult,
+  TranscriptSegment,
+  PaperResult,
+} from "@trawl/sdk";
+```
+
+## Requirements
+
+- Node.js 18+ (native `fetch`)
+- TypeScript 5+ (optional)
+
+## Links
+
+- [API Documentation](https://gettrawl.com/docs)
+- [RAG Pipeline Tutorial](https://gettrawl.com/blog/youtube-rag-pipeline)
+- [GitHub](https://github.com/trawl/trawl)

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "trawl-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Trawl unified content API",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsup src/index.ts --format esm,cjs --dts"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "tsup": "^8.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,341 @@
+import {
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  TrawlError,
+  ValidationError,
+} from "./errors";
+import type {
+  Job,
+  JobListResponse,
+  PodcastEpisode,
+  PodcastEpisodeListResponse,
+  PodcastSearchResponse,
+  SearchResponse,
+  TranscriptPreviewResponse,
+  TranscriptResponse,
+} from "./types";
+
+const DEFAULT_BASE_URL = "https://api.gettrawl.com";
+
+async function handleError(response: Response): Promise<never> {
+  let detail: string;
+  try {
+    const body = await response.json();
+    detail = body.detail || response.statusText;
+  } catch {
+    detail = response.statusText;
+  }
+
+  switch (response.status) {
+    case 401:
+      throw new AuthenticationError(detail);
+    case 404:
+      throw new NotFoundError(detail);
+    case 422:
+      throw new ValidationError(detail);
+    case 429: {
+      const retryAfter = response.headers.get("Retry-After");
+      throw new RateLimitError(
+        detail,
+        retryAfter ? parseInt(retryAfter, 10) : undefined,
+      );
+    }
+    default:
+      throw new TrawlError(detail, response.status);
+  }
+}
+
+export interface TrawlClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+class TranscriptsResource {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  async extract(
+    url: string,
+    language?: string,
+  ): Promise<TranscriptResponse> {
+    const body: Record<string, unknown> = { url };
+    if (language) body.language = language;
+    const res = await fetch(`${this.baseUrl}/api/transcripts`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async preview(
+    url: string,
+    language?: string,
+  ): Promise<TranscriptPreviewResponse> {
+    const body: Record<string, unknown> = { url };
+    if (language) body.language = language;
+    const res = await fetch(`${this.baseUrl}/api/transcripts/preview`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async download(transcriptId: number, format = "txt"): Promise<string> {
+    const res = await fetch(
+      `${this.baseUrl}/api/transcripts/${transcriptId}/download?format=${format}`,
+      { headers: this.headers },
+    );
+    if (!res.ok) await handleError(res);
+    return res.text();
+  }
+}
+
+class SearchResource {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  async youtube(query: string, maxResults = 10): Promise<SearchResponse> {
+    const params = new URLSearchParams({
+      q: query,
+      max_results: String(maxResults),
+    });
+    const res = await fetch(`${this.baseUrl}/api/search?${params}`, {
+      headers: this.headers,
+    });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async podcasts(query: string, maxResults = 20): Promise<PodcastSearchResponse> {
+    const params = new URLSearchParams({
+      q: query,
+      max_results: String(maxResults),
+    });
+    const res = await fetch(`${this.baseUrl}/api/podcasts/search?${params}`, {
+      headers: this.headers,
+    });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+}
+
+class PodcastsResource {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  async episodes(
+    podcastId: number,
+    maxResults = 50,
+  ): Promise<PodcastEpisode[]> {
+    const params = new URLSearchParams({
+      max_results: String(maxResults),
+    });
+    const res = await fetch(
+      `${this.baseUrl}/api/podcasts/${podcastId}/episodes?${params}`,
+      { headers: this.headers },
+    );
+    if (!res.ok) await handleError(res);
+    const data: PodcastEpisodeListResponse = await res.json();
+    return data.episodes;
+  }
+
+  async transcribe(
+    audioUrl: string,
+    options?: Record<string, unknown>,
+  ): Promise<Job> {
+    const res = await fetch(`${this.baseUrl}/api/podcasts/transcribe`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({ audio_url: audioUrl, ...options }),
+    });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+}
+
+class JobsResource {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  async get(jobId: string): Promise<Job> {
+    const res = await fetch(`${this.baseUrl}/api/jobs/${jobId}`, {
+      headers: this.headers,
+    });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async list(): Promise<Job[]> {
+    const res = await fetch(`${this.baseUrl}/api/jobs`, {
+      headers: this.headers,
+    });
+    if (!res.ok) await handleError(res);
+    const data: JobListResponse = await res.json();
+    return data.items;
+  }
+}
+
+class BulkResource {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>,
+  ) {}
+
+  async download(
+    videoIds: string[],
+    format = "txt",
+  ): Promise<ArrayBuffer> {
+    const res = await fetch(`${this.baseUrl}/api/bulk-download`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ video_ids: videoIds, format }),
+    });
+    if (!res.ok) await handleError(res);
+    return res.arrayBuffer();
+  }
+}
+
+class EarningsResource {
+  constructor(private baseUrl: string, private headers: Record<string, string>) {}
+
+  async search(ticker: string): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/api/earnings/search?ticker=${encodeURIComponent(ticker)}`, { headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async getTranscript(ticker: string, year: number, quarter: number): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/api/earnings/${ticker}/${year}/${quarter}`, { headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+}
+
+class FilingsResource {
+  constructor(private baseUrl: string, private headers: Record<string, string>) {}
+
+  async search(ticker: string, formType?: string): Promise<Record<string, unknown>> {
+    const params = new URLSearchParams({ ticker });
+    if (formType) params.set("form_type", formType);
+    const res = await fetch(`${this.baseUrl}/api/filings/search?${params}`, { headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+}
+
+class NewsResource {
+  constructor(private baseUrl: string, private headers: Record<string, string>) {}
+
+  async search(query: string, language?: string, country?: string): Promise<Record<string, unknown>> {
+    const params = new URLSearchParams({ q: query });
+    if (language) params.set("language", language);
+    if (country) params.set("country", country);
+    const res = await fetch(`${this.baseUrl}/api/news/search?${params}`, { headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async getArticleText(url: string): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/api/news/article?url=${encodeURIComponent(url)}`, { headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+}
+
+class PapersResourceSDK {
+  constructor(private baseUrl: string, private headers: Record<string, string>) {}
+
+  async search(query: string, source = "all"): Promise<Record<string, unknown>> {
+    const params = new URLSearchParams({ q: query, source });
+    const res = await fetch(`${this.baseUrl}/api/papers/search?${params}`, { headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async extract(arxivId?: string, doi?: string): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/api/papers/extract`, {
+      method: "POST", headers: this.headers,
+      body: JSON.stringify({ arxiv_id: arxivId || null, doi: doi || null }),
+    });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+}
+
+class AIResource {
+  constructor(private baseUrl: string, private headers: Record<string, string>) {}
+
+  async summarize(transcriptId: number): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/api/ai/${transcriptId}/summarize`, { method: "POST", headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async topics(transcriptId: number): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/api/ai/${transcriptId}/topics`, { method: "POST", headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async entities(transcriptId: number): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/api/ai/${transcriptId}/entities`, { method: "POST", headers: this.headers });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+
+  async previewSummarize(text: string): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/api/ai/preview/summarize`, {
+      method: "POST", headers: this.headers,
+      body: JSON.stringify({ text }),
+    });
+    if (!res.ok) await handleError(res);
+    return res.json();
+  }
+}
+
+export class TrawlClient {
+  public transcripts: TranscriptsResource;
+  public search: SearchResource;
+  public podcasts: PodcastsResource;
+  public jobs: JobsResource;
+  public bulk: BulkResource;
+  public earnings: EarningsResource;
+  public filings: FilingsResource;
+  public news: NewsResource;
+  public papers: PapersResourceSDK;
+  public ai: AIResource;
+
+  constructor(options: TrawlClientOptions = {}) {
+    const baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (options.apiKey) {
+      headers["X-API-Key"] = options.apiKey;
+    }
+
+    this.transcripts = new TranscriptsResource(baseUrl, headers);
+    this.search = new SearchResource(baseUrl, headers);
+    this.podcasts = new PodcastsResource(baseUrl, headers);
+    this.jobs = new JobsResource(baseUrl, headers);
+    this.bulk = new BulkResource(baseUrl, headers);
+    this.earnings = new EarningsResource(baseUrl, headers);
+    this.filings = new FilingsResource(baseUrl, headers);
+    this.news = new NewsResource(baseUrl, headers);
+    this.papers = new PapersResourceSDK(baseUrl, headers);
+    this.ai = new AIResource(baseUrl, headers);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,42 @@
+export class TrawlError extends Error {
+  constructor(
+    message: string,
+    public statusCode?: number,
+  ) {
+    super(message);
+    this.name = "TrawlError";
+  }
+}
+
+// Backwards compatibility alias
+export const TranscriptaError = TrawlError;
+
+export class AuthenticationError extends TrawlError {
+  constructor(message: string) {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+}
+
+export class NotFoundError extends TrawlError {
+  constructor(message: string) {
+    super(message, 404);
+    this.name = "NotFoundError";
+  }
+}
+
+export class RateLimitError extends TrawlError {
+  retryAfter?: number;
+  constructor(message: string, retryAfter?: number) {
+    super(message, 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class ValidationError extends TrawlError {
+  constructor(message: string) {
+    super(message, 422);
+    this.name = "ValidationError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { TrawlClient } from "./client";
+export type { TrawlClientOptions } from "./client";
+export * from "./types";
+export * from "./errors";

package/src/types.ts

@@ -0,0 +1,82 @@
+export interface TranscriptSegment {
+  text: string;
+  start: number;
+  duration: number;
+}
+
+export interface TranscriptResponse {
+  id: number;
+  video_id: string;
+  title: string | null;
+  channel: string | null;
+  thumbnail: string | null;
+  language: string;
+  is_auto_generated: boolean;
+  segments: TranscriptSegment[];
+  created_at: string;
+}
+
+export interface TranscriptPreviewResponse {
+  video_id: string;
+  title: string | null;
+  channel: string | null;
+  thumbnail: string | null;
+  language: string;
+  is_auto_generated: boolean;
+  segments: TranscriptSegment[];
+}
+
+export interface SearchResult {
+  video_id: string;
+  title: string;
+  channel: string;
+  thumbnail: string;
+  published_at: string;
+  description: string;
+}
+
+export interface SearchResponse {
+  query: string;
+  results: SearchResult[];
+}
+
+export interface PodcastSearchResult {
+  id: number;
+  title: string;
+  author: string;
+  description: string;
+  artwork_url: string;
+  feed_url: string;
+  episode_count: number;
+}
+
+export interface PodcastSearchResponse {
+  query: string;
+  results: PodcastSearchResult[];
+}
+
+export interface PodcastEpisode {
+  id: number;
+  title: string;
+  description: string;
+  audio_url: string;
+  duration_seconds: number;
+  published_at: string;
+  has_transcript: boolean;
+}
+
+export interface PodcastEpisodeListResponse {
+  podcast_id: number;
+  episodes: PodcastEpisode[];
+}
+
+export interface Job {
+  id: string;
+  status: string;
+  created_at: string;
+}
+
+export interface JobListResponse {
+  items: Job[];
+  total: number;
+}

package/tests/client.test.ts

@@ -0,0 +1,329 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { TrawlClient } from "../src/client";
+import {
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError,
+  TrawlError,
+} from "../src/errors";
+
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+beforeEach(() => {
+  mockFetch.mockReset();
+});
+
+function mockResponse(status: number, body: unknown = {}, headers: Record<string, string> = {}) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? "OK" : "Error",
+    json: () => Promise.resolve(body),
+    text: () => Promise.resolve(typeof body === "string" ? body : JSON.stringify(body)),
+    arrayBuffer: () => Promise.resolve(new ArrayBuffer(8)),
+    headers: new Map(Object.entries(headers)),
+  };
+}
+
+const TRANSCRIPT = {
+  id: 1,
+  video_id: "abc123",
+  title: "Test",
+  channel: "Chan",
+  thumbnail: null,
+  language: "en",
+  is_auto_generated: true,
+  segments: [{ text: "Hello", start: 0, duration: 1 }],
+  created_at: "2026-01-01",
+};
+
+describe("TrawlClient", () => {
+  it("creates client with API key", () => {
+    const client = new TrawlClient({ apiKey: "trawl_test", baseUrl: "http://test" });
+    expect(client.transcripts).toBeDefined();
+    expect(client.search).toBeDefined();
+    expect(client.podcasts).toBeDefined();
+    expect(client.jobs).toBeDefined();
+    expect(client.bulk).toBeDefined();
+  });
+});
+
+describe("transcripts", () => {
+  it("extracts a transcript", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, TRANSCRIPT));
+    const client = new TrawlClient({ apiKey: "trawl_test", baseUrl: "http://test" });
+
+    const result = await client.transcripts.extract("https://youtube.com/watch?v=abc");
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      "http://test/api/transcripts",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(result.video_id).toBe("abc123");
+    expect(result.segments).toHaveLength(1);
+  });
+
+  it("previews a transcript (no auth)", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { ...TRANSCRIPT, id: undefined }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+
+    const result = await client.transcripts.preview("https://youtube.com/watch?v=abc");
+
+    expect(result.video_id).toBe("abc123");
+  });
+
+  it("downloads a transcript", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, "Hello world"));
+    const client = new TrawlClient({ apiKey: "trawl_test", baseUrl: "http://test" });
+
+    const result = await client.transcripts.download(1, "txt");
+
+    expect(result).toContain("Hello");
+  });
+
+  it("throws AuthenticationError on 401", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(401, { detail: "Not authenticated" }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+
+    await expect(client.transcripts.extract("https://youtube.com/watch?v=abc")).rejects.toThrow(
+      AuthenticationError,
+    );
+  });
+
+  it("throws NotFoundError on 404", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(404, { detail: "Not found" }));
+    const client = new TrawlClient({ apiKey: "test", baseUrl: "http://test" });
+
+    await expect(client.transcripts.extract("https://youtube.com/watch?v=abc")).rejects.toThrow(
+      NotFoundError,
+    );
+  });
+
+  it("throws ValidationError on 422", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(422, { detail: "Invalid URL" }));
+    const client = new TrawlClient({ apiKey: "test", baseUrl: "http://test" });
+
+    await expect(client.transcripts.extract("bad-url")).rejects.toThrow(ValidationError);
+  });
+
+  it("throws RateLimitError on 429 with retry-after", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse(429, { detail: "Rate limited" }, { "Retry-After": "30" }),
+    );
+    const client = new TrawlClient({ apiKey: "test", baseUrl: "http://test" });
+
+    try {
+      await client.transcripts.extract("https://youtube.com/watch?v=abc");
+      expect.fail("Should have thrown");
+    } catch (e) {
+      expect(e).toBeInstanceOf(RateLimitError);
+      expect((e as RateLimitError).retryAfter).toBe(30);
+    }
+  });
+});
+
+describe("search", () => {
+  it("searches YouTube", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse(200, {
+        query: "python",
+        results: [{ video_id: "v1", title: "Python Tutorial", channel: "Ch", thumbnail: "", published_at: "", description: "" }],
+      }),
+    );
+    const client = new TrawlClient({ baseUrl: "http://test" });
+
+    const result = await client.search.youtube("python", 5);
+
+    expect(result.query).toBe("python");
+    expect(result.results).toHaveLength(1);
+  });
+
+  it("searches podcasts", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse(200, {
+        query: "ai",
+        results: [{ id: 1, title: "AI Pod", author: "Host", description: "", artwork_url: "", feed_url: "", episode_count: 10 }],
+      }),
+    );
+    const client = new TrawlClient({ baseUrl: "http://test" });
+
+    const result = await client.search.podcasts("ai");
+
+    expect(result.results[0].title).toBe("AI Pod");
+  });
+});
+
+describe("podcasts", () => {
+  it("lists episodes", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse(200, {
+        podcast_id: 1,
+        episodes: [{ id: 1, title: "Ep 1", description: "", audio_url: "", duration_seconds: 3600, published_at: "", has_transcript: false }],
+      }),
+    );
+    const client = new TrawlClient({ baseUrl: "http://test" });
+
+    const episodes = await client.podcasts.episodes(1);
+
+    expect(episodes).toHaveLength(1);
+    expect(episodes[0].title).toBe("Ep 1");
+  });
+
+  it("submits transcription job", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse(200, { id: "job-1", status: "pending", created_at: "2026-01-01" }),
+    );
+    const client = new TrawlClient({ apiKey: "test", baseUrl: "http://test" });
+
+    const job = await client.podcasts.transcribe("https://example.com/ep.mp3");
+
+    expect(job.id).toBe("job-1");
+    expect(job.status).toBe("pending");
+  });
+});
+
+describe("jobs", () => {
+  it("gets a job", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse(200, { id: "j1", status: "completed", created_at: "2026-01-01" }),
+    );
+    const client = new TrawlClient({ apiKey: "test", baseUrl: "http://test" });
+
+    const job = await client.jobs.get("j1");
+
+    expect(job.status).toBe("completed");
+  });
+
+  it("lists jobs", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse(200, { items: [{ id: "j1", status: "pending", created_at: "2026-01-01" }], total: 1 }),
+    );
+    const client = new TrawlClient({ apiKey: "test", baseUrl: "http://test" });
+
+    const jobs = await client.jobs.list();
+
+    expect(jobs).toHaveLength(1);
+  });
+});
+
+describe("bulk", () => {
+  it("downloads ZIP", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+
+    const result = await client.bulk.download(["v1", "v2"], "jsonl");
+
+    expect(result).toBeInstanceOf(ArrayBuffer);
+    expect(mockFetch).toHaveBeenCalledWith(
+      "http://test/api/bulk-download",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+});
+
+describe("earnings", () => {
+  it("searches earnings by ticker", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { ticker: "AAPL", results: [{ year: 2024, quarter: 4 }] }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    const result = await client.earnings.search("AAPL");
+    expect(result.ticker).toBe("AAPL");
+  });
+
+  it("gets earnings transcript", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { ticker: "AAPL", sections: [] }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    const result = await client.earnings.getTranscript("AAPL", 2024, 4);
+    expect(result.ticker).toBe("AAPL");
+  });
+});
+
+describe("filings", () => {
+  it("searches SEC filings", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { results: [{ form_type: "10-K" }] }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    const result = await client.filings.search("AAPL", "10-K");
+    expect(result.results).toHaveLength(1);
+  });
+});
+
+describe("news", () => {
+  it("searches global news", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { articles: [{ title: "Fed Holds Rates" }] }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    const result = await client.news.search("Federal Reserve");
+    expect(result.articles).toHaveLength(1);
+  });
+
+  it("extracts article text", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { text: "Article content", word_count: 50 }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    const result = await client.news.getArticleText("https://example.com");
+    expect(result.word_count).toBe(50);
+  });
+});
+
+describe("papers", () => {
+  it("searches papers", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { results: [{ title: "Attention" }] }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    const result = await client.papers.search("transformer");
+    expect(result.results).toHaveLength(1);
+  });
+
+  it("extracts paper", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { paper: { paper_id: "2301.08745" } }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    const result = await client.papers.extract("2301.08745");
+    expect(result.paper.paper_id).toBe("2301.08745");
+  });
+});
+
+describe("ai", () => {
+  it("summarizes transcript", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { title: "Summary", key_points: [] }));
+    const client = new TrawlClient({ apiKey: "test", baseUrl: "http://test" });
+    const result = await client.ai.summarize(1);
+    expect(result.title).toBe("Summary");
+  });
+
+  it("extracts entities", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { entities: { people: [] } }));
+    const client = new TrawlClient({ apiKey: "test", baseUrl: "http://test" });
+    const result = await client.ai.entities(1);
+    expect(result.entities).toBeDefined();
+  });
+
+  it("preview summarizes text", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(200, { title: "Preview" }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    const result = await client.ai.previewSummarize("Some text");
+    expect(result.title).toBe("Preview");
+  });
+});
+
+describe("has all resources", () => {
+  it("exposes all 10 resources", () => {
+    const client = new TrawlClient({ baseUrl: "http://test" });
+    expect(client.transcripts).toBeDefined();
+    expect(client.search).toBeDefined();
+    expect(client.podcasts).toBeDefined();
+    expect(client.jobs).toBeDefined();
+    expect(client.bulk).toBeDefined();
+    expect(client.earnings).toBeDefined();
+    expect(client.filings).toBeDefined();
+    expect(client.news).toBeDefined();
+    expect(client.papers).toBeDefined();
+    expect(client.ai).toBeDefined();
+  });
+});
+
+describe("error handling", () => {
+  it("throws TrawlError on 500", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse(500, { detail: "Server error" }));
+    const client = new TrawlClient({ baseUrl: "http://test" });
+
+    await expect(client.search.youtube("test")).rejects.toThrow(TrawlError);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "declaration": true
+  },
+  "include": ["src/**/*.ts"]
+}