@argosvix/sdk 0.4.15-alpha.0 → 0.4.17-alpha.0

package/README.md

@@ -2,10 +2,10 @@
 
 Transparent observability wrapper for AI provider SDKs. Wrap a single line of code and get cost, latency, token, and error records for every LLM call across OpenAI, Anthropic, Gemini, and Mistral.
 
-> 🟢 **Alpha released** — backend ingest (`ingest.argosvix.com`) and dashboard (`dashboard.argosvix.com`) are live. Published on npm as `@argosvix/sdk@alpha`. We operate as a Free-only plan during the current beta phase; the entire sign-up to API-key flow runs in the browser. See [`CHANGELOG.md`](./CHANGELOG.md) for the full change log.
+> 🟢 **Alpha released** — backend ingest (`ingest.argosvix.com`) and dashboard (`dashboard.argosvix.com`) are live. Published on npm as `@argosvix/sdk@alpha`. The entire sign-up to API-key flow runs in the browser; a Free plan and paid plans (Pro / Team) are available. See [`CHANGELOG.md`](./CHANGELOG.md) for the full change log.
 >
 > Design principles:
-> - **No end-user PII is sent.** Prompt and completion bodies are never recorded; only token counts, cost, latency, and error codes leave your process.
+> - **No end-user PII is sent.** By default, prompt and completion bodies are never recorded; only token counts, cost, latency, and error codes leave your process. Content capture is a separate opt-in (`captureContent`, see below) and always applies PII masking before send.
 > - **Idempotent wrap.** Wrapping the same client twice is a no-op; we track instances via WeakMap / WeakSet.
 > - **No global monkey-patching.** Only the client argument you pass in is mutated; the global namespace is untouched.
 
@@ -31,10 +31,12 @@ npm install @argosvix/sdk@alpha openai
 
 1. Sign up at <https://dashboard.argosvix.com/en/signup> with an email address and password.
 2. Open the verification link sent to your inbox.
-3. The verification screen displays your API key (`argosvix_live_…`) **once**. Copy and store it safely — it cannot be retrieved later (rotation will be available in a future release).
+3. Create an API key from the dashboard's API keys page. The raw key (`argk_…`) is displayed **once** at creation — copy and store it safely. You can create additional keys or revoke a key from the same page at any time.
+
+Alternatively, run `npx @argosvix/cli init` — it opens the browser for a one-time approval, issues a least-privilege key, and writes it to `.env` for you.
 
 ```bash
-export ARGOSVIX_API_KEY=argosvix_live_...
+export ARGOSVIX_API_KEY=argk_...
 # Default ingest endpoint = https://ingest.argosvix.com
 # Override with ARGOSVIX_API_BASE if you self-host the backend.
 ```
@@ -70,7 +72,24 @@ Each call automatically records:
 - Arbitrary tags (`tags: { service: "X", env: "prod" }`).
 - Structured error details (`statusCode`, `code`, `type`, `retryAfter`).
 
-**Not recorded:** prompt bodies, completion bodies, system messages, or tool-call argument bodies. Only the metadata required for aggregation is sent — no PII or confidential strings are stored.
+**Not recorded by default:** prompt bodies, completion bodies, system messages, or tool-call argument bodies. Only the metadata required for aggregation is sent. To record bodies as well, see [Content capture (opt-in)](#content-capture-opt-in) below.
+
+## Content capture (opt-in)
+
+By default only metadata leaves your process. Set `captureContent: true` to also record prompt and completion bodies (and tool-call arguments / results) — useful for quality review, eval datasets, and debugging:
+
+```typescript
+const client = wrap(new OpenAI(), {
+  apiKey: process.env.ARGOSVIX_API_KEY,
+  captureContent: true,
+});
+```
+
+- **Coverage:** non-streaming calls on all four providers — OpenAI (Chat Completions + Responses), Anthropic, Gemini (legacy + current SDK), and Mistral. Streaming calls keep recording metadata as usual, but bodies are not captured.
+- **PII masking before send:** emails, credit-card numbers, phone numbers, IP addresses, etc. are replaced with `[REDACTED_*]` inside your process, before the record leaves it. (`disablePiiRedaction: true` turns the filter off — at your own risk.)
+- **Server-side consent gate:** unless the account is on a paid plan (Pro or higher) **and** plaintext storage has been explicitly enabled in the dashboard settings (consent dialog), the backend discards the bodies. Flipping the SDK flag alone stores nothing.
+
+See <https://argosvix.com/en/docs/sdk-reference> for details.
 
 ## Short-lived runtimes (Cloudflare Workers / AWS Lambda / Vercel Edge)
 
@@ -324,6 +343,37 @@ await withTrace(async () => {
 `withSpan` records the step's latency/status/error automatically. Keep `metadata` to
 non-sensitive structured attributes (counts, sizes) — don't put raw documents or args there.
 
+## Deployed prompts (`resolvePrompt` / `withPrompt`)
+
+If you manage prompts in Argosvix (prompt registry + deployments), `resolvePrompt` fetches the
+currently deployed version of a prompt at runtime, and `withPrompt` tags every wrapped LLM call
+inside it with `prompt: {name}@v{version}` — so quality and cost can be compared per prompt
+version in the dashboard:
+
+```typescript
+import { resolvePrompt, withPrompt } from "@argosvix/sdk";
+
+const p = await resolvePrompt("support-bot", { apiKey: process.env.ARGOSVIX_API_KEY! });
+// p.template = prompt body · p.version = deployed version · p.tag = "support-bot@v3"
+
+await withPrompt(p, async () => {
+  // this call is tagged prompt:support-bot@v3 automatically
+  await client.chat.completions.create({
+    model: "gpt-5.5",
+    messages: [{ role: "system", content: p.template }, { role: "user", content: input }],
+  });
+});
+```
+
+- `resolvePrompt(name, options)` resolves the current version for a deploy label (default
+  `"production"`, override with `options.label`). Results are cached in-memory with a
+  60-second TTL (`cacheTtlMs`, `0` disables), so it is safe on the hot path.
+- Stale fallback: on network errors / timeouts / 5xx an expired cache entry is returned
+  instead of failing, so a transient backend outage doesn't stop your app. With no cached
+  value the error is thrown. 4xx (e.g. a deployment that doesn't exist) always throws.
+- `withPrompt` accepts the `resolvePrompt` result, a `{ name, version }` object, or a raw
+  tag string. An explicit `tags.prompt` on the call wins over the ambient tag.
+
 ## Tags + aggregation
 
 Tags are persisted per record. The backend dashboard supports cross-dimension aggregation such as "cost trend for `service=support-bot`" (Phase C dashboard and beyond).
@@ -468,14 +518,20 @@ Helper for short-lived runtimes (Cloudflare Workers, AWS Lambda, Vercel Edge). A
 
 ### `class Recorder`
 - `record(record: LlmCallRecord): void`
-- `flush(): Promise<LlmCallRecord[]>` — POSTs the buffer to the backend. Retries on 5xx and network errors; 4xx errors are not retried.
+- `flush(): Promise<LlmCallRecord[]>` — POSTs the buffer to the backend. Retries on 5xx and network errors; 4xx errors are not retried. On `429` (monthly ingest quota reached) the SDK logs a warning once per process, so records don't stop silently at the end of the month.
 - `getBufferSize(): number`
 
+### `resolvePrompt(name: string, options: ResolvePromptOptions): Promise<ResolvedPrompt>`
+Fetches the currently deployed version of a registered prompt (60 s TTL cache + stale fallback on backend failure). See "Deployed prompts" above.
+
+### `withPrompt(prompt, fn)`
+Runs `fn` with an ambient prompt tag; every wrapped call inside gets `tags.prompt = "{name}@v{version}"` automatically.
+
 ### `calculateCost(provider, model, promptTokens, completionTokens): number`
 Internal pricing calculator returning USD. Exported for unit tests and custom-pricing experimentation. Resource-prefixed model names (e.g. `models/gemini-2.0-flash`) are looked up by their terminal model name.
 
 ### Types
-`Provider` · `ArgosvixConfig` · `LlmCallRecord` · `PricingEntry`
+`Provider` · `ArgosvixConfig` · `LlmCallRecord` · `PricingEntry` · `ResolvedPrompt` · `ResolvePromptOptions`
 
 ## License
 

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAE,cAAmB,GAAG,CAAC,CAuChF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE1E;AA0eD,0FAA0F;AAC1F,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAqyCD;;;;;;;;;GASG"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAE,cAAmB,GAAG,CAAC,CAyChF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE1E;AA0oBD,0FAA0F;AAC1F,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AA82CD;;;;;;;;;GASG"}