hive-skills 0.1.0

package/assets/skills/converted/claude-api/composable/mini/57-typescript-streaming-batches-files.md

@@ -0,0 +1,384 @@
+# Streaming — TypeScript
+
+## Quick Start
+
+```typescript
+const stream = client.messages.stream({
+  model: "claude-opus-4-8",
+  max_tokens: 64000,
+  messages: [{ role: "user", content: "Write a story" }],
+});
+
+for await (const event of stream) {
+  if (
+    event.type === "content_block_delta" &&
+    event.delta.type === "text_delta"
+  ) {
+    process.stdout.write(event.delta.text);
+  }
+}
+```
+
+---
+
+## Handling Different Content Types
+
+> **Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
+
+```typescript
+const stream = client.messages.stream({
+  model: "claude-opus-4-8",
+  max_tokens: 64000,
+  thinking: { type: "adaptive", display: "summarized" }, // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Opus 4.8 / 4.7
+  messages: [{ role: "user", content: "Analyze this problem" }],
+});
+
+for await (const event of stream) {
+  switch (event.type) {
+    case "content_block_start":
+      switch (event.content_block.type) {
+        case "thinking":
+          console.log("\n[Thinking...]");
+          break;
+        case "text":
+          console.log("\n[Response:]");
+          break;
+      }
+      break;
+    case "content_block_delta":
+      switch (event.delta.type) {
+        case "thinking_delta":
+          process.stdout.write(event.delta.thinking);
+          break;
+        case "text_delta":
+          process.stdout.write(event.delta.text);
+          break;
+      }
+      break;
+  }
+}
+```
+
+---
+
+## Streaming with Tool Use (Tool Runner)
+
+Use the tool runner with `stream: true`. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events:
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
+import { z } from "zod";
+
+const client = new Anthropic();
+
+const getWeather = betaZodTool({
+  name: "get_weather",
+  description: "Get current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("City and state, e.g., San Francisco, CA"),
+  }),
+  run: async ({ location }) => `72°F and sunny in ${location}`,
+});
+
+const runner = client.beta.messages.toolRunner({
+  model: "claude-opus-4-8",
+  max_tokens: 64000,
+  tools: [getWeather],
+  messages: [
+    { role: "user", content: "What's the weather in Paris and London?" },
+  ],
+  stream: true,
+});
+
+// Outer loop: each tool runner iteration
+for await (const messageStream of runner) {
+  // Inner loop: stream events for this iteration
+  for await (const event of messageStream) {
+    switch (event.type) {
+      case "content_block_delta":
+        switch (event.delta.type) {
+          case "text_delta":
+            process.stdout.write(event.delta.text);
+            break;
+          case "input_json_delta":
+            // Tool input being streamed
+            break;
+        }
+        break;
+    }
+  }
+}
+```
+
+---
+
+## Getting the Final Message
+
+```typescript
+const stream = client.messages.stream({
+  model: "claude-opus-4-8",
+  max_tokens: 64000,
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+for await (const event of stream) {
+  // Process events...
+}
+
+const finalMessage = await stream.finalMessage();
+console.log(`Tokens used: ${finalMessage.usage.output_tokens}`);
+```
+
+---
+
+## Stream Event Types
+
+| Event Type            | Description                 | When it fires                     |
+| --------------------- | --------------------------- | --------------------------------- |
+| `message_start`       | Contains message metadata   | Once at the beginning             |
+| `content_block_start` | New content block beginning | When a text/tool_use block starts |
+| `content_block_delta` | Incremental content update  | For each token/chunk              |
+| `content_block_stop`  | Content block complete      | When a block finishes             |
+| `message_delta`       | Message-level updates       | Contains `stop_reason`, usage     |
+| `message_stop`        | Message complete            | Once at the end                   |
+
+## Best Practices
+
+1. **Always flush output** — Use `process.stdout.write()` for immediate display
+2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content
+3. **Track token usage** — The `message_delta` event contains usage information
+4. **Use `finalMessage()`** — Get the complete `Anthropic.Message` object even when streaming. Don't wrap `.on()` events in `new Promise()` — `finalMessage()` handles all completion/error/abort states internally
+5. **Buffer for web UIs** — Consider buffering a few tokens before rendering to avoid excessive DOM updates
+6. **Use `stream.on("text", ...)` for deltas** — The `text` event provides just the delta string, simpler than manually filtering `content_block_delta` events
+7. **For agentic loops with streaming** — See the [Streaming Manual Loop](./tool-use.md#streaming-manual-loop) section in tool-use.md for combining `stream()` + `finalMessage()` with a tool-use loop
+
+## Raw SSE Format
+
+If using raw HTTP (not SDKs), the stream returns Server-Sent Events:
+
+```
+event: message_start
+data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}
+
+event: content_block_start
+data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":0}
+
+event: message_delta
+data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}
+
+event: message_stop
+data: {"type":"message_stop"}
+```
+
+# Message Batches API — TypeScript
+
+The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.
+
+## Key Facts
+
+- Up to 100,000 requests or 256 MB per batch
+- Most batches complete within 1 hour; maximum 24 hours
+- Results available for 29 days after creation
+- 50% cost reduction on all token usage
+- All Messages API features supported (vision, tools, caching, etc.)
+
+---
+
+## Create a Batch
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic();
+
+const messageBatch = await client.messages.batches.create({
+  requests: [
+    {
+      custom_id: "request-1",
+      params: {
+        model: "claude-opus-4-8",
+        max_tokens: 16000,
+        messages: [
+          { role: "user", content: "Summarize climate change impacts" },
+        ],
+      },
+    },
+    {
+      custom_id: "request-2",
+      params: {
+        model: "claude-opus-4-8",
+        max_tokens: 16000,
+        messages: [
+          { role: "user", content: "Explain quantum computing basics" },
+        ],
+      },
+    },
+  ],
+});
+
+console.log(`Batch ID: ${messageBatch.id}`);
+console.log(`Status: ${messageBatch.processing_status}`);
+```
+
+---
+
+## Poll for Completion
+
+```typescript
+let batch;
+while (true) {
+  batch = await client.messages.batches.retrieve(messageBatch.id);
+  if (batch.processing_status === "ended") break;
+  console.log(
+    `Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`,
+  );
+  await new Promise((resolve) => setTimeout(resolve, 60_000));
+}
+
+console.log("Batch complete!");
+console.log(`Succeeded: ${batch.request_counts.succeeded}`);
+console.log(`Errored: ${batch.request_counts.errored}`);
+```
+
+---
+
+## Retrieve Results
+
+```typescript
+for await (const result of await client.messages.batches.results(
+  messageBatch.id,
+)) {
+  switch (result.result.type) {
+    case "succeeded":
+      console.log(
+        `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`,
+      );
+      break;
+    case "errored":
+      if (result.result.error.type === "invalid_request") {
+        console.log(`[${result.custom_id}] Validation error - fix and retry`);
+      } else {
+        console.log(`[${result.custom_id}] Server error - safe to retry`);
+      }
+      break;
+    case "expired":
+      console.log(`[${result.custom_id}] Expired - resubmit`);
+      break;
+  }
+}
+```
+
+---
+
+## Cancel a Batch
+
+```typescript
+const cancelled = await client.messages.batches.cancel(messageBatch.id);
+console.log(`Status: ${cancelled.processing_status}`); // "canceling"
+```
+
+# Files API — TypeScript
+
+The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.
+
+**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).
+
+## Key Facts
+
+- Maximum file size: 500 MB
+- Total storage: 100 GB per organization
+- Files persist until deleted
+- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
+- Not available on Amazon Bedrock or Google Vertex AI
+
+---
+
+## Upload a File
+
+```typescript
+import Anthropic, { toFile } from "@anthropic-ai/sdk";
+import fs from "fs";
+
+const client = new Anthropic();
+
+const uploaded = await client.beta.files.upload({
+  file: await toFile(fs.createReadStream("report.pdf"), undefined, {
+    type: "application/pdf",
+  }),
+  betas: ["files-api-2025-04-14"],
+});
+
+console.log(`File ID: ${uploaded.id}`);
+console.log(`Size: ${uploaded.size_bytes} bytes`);
+```
+
+---
+
+## Use a File in Messages
+
+### PDF / Text Document
+
+```typescript
+const response = await client.beta.messages.create({
+  model: "claude-opus-4-8",
+  max_tokens: 16000,
+  messages: [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "Summarize the key findings in this report." },
+        {
+          type: "document",
+          source: { type: "file", file_id: uploaded.id },
+          title: "Q4 Report",
+          citations: { enabled: true },
+        },
+      ],
+    },
+  ],
+  betas: ["files-api-2025-04-14"],
+});
+
+console.log(response.content[0].text);
+```
+
+---
+
+## Manage Files
+
+### List Files
+
+```typescript
+const files = await client.beta.files.list({
+  betas: ["files-api-2025-04-14"],
+});
+for (const f of files.data) {
+  console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`);
+}
+```
+
+### Delete a File
+
+```typescript
+await client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", {
+  betas: ["files-api-2025-04-14"],
+});
+```
+
+### Download a File
+
+```typescript
+const response = await client.beta.files.download(
+  "file_011CNha8iCJcU1wXNR6q4V8w",
+  { betas: ["files-api-2025-04-14"] },
+);
+const content = Buffer.from(await response.arrayBuffer());
+await fs.promises.writeFile("output.txt", content);
+```