@sentro/sdk 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,126 @@
+# @sentro/sdk
+
+**Error tracking and agent observability for AI agents.** TypeScript SDK for [Sentro](https://github.com/yzzztech/sentro).
+
+Sentro is an open-source Sentry alternative built specifically for AI agents. This SDK gives you full observability into every run, step, tool call, and LLM call your agents make — plus traditional error tracking.
+
+## Install
+
+```bash
+npm install @sentro/sdk
+```
+
+## Quick Start
+
+### Error tracking
+
+```typescript
+import { Sentro } from '@sentro/sdk';
+
+const sentro = new Sentro({ dsn: 'http://token@localhost:3000/api/ingest/proj_1' });
+
+sentro.captureException(new Error('Payment failed'));
+```
+
+### Agent observability
+
+```typescript
+const result = await sentro.trace('order-processor', {
+  goal: 'Process refund for order #456',
+  model: 'claude-sonnet-4-6',
+}, async (run) => {
+
+  return await run.trace('Looking up order', async (step) => {
+    // Track tool calls
+    const order = await step.traceToolCall('database.query',
+      { sql: 'SELECT * FROM orders WHERE id = 456' },
+      async () => db.query('SELECT * FROM orders WHERE id = 456')
+    );
+
+    // Track LLM calls
+    const llm = step.llmCall({ model: 'claude-sonnet-4-6' });
+    const decision = await callLLM('Should we approve this refund?');
+    llm.end({ promptTokens: 150, completionTokens: 20, cost: 0.001 });
+
+    return decision;
+  });
+});
+// Automatically captures: duration, tokens, cost, success/failure
+```
+
+### Explicit API
+
+For more control, use the explicit start/end API:
+
+```typescript
+const run = sentro.startRun({
+  agent: 'research-agent',
+  goal: 'Find recent papers',
+  model: 'gpt-4o',
+  trigger: 'api',
+});
+
+try {
+  const step = run.step('Search for papers');
+  const llm = step.llmCall({ model: 'gpt-4o', provider: 'openai' });
+  const res = await openai.chat.completions.create({ ... });
+  await llm.end({
+    promptTokens: res.usage?.prompt_tokens,
+    completionTokens: res.usage?.completion_tokens,
+  });
+  await step.end();
+  await run.end({ status: 'success' });
+} catch (err) {
+  await run.error(err instanceof Error ? err : new Error(String(err)));
+  throw err;
+}
+```
+
+## Configuration
+
+```typescript
+const sentro = new Sentro({
+  dsn: 'http://token@localhost:3000/api/ingest/proj_1',
+  capturePrompts: false,      // set true to store prompt/response bodies
+  flushIntervalMs: 1000,      // batch send every 1s
+  maxBatchSize: 100,           // flush when buffer hits 100
+  defaultTags: {
+    env: 'production',
+    version: '1.0.0',
+  },
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dsn` | string | required | Full DSN URL from your project settings |
+| `capturePrompts` | boolean | `false` | Store prompt/response bodies verbatim |
+| `flushIntervalMs` | number | `1000` | How often (ms) to flush the buffer |
+| `maxBatchSize` | number | `100` | Max events per batch before immediate flush |
+| `defaultTags` | Record\<string, string\> | — | Tags merged into every event |
+
+## Security Considerations
+
+- Set `capturePrompts: false` (the default) to avoid storing LLM prompt/response bodies that may contain PII
+- DSN tokens are API keys — treat them like passwords, don't commit them to source control
+- Tool call inputs/outputs are stored as-is — avoid passing sensitive data (API keys, passwords) through traced tool calls
+
+## Graceful Shutdown
+
+```typescript
+// Before process exit
+await sentro.shutdown();
+
+// In serverless environments
+await sentro.flush();
+```
+
+## Links
+
+- **GitHub:** [github.com/yzzztech/sentro](https://github.com/yzzztech/sentro)
+- **Docs:** Available at `/docs` when running Sentro
+- **Python SDK:** `pip install sentro-sdk`
+
+## License
+
+MIT

package/dist/integrations/vercel-ai.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Sentro integration for Vercel AI SDK.
+ *
+ * Usage:
+ *   import { Sentro } from '@sentro/sdk';
+ *   import { sentroMiddleware } from '@sentro/sdk/vercel-ai';
+ *
+ *   const sentro = new Sentro({ dsn: '...' });
+ *
+ *   const result = await generateText({
+ *     model: openai('gpt-4o'),
+ *     prompt: 'Hello!',
+ *     experimental_telemetry: sentroMiddleware(sentro),
+ *   });
+ */
+import type { Sentro } from '../client';
+interface TelemetrySettings {
+    isEnabled: boolean;
+    functionId?: string;
+    metadata?: Record<string, string>;
+    tracer?: {
+        startSpan: (name: string, options?: Record<string, unknown>) => Span;
+    };
+}
+interface Span {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    end(): void;
+}
+interface SentroMiddlewareOptions {
+    agentName?: string;
+}
+export declare function sentroMiddleware(client: Sentro, options?: SentroMiddlewareOptions): TelemetrySettings;
+export {};
+//# sourceMappingURL=vercel-ai.d.ts.map

package/dist/integrations/vercel-ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-ai.d.ts","sourceRoot":"","sources":["../../src/integrations/vercel-ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,UAAU,iBAAiB;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE;QACP,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KACtE,CAAC;CACH;AAED,UAAU,IAAI;IACZ,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,GAAG,IAAI,IAAI,CAAC;CACb;AAED,UAAU,uBAAuB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,iBAAiB,CAoDnB"}

package/dist/integrations/vercel-ai.js

@@ -0,0 +1,62 @@
+/**
+ * Sentro integration for Vercel AI SDK.
+ *
+ * Usage:
+ *   import { Sentro } from '@sentro/sdk';
+ *   import { sentroMiddleware } from '@sentro/sdk/vercel-ai';
+ *
+ *   const sentro = new Sentro({ dsn: '...' });
+ *
+ *   const result = await generateText({
+ *     model: openai('gpt-4o'),
+ *     prompt: 'Hello!',
+ *     experimental_telemetry: sentroMiddleware(sentro),
+ *   });
+ */
+export function sentroMiddleware(client, options = {}) {
+    const agentName = options.agentName ?? 'vercel-ai-agent';
+    return {
+        isEnabled: true,
+        functionId: agentName,
+        tracer: {
+            startSpan(name, spanOptions) {
+                const attributes = {};
+                const span = {
+                    setAttribute(key, value) {
+                        attributes[key] = String(value);
+                        // Capture LLM call data when available
+                        if (key === 'ai.model.id') {
+                            const step = client._currentStep;
+                            if (step) {
+                                const llm = step.llmCall({ model: String(value) });
+                                span._llmCall = llm;
+                            }
+                        }
+                        if (key === 'ai.usage.promptTokens' && span._llmCall) {
+                            span._promptTokens = Number(value);
+                        }
+                        if (key === 'ai.usage.completionTokens' && span._llmCall) {
+                            span._completionTokens = Number(value);
+                        }
+                    },
+                    setStatus(status) {
+                        attributes['status.code'] = status.code;
+                        if (status.message)
+                            attributes['status.message'] = status.message;
+                    },
+                    end() {
+                        const llmCall = span._llmCall;
+                        if (llmCall) {
+                            llmCall.end({
+                                promptTokens: span._promptTokens,
+                                completionTokens: span._completionTokens,
+                            });
+                        }
+                    },
+                };
+                return span;
+            },
+        },
+    };
+}
+//# sourceMappingURL=vercel-ai.js.map

package/dist/integrations/vercel-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-ai.js","sourceRoot":"","sources":["../../src/integrations/vercel-ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAuBH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,UAAmC,EAAE;IAErC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,iBAAiB,CAAC;IAEzD,OAAO;QACL,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,SAAS;QACrB,MAAM,EAAE;YACN,SAAS,CAAC,IAAY,EAAE,WAAqC;gBAC3D,MAAM,UAAU,GAAoC,EAAE,CAAC;gBAEvD,MAAM,IAAI,GAAS;oBACjB,YAAY,CAAC,GAAW,EAAE,KAAgC;wBACxD,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;wBAEhC,uCAAuC;wBACvC,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;4BAC1B,MAAM,IAAI,GAAI,MAAc,CAAC,YAAY,CAAC;4BAC1C,IAAI,IAAI,EAAE,CAAC;gCACT,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gCAClD,IAAY,CAAC,QAAQ,GAAG,GAAG,CAAC;4BAC/B,CAAC;wBACH,CAAC;wBAED,IAAI,GAAG,KAAK,uBAAuB,IAAK,IAAY,CAAC,QAAQ,EAAE,CAAC;4BAC7D,IAAY,CAAC,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;wBAC9C,CAAC;wBAED,IAAI,GAAG,KAAK,2BAA2B,IAAK,IAAY,CAAC,QAAQ,EAAE,CAAC;4BACjE,IAAY,CAAC,iBAAiB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;wBAClD,CAAC;oBACH,CAAC;oBAED,SAAS,CAAC,MAA0C;wBAClD,UAAU,CAAC,aAAa,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;wBACxC,IAAI,MAAM,CAAC,OAAO;4BAAE,UAAU,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC;oBACpE,CAAC;oBAED,GAAG;wBACD,MAAM,OAAO,GAAI,IAAY,CAAC,QAAQ,CAAC;wBACvC,IAAI,OAAO,EAAE,CAAC;4BACZ,OAAO,CAAC,GAAG,CAAC;gCACV,YAAY,EAAG,IAAY,CAAC,aAAa;gCACzC,gBAAgB,EAAG,IAAY,CAAC,iBAAiB;6BAClD,CAAC,CAAC;wBACL,CAAC;oBACH,CAAC;iBACF,CAAC;gBAEF,OAAO,IAAI,CAAC;YACd,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,16 +1,49 @@
 {
   "name": "@sentro/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "description": "Error tracking and agent observability for AI agents — TypeScript SDK for Sentro",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vercel-ai": {
+      "types": "./dist/integrations/vercel-ai.d.ts",
+      "default": "./dist/integrations/vercel-ai.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "sentro",
+    "observability",
+    "error-tracking",
+    "ai-agents",
+    "llm",
+    "tracing",
+    "sentry-alternative"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yzzztech/sentro.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/yzzztech/sentro",
+  "bugs": "https://github.com/yzzztech/sentro/issues",
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "dev": "tsc --watch"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
     "typescript": "^5.7.0",
     "vitest": "^3.1.0"
   }