@rawdash/connector-anthropic 0.0.1

package/README.md

@@ -0,0 +1,143 @@
+<!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
+
+# @rawdash/connector-anthropic
+
+[![npm version](https://img.shields.io/npm/v/@rawdash/connector-anthropic)](https://www.npmjs.com/package/@rawdash/connector-anthropic)
+[![license](https://img.shields.io/npm/l/@rawdash/connector-anthropic)](https://github.com/rawdash/rawdash/blob/main/LICENSE)
+
+Track Anthropic spend, daily token usage across Claude models, cache hit volumes, and web-search tool requests from the Anthropic Admin API.
+
+## Install
+
+```sh
+npm install @rawdash/connector-anthropic
+```
+
+## Authentication
+
+Authenticates with an Anthropic organization admin API key (sk-ant-admin-). Admin keys are the only key class that can read the Usage and Cost reports; regular API keys return 403.
+
+1. Open console.anthropic.com -> Settings -> Admin Keys and create a new admin key. Admin keys are organization-scoped, so create the key from the organization whose usage you want to read.
+2. Store the key as a secret (e.g. ANTHROPIC_ADMIN_API_KEY).
+3. Reference it from config as `adminApiKey: secret("ANTHROPIC_ADMIN_API_KEY")`.
+4. Optionally set `workspaceIds` to restrict the query to a subset of workspaces.
+
+## Configuration
+
+| Field          | Type   | Required | Description                                                                                                                                                                                                    |
+| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `adminApiKey`  | secret | Yes      | Anthropic organization admin API key (starts with sk-ant-admin-). Create one at console.anthropic.com -> Settings -> Admin keys. Regular API keys (sk-ant-api-) cannot read the Usage and Cost reports.        |
+| `workspaceIds` | array  | No       | Restrict usage and cost queries to specific Anthropic workspace ids (wrkspc\_...). Omit to aggregate every workspace the admin key can see.                                                                    |
+| `resources`    | array  | No       | Which Anthropic metric series to sync. Omit to sync all of them. The five usage metrics share one upstream call to the Messages Usage Report; enabling any one of them fetches the report and writes all five. |
+| `lookbackDays` | number | No       | How many days of usage history to fetch on a full sync. Defaults to 30. The Usage Report returns at most 31 buckets per page, so longer windows paginate.                                                      |
+
+## Resources
+
+- **`anthropic_input_tokens`** _(metric)_ - Daily uncached input tokens processed by the Anthropic Messages API, grouped by model and workspace.
+  - Endpoint: `GET /v1/organizations/usage_report/messages`
+  - Unit: tokens
+  - Granularity: daily
+  - Dimensions: `model`, `workspace_id`, `api_key_id`, `service_tier`, `context_window`, `inference_geo`
+  - Sample value is uncached_input_tokens. Cache-read and cache-creation token volumes are mirrored on their own metrics so a cache hit ratio can be computed at query time.
+- **`anthropic_output_tokens`** _(metric)_ - Daily output tokens generated by the Anthropic Messages API, grouped by model and workspace.
+  - Endpoint: `GET /v1/organizations/usage_report/messages`
+  - Unit: tokens
+  - Granularity: daily
+  - Dimensions: `model`, `workspace_id`, `api_key_id`, `service_tier`, `context_window`, `inference_geo`
+  - Written alongside anthropic_input_tokens from the same usage_messages API call.
+- **`anthropic_cache_read_tokens`** _(metric)_ - Daily input tokens read from the prompt cache, grouped by model and workspace.
+  - Endpoint: `GET /v1/organizations/usage_report/messages`
+  - Unit: tokens
+  - Granularity: daily
+  - Dimensions: `model`, `workspace_id`, `api_key_id`, `service_tier`, `context_window`, `inference_geo`
+  - Cache hits are charged at a fraction of the uncached rate, so this metric paired with anthropic_input_tokens gives the cache hit ratio.
+- **`anthropic_cache_creation_tokens`** _(metric)_ - Daily input tokens written into the prompt cache (sum of the 1h and 5m ephemeral caches), grouped by model and workspace.
+  - Endpoint: `GET /v1/organizations/usage_report/messages`
+  - Unit: tokens
+  - Granularity: daily
+  - Dimensions: `model`, `workspace_id`, `api_key_id`, `service_tier`, `context_window`, `inference_geo`
+  - The per-cache-bucket counts (ephemeral_1h_input_tokens, ephemeral_5m_input_tokens) are mirrored in attributes for finer-grained widgets.
+- **`anthropic_web_search_requests`** _(metric)_ - Daily count of web-search tool requests executed server-side by Claude, grouped by model and workspace.
+  - Endpoint: `GET /v1/organizations/usage_report/messages`
+  - Unit: requests
+  - Granularity: daily
+  - Dimensions: `model`, `workspace_id`, `api_key_id`, `service_tier`, `context_window`, `inference_geo`
+  - Sourced from server_tool_use.web_search_requests on each usage bucket. Zero rows are still written so a "no usage today" widget renders correctly.
+- **`anthropic_cost_usd`** _(metric)_ - Daily organization spend in USD, broken down by workspace and cost line item, pulled from the Anthropic Cost Report.
+  - Endpoint: `GET /v1/organizations/cost_report`
+  - Unit: USD
+  - Granularity: daily
+  - Dimensions: `workspace_id`, `description`, `cost_type`, `model`, `token_type`, `service_tier`, `context_window`, `currency`
+  - The Cost Report returns amounts as a decimal string in the lowest currency unit (cents for USD). The connector divides by 100 so the stored metric value is dollars. Costs can be revised for a couple of days after the fact; incremental syncs refetch a short trailing window to pick up adjustments.
+
+## Example
+
+```ts
+import {
+  defineConfig,
+  defineDashboard,
+  defineMetric,
+  secret,
+} from '@rawdash/core';
+
+const anthropic = {
+  name: 'anthropic',
+  connectorId: 'anthropic',
+  config: {
+    adminApiKey: secret('ANTHROPIC_ADMIN_API_KEY'),
+  },
+};
+
+export default defineConfig({
+  connectors: [anthropic],
+  dashboards: {
+    ai: defineDashboard({
+      widgets: {
+        spend_mtd: {
+          kind: 'stat',
+          title: 'Anthropic spend (last 30d)',
+          window: '30d',
+          metric: defineMetric({
+            connector: anthropic,
+            shape: 'metric',
+            name: 'anthropic_cost_usd',
+            fn: 'sum',
+          }),
+        },
+        input_tokens_today: {
+          kind: 'stat',
+          title: 'Input tokens today',
+          window: '1d',
+          metric: defineMetric({
+            connector: anthropic,
+            shape: 'metric',
+            name: 'anthropic_input_tokens',
+            fn: 'sum',
+          }),
+        },
+      },
+    }),
+  },
+});
+```
+
+## Rate limits
+
+The Admin API returns 429 with a Retry-After header on burst; the shared HTTP client honors it automatically. Daily syncs against the Usage and Cost reports are well below the per-organization Admin API budget.
+
+## Limitations
+
+- Only the organization Messages Usage Report and Cost Report endpoints are synced. Per-request logs and individual message bodies are not exposed by the Admin API.
+- All samples are bucketed daily (1d bucket_width). The Usage Report also supports hourly and per-minute granularity but those are not exposed here in v1.
+- The Cost Report only supports 1d bucket_width and reports cost in USD; non-USD billing currencies are not converted.
+- Admin API keys are required - regular sk-ant-api- keys do not have access to the organization Usage and Cost reports.
+
+## Links
+
+- [Rawdash docs](https://rawdash.dev/docs/connectors/)
+- [Anthropic API docs](https://docs.claude.com/en/api/admin-api/usage-cost/get-messages-usage-report)
+- [GitHub](https://github.com/rawdash/rawdash)
+
+## License
+
+Apache-2.0