@fulcrum-governance/sdk 0.1.1 → 0.1.3

package/dist/clients/envelope.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * EnvelopeClient - REST-based client for envelope management
+ *
+ * Works with the Fulcrum API for managing execution envelopes that wrap AI agent operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvelopeClient = exports.EnvelopeClientError = void 0;
+class EnvelopeClientError extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = 'EnvelopeClientError';
+    }
+}
+exports.EnvelopeClientError = EnvelopeClientError;
+class EnvelopeClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.apiKey = options.apiKey;
+        this.timeout = options.timeout || 30000;
+    }
+    async request(method, path, body, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.append(key, value);
+                }
+            });
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url.toString(), {
+                method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({}));
+                throw new EnvelopeClientError(error.message || `Request failed with status ${response.status}`, response.status, error);
+            }
+            return await response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Create a new execution envelope.
+     */
+    async create(request) {
+        const response = await this.request('POST', '/v1/envelopes', request);
+        return response.envelope;
+    }
+    /**
+     * Get an envelope by ID.
+     */
+    async get(envelopeId) {
+        const response = await this.request('GET', `/v1/envelopes/${envelopeId}`);
+        return response.envelope;
+    }
+    /**
+     * Update the status of an envelope.
+     */
+    async updateStatus(request) {
+        const { envelope_id, ...body } = request;
+        const response = await this.request('PATCH', `/v1/envelopes/${envelope_id}/status`, body);
+        return response.envelope;
+    }
+    /**
+     * List envelopes with optional filters.
+     */
+    async list(request = {}) {
+        const params = {
+            limit: String(request.limit || 100),
+            offset: String(request.offset || 0),
+        };
+        if (request.tenant_id)
+            params.tenant_id = request.tenant_id;
+        if (request.workflow_id)
+            params.workflow_id = request.workflow_id;
+        if (request.status)
+            params.status = request.status;
+        const response = await this.request('GET', '/v1/envelopes', undefined, params);
+        return response.envelopes;
+    }
+}
+exports.EnvelopeClient = EnvelopeClient;

package/dist/clients/eventstore.d.ts

@@ -0,0 +1,87 @@
+/**
+ * EventStoreClient - REST-based client for event store operations
+ *
+ * Works with the Fulcrum API for managing and querying execution events.
+ */
+export interface StoredEvent {
+    event_id: string;
+    execution_id: string;
+    envelope_id: string;
+    tenant_id: string;
+    workflow_id: string;
+    event_type: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+    metadata: Record<string, string>;
+    parent_event_id?: string;
+    trace_id?: string;
+    span_id?: string;
+}
+export interface EventStoreStats {
+    total_events: number;
+    events_by_type: Record<string, number>;
+    events_by_tenant: Record<string, number>;
+    oldest_event?: string;
+    newest_event?: string;
+    storage_size_bytes: number;
+}
+export interface PublishEventRequest {
+    execution_id: string;
+    envelope_id: string;
+    tenant_id: string;
+    workflow_id: string;
+    event_type: string;
+    data: Record<string, unknown>;
+    metadata?: Record<string, string>;
+    parent_event_id?: string;
+    trace_id?: string;
+    span_id?: string;
+}
+export interface QueryEventsRequest {
+    tenant_id?: string;
+    execution_ids?: string[];
+    envelope_ids?: string[];
+    workflow_ids?: string[];
+    event_types?: string[];
+    start_time?: string;
+    end_time?: string;
+    limit?: number;
+    offset?: number;
+}
+export declare class EventStoreClientError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+export interface EventStoreClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+}
+export declare class EventStoreClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    constructor(options: EventStoreClientOptions);
+    private request;
+    /**
+     * Publish a single event to the event store.
+     */
+    publishEvent(request: PublishEventRequest): Promise<StoredEvent>;
+    /**
+     * Publish multiple events in a single batch.
+     */
+    publishEventBatch(events: PublishEventRequest[]): Promise<StoredEvent[]>;
+    /**
+     * Query events with various filters.
+     */
+    queryEvents(request: QueryEventsRequest): Promise<StoredEvent[]>;
+    /**
+     * Get all events for a specific execution.
+     */
+    getExecutionEvents(executionId: string, limit?: number, offset?: number): Promise<StoredEvent[]>;
+    /**
+     * Get event store statistics.
+     */
+    getStats(): Promise<EventStoreStats>;
+}

package/dist/clients/eventstore.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * EventStoreClient - REST-based client for event store operations
+ *
+ * Works with the Fulcrum API for managing and querying execution events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventStoreClient = exports.EventStoreClientError = void 0;
+class EventStoreClientError extends Error {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = 'EventStoreClientError';
+    }
+}
+exports.EventStoreClientError = EventStoreClientError;
+class EventStoreClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.apiKey = options.apiKey;
+        this.timeout = options.timeout || 30000;
+    }
+    async request(method, path, body, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.append(key, value);
+                }
+            });
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url.toString(), {
+                method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({}));
+                throw new EventStoreClientError(error.message || `Request failed with status ${response.status}`, response.status, error);
+            }
+            return await response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Publish a single event to the event store.
+     */
+    async publishEvent(request) {
+        const response = await this.request('POST', '/v1/events', request);
+        return response.event;
+    }
+    /**
+     * Publish multiple events in a single batch.
+     */
+    async publishEventBatch(events) {
+        const response = await this.request('POST', '/v1/events/batch', { events });
+        return response.events;
+    }
+    /**
+     * Query events with various filters.
+     */
+    async queryEvents(request) {
+        const params = {
+            limit: String(request.limit || 100),
+            offset: String(request.offset || 0),
+        };
+        if (request.tenant_id)
+            params.tenant_id = request.tenant_id;
+        if (request.execution_ids)
+            params.execution_ids = request.execution_ids.join(',');
+        if (request.envelope_ids)
+            params.envelope_ids = request.envelope_ids.join(',');
+        if (request.workflow_ids)
+            params.workflow_ids = request.workflow_ids.join(',');
+        if (request.event_types)
+            params.event_types = request.event_types.join(',');
+        if (request.start_time)
+            params.start_time = request.start_time;
+        if (request.end_time)
+            params.end_time = request.end_time;
+        const response = await this.request('GET', '/v1/events', undefined, params);
+        return response.events;
+    }
+    /**
+     * Get all events for a specific execution.
+     */
+    async getExecutionEvents(executionId, limit = 100, offset = 0) {
+        const params = {
+            limit: String(limit),
+            offset: String(offset),
+        };
+        const response = await this.request('GET', `/v1/executions/${executionId}/events`, undefined, params);
+        return response.events;
+    }
+    /**
+     * Get event store statistics.
+     */
+    async getStats() {
+        const response = await this.request('GET', '/v1/events/stats');
+        return response.stats;
+    }
+}
+exports.EventStoreClient = EventStoreClient;

package/dist/clients/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fulcrum SDK REST Clients
+ *
+ * These clients provide REST-based access to Fulcrum Dashboard APIs
+ * for managing policies, approvals, budgets, checkpoints, and other resources.
+ */
+export { PolicyClient, PolicyClientError, type Policy, type PolicyFilter, type CreatePolicyRequest, type UpdatePolicyRequest, type PolicyClientOptions, } from './policy';
+export { ApprovalClient, ApprovalClientError, type Approval, type ApprovalFilter, type ApprovalDecision, type ApprovalClientOptions, } from './approval';
+export { BudgetClient, BudgetClientError, type Budget, type BudgetSummary, type BudgetsResponse, type BudgetFilter, type CreateBudgetRequest, type UpdateBudgetRequest, type BudgetClientOptions, type BudgetScope, type BudgetPeriod, type BudgetAction, type BudgetStatus, type CostSummary, type SpendSummary, type SpendSummaryOptions, type SpendSummaryResponse, type GroupedSpendSummary, type SpendGroupBy, type BudgetStatusDetail, type PredictCostRequest, type CostPrediction, type ModelCostPrediction, } from './budget';
+export { MetricsClient, MetricsClientError, type PublicMetrics, type CognitiveLayerMetrics, type AuditLogEntry, type AuditLogsResponse, type AuditLogPagination, type AuditLogActor, type AuditLogFilter, type ResourceType, type MetricsClientOptions, } from './metrics';
+export { CheckpointClient, CheckpointClientError, type Checkpoint, type CheckpointMetadata, type CheckpointVersion, type CheckpointData, type CheckpointQuery, type CheckpointType, type ContextScope, type MergeStrategy, type ExecutionContext, type SaveCheckpointRequest, type SaveCheckpointResponse, type ListCheckpointsOptions, type ListCheckpointsResponse, type ListVersionsResponse, type UpdateContextRequest, type UpdateContextResponse, type CheckpointClientOptions, } from './checkpoint';
+export { EventStoreClient, EventStoreClientError, type StoredEvent, type EventStoreStats, type PublishEventRequest, type QueryEventsRequest, type EventStoreClientOptions, } from './eventstore';
+export { EnvelopeClient, EnvelopeClientError, type EnvelopeData, type EnvelopeStatus, type CreateEnvelopeRequest, type UpdateEnvelopeStatusRequest, type ListEnvelopesRequest, type EnvelopeClientOptions, } from './envelope';
+export { TenantClient, TenantClientError, type ApiKey, type CreateApiKeyRequest, type CreateApiKeyResponse, type ListApiKeysRequest, type ListApiKeysResponse, type TenantClientOptions, } from './tenant';
+export { AgentClient, type Agent, type CreateAgentRequest, type UpdateAgentRequest, type ListAgentsRequest, type ListAgentsResponse, } from './agent';

package/dist/clients/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Fulcrum SDK REST Clients
+ *
+ * These clients provide REST-based access to Fulcrum Dashboard APIs
+ * for managing policies, approvals, budgets, checkpoints, and other resources.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentClient = exports.TenantClientError = exports.TenantClient = exports.EnvelopeClientError = exports.EnvelopeClient = exports.EventStoreClientError = exports.EventStoreClient = exports.CheckpointClientError = exports.CheckpointClient = exports.MetricsClientError = exports.MetricsClient = exports.BudgetClientError = exports.BudgetClient = exports.ApprovalClientError = exports.ApprovalClient = exports.PolicyClientError = exports.PolicyClient = void 0;
+var policy_1 = require("./policy");
+Object.defineProperty(exports, "PolicyClient", { enumerable: true, get: function () { return policy_1.PolicyClient; } });
+Object.defineProperty(exports, "PolicyClientError", { enumerable: true, get: function () { return policy_1.PolicyClientError; } });
+var approval_1 = require("./approval");
+Object.defineProperty(exports, "ApprovalClient", { enumerable: true, get: function () { return approval_1.ApprovalClient; } });
+Object.defineProperty(exports, "ApprovalClientError", { enumerable: true, get: function () { return approval_1.ApprovalClientError; } });
+var budget_1 = require("./budget");
+Object.defineProperty(exports, "BudgetClient", { enumerable: true, get: function () { return budget_1.BudgetClient; } });
+Object.defineProperty(exports, "BudgetClientError", { enumerable: true, get: function () { return budget_1.BudgetClientError; } });
+var metrics_1 = require("./metrics");
+Object.defineProperty(exports, "MetricsClient", { enumerable: true, get: function () { return metrics_1.MetricsClient; } });
+Object.defineProperty(exports, "MetricsClientError", { enumerable: true, get: function () { return metrics_1.MetricsClientError; } });
+var checkpoint_1 = require("./checkpoint");
+Object.defineProperty(exports, "CheckpointClient", { enumerable: true, get: function () { return checkpoint_1.CheckpointClient; } });
+Object.defineProperty(exports, "CheckpointClientError", { enumerable: true, get: function () { return checkpoint_1.CheckpointClientError; } });
+var eventstore_1 = require("./eventstore");
+Object.defineProperty(exports, "EventStoreClient", { enumerable: true, get: function () { return eventstore_1.EventStoreClient; } });
+Object.defineProperty(exports, "EventStoreClientError", { enumerable: true, get: function () { return eventstore_1.EventStoreClientError; } });
+var envelope_1 = require("./envelope");
+Object.defineProperty(exports, "EnvelopeClient", { enumerable: true, get: function () { return envelope_1.EnvelopeClient; } });
+Object.defineProperty(exports, "EnvelopeClientError", { enumerable: true, get: function () { return envelope_1.EnvelopeClientError; } });
+var tenant_1 = require("./tenant");
+Object.defineProperty(exports, "TenantClient", { enumerable: true, get: function () { return tenant_1.TenantClient; } });
+Object.defineProperty(exports, "TenantClientError", { enumerable: true, get: function () { return tenant_1.TenantClientError; } });
+var agent_1 = require("./agent");
+Object.defineProperty(exports, "AgentClient", { enumerable: true, get: function () { return agent_1.AgentClient; } });

package/dist/clients/metrics.d.ts

@@ -0,0 +1,126 @@
+/**
+ * MetricsClient - REST-based client for observability and metrics operations
+ *
+ * Works with the Fulcrum Dashboard REST API for retrieving metrics and audit logs.
+ */
+export interface CognitiveLayerMetrics {
+    semanticJudgeRequests: number;
+    semanticJudgeViolations: number;
+    oraclePredictions: number;
+    oracleSavings: number;
+    immunePoliciesGenerated: number;
+}
+export interface PublicMetrics {
+    lastUpdated: string;
+    policiesEvaluated24h: number;
+    avgLatencyMs: number;
+    budgetAlerts24h: number;
+    activeTenants: number;
+    blockedRequests24h: number;
+    cognitiveLayer: CognitiveLayerMetrics;
+}
+export type ResourceType = 'User' | 'Policy' | 'Budget' | 'APIKey' | 'Workflow' | 'Envelope' | 'Approval';
+export interface AuditLogEntry {
+    id: string;
+    org_id: string;
+    timestamp: string;
+    actor_id: string;
+    actor_email: string;
+    action: string;
+    resource_type: ResourceType;
+    resource_id?: string;
+    resource_name?: string;
+    changes?: Record<string, {
+        old: unknown;
+        new: unknown;
+    }>;
+    ip_address?: string;
+    user_agent?: string;
+    status: 'success' | 'failure';
+    error_message?: string;
+}
+export interface AuditLogPagination {
+    page: number;
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+}
+export interface AuditLogActor {
+    id: string;
+    email: string;
+}
+export interface AuditLogsResponse {
+    logs: AuditLogEntry[];
+    pagination: AuditLogPagination;
+    actors: AuditLogActor[];
+}
+export interface AuditLogFilter {
+    user_id?: string;
+    resource_type?: ResourceType;
+    start_date?: string;
+    end_date?: string;
+    search?: string;
+    page?: number;
+    page_size?: number;
+}
+export interface MetricsClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    timeoutMs?: number;
+}
+export declare class MetricsClient {
+    private baseUrl;
+    private apiKey?;
+    private timeoutMs;
+    constructor(options: MetricsClientOptions);
+    private request;
+    /**
+     * Get public metrics (no authentication required)
+     * Returns 24h aggregated metrics including cognitive layer stats
+     */
+    getPublicMetrics(): Promise<PublicMetrics>;
+    /**
+     * Get just the cognitive layer metrics
+     */
+    getCognitiveMetrics(): Promise<CognitiveLayerMetrics>;
+    /**
+     * Get average latency in milliseconds
+     */
+    getAverageLatency(): Promise<number>;
+    /**
+     * Get 24h policy evaluation count
+     */
+    getPolicyEvaluationCount(): Promise<number>;
+    /**
+     * Get audit logs with filtering and pagination
+     */
+    getAuditLogs(filter?: AuditLogFilter): Promise<AuditLogsResponse>;
+    /**
+     * Get only the audit log entries
+     */
+    listAuditLogs(filter?: AuditLogFilter): Promise<AuditLogEntry[]>;
+    /**
+     * Get audit logs for a specific resource type
+     */
+    getLogsByResourceType(resourceType: ResourceType, page?: number): Promise<AuditLogEntry[]>;
+    /**
+     * Get audit logs for a specific user
+     */
+    getLogsByUser(userId: string, page?: number): Promise<AuditLogEntry[]>;
+    /**
+     * Get audit logs within a date range
+     */
+    getLogsByDateRange(startDate: Date, endDate: Date, page?: number): Promise<AuditLogEntry[]>;
+    /**
+     * Search audit logs by text
+     */
+    searchAuditLogs(searchTerm: string, page?: number): Promise<AuditLogEntry[]>;
+    /**
+     * Get the list of unique actors from audit logs
+     */
+    getAuditLogActors(): Promise<AuditLogActor[]>;
+}
+export declare class MetricsClientError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}

package/dist/clients/metrics.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * MetricsClient - REST-based client for observability and metrics operations
+ *
+ * Works with the Fulcrum Dashboard REST API for retrieving metrics and audit logs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsClientError = exports.MetricsClient = void 0;
+class MetricsClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.apiKey = options.apiKey;
+        this.timeoutMs = options.timeoutMs || 5000;
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            if (this.apiKey) {
+                headers['Authorization'] = `Bearer ${this.apiKey}`;
+            }
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorData = (await response.json().catch(() => ({})));
+                throw new MetricsClientError(errorData.error || `Request failed with status ${response.status}`, response.status);
+            }
+            return (await response.json());
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    // =====================
+    // Public Metrics
+    // =====================
+    /**
+     * Get public metrics (no authentication required)
+     * Returns 24h aggregated metrics including cognitive layer stats
+     */
+    async getPublicMetrics() {
+        return this.request('GET', '/api/metrics/public');
+    }
+    /**
+     * Get just the cognitive layer metrics
+     */
+    async getCognitiveMetrics() {
+        const metrics = await this.getPublicMetrics();
+        return metrics.cognitiveLayer;
+    }
+    /**
+     * Get average latency in milliseconds
+     */
+    async getAverageLatency() {
+        const metrics = await this.getPublicMetrics();
+        return metrics.avgLatencyMs;
+    }
+    /**
+     * Get 24h policy evaluation count
+     */
+    async getPolicyEvaluationCount() {
+        const metrics = await this.getPublicMetrics();
+        return metrics.policiesEvaluated24h;
+    }
+    // =====================
+    // Audit Logs
+    // =====================
+    /**
+     * Get audit logs with filtering and pagination
+     */
+    async getAuditLogs(filter) {
+        const params = new URLSearchParams();
+        if (filter?.user_id)
+            params.append('user_id', filter.user_id);
+        if (filter?.resource_type)
+            params.append('resource_type', filter.resource_type);
+        if (filter?.start_date)
+            params.append('start_date', filter.start_date);
+        if (filter?.end_date)
+            params.append('end_date', filter.end_date);
+        if (filter?.search)
+            params.append('search', filter.search);
+        if (filter?.page)
+            params.append('page', String(filter.page));
+        if (filter?.page_size)
+            params.append('page_size', String(filter.page_size));
+        const query = params.toString();
+        const path = query ? `/api/audit-logs?${query}` : '/api/audit-logs';
+        return this.request('GET', path);
+    }
+    /**
+     * Get only the audit log entries
+     */
+    async listAuditLogs(filter) {
+        const response = await this.getAuditLogs(filter);
+        return response.logs;
+    }
+    /**
+     * Get audit logs for a specific resource type
+     */
+    async getLogsByResourceType(resourceType, page) {
+        const response = await this.getAuditLogs({
+            resource_type: resourceType,
+            page,
+        });
+        return response.logs;
+    }
+    /**
+     * Get audit logs for a specific user
+     */
+    async getLogsByUser(userId, page) {
+        const response = await this.getAuditLogs({
+            user_id: userId,
+            page,
+        });
+        return response.logs;
+    }
+    /**
+     * Get audit logs within a date range
+     */
+    async getLogsByDateRange(startDate, endDate, page) {
+        const response = await this.getAuditLogs({
+            start_date: startDate.toISOString(),
+            end_date: endDate.toISOString(),
+            page,
+        });
+        return response.logs;
+    }
+    /**
+     * Search audit logs by text
+     */
+    async searchAuditLogs(searchTerm, page) {
+        const response = await this.getAuditLogs({
+            search: searchTerm,
+            page,
+        });
+        return response.logs;
+    }
+    /**
+     * Get the list of unique actors from audit logs
+     */
+    async getAuditLogActors() {
+        const response = await this.getAuditLogs({ page_size: 1 });
+        return response.actors;
+    }
+}
+exports.MetricsClient = MetricsClient;
+class MetricsClientError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'MetricsClientError';
+    }
+}
+exports.MetricsClientError = MetricsClientError;