# segi · Error monitoring · LLM integration guide
This file is written for AI coding agents. It gives the smallest set of steps
that get the segi error SDK wired into a project. Each section is independent —
pick the one that matches the user's stack.
## TL;DR
1. User creates a project at https://segi.extn.ai and copies a key like
`segi_pk_live_…`.
2. Install the SDK for the stack (`@extn/segi-js`, `@extn/segi-nextjs`, or
`@extn/segi-nestjs`).
3. Call `Segi.init({ projectKey, endpoint: "https://segiapi.extn.ai" })` (or
the framework-specific wrapper). For NestJS also register the global
exception filter.
4. Verify: throw a test error, see it group into an Issue in the dashboard.
## Ingest endpoint
- `POST https://segiapi.extn.ai/api/ingest/events`
- Header: `X-Segi-Project-Key: segi_pk_live_…` (or `?pk=` for sendBeacon paths)
- Origin allow-list lives on each project key — set it for browser keys.
- Per-project rate limit (default 600/min) plus a plan-level monthly cap
(Free 1,000 / Team 10,000 / Enterprise 10M soft).
- Over-cap response: `429 { error: "quota_exceeded", metric, limit, used,
resetsAt, upgradeUrl }`. The SDK does not retry these.
- Success response: `202 { ok: true, accepted: true }`.
## Browser (npm)
```ts
import Segi from "@extn/segi-js";
Segi.init({
projectKey: "segi_pk_live_...",
endpoint: "https://segiapi.extn.ai",
environment: "production", // optional
release: "v2.14.3", // optional
});
// Auto-captures window.onerror + unhandledrejection.
// Manual:
Segi.captureException(new Error("boom"));
Segi.captureMessage("checkout finished", { level: "info" });
Segi.setUser({ id: "u_123", email: "alice@example.com" });
Segi.addBreadcrumb({ type: "click", message: "cart-add" });
```
## Plain HTML / CDN (no bundler)
```html
```
Note: the CDN bundle does NOT include the session-recording submodule. Use npm
if recording is needed.
## Next.js
Client side (`app/segi-init.tsx`, marked `"use client"`):
```ts
"use client";
import { initSegiClient } from "@extn/segi-nextjs/client";
initSegiClient({
publicKey: process.env.NEXT_PUBLIC_SEGI_KEY!,
environment: process.env.NEXT_PUBLIC_VERCEL_ENV ?? "development",
release: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
});
export default function SegiInit() { return null; }
```
Mount once in root `layout.tsx`:
```tsx
import SegiInit from "./segi-init";
// inside :
```
Server side (`instrumentation.ts`):
```ts
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
const { initSegiServer } = await import("@extn/segi-nextjs");
initSegiServer({
publicKey: process.env.SEGI_KEY!,
environment: process.env.NODE_ENV,
});
}
}
```
MCP: `claude mcp add segi-nextjs -- npx -y @extn/segi-mcp-nextjs`. Tools:
`get_install_command`, `get_required_env_vars`, `get_setup_files`,
`get_test_snippets`.
## NestJS
`src/app.module.ts`:
```ts
import { SegiModule } from "@extn/segi-nestjs";
@Module({
imports: [
SegiModule.forRoot({
publicKey: process.env.SEGI_KEY!,
environment: process.env.NODE_ENV,
release: process.env.GIT_SHA,
}),
],
})
export class AppModule {}
```
`src/main.ts`:
```ts
import { SegiExceptionFilter } from "@extn/segi-nestjs";
const app = await NestFactory.create(AppModule);
app.useGlobalFilters(new SegiExceptionFilter());
await app.listen(3000);
```
Inject `SegiService` to call `captureException(error, context?)` or
`captureMessage(message, context?)` manually.
MCP: `claude mcp add segi-nestjs -- npx -y @extn/segi-mcp-nestjs`.
## Scrubbing / PII
- Server scrubs known sensitive header values (`authorization`, `cookie`,
`x-api-key`, etc.) and field names matching `password`, `pwd`, `secret`,
`token`, `card_number` from event payloads before persistence.
- Browser SDK never serializes input element values from form events.
- For per-event masking, use the `beforeSend(event)` hook in `Segi.init` —
return `null` to drop the event, or mutate fields in place.
## Common errors
- `401 Invalid project key` — key missing/revoked or wrong env.
- `403 Origin not allowed` — browser request origin not in the key's allow-list.
- `429 Too many requests` — per-minute rate limit hit (not the plan quota).
- `429 quota_exceeded` — monthly plan quota hit. Body has `limit`, `used`,
`resetsAt`, `upgradeUrl`. Do not retry — events for the rest of the period
are dropped until reset or plan upgrade.
## Verifying ingestion
```bash
curl -X POST https://segiapi.extn.ai/api/ingest/events \
-H "Content-Type: application/json" \
-H "X-Segi-Project-Key: segi_pk_live_..." \
-d '{"type":"error","level":"error","message":"smoke test"}'
# expect: 202 {"ok":true,"accepted":true}
```
Then visit Project → Issues; the test event should appear within a few seconds.