tako-sdk 0.1.4 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tako
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,121 +1,136 @@
-# Tako SDK
+# Tako TypeScript SDK
 
-A lightweight TypeScript SDK for the [Tako API](https://trytako.com).
+The Tako SDK provides typed access to the [Tako](https://tako.com) API from Node.js (≥ 18), the browser, and edge runtimes. It ships fully typed request/response models, a `Tako` client, and a live agent-streaming API. Generated from Tako's OpenAPI spec with `openapi-generator` (`typescript-fetch`) — zero runtime dependencies.
 
 ## Installation
 
 ```bash
 npm install tako-sdk
-# or
-yarn add tako-sdk
-# or
-pnpm add tako-sdk
 ```
 
-## Quick Start
+## Authentication
 
-```typescript
-import { createTakoClient } from 'tako-sdk';
+Create an API key from your Tako account and keep it out of source control:
 
-// Initialize the client
-const tako = createTakoClient(process.env.TAKO_API_KEY!);
+```typescript
+import { Tako } from "tako-sdk";
 
-// Search Tako Knowledge
-const results = await tako.knowledgeSearch('AMD vs. Nvidia headcount since 2015');
-console.log(results.outputs.knowledge_cards);
+const tako = new Tako({ apiKey: process.env.TAKO_API_KEY! });
 ```
 
-### Usage Example: Next.js API Route (App Router)
+## Usage
 
 ```typescript
-// app/api/tako-search/route.ts
-import { createTakoClient } from 'tako-sdk';
-import { NextResponse } from 'next/server';
-
-export async function POST(request: Request) {
-  const { query, sourceIndexes } = await request.json();
-  const tako = createTakoClient(process.env.TAKO_API_KEY!);
-  
-  try {
-    const results = await tako.knowledgeSearch(query, sourceIndexes);
-    return NextResponse.json(results);
-  } catch (error: any) {
-    return NextResponse.json(
-      { error: error.message || 'An error occurred' },
-      { status: error.status || 500 }
-    );
-  }
+const results = await tako.search({ query: "S&P 500 performance this year" });
+console.log(results.request_id);
+for (const card of results.cards ?? []) {
+  console.log(card.title, card.webpage_url);
 }
 ```
 
-## API Reference
+### Operations
 
-### `createTakoClient(apiKey)`
+| Method                     | Description                                                             |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `tako.search(request)`     | Search the Tako knowledge base; returns matching cards and web results. |
+| `tako.answer(request)`     | Get a written answer with supporting cards.                             |
+| `tako.createCard(request)` | Build a visualization card from component configurations.               |
+| `tako.contents(request)`   | Fetch downloadable content (e.g. a CSV) for a card or web URL.          |
 
-Creates a new Tako API client.
+Fetch the underlying data for a card returned by a search (guard for cards with no exportable `content`):
 
 ```typescript
-const tako = createTakoClient('your-api-key');
+const results = await tako.search({ query: "US Oil Prices" });
+const card = (results.cards ?? []).find((c) => c.webpage_url && c.content);
+if (card?.webpage_url) {
+  const contents = await tako.contents({ url: card.webpage_url });
+  for (const item of contents.contents ?? []) console.log(item.format, item.url); // url is populated only in URL delivery mode (url?: string | null)
+}
 ```
 
-Parameters:
-- `apiKey` (string): Your Tako API key
+> **Async only.** JavaScript is uniformly promise-based, so there is a single `Tako` client (unlike the Python SDK's separate `Tako`/`AsyncTako`). Every operation returns a `Promise`.
 
-### `takoClient.knowledgeSearch(text, sourceIndexes?)`
+## Streaming
 
-Search Tako Knowledge using natural language.
+Stream an agent run live over Server-Sent Events. The stream yields typed `AgentStreamEnvelope` objects and auto-reconnects (resuming via the last `seq`) on transient drops. Always close it (or use `try`/`finally`):
 
 ```typescript
-const results = await tako.knowledgeSearch('AMD vs. Nvidia headcount since 2015');
+const stream = tako.agent.stream({ query: "Compare Nvidia and AMD revenue" });
+try {
+  for await (const event of stream) {
+    console.log(event.seq, event.block.kind);
+  }
+  // The stream ends at stream_done. If it ended without a terminal result
+  // (and produced at least one event, so run_id is known), poll for status:
+  if (stream.result === null && stream.run_id !== null) {
+    const run = await tako.agent.get(stream.run_id);
+    console.log(run.status);
+  }
+} finally {
+  await stream.close();
+}
 ```
 
-Parameters:
-- `text` (string): The natural language query text
-- `sourceIndexes` (SourceIndex[], optional): Array of source indexes to search within. Available values: `SourceIndex.TAKO` or `SourceIndex.WEB`
+Tune reconnect behavior with the second argument — `maxRetries` (reconnect attempts after a transient drop, default 5) and `readTimeoutMs` (idle read before a connection is treated as dropped, default 120000):
 
-Returns: `Promise<KnowledgeSearchResponse>`
+```typescript
+const stream = tako.agent.stream({ query: "..." }, { maxRetries: 5, readTimeoutMs: 120_000 });
+```
 
-The response contains an array of knowledge cards in the `outputs.knowledge_cards` field. Each knowledge card contains:
-- `card_id`: Unique identifier for the card
-- `title`: Card title
-- `description`: Detailed description of the card's content
-- `webpage_url`: URL of a webpage hosting the interactive knowledge card
-- `image_url`: URL of a static image of the knowledge card
-- `embed_url`: URL of an embeddable iframe of the knowledge card
-- `sources`: The sources of the knowledge card
-- `methodologies`: The methodologies of the knowledge card
+Non-streaming dispatch/poll is also available: `tako.agent.run(request)` returns an `AgentRun` (202 dispatch); `tako.agent.get(runId)` polls for status.
 
-For detailed API response types and subfield structure, see the [Tako API Documentation](https://docs.trytako.com/api-reference/search).
+## Configuration
 
-## Error Handling
+By default the client targets the Tako production API (`https://tako.com/api`). Override the base path for staging or self-host:
 
-The SDK throws typed exceptions for different errors:
+```typescript
+const tako = new Tako({ apiKey: "...", basePath: "https://staging.tako.com/api" });
+```
+
+## Error handling
+
+Non-2xx responses throw a `ResponseError` carrying the raw `Response`:
 
 ```typescript
-import { 
-  TakoException,
-  TakoUnauthorizedException,
-  TakoRateLimitException,
-} from 'tako-sdk';
+import { ResponseError } from "tako-sdk";
 
 try {
-  const results = await tako.knowledgeSearch(query);
-} catch (error) {
-  if (error instanceof TakoUnauthorizedException) {
-    console.error('Authentication error:', error.message);
-  } else if (error instanceof TakoRateLimitException) {
-    console.error('Rate limit exceeded:', error.message);
-  } else if (error instanceof TakoNotFoundException) {
-    console.error('Resource not found:', error.message);
-  } else if (error instanceof TakoException) {
-    console.error('API error:', error.message);
+  await tako.search({ query: "..." });
+} catch (err) {
+  if (err instanceof ResponseError) {
+    console.error(err.response.status, await err.response.text());
   } else {
-    console.error('Unexpected error:', error);
+    throw err;
   }
 }
 ```
 
-Each exception includes:
-- `status`: HTTP status code
-- `message`: Error message
-- `details`: Additional error details from the API (if available)
+## TypeScript
+
+All request/response models are exported as types:
+
+```typescript
+import type {
+  SearchRequest,
+  SearchResponse, // .cards is Array<TakoCard>
+  AnswerResponse, // .cards is Array<TakoCard>
+  ContentsRequest,
+  ContentsResponse,
+  CreateCardRequest,
+  TakoCard, // card type returned by search() and answer()
+  KnowledgeCard, // card type returned by createCard()
+  AgentRunRequest,
+  AgentStreamEnvelope,
+} from "tako-sdk";
+```
+
+`search` and `answer` return `TakoCard[]` via `SearchResponse.cards` / `AnswerResponse.cards`. `createCard` returns a `KnowledgeCard`.
+
+## License
+
+MIT
+
+## Links
+
+- [Tako documentation](https://docs.tako.com)
+- [GitHub repository](https://github.com/TakoData/tako-sdk-ts)