anymous 1.3.0 → 1.3.2

package/skills/claude-api/typescript/claude-api/README.md

@@ -1,405 +0,0 @@
-# Claude API — TypeScript
-
-| Feature | Namespace | Key types / call |
-|---|---|---|
-| User profiles | beta | `client.beta.userProfiles.create(...)` / `.retrieve(id)` / `.list()`. Pass the returned profile id on `client.beta.messages.create`. Requires a beta header — check the SDK's beta-headers reference for the current flag. |
-
-## Installation
-
-```bash
-npm install @anthropic-ai/sdk
-```
-
-> **Reading local files (ESM):** `__dirname` and `__filename` are **undefined** in ES modules — using either throws `ReferenceError: __dirname is not defined` at runtime. For cwd-relative reads, pass the bare relative path (`fs.readFileSync("./sample.png")`). For script-relative paths, derive the directory from `import.meta.url`: `const here = path.dirname(fileURLToPath(import.meta.url))`. Never write `path.join(__dirname, …)` in an ESM `.ts` file.
-
-## Client Initialization
-
-```typescript
-import Anthropic from "@anthropic-ai/sdk";
-
-// Default — resolves credentials from the environment:
-// ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
-// Prefer this for local dev; don't hardcode a key.
-const client = new Anthropic();
-
-// Explicit API key (only when you must inject a specific key)
-const client = new Anthropic({ apiKey: "your-api-key" });
-```
-
----
-
-## Basic Message Request
-
-```typescript
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  messages: [{ role: "user", content: "What is the capital of France?" }],
-});
-// response.content is ContentBlock[] — a discriminated union. Narrow by .type
-// before accessing .text (TypeScript will error on content[0].text without this).
-for (const block of response.content) {
-  if (block.type === "text") {
-    console.log(block.text);
-  }
-}
-```
-
----
-
-## System Prompts
-
-```typescript
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  system:
-    "You are a helpful coding assistant. Always provide examples in Python.",
-  messages: [{ role: "user", content: "How do I read a JSON file?" }],
-});
-```
-
-### Mid-conversation system messages (model-gated)
-
-For operator instructions that arrive mid-conversation (mode switches, injected state), append `{role: "system", ...}` to `messages` instead of editing top-level `system` — this preserves the cached prefix and carries operator authority. Must follow a user message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn; cannot be `messages[0]`. Unsupported models return a 400 (`role 'system' is not supported on this model`). See `shared/prompt-caching.md` for when to use this vs. top-level `system`.
-
-```typescript
-// No beta header needed — use regular client.messages.create.
-const response = await client.messages.create({
-  model: MODEL_ID, // must support mid-conversation system messages
-  max_tokens: 16000,
-  system: [
-    { type: "text", text: STABLE_SYSTEM, cache_control: { type: "ephemeral" } },
-  ],
-  messages: [
-    ...history,
-    { role: "user", content: userMessage },
-    { role: "system", content: "Terse mode enabled — keep responses under 40 words." },
-  ],
-});
-```
-
----
-
-## Vision (Images)
-
-### URL
-
-```typescript
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  messages: [
-    {
-      role: "user",
-      content: [
-        {
-          type: "image",
-          source: { type: "url", url: "https://example.com/image.png" },
-        },
-        { type: "text", text: "Describe this image" },
-      ],
-    },
-  ],
-});
-```
-
-### Base64
-
-```typescript
-import fs from "fs";
-
-const imageData = fs.readFileSync("image.png").toString("base64");
-
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  messages: [
-    {
-      role: "user",
-      content: [
-        {
-          type: "image",
-          source: { type: "base64", media_type: "image/png", data: imageData },
-        },
-        { type: "text", text: "What's in this image?" },
-      ],
-    },
-  ],
-});
-```
-
----
-
-## Prompt Caching
-
-**Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`.
-
-### Automatic Caching (Recommended)
-
-Use top-level `cache_control` to automatically cache the last cacheable block in the request:
-
-```typescript
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block
-  system: "You are an expert on this large document...",
-  messages: [{ role: "user", content: "Summarize the key points" }],
-});
-```
-
-### Manual Cache Control
-
-For fine-grained control, add `cache_control` to specific content blocks:
-
-```typescript
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  system: [
-    {
-      type: "text",
-      text: "You are an expert on this large document...",
-      cache_control: { type: "ephemeral" }, // default TTL is 5 minutes
-    },
-  ],
-  messages: [{ role: "user", content: "Summarize the key points" }],
-});
-
-// With explicit TTL (time-to-live)
-const response2 = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  system: [
-    {
-      type: "text",
-      text: "You are an expert on this large document...",
-      cache_control: { type: "ephemeral", ttl: "1h" }, // 1 hour TTL
-    },
-  ],
-  messages: [{ role: "user", content: "Summarize the key points" }],
-});
-```
-
-### Verifying Cache Hits
-
-```typescript
-console.log(response.usage.cache_creation_input_tokens); // tokens written to cache (~1.25x cost)
-console.log(response.usage.cache_read_input_tokens);     // tokens served from cache (~0.1x cost)
-console.log(response.usage.input_tokens);                // uncached tokens (full cost)
-```
-
-If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `Date.now()` or a UUID in the system prompt, non-deterministic key ordering, or a varying tool set. See `shared/prompt-caching.md` for the full audit table.
-
----
-
-## Extended Thinking
-
-> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
-> **Claude Opus 5:** thinking is on by default — omitting `thinking` runs adaptive (`{ type: "adaptive" }` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{ type: "disabled" }` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
-> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024).
-
-```typescript
-// Fable 5 / Claude Opus 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  thinking: { type: "adaptive", display: "summarized" }, // display opt-in: default is omitted (empty thinking text) on Fable 5 / Mythos 5 / Claude Opus 5 / Opus 4.8 / 4.7
-  output_config: { effort: "high" }, // low | medium | high | xhigh | max
-  messages: [
-    { role: "user", content: "Solve this math problem step by step..." },
-  ],
-});
-
-for (const block of response.content) {
-  if (block.type === "thinking") {
-    console.log("Thinking:", block.thinking);
-  } else if (block.type === "text") {
-    console.log("Response:", block.text);
-  }
-}
-```
-
----
-
-## Error Handling
-
-Use the SDK's typed exception classes — never check error messages with string matching:
-
-```typescript
-import Anthropic from "@anthropic-ai/sdk";
-
-try {
-  const response = await client.messages.create({...});
-} catch (error) {
-  if (error instanceof Anthropic.BadRequestError) {
-    console.error("Bad request:", error.message);
-  } else if (error instanceof Anthropic.AuthenticationError) {
-    console.error("Invalid API key");
-  } else if (error instanceof Anthropic.RateLimitError) {
-    console.error("Rate limited - retry later");
-  } else if (error instanceof Anthropic.APIError) {
-    console.error(`API error ${error.status}:`, error.message);
-  }
-}
-```
-
-All classes extend `Anthropic.APIError` with a typed `status` field. Check from most specific to least specific. See [shared/error-codes.md](../../shared/error-codes.md) for the full error code reference.
-
----
-
-## Multi-Turn Conversations
-
-The API is stateless — send the full conversation history each time. Use `Anthropic.MessageParam[]` to type the messages array:
-
-```typescript
-const messages: Anthropic.MessageParam[] = [
-  { role: "user", content: "My name is Alice." },
-  { role: "assistant", content: "Hello Alice! Nice to meet you." },
-  { role: "user", content: "What's my name?" },
-];
-
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  messages: messages,
-});
-```
-
-**Rules:**
-
-- Consecutive same-role messages are allowed — the API combines them into a single turn
-- First message must be `user`
-- Use SDK types (`Anthropic.MessageParam`, `Anthropic.Message`, `Anthropic.Tool`, etc.) for all API data structures — don't redefine equivalent interfaces
-
----
-
-### Compaction (long conversations)
-
-> **Beta, Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
-
-```typescript
-import Anthropic from "@anthropic-ai/sdk";
-
-const client = new Anthropic();
-const messages: Anthropic.Beta.BetaMessageParam[] = [];
-
-async function chat(userMessage: string): Promise<string> {
-  messages.push({ role: "user", content: userMessage });
-
-  const response = await client.beta.messages.create({
-    betas: ["compact-2026-01-12"],
-    model: "claude-opus-5",
-    max_tokens: 16000,
-    messages,
-    context_management: {
-      edits: [{ type: "compact_20260112" }],
-    },
-  });
-
-  // Append full content — compaction blocks must be preserved
-  messages.push({ role: "assistant", content: response.content });
-
-  const textBlock = response.content.find(
-    (b): b is Anthropic.Beta.BetaTextBlock => b.type === "text",
-  );
-  return textBlock?.text ?? "";
-}
-
-// Compaction triggers automatically when context grows large
-console.log(await chat("Help me build a Python web scraper"));
-console.log(await chat("Add support for JavaScript-rendered pages"));
-console.log(await chat("Now add rate limiting and error handling"));
-```
-
----
-
-## Stop Reasons
-
-The `stop_reason` field in the response indicates why the model stopped generating:
-
-| Value           | Meaning                                                         |
-| --------------- | --------------------------------------------------------------- |
-| `end_turn`      | Claude finished its response naturally                          |
-| `max_tokens`    | Hit the `max_tokens` limit — increase it or use streaming       |
-| `stop_sequence` | Hit a custom stop sequence                                      |
-| `tool_use`      | Claude wants to call a tool — execute it and continue           |
-| `pause_turn`    | Model paused and can be resumed (agentic flows)                 |
-| `refusal`       | Claude refused for safety reasons — check `stop_details`        |
-
-### Structured Stop Details
-
-When `stop_reason` is `"refusal"`, the response includes a `stop_details` object with structured information about the refusal:
-
-```typescript
-if (response.stop_reason === "refusal" && response.stop_details) {
-  console.log(`Category: ${response.stop_details.category}`); // e.g. "cyber", "bio", "reasoning_extraction", "frontier_llm", or null — see docs for the full set
-  console.log(`Explanation: ${response.stop_details.explanation}`);
-}
-```
-
-### Refusal Fallbacks (Claude Fable 5) — opt in by default
-
-Fallbacks are **opt-in**: without them a refused request simply stops. Include the server-side `fallbacks` parameter in `claude-fable-5` code by default — on a policy decline the API re-runs the same request on the fallback model inside the same call. A decline before any output isn't billed (a mid-stream decline bills the streamed partial); the rescue bills at the fallback model's own rates, with cache repricing applied automatically.
-
-```typescript
-const response = await client.beta.messages.create({
-  model: "claude-fable-5",
-  max_tokens: 16000,
-  betas: ["server-side-fallback-2026-06-01"],
-  fallbacks: [{ model: "claude-opus-4-8" }],
-  messages: [{ role: "user", content: "..." }],
-});
-
-// Switch points: one fallback block per model that ran and declined this turn
-for (const block of response.content) {
-  if (block.type === "fallback") {
-    console.log(`${block.from.model} declined; ${block.to.model} continued`);
-  }
-}
-
-// Served-by signal — covers sticky turns, which carry no fallback block.
-// Pair with stop_reason: the fallback model can itself refuse.
-const fallbackRan = (response.usage.iterations ?? []).some(
-  (entry) => entry.type === "fallback_message",
-);
-if (fallbackRan && response.stop_reason !== "refusal") {
-  console.log(`Served by ${response.model}`);
-}
-```
-
-A `stop_reason: "refusal"` on the final response means the whole chain refused. The header must be exactly `server-side-fallback-2026-06-01` **for this array form**; the newer `fallbacks: "default"` scalar form uses `server-side-fallback-2026-07-01` instead (see `shared/model-migration.md` → Migrating to Claude Opus 5 → New API features), and pairing either header with the other form returns a 400. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry — register the client-side `betaRefusalFallbackMiddleware` on the client there instead. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
-
----
-
-## Cost Optimization Strategies
-
-### 1. Use Prompt Caching for Repeated Context
-
-```typescript
-// Automatic caching (simplest — caches the last cacheable block)
-const response = await client.messages.create({
-  model: "claude-opus-5",
-  max_tokens: 16000,
-  cache_control: { type: "ephemeral" },
-  system: largeDocumentText, // e.g., 50KB of context
-  messages: [{ role: "user", content: "Summarize the key points" }],
-});
-
-// First request: full cost
-// Subsequent requests: ~90% cheaper for cached portion
-```
-
-### 2. Use Token Counting Before Requests
-
-```typescript
-const countResponse = await client.messages.countTokens({
-  model: "claude-opus-5",
-  messages: messages,
-  system: system,
-});
-
-const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens
-console.log(`Estimated input cost: $${estimatedInputCost.toFixed(4)}`);
-```

package/skills/claude-api/typescript/claude-api/batches.md

@@ -1,106 +0,0 @@
-# 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-5",
-        max_tokens: 16000,
-        messages: [
-          { role: "user", content: "Summarize climate change impacts" },
-        ],
-      },
-    },
-    {
-      custom_id: "request-2",
-      params: {
-        model: "claude-opus-5",
-        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"
-```

package/skills/claude-api/typescript/claude-api/files-api.md

@@ -1,98 +0,0 @@
-# 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-5",
-  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);
-```