@fulcrum-governance/sdk 0.1.4 → 0.1.5

package/dist/clients/metrics.js

@@ -20,7 +20,7 @@ class MetricsClient {
                 'Content-Type': 'application/json',
             };
             if (this.apiKey) {
-                headers['Authorization'] = `Bearer ${this.apiKey}`;
+                headers['X-API-Key'] = this.apiKey;
             }
             const response = await fetch(`${this.baseUrl}${path}`, {
                 method,
@@ -30,7 +30,20 @@ class MetricsClient {
             });
             if (!response.ok) {
                 const errorData = (await response.json().catch(() => ({})));
-                throw new MetricsClientError(errorData.error || `Request failed with status ${response.status}`, response.status);
+                const serverMessage = errorData.error || errorData.message || errorData.detail || '';
+                let errorMessage;
+                if (response.status === 401) {
+                    errorMessage = this.apiKey
+                        ? `Authentication failed: ${serverMessage || 'invalid API key'}. Verify your API key is correct and active. Check your keys in the Fulcrum dashboard under Settings > API Keys.`
+                        : 'Authentication required: no API key configured. Pass apiKey when creating the client. Generate a key in the Fulcrum dashboard under Settings > API Keys.';
+                }
+                else if (response.status === 403) {
+                    errorMessage = `Insufficient permissions: ${serverMessage || 'access denied'}. Your API key does not have the required scopes. Update key permissions in the Fulcrum dashboard under Settings > API Keys.`;
+                }
+                else {
+                    errorMessage = serverMessage || `Request failed with status ${response.status}`;
+                }
+                throw new MetricsClientError(errorMessage, response.status);
             }
             return (await response.json());
         }

package/dist/clients/policy.d.ts

@@ -1,7 +1,9 @@
 /**
- * PolicyClient - REST-based client for policy CRUD operations
+ * PolicyClient - REST-based client for policy access
  *
- * Works with the Fulcrum Dashboard REST API for managing policies.
+ * Works with the Fulcrum hosted REST API for listing policies. Write methods are
+ * retained for compatible admin/self-hosted API surfaces and may not be enabled on
+ * the public API-key gateway.
  * For high-performance policy evaluation, use FulcrumClient.evaluatePolicy() instead.
  */
 export interface Policy {
@@ -46,8 +48,11 @@ export declare class PolicyClient {
     private baseUrl;
     private apiKey?;
     private timeoutMs;
+    private readonly policiesPath;
     constructor(options: PolicyClientOptions);
     private request;
+    private normalizeStatus;
+    private normalizePolicy;
     /**
      * List all policies, optionally filtered
      */

package/dist/clients/policy.js

@@ -1,14 +1,17 @@
 "use strict";
 /**
- * PolicyClient - REST-based client for policy CRUD operations
+ * PolicyClient - REST-based client for policy access
  *
- * Works with the Fulcrum Dashboard REST API for managing policies.
+ * Works with the Fulcrum hosted REST API for listing policies. Write methods are
+ * retained for compatible admin/self-hosted API surfaces and may not be enabled on
+ * the public API-key gateway.
  * For high-performance policy evaluation, use FulcrumClient.evaluatePolicy() instead.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PolicyClientError = exports.PolicyClient = void 0;
 class PolicyClient {
     constructor(options) {
+        this.policiesPath = '/api/v1/policies';
         this.baseUrl = options.baseUrl.replace(/\/$/, '');
         this.apiKey = options.apiKey;
         this.timeoutMs = options.timeoutMs || 5000;
@@ -21,7 +24,7 @@ class PolicyClient {
                 'Content-Type': 'application/json',
             };
             if (this.apiKey) {
-                headers['Authorization'] = `Bearer ${this.apiKey}`;
+                headers['X-API-Key'] = this.apiKey;
             }
             const response = await fetch(`${this.baseUrl}${path}`, {
                 method,
@@ -31,7 +34,20 @@ class PolicyClient {
             });
             if (!response.ok) {
                 const errorData = (await response.json().catch(() => ({})));
-                throw new PolicyClientError(errorData.error || `Request failed with status ${response.status}`, response.status);
+                const serverMessage = errorData.error || errorData.message || errorData.detail || '';
+                let errorMessage;
+                if (response.status === 401) {
+                    errorMessage = this.apiKey
+                        ? `Authentication failed: ${serverMessage || 'invalid API key'}. Verify your API key is correct and active. Check your keys in the Fulcrum dashboard under Settings > API Keys.`
+                        : 'Authentication required: no API key configured. Pass apiKey when creating the client. Generate a key in the Fulcrum dashboard under Settings > API Keys.';
+                }
+                else if (response.status === 403) {
+                    errorMessage = `Insufficient permissions: ${serverMessage || 'access denied'}. Your API key does not have the required scopes. Update key permissions in the Fulcrum dashboard under Settings > API Keys.`;
+                }
+                else {
+                    errorMessage = serverMessage || `Request failed with status ${response.status}`;
+                }
+                throw new PolicyClientError(errorMessage, response.status);
             }
             return (await response.json());
         }
@@ -39,6 +55,30 @@ class PolicyClient {
             clearTimeout(timeout);
         }
     }
+    normalizeStatus(status) {
+        return status?.replace(/^POLICY_STATUS_/, '') || 'ACTIVE';
+    }
+    normalizePolicy(policy) {
+        const status = this.normalizeStatus(policy.status);
+        const normalized = {
+            id: policy.id || policy.policy_id || '',
+            name: policy.name || '',
+            policy_type: policy.policy_type || 'governance',
+            rules: policy.rules || {},
+            enabled: policy.enabled ?? status === 'ACTIVE',
+            priority: policy.priority ?? 0,
+            status,
+            created_at: policy.created_at || '',
+            updated_at: policy.updated_at || '',
+        };
+        if (policy.violation_count !== undefined) {
+            normalized.violation_count = policy.violation_count;
+        }
+        if (policy.total_evaluations !== undefined) {
+            normalized.total_evaluations = policy.total_evaluations;
+        }
+        return normalized;
+    }
     /**
      * List all policies, optionally filtered
      */
@@ -51,32 +91,37 @@ class PolicyClient {
         if (filter?.enabled !== undefined)
             params.append('enabled', String(filter.enabled));
         const query = params.toString();
-        const path = query ? `/api/policies?${query}` : '/api/policies';
-        return this.request('GET', path);
+        const path = query ? `${this.policiesPath}?${query}` : this.policiesPath;
+        const response = await this.request('GET', path);
+        const policies = Array.isArray(response) ? response : response.policies || [];
+        return policies.map((policy) => this.normalizePolicy(policy));
     }
     /**
      * Get a single policy by ID
      */
     async get(id) {
-        return this.request('GET', `/api/policies/${id}`);
+        const response = await this.request('GET', `${this.policiesPath}/${id}`);
+        return this.normalizePolicy(response);
     }
     /**
      * Create a new policy
      */
     async create(policy) {
-        return this.request('POST', '/api/policies', policy);
+        const response = await this.request('POST', this.policiesPath, policy);
+        return this.normalizePolicy(response);
     }
     /**
      * Update an existing policy
      */
     async update(id, updates) {
-        return this.request('PATCH', `/api/policies/${id}`, updates);
+        const response = await this.request('PATCH', `${this.policiesPath}/${id}`, updates);
+        return this.normalizePolicy(response);
     }
     /**
      * Delete a policy
      */
     async delete(id) {
-        await this.request('DELETE', `/api/policies/${id}`);
+        await this.request('DELETE', `${this.policiesPath}/${id}`);
     }
     /**
      * Toggle policy enabled state

package/dist/clients/tenant.js

@@ -43,8 +43,21 @@ class TenantClient {
                 signal: controller.signal,
             });
             if (!response.ok) {
-                const error = await response.json().catch(() => ({}));
-                throw new TenantClientError(error.message || `Request failed with status ${response.status}`, response.status, error);
+                const errorData = await response.json().catch(() => ({}));
+                const serverMessage = errorData.error || errorData.message || errorData.detail || '';
+                let errorMessage;
+                if (response.status === 401) {
+                    errorMessage = this.apiKey
+                        ? `Authentication failed: ${serverMessage || 'invalid API key'}. Verify your API key is correct and active. Check your keys in the Fulcrum dashboard under Settings > API Keys.`
+                        : 'Authentication required: no API key configured. Pass apiKey when creating the client. Generate a key in the Fulcrum dashboard under Settings > API Keys.';
+                }
+                else if (response.status === 403) {
+                    errorMessage = `Insufficient permissions: ${serverMessage || 'access denied'}. Your API key does not have the required scopes. Update key permissions in the Fulcrum dashboard under Settings > API Keys.`;
+                }
+                else {
+                    errorMessage = serverMessage || `Request failed with status ${response.status}`;
+                }
+                throw new TenantClientError(errorMessage, response.status, errorData);
             }
             // For DELETE requests, return empty object if no content
             if (response.status === 204 || response.headers.get('content-length') === '0') {

package/dist/index.js

@@ -57,14 +57,18 @@ class FulcrumClient {
             oneofs: true,
             includeDirs: [protoPath]
         };
+        // Use TLS for port 443 (production), insecure for local dev
+        const channelCreds = this.host.endsWith(':443')
+            ? grpc.credentials.createSsl()
+            : grpc.credentials.createInsecure();
         // Load policy service
         const policyProto = protoLoader.loadSync(path.join(protoPath, 'fulcrum/policy/v1/policy_service.proto'), protoOptions);
         const policyPackage = grpc.loadPackageDefinition(policyProto);
-        this.policyClient = new policyPackage.fulcrum.policy.v1.PolicyService(this.host, grpc.credentials.createInsecure());
+        this.policyClient = new policyPackage.fulcrum.policy.v1.PolicyService(this.host, channelCreds);
         // Load envelope service
         const envelopeProto = protoLoader.loadSync(path.join(protoPath, 'fulcrum/envelope/v1/envelope_service.proto'), protoOptions);
         const envelopePackage = grpc.loadPackageDefinition(envelopeProto);
-        this.envelopeClient = new envelopePackage.fulcrum.envelope.v1.EnvelopeService(this.host, grpc.credentials.createInsecure());
+        this.envelopeClient = new envelopePackage.fulcrum.envelope.v1.EnvelopeService(this.host, channelCreds);
     }
     getMetadata() {
         const metadata = new grpc.Metadata();

package/dist/instrumentation/__tests__/autoGovern.test.js

@@ -394,8 +394,9 @@ describe('autoGovern - fetch patching integration', () => {
             },
         ]);
         await expect(globalThis.fetch('https://example.com/api')).rejects.toThrow(/blocked by Fulcrum policy/);
-        // Original fetch should not have been called
-        expect(mockFetch).not.toHaveBeenCalled();
+        // Original fetch should not have been called for the blocked URL.
+        // (The SDK may call fetch internally for policy sync — that's expected.)
+        expect(mockFetch).not.toHaveBeenCalledWith('https://example.com/api', expect.anything());
     });
     it('should allow fetch when policy allows', async () => {
         // Mock fetch

package/dist/instrumentation/__tests__/costReporter.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for CostReporter.
+ * Tests cover: queueing, flushing, batch limits, no-key behavior, error resilience.
+ */
+export {};

package/dist/instrumentation/__tests__/costReporter.test.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Unit tests for CostReporter.
+ * Tests cover: queueing, flushing, batch limits, no-key behavior, error resilience.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const costReporter_1 = require("../costReporter");
+describe('CostReporter', () => {
+    let reporter;
+    let fetchSpy;
+    beforeEach(() => {
+        fetchSpy = jest.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({ status: 'accepted' }),
+        });
+        reporter = new costReporter_1.CostReporter({
+            serverUrl: 'https://api.fulcrumlayer.io',
+            apiKey: 'test-key',
+            rawFetch: fetchSpy,
+            batchSize: 10,
+            flushIntervalMs: 60000, // long interval to avoid auto-flush in tests
+        });
+    });
+    afterEach(() => {
+        reporter.stop();
+    });
+    it('queues cost events', () => {
+        reporter.report({
+            event_type: 'llm',
+            tool_name: 'llm:api.openai.com',
+            cost_usd: 0.0023,
+            tokens_in: 500,
+            tokens_out: 200,
+            model_id: 'gpt-4o-mini',
+        });
+        expect(reporter.queueSize).toBe(1);
+    });
+    it('flushes cost events to /api/v1/costs/report', async () => {
+        reporter.report({
+            event_type: 'llm',
+            tool_name: 'llm:api.openai.com',
+            cost_usd: 0.005,
+            tokens_in: 1000,
+            tokens_out: 400,
+            model_id: 'gpt-4o',
+        });
+        await reporter.flush();
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://api.fulcrumlayer.io/api/v1/costs/report');
+        expect(init.method).toBe('POST');
+        expect(init.headers['X-API-Key']).toBe('test-key');
+        const body = JSON.parse(init.body);
+        expect(body.event_type).toBe('llm');
+        expect(body.cost_usd).toBe(0.005);
+        expect(body.tokens_in).toBe(1000);
+        expect(body.model_id).toBe('gpt-4o');
+        expect(reporter.queueSize).toBe(0);
+    });
+    it('respects batch size limit', async () => {
+        const smallReporter = new costReporter_1.CostReporter({
+            serverUrl: 'https://api.fulcrumlayer.io',
+            apiKey: 'test-key',
+            rawFetch: fetchSpy,
+            batchSize: 2,
+            flushIntervalMs: 60000,
+        });
+        for (let i = 0; i < 5; i++) {
+            smallReporter.report({
+                event_type: 'tool',
+                tool_name: `tool-${i}`,
+                cost_usd: 0.01,
+            });
+        }
+        await smallReporter.flush();
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+        expect(smallReporter.queueSize).toBe(3);
+        smallReporter.stop();
+    });
+    it('drops events when no API key', () => {
+        const noKeyReporter = new costReporter_1.CostReporter({
+            serverUrl: 'https://api.fulcrumlayer.io',
+            apiKey: '',
+            rawFetch: fetchSpy,
+            batchSize: 10,
+            flushIntervalMs: 60000,
+        });
+        noKeyReporter.report({
+            event_type: 'llm',
+            tool_name: 'test',
+            cost_usd: 0.001,
+        });
+        expect(noKeyReporter.queueSize).toBe(0);
+        noKeyReporter.stop();
+    });
+    it('fails silently on network errors', async () => {
+        fetchSpy.mockRejectedValueOnce(new Error('connection refused'));
+        reporter.report({
+            event_type: 'llm',
+            tool_name: 'test',
+            cost_usd: 0.001,
+        });
+        await reporter.flush();
+        expect(reporter.queueSize).toBe(0);
+    });
+    it('enforces maximum queue size of 1000', () => {
+        for (let i = 0; i < 1005; i++) {
+            reporter.report({
+                event_type: 'tool',
+                tool_name: `tool-${i}`,
+                cost_usd: 0.001,
+            });
+        }
+        expect(reporter.queueSize).toBe(1000);
+    });
+    it('strips trailing slash from server URL', async () => {
+        const slashReporter = new costReporter_1.CostReporter({
+            serverUrl: 'https://api.fulcrumlayer.io/',
+            apiKey: 'test-key',
+            rawFetch: fetchSpy,
+            flushIntervalMs: 60000,
+        });
+        slashReporter.report({
+            event_type: 'llm',
+            tool_name: 'test',
+            cost_usd: 0.001,
+        });
+        await slashReporter.flush();
+        const [url] = fetchSpy.mock.calls[0];
+        expect(url).toBe('https://api.fulcrumlayer.io/api/v1/costs/report');
+        slashReporter.stop();
+    });
+    it('does nothing on flush when queue is empty', async () => {
+        await reporter.flush();
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+});

package/dist/instrumentation/autoGovern.js

@@ -16,6 +16,7 @@ exports.getMetrics = getMetrics;
 exports.evaluateCall = evaluateCall;
 const types_1 = require("./types");
 const evaluator_1 = require("./evaluator");
+const costReporter_1 = require("./costReporter");
 // Global state
 let evaluator = null;
 let config = null;
@@ -27,6 +28,7 @@ const metrics = {
     allowedCalls: 0,
     patchFailures: 0,
 };
+let costReporter = null;
 /**
  * Activate Fulcrum governance for TypeScript/Node.js.
  *
@@ -59,6 +61,14 @@ function activate(userConfig = {}) {
     // Create and start evaluator
     evaluator = new evaluator_1.PolicyEvaluator(config);
     evaluator.start();
+    // Create cost reporter (capture rawFetch before patching)
+    costReporter = new costReporter_1.CostReporter({
+        serverUrl: config.serverUrl,
+        apiKey: config.apiKey,
+        rawFetch: globalThis.fetch,
+        batchSize: 10,
+        flushIntervalMs: 5000,
+    });
     // Apply patches
     applyPatches();
     active = true;
@@ -78,6 +88,11 @@ function deactivate() {
         evaluator.stop();
         evaluator = null;
     }
+    // Stop cost reporter
+    if (costReporter) {
+        costReporter.stop();
+        costReporter = null;
+    }
     // Restore originals
     restoreOriginals();
     active = false;
@@ -174,7 +189,12 @@ function patchFetch() {
             if (decision.action === 'deny') {
                 throw new Error(`HTTP request to '${url}' blocked by Fulcrum policy: ${decision.reason}`);
             }
-            return originalFetch(input, init);
+            const response = await originalFetch(input, init);
+            // Extract cost from LLM API responses (best-effort)
+            if (costReporter && response.ok && typeof response.clone === 'function') {
+                maybeReportCost(url, response.clone());
+            }
+            return response;
         };
         console.debug('[fulcrum] Patched global fetch');
     }
@@ -282,6 +302,48 @@ function patchChildProcess() {
         recordMetric('patchFailures');
     }
 }
+const LLM_PRICING = {
+    'api.openai.com': {
+        'gpt-4o-mini': [0.15, 0.60],
+        'gpt-4o': [2.50, 10.00],
+        'gpt-4-turbo': [10.00, 30.00],
+    },
+    'api.anthropic.com': {
+        'claude-sonnet-4-20250514': [3.00, 15.00],
+        'claude-haiku-4-5-20251001': [0.80, 4.00],
+    },
+};
+async function maybeReportCost(url, response) {
+    try {
+        const host = new URL(url).host;
+        const pricing = LLM_PRICING[host];
+        if (!pricing)
+            return;
+        const data = await response.json();
+        const usage = data.usage;
+        if (!usage)
+            return;
+        const tokensIn = usage.prompt_tokens ?? usage.input_tokens ?? 0;
+        const tokensOut = usage.completion_tokens ?? usage.output_tokens ?? 0;
+        if (!tokensIn && !tokensOut)
+            return;
+        const model = data.model ?? '';
+        const defaultRate = host.includes('openai') ? [0.15, 0.60] : [3.00, 15.00];
+        const [inRate, outRate] = pricing[model] ?? defaultRate;
+        const costUsd = (tokensIn * inRate + tokensOut * outRate) / 1000000;
+        costReporter.report({
+            event_type: 'llm',
+            tool_name: `llm:${host}`,
+            cost_usd: costUsd,
+            tokens_in: tokensIn,
+            tokens_out: tokensOut,
+            model_id: model,
+        });
+    }
+    catch {
+        // Best-effort — never fail governed calls
+    }
+}
 function restoreOriginals() {
     // Restore fetch
     if (originals.has('fetch')) {

package/dist/instrumentation/costReporter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Batched cost event reporter for the TypeScript SDK.
+ *
+ * Queues cost events and periodically POSTs them to /api/v1/costs/report.
+ * Uses a captured fetch reference to avoid governance interception.
+ */
+import type { CostEvent } from './types';
+export interface CostReporterConfig {
+    serverUrl: string;
+    apiKey: string;
+    rawFetch: typeof globalThis.fetch;
+    batchSize?: number;
+    flushIntervalMs?: number;
+}
+export declare class CostReporter {
+    private readonly serverUrl;
+    private readonly apiKey;
+    private readonly rawFetch;
+    private readonly batchSize;
+    private readonly queue;
+    private timer;
+    constructor(config: CostReporterConfig);
+    get queueSize(): number;
+    report(event: CostEvent): void;
+    flush(): Promise<void>;
+    stop(): void;
+}

package/dist/instrumentation/costReporter.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Batched cost event reporter for the TypeScript SDK.
+ *
+ * Queues cost events and periodically POSTs them to /api/v1/costs/report.
+ * Uses a captured fetch reference to avoid governance interception.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostReporter = void 0;
+class CostReporter {
+    constructor(config) {
+        this.queue = [];
+        this.timer = null;
+        this.serverUrl = config.serverUrl.replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+        this.rawFetch = config.rawFetch;
+        this.batchSize = config.batchSize ?? 10;
+        if (this.apiKey) {
+            this.timer = setInterval(() => this.flush().catch(() => { }), config.flushIntervalMs ?? 5000);
+        }
+    }
+    get queueSize() {
+        return this.queue.length;
+    }
+    report(event) {
+        if (!this.apiKey)
+            return;
+        if (this.queue.length >= 1000) {
+            this.queue.shift();
+        }
+        this.queue.push(event);
+    }
+    async flush() {
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue.splice(0, this.batchSize);
+        const url = `${this.serverUrl}/api/v1/costs/report`;
+        // Send batch concurrently using AbortController (ES2020 compatible)
+        const promises = batch.map(async (event) => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 5000);
+            try {
+                await this.rawFetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-API-Key': this.apiKey,
+                    },
+                    body: JSON.stringify(event),
+                    signal: controller.signal,
+                });
+            }
+            catch {
+                // Best-effort — never propagate errors
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        });
+        await Promise.allSettled(promises);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+exports.CostReporter = CostReporter;

package/dist/instrumentation/evaluator.d.ts

@@ -17,6 +17,7 @@ export declare class PolicyEvaluator {
     private syncError;
     private syncInterval;
     private running;
+    private readonly rawFetch;
     constructor(config?: InstrumentationConfig);
     /**
      * Start the background policy sync.
@@ -40,6 +41,13 @@ export declare class PolicyEvaluator {
     private getFieldValue;
     private getRuleAction;
     private syncPolicies;
+    /**
+     * Evaluate a request server-side via the REST gateway.
+     *
+     * Used as fallback when local cache is empty but credentials are configured.
+     * Returns null on any error so the caller can fall back to local evaluation.
+     */
+    evaluateServerSide(request: EvaluationRequest): Promise<Decision | null>;
     /**
      * Manually update the policy cache (for testing).
      */