@nvsudo/sdk-js 0.1.0

package/README.md

@@ -0,0 +1,196 @@
+# @behavr/sdk
+
+Official SDK for **Behavr** — Calibration-as-a-service for AI agent communication.
+
+## Installation
+
+```bash
+npm install @behavr/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Behavr } from '@behavr/sdk';
+
+// Initialize with your API key
+const behavr = new Behavr({
+  apiKey: 'bvr_your_api_key_here',
+});
+
+// Capture a message after sending it (async, non-blocking)
+await behavr.capture({
+  messageId: 'msg_123',
+  content: 'Following up on our conversation from last week...',
+  channel: 'email',
+  interactionType: 'followup',
+  conversationId: 'conv_456',
+});
+
+// Record an outcome when you receive a reply
+await behavr.outcome({
+  messageId: 'msg_123',
+  type: 'reply',
+  delay: '2 hours',
+  sentiment: 'positive',
+});
+```
+
+## Features
+
+- ✅ **Async & Non-blocking** — Fire-and-forget, never blocks your app
+- ✅ **Automatic Retries** — Handles transient failures gracefully
+- ✅ **Rate Limiting** — Respects API quotas automatically
+- ✅ **TypeScript** — Full type safety out of the box
+- ✅ **Framework Agnostic** — Works with any stack
+
+## API Reference
+
+### `new Behavr(config)`
+
+Create a new Behavr client.
+
+**Options:**
+- `apiKey` (required) — Your Behavr API key
+- `baseUrl` (optional) — Custom API endpoint (defaults to `https://api.behavr.dev`)
+- `retryAttempts` (optional) — Number of retry attempts (default: 3)
+- `retryDelay` (optional) — Base retry delay in ms (default: 1000)
+- `debug` (optional) — Enable debug logging (default: false)
+
+### `behavr.capture(options)`
+
+Capture a message sent by your AI agent (async, returns immediately).
+
+**Options:**
+- `messageId` (required) — Unique identifier for this message
+- `content` (required) — The actual message content
+- `channel` (optional) — `email | slack | sms | chat | whatsapp | other`
+- `interactionType` (optional) — `followup | decline | escalation | cold_outreach | support | other`
+- `conversationId` (optional) — Group messages into conversations
+- `metadata` (optional) — Additional custom data
+
+### `behavr.outcome(options)`
+
+Record an outcome for a previously captured message (async).
+
+**Options:**
+- `messageId` (required) — The message ID this outcome relates to
+- `type` (required) — `reply | no_reply | escalation | churn | positive | negative`
+- `delay` (optional) — Time between message and outcome (e.g., `'2 hours'`)
+- `sentiment` (optional) — `positive | neutral | negative | unknown`
+- `metadata` (optional) — Additional custom data
+
+### `behavr.flush()`
+
+Wait for all queued operations to complete. Useful for graceful shutdown.
+
+```typescript
+await behavr.flush();
+```
+
+## Use Cases
+
+### Sales SDR Follow-ups
+
+```typescript
+const behavr = new Behavr({ apiKey: process.env.BEHAVR_API_KEY });
+
+// After sending follow-up
+await behavr.capture({
+  messageId: outboundEmail.id,
+  content: outboundEmail.body,
+  channel: 'email',
+  interactionType: 'followup',
+  metadata: {
+    prospectId: prospect.id,
+    sequence: 'cold-outreach-v2',
+  },
+});
+
+// When they reply
+await behavr.outcome({
+  messageId: outboundEmail.id,
+  type: 'reply',
+  delay: '4 hours',
+  sentiment: 'positive',
+});
+```
+
+### Customer Support
+
+```typescript
+// After sending support response
+await behavr.capture({
+  messageId: ticket.lastMessageId,
+  content: agent.response,
+  channel: 'chat',
+  interactionType: 'support',
+  conversationId: ticket.id,
+});
+
+// If escalated
+await behavr.outcome({
+  messageId: ticket.lastMessageId,
+  type: 'escalation',
+  delay: '10 minutes',
+});
+```
+
+### Consumer Apps (Boundaries)
+
+```typescript
+// When handling sensitive requests
+await behavr.capture({
+  messageId: messageId,
+  content: agentResponse,
+  channel: 'chat',
+  interactionType: 'decline',
+  metadata: {
+    requestType: 'inappropriate-dating',
+  },
+});
+```
+
+## Environment Variables
+
+```bash
+BEHAVR_API_KEY=bvr_your_api_key_here
+```
+
+## Debug Mode
+
+Enable debug logging to troubleshoot integration issues:
+
+```typescript
+const behavr = new Behavr({
+  apiKey: 'bvr_...',
+  debug: true, // Logs all API calls and errors
+});
+```
+
+## Error Handling
+
+The SDK automatically retries on transient failures (network errors, 5xx responses). It will **not** retry on client errors (4xx) except rate limits (429).
+
+If you need to handle errors explicitly, use the sync methods:
+
+```typescript
+try {
+  await behavr.captureSync({
+    messageId: 'msg_123',
+    content: 'Hello world',
+  });
+} catch (error) {
+  console.error('Failed to capture message:', error);
+}
+```
+
+## License
+
+MIT
+
+## Support
+
+- 📖 Documentation: https://docs.behavr.dev
+- 💬 Discord: https://discord.gg/behavr
+- 📧 Email: support@behavr.dev

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @behavr/sdk - Official SDK for Behavr
+ * Calibration-as-a-service for AI agent communication
+ */
+export interface BehavrConfig {
+    apiKey: string;
+    baseUrl?: string;
+    retryAttempts?: number;
+    retryDelay?: number;
+    debug?: boolean;
+}
+export interface BehavrReservedMetadata {
+    segmentKey?: string;
+    modelFamily?: string;
+    modelName?: string;
+    modelVersion?: string;
+    configId?: string;
+    configVersionId?: string;
+    deploymentId?: string;
+    sdr?: {
+        sequenceStep?: number;
+        daysSinceLastContact?: number;
+        prospectState?: 'cold' | 'warm' | 'engaged' | 'soft_decline' | 'hard_decline' | 'unknown';
+        replyIntent?: 'none' | 'positive' | 'neutral' | 'negative' | 'unknown';
+    };
+    proxyEvidence?: {
+        humanEdited?: boolean;
+        humanEditDistancePct?: number;
+        regenerationCount?: number;
+        rollbackFlag?: boolean;
+        timeToSendSeconds?: number;
+    };
+}
+export type BehavrMetadata = Record<string, any> & {
+    behavr?: BehavrReservedMetadata;
+};
+export interface CaptureMessageOptions {
+    messageId: string;
+    content: string;
+    channel?: 'email' | 'slack' | 'sms' | 'chat' | 'whatsapp' | 'other';
+    interactionType?: 'followup' | 'decline' | 'escalation' | 'cold_outreach' | 'support' | 'other';
+    conversationId?: string;
+    metadata?: BehavrMetadata;
+}
+export interface RecordOutcomeOptions {
+    messageId: string;
+    type: 'reply' | 'no_reply' | 'escalation' | 'churn' | 'positive' | 'negative';
+    delay?: string;
+    sentiment?: 'positive' | 'neutral' | 'negative' | 'unknown';
+    metadata?: BehavrMetadata;
+}
+export interface CaptureResponse {
+    success: boolean;
+    messageId: string;
+    id: string;
+}
+export interface OutcomeResponse {
+    success: boolean;
+    outcomeId: string;
+    messageId: string;
+}
+export declare class Behavr {
+    private client;
+    private config;
+    private queue;
+    private processing;
+    constructor(config: BehavrConfig);
+    /**
+     * Capture a message sent by your AI agent (async, non-blocking)
+     * This method queues the message and returns immediately
+     */
+    capture(options: CaptureMessageOptions): Promise<void>;
+    /**
+     * Record an outcome for a previously captured message (async, non-blocking)
+     */
+    outcome(options: RecordOutcomeOptions): Promise<void>;
+    /**
+     * Capture a message synchronously (blocks until complete)
+     * Use this only if you need confirmation that the message was captured
+     */
+    captureSync(options: CaptureMessageOptions): Promise<CaptureResponse>;
+    /**
+     * Record an outcome synchronously (blocks until complete)
+     */
+    outcomeSync(options: RecordOutcomeOptions): Promise<OutcomeResponse>;
+    /**
+     * Wait for all queued operations to complete
+     * Useful for graceful shutdown
+     */
+    flush(): Promise<void>;
+    private enqueue;
+    private processQueue;
+    private captureWithRetry;
+    private outcomeWithRetry;
+    private handleError;
+    private log;
+}
+export default Behavr;
+export { Behavr as BehavrClient };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * @behavr/sdk - Official SDK for Behavr
+ * Calibration-as-a-service for AI agent communication
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BehavrClient = exports.Behavr = void 0;
+const axios_1 = __importDefault(require("axios"));
+// ============================================================================
+// SDK CLASS
+// ============================================================================
+class Behavr {
+    constructor(config) {
+        this.queue = [];
+        this.processing = false;
+        if (!config.apiKey) {
+            throw new Error('Behavr: apiKey is required');
+        }
+        this.config = {
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl || 'https://api.behavr.dev',
+            retryAttempts: config.retryAttempts ?? 3,
+            retryDelay: config.retryDelay ?? 1000,
+            debug: config.debug ?? false,
+        };
+        this.client = axios_1.default.create({
+            baseURL: this.config.baseUrl,
+            headers: {
+                'Authorization': `Bearer ${this.config.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            timeout: 10000, // 10 second timeout
+        });
+    }
+    // ============================================================================
+    // PUBLIC METHODS
+    // ============================================================================
+    /**
+     * Capture a message sent by your AI agent (async, non-blocking)
+     * This method queues the message and returns immediately
+     */
+    async capture(options) {
+        this.log('Capturing message:', options.messageId);
+        this.enqueue(async () => {
+            await this.captureWithRetry(options);
+        });
+    }
+    /**
+     * Record an outcome for a previously captured message (async, non-blocking)
+     */
+    async outcome(options) {
+        this.log('Recording outcome:', options.messageId, options.type);
+        this.enqueue(async () => {
+            await this.outcomeWithRetry(options);
+        });
+    }
+    /**
+     * Capture a message synchronously (blocks until complete)
+     * Use this only if you need confirmation that the message was captured
+     */
+    async captureSync(options) {
+        this.log('Capturing message (sync):', options.messageId);
+        return await this.captureWithRetry(options);
+    }
+    /**
+     * Record an outcome synchronously (blocks until complete)
+     */
+    async outcomeSync(options) {
+        this.log('Recording outcome (sync):', options.messageId, options.type);
+        return await this.outcomeWithRetry(options);
+    }
+    /**
+     * Wait for all queued operations to complete
+     * Useful for graceful shutdown
+     */
+    async flush() {
+        this.log('Flushing queue...');
+        while (this.queue.length > 0 || this.processing) {
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        this.log('Queue flushed');
+    }
+    // ============================================================================
+    // PRIVATE METHODS
+    // ============================================================================
+    enqueue(fn) {
+        this.queue.push(fn);
+        this.processQueue();
+    }
+    async processQueue() {
+        if (this.processing || this.queue.length === 0) {
+            return;
+        }
+        this.processing = true;
+        while (this.queue.length > 0) {
+            const fn = this.queue.shift();
+            if (fn) {
+                try {
+                    await fn();
+                }
+                catch (error) {
+                    this.log('Queue processing error:', error);
+                }
+            }
+        }
+        this.processing = false;
+    }
+    async captureWithRetry(options, attempt = 1) {
+        try {
+            const response = await this.client.post('/v1/ingest/message', options);
+            this.log('Message captured successfully:', options.messageId);
+            return response.data;
+        }
+        catch (error) {
+            return this.handleError(error, attempt, () => this.captureWithRetry(options, attempt + 1));
+        }
+    }
+    async outcomeWithRetry(options, attempt = 1) {
+        try {
+            const response = await this.client.post('/v1/ingest/outcome', options);
+            this.log('Outcome recorded successfully:', options.messageId, options.type);
+            return response.data;
+        }
+        catch (error) {
+            return this.handleError(error, attempt, () => this.outcomeWithRetry(options, attempt + 1));
+        }
+    }
+    async handleError(error, attempt, retryFn) {
+        const isAxiosError = axios_1.default.isAxiosError(error);
+        const statusCode = isAxiosError ? error.response?.status : null;
+        const errorMessage = isAxiosError
+            ? error.response?.data || error.message
+            : String(error);
+        this.log(`Error (attempt ${attempt}/${this.config.retryAttempts}):`, errorMessage);
+        // Don't retry client errors (4xx) except 429 (rate limit)
+        if (statusCode && statusCode >= 400 && statusCode < 500 && statusCode !== 429) {
+            throw new Error(`Behavr: ${errorMessage}`);
+        }
+        // Retry if we haven't exhausted attempts
+        if (attempt < this.config.retryAttempts) {
+            const delay = this.config.retryDelay * attempt; // Exponential backoff
+            this.log(`Retrying in ${delay}ms...`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+            return retryFn();
+        }
+        // Exhausted retries
+        throw new Error(`Behavr: Failed after ${attempt} attempts: ${errorMessage}`);
+    }
+    log(...args) {
+        if (this.config.debug) {
+            console.log('[Behavr]', ...args);
+        }
+    }
+}
+exports.Behavr = Behavr;
+exports.BehavrClient = Behavr;
+// ============================================================================
+// EXPORTS
+// ============================================================================
+exports.default = Behavr;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nvsudo/sdk-js",
+  "version": "0.1.0",
+  "description": "Official SDK for Behavr - Calibration-as-a-service for AI agent communication",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Tests coming soon\" && exit 0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "communication",
+    "behavioral",
+    "scoring",
+    "calibration"
+  ],
+  "author": "Behavr Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/behavr/behavr-oss"
+  },
+  "bugs": {
+    "url": "https://github.com/behavr/behavr-oss/issues"
+  },
+  "homepage": "https://behavr.dev",
+  "dependencies": {
+    "axios": "^1.13.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nvsudo/behavr-oss.git"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}