@scope-analytics/node 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# @scope-analytics/node — Scope Node.js backend SDK
+
+Zero-code analytics for AI products. Captures your server-side LLM calls (and ships them to
+Scope as universal events) by **wrapping OpenTelemetry + Arize OpenInference** rather than
+reinventing provider patching. Wire-compatible with the Python SDK (`scope_analytics`) — both
+emit the same universal event schema, so one Scope project can mix Python and Node services.
+
+> **Status: in development — not yet published to npm.** Auto-captures **four providers** today:
+> **OpenAI** + **Anthropic** (Arize OpenInference drop-ins), **Google Gemini** (`@google/genai`, a
+> Scope-authored instrumentation — no drop-in exists), and the **Vercel AI SDK** (`ai`, zero-code — Scope
+> auto-enables its telemetry and translates the native spans; see "Supported providers"). Also shipped: the
+> OpenTelemetry → Scope exporter (handles chat-completions, the Responses API, and multimodal content
+> shapes), the `--import` bootstrap, config + deploy/`git_sha` resolution, `AsyncLocalStorage`
+> session/user/thread/url context, raw-by-default capture with an opt-in credential scrub (Python
+> parity), and live call-and-capture + version-pin tests per provider, plus dual ESM+CJS builds.
+> **Coming next:** framework middleware (Express/Fastify/Hono/Nest/Next route handlers), the
+> Edge-runtime manual wrapper, an `identify()` helper, per-field size caps, and npm publish.
+
+## Install
+
+```bash
+npm install @scope-analytics/node
+```
+
+Set your project **secret** key (from the Scope dashboard) in the environment:
+
+```bash
+export SCOPE_API_KEY="sk_live_…"   # or sk_test_…
+```
+
+## Use it (two paths, both zero app-code for capture)
+
+### 1. Zero-code bootstrap (recommended)
+
+Start your server with the tracer pre-loaded — no code change, just a flag. The bootstrap must
+load before your app imports `openai`, which `--import` guarantees:
+
+```bash
+NODE_OPTIONS="--import @scope-analytics/node/register" node server.js
+```
+
+### 2. Explicit init
+
+Call `init()` once at the very top of your entrypoint, **before** importing `openai`:
+
+```ts
+import { init } from '@scope-analytics/node';
+init(); // reads SCOPE_API_KEY / SCOPE_ENDPOINT from the env (or pass { apiKey, endpoint })
+
+import OpenAI from 'openai';
+// …every OpenAI call from here on is captured and shipped to Scope.
+```
+
+## Session stitching (optional, recommended)
+
+Wrap each request so the LLM calls inside it are attributed to a user/session — this is what
+lets Scope stitch a user's activity across your frontend, backend, and LLM layers:
+
+```ts
+import { runWithContext } from '@scope-analytics/node';
+
+app.use((req, res, next) => {
+  runWithContext({ sessionId: req.headers['x-scope-session-id'], userId: req.user?.id }, next);
+});
+```
+
+Without it, backend LLM calls get a `temp_…` session (captured, but not tied to a user).
+
+## Supported providers
+
+Auto-captured with no app-code change: **OpenAI** (`openai`), **Anthropic** (`@anthropic-ai/sdk`), and
+**Google Gemini** (`@google/genai`) — plus the entire **OpenAI-compatible ecosystem** (Groq, Together,
+OpenRouter, DeepSeek, xAI, Azure OpenAI, Ollama, vLLM, …) reached through the `openai` SDK with a custom
+`base_url`, captured at the call site so the base URL is irrelevant.
+
+**Vercel AI SDK (`ai`)** is also captured, **zero-code** — `generateText`, `streamText`, `generateObject`,
+`streamObject`. The AI SDK emits telemetry only when it's enabled per call, so `@scope-analytics/node` enables it
+for you: it injects `experimental_telemetry: { isEnabled: true }` into those calls, **deep-merged** with any
+telemetry config you already pass (your `functionId`/`metadata`/`recordInputs`/… are preserved). To opt a
+specific call out, set `experimental_telemetry: { isEnabled: false }` yourself — that's respected. If you
+pass your **own** `tracer` in `experimental_telemetry`, those spans go to your tracer rather than Scope.
+
+### Module systems (CommonJS & ESM)
+
+Auto-capture hooks your module loader, so it must be in place before your app imports its LLM SDKs — which
+is exactly what the `--import @scope-analytics/node/register` bootstrap guarantees (it also registers the ESM loader
+needed to instrument `import`s). **On that bootstrap, all four providers are captured under both CommonJS
+and ESM.** The explicit `init()` path covers CommonJS (where you control `require` order); for ESM, use the
+bootstrap, since `import`s are hoisted and a loader can't retroactively hook modules already imported.
+
+## Privacy
+
+**Raw by default** (full-fidelity capture). Opt in to a best-effort credential scrub with
+`init({ redactPatterns: CREDENTIAL_REDACT_PATTERNS })` (exported from this package) — it keeps the key and
+drops the value over `key=value` free text in prompts/responses/messages. Not a structural guarantee.
+
+## Configuration
+
+| Option (`init({…})`) | Env var | Default | Notes |
+|---|---|---|---|
+| `apiKey` | `SCOPE_API_KEY` | — (required) | Project **secret** key (`sk_live_…`/`sk_test_…`). A public `pk_…` key is rejected. |
+| `endpoint` | `SCOPE_ENDPOINT` | `https://api.scopeai.dev` | Scope ingest base URL. |
+| `environment` | `SCOPE_ENVIRONMENT` | `production` | Tag on every event. |
+| `debug` | `SCOPE_DEBUG` | `false` | Verbose logging. |
+| `serviceName` | `SCOPE_SERVICE_NAME` | `scope-app` | OTel `service.name`. |
+
+Deploy metadata (`git_sha`, `deployment_id`) is read once at startup from your platform's commit
+env var (Railway / Vercel / Render / Heroku / Cloud Run / Lambda / `GIT_COMMIT_SHA`) and stamped
+on every event — so the analyst can reason about "what changed before the drop?". Nothing is
+invented when no env var is present (honest non-coverage).
+
+## Design
+
+`@scope-analytics/node` is a thin Scope layer over OpenTelemetry:
+
+- Provider instrumentations produce OpenInference GenAI spans — Arize drop-ins for OpenAI/Anthropic, a
+  Scope-authored instrumentation for `@google/genai`, and the `@arizeai/openinference-vercel` span
+  processor that translates the Vercel AI SDK's native spans into the same shape.
+- `ScopeSpanExporter` translates each LLM span into a Scope universal event and POSTs
+  `{ events, source: "backend_sdk" }` to `${endpoint}/api/events` with `Authorization: Bearer <secret>`.
+- Telemetry is best-effort and **never throws** — a Scope outage can't crash or slow your app.
+
+## Development
+
+```bash
+npm install
+npm test       # vitest (unit + a real-use pipeline → local HTTP collector)
+npm run build  # tsup → dual ESM + CJS + .d.ts
+```