@getmarrow/sdk 1.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @marrow/sdk
+
+TypeScript SDK for [Marrow](https://getmarrow.ai) — decision intelligence for AI agents.
+
+## Install
+
+```bash
+npm install @marrow/sdk
+```
+
+## Usage
+
+```typescript
+import { Marrow } from '@marrow/sdk'
+
+const marrow = new Marrow({ apiKey: 'mrw_your_key' })
+
+// Before a decision
+const { decisionId, insight, insights } = await marrow.think({
+  action: 'deploying new feature',
+  type: 'deployment'
+})
+
+// After completion
+await marrow.commit({
+  decisionId,
+  success: true,
+  outcome: 'deploy successful'
+})
+
+// Get patterns
+const patterns = await marrow.patterns()
+```
+
+## What's new in v1.1.0
+
+### Query your agent's patterns
+```typescript
+const patterns = await marrow.agentPatterns({ type: 'deploy' })
+// Returns failure rates, recurring decisions, behavioral drift
+```
+
+### Health score
+```typescript
+const analytics = await marrow.analytics()
+console.log(analytics.healthScore) // { score: 78, label: 'Good', ... }
+```
+
+### PII detection signal
+```typescript
+const { sanitized } = await marrow.think({ action: '...', type: '...' })
+if (sanitized) console.log('PII was detected and stripped')
+```
+
+### Upgrade nudges (free tier)
+```typescript
+const { upgradeHint } = await marrow.think({ action: '...', type: '...' })
+if (upgradeHint) console.log(upgradeHint.message)
+```
+
+## Features
+- Zero dependencies (fetch-based)
+- Auto-retry on 429 with exponential backoff
+- TypeScript types included
+- Browser + Node compatible

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Marrow SDK — HTTP client (fetch-based, no heavy deps)
+ */
+import { MarrowConfig, ThinkParams, ThinkResult, CommitParams, Pattern, AgentPatternsResult, HealthScore } from './types.js';
+export declare class Marrow {
+    private apiKey;
+    private baseUrl;
+    constructor(config?: MarrowConfig);
+    think(params: ThinkParams): Promise<ThinkResult>;
+    commit(params: CommitParams): Promise<void>;
+    agentPatterns(params?: {
+        type?: string;
+        limit?: number;
+    }): Promise<AgentPatternsResult>;
+    analytics(): Promise<{
+        healthScore: HealthScore;
+        [key: string]: unknown;
+    }>;
+    patterns(): Promise<Pattern[]>;
+    private post;
+    private get;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Marrow = void 0;
+const errors_js_1 = require("./errors.js");
+const DEFAULT_BASE_URL = 'https://api.getmarrow.ai';
+const MAX_RETRIES = 3;
+class Marrow {
+    apiKey;
+    baseUrl;
+    constructor(config) {
+        const key = config?.apiKey || (typeof process !== 'undefined' ? process.env?.MARROW_API_KEY : undefined);
+        if (!key) {
+            throw new errors_js_1.AuthError('API key required. Pass apiKey in config or set MARROW_API_KEY env var.');
+        }
+        this.apiKey = key;
+        this.baseUrl = config?.baseUrl || DEFAULT_BASE_URL;
+    }
+    async think(params) {
+        const body = {
+            action: params.action,
+            type: params.type,
+        };
+        if (params.previousDecisionId)
+            body.previous_decision_id = params.previousDecisionId;
+        if (params.previousSuccess !== undefined)
+            body.previous_success = params.previousSuccess;
+        if (params.previousOutcome)
+            body.previous_outcome = params.previousOutcome;
+        const res = await this.post('/v1/agent/think', body);
+        const data = res.data || res;
+        const intel = (data.intelligence || {});
+        return {
+            decisionId: String(data.decision_id || ''),
+            insight: intel.insight ? String(intel.insight) : null,
+            insights: (intel.insights || []),
+            clusterId: intel.cluster_id ? String(intel.cluster_id) : null,
+            successRate: Number(intel.success_rate || 0),
+            similarCount: Number(intel.similar_count || 0),
+            sanitized: Boolean(data.sanitized),
+            upgradeHint: data.upgrade_hint ? data.upgrade_hint : undefined,
+        };
+    }
+    async commit(params) {
+        await this.post('/v1/agent/commit', {
+            decision_id: params.decisionId,
+            success: params.success,
+            outcome: params.outcome,
+        });
+    }
+    async agentPatterns(params) {
+        const qs = new URLSearchParams();
+        if (params?.type)
+            qs.set('type', params.type);
+        if (params?.limit)
+            qs.set('limit', String(params.limit));
+        const res = await this.get(`/v1/agent/patterns${qs.toString() ? '?' + qs.toString() : ''}`);
+        const data = res.data || res;
+        return {
+            failurePatterns: (data.failure_patterns || []),
+            recurringDecisions: (data.recurring_decisions || []),
+            behavioralDrift: (data.behavioral_drift || {}),
+            topFailureTypes: (data.top_failure_types || []),
+            generatedAt: String(data.generated_at || ''),
+        };
+    }
+    async analytics() {
+        const res = await this.get('/v1/analytics');
+        const data = res.data || res;
+        const hs = (data.health_score || {});
+        return {
+            ...data,
+            healthScore: {
+                score: Number(hs.score || 0),
+                label: String(hs.label || ''),
+                breakdown: (hs.breakdown || {}),
+                trend: String(hs.trend || ''),
+                vsLastWeek: String(hs.vs_last_week || ''),
+            },
+        };
+    }
+    async patterns() {
+        const res = await this.get('/v1/patterns');
+        const data = (res.data || []);
+        return data.map(p => ({
+            patternId: String(p.pattern_id || p.id || ''),
+            signature: String(p.signature || p.pattern_signature || ''),
+            frequency: Number(p.frequency || 0),
+            confidence: Number(p.confidence || 0),
+        }));
+    }
+    async post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async get(path) {
+        return this.request('GET', path);
+    }
+    async request(method, path, body) {
+        let lastError = null;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            try {
+                const opts = {
+                    method,
+                    headers: {
+                        'Authorization': `Bearer ${this.apiKey}`,
+                        ...(body ? { 'Content-Type': 'application/json' } : {}),
+                    },
+                    ...(body ? { body: JSON.stringify(body) } : {}),
+                };
+                const res = await fetch(`${this.baseUrl}${path}`, opts);
+                if (res.ok) {
+                    return res.json();
+                }
+                if (res.status === 429) {
+                    const retryAfter = parseInt(res.headers.get('Retry-After') || '60', 10);
+                    if (attempt < MAX_RETRIES - 1) {
+                        await new Promise(r => setTimeout(r, retryAfter * 1000 * (attempt + 1)));
+                        continue;
+                    }
+                    throw new errors_js_1.RateLimitError(retryAfter);
+                }
+                const text = await res.text();
+                if (res.status === 401)
+                    throw new errors_js_1.AuthError(text);
+                if (res.status === 400)
+                    throw new errors_js_1.ValidationError(text);
+                throw new errors_js_1.MarrowError(`API error (${res.status}): ${text}`, res.status);
+            }
+            catch (e) {
+                if (e instanceof errors_js_1.MarrowError)
+                    throw e;
+                lastError = e instanceof Error ? e : new Error(String(e));
+                if (attempt < MAX_RETRIES - 1) {
+                    await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
+                    continue;
+                }
+            }
+        }
+        throw lastError || new errors_js_1.MarrowError('Request failed after retries');
+    }
+}
+exports.Marrow = Marrow;

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export declare class MarrowError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare class AuthError extends MarrowError {
+    constructor(message?: string);
+}
+export declare class ValidationError extends MarrowError {
+    constructor(message: string);
+}
+export declare class RateLimitError extends MarrowError {
+    retryAfter: number;
+    constructor(retryAfter?: number);
+}

package/dist/errors.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = exports.ValidationError = exports.AuthError = exports.MarrowError = void 0;
+class MarrowError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'MarrowError';
+    }
+}
+exports.MarrowError = MarrowError;
+class AuthError extends MarrowError {
+    constructor(message = 'Invalid API key') {
+        super(message, 401);
+        this.name = 'AuthError';
+    }
+}
+exports.AuthError = AuthError;
+class ValidationError extends MarrowError {
+    constructor(message) {
+        super(message, 400);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+class RateLimitError extends MarrowError {
+    retryAfter;
+    constructor(retryAfter = 60) {
+        super(`Rate limited. Retry after ${retryAfter}s`);
+        this.name = 'RateLimitError';
+        this.statusCode = 429;
+        this.retryAfter = retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Marrow } from './client.js';
+export { MarrowError, AuthError, ValidationError, RateLimitError } from './errors.js';
+export type { MarrowConfig, ThinkParams, ThinkResult, CommitParams, Pattern, ActionableInsight, AgentPatternsResult, UpgradeHint, HealthScore } from './types.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = exports.ValidationError = exports.AuthError = exports.MarrowError = exports.Marrow = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Marrow", { enumerable: true, get: function () { return client_js_1.Marrow; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "MarrowError", { enumerable: true, get: function () { return errors_js_1.MarrowError; } });
+Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_js_1.AuthError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+export interface MarrowConfig {
+    apiKey?: string;
+    baseUrl?: string;
+}
+export interface ThinkParams {
+    action: string;
+    type: string;
+    previousDecisionId?: string;
+    previousSuccess?: boolean;
+    previousOutcome?: string;
+}
+export interface ThinkResult {
+    decisionId: string;
+    insight: string | null;
+    insights: ActionableInsight[];
+    clusterId: string | null;
+    successRate: number;
+    similarCount: number;
+    sanitized: boolean;
+    upgradeHint?: UpgradeHint;
+}
+export interface ActionableInsight {
+    type: 'frequency' | 'failure_pattern' | 'workflow_gap' | 'hive_trend';
+    summary: string;
+    action: string;
+    severity: 'info' | 'warning' | 'critical';
+    count: number;
+}
+export interface CommitParams {
+    decisionId: string;
+    success: boolean;
+    outcome: string;
+}
+export interface Pattern {
+    patternId: string;
+    signature: string;
+    frequency: number;
+    confidence: number;
+}
+export interface AgentPatternsResult {
+    failurePatterns: Array<{
+        decisionType: string;
+        failureRate: number;
+        count: number;
+        lastSeen: string;
+    }>;
+    recurringDecisions: Array<{
+        decisionType: string;
+        frequency: number;
+        avgConfidence: number;
+        trend: string;
+    }>;
+    behavioralDrift: {
+        successRate7d: number;
+        successRate30d: number;
+        drift: string;
+        direction: string;
+    };
+    topFailureTypes: string[];
+    generatedAt: string;
+}
+export interface UpgradeHint {
+    message: string;
+    tier: string;
+    url: string;
+}
+export interface HealthScore {
+    score: number;
+    label: string;
+    breakdown: {
+        successRate: number;
+        decisionVelocity: number;
+        patternDiscovery: number;
+        improvementTrend: string;
+    };
+    trend: string;
+    vsLastWeek: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@getmarrow/sdk",
+  "version": "1.1.0",
+  "description": "TypeScript SDK for Marrow — decision intelligence for AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "marrow",
+    "sdk",
+    "ai",
+    "decision",
+    "intelligence"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}