@fulcrum-governance/sdk 0.1.1 → 0.1.3

package/dist/clients/budget.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * BudgetClient - REST-based client for budget management operations
+ *
+ * Works with the Fulcrum Dashboard REST API for managing budgets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgetClientError = exports.BudgetClient = void 0;
+class BudgetClient {
+    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 BudgetClientError(errorData.error || `Request failed with status ${response.status}`, response.status);
+            }
+            return (await response.json());
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * List all budgets with optional filter
+     * Returns budgets and summary statistics
+     */
+    async list(filter) {
+        const params = new URLSearchParams();
+        if (filter?.scope)
+            params.append('scope', filter.scope);
+        if (filter?.status)
+            params.append('status', filter.status);
+        const query = params.toString();
+        const path = query ? `/api/budgets?${query}` : '/api/budgets';
+        return this.request('GET', path);
+    }
+    /**
+     * Get budgets only (without summary)
+     */
+    async listBudgets(filter) {
+        const response = await this.list(filter);
+        return response.budgets;
+    }
+    /**
+     * Get budget summary only
+     */
+    async getSummary() {
+        const response = await this.list();
+        return response.summary;
+    }
+    /**
+     * Get a single budget by ID
+     */
+    async get(id) {
+        return this.request('GET', `/api/budgets/${id}`);
+    }
+    /**
+     * Create a new budget
+     */
+    async create(budget) {
+        const response = await this.request('POST', '/api/budgets', budget);
+        return response.budget;
+    }
+    /**
+     * Update an existing budget
+     */
+    async update(id, updates) {
+        return this.request('PATCH', `/api/budgets/${id}`, updates);
+    }
+    /**
+     * Delete a budget
+     */
+    async delete(id) {
+        await this.request('DELETE', `/api/budgets/${id}`);
+    }
+    /**
+     * Get budgets that have exceeded their limits
+     */
+    async getExceeded() {
+        const response = await this.list({ status: 'exceeded' });
+        return response.budgets;
+    }
+    /**
+     * Get budgets in warning state
+     */
+    async getWarnings() {
+        const response = await this.list({ status: 'warning' });
+        return response.budgets;
+    }
+    /**
+     * Calculate spending percentage for a budget
+     */
+    calculatePercentage(budget) {
+        if (budget.limit_amount <= 0)
+            return 0;
+        return Math.round((budget.current_spend / budget.limit_amount) * 100);
+    }
+    /**
+     * Check if budget is at or above a threshold
+     */
+    isAtThreshold(budget, threshold) {
+        const percentage = this.calculatePercentage(budget);
+        return percentage >= threshold;
+    }
+    // ===== Cost Service Methods =====
+    /**
+     * Get cost summary for a specific execution envelope
+     */
+    async getCostSummary(envelopeId) {
+        const response = await this.request('GET', `/v1/costs/${envelopeId}`);
+        return 'cost_summary' in response && response.cost_summary
+            ? response.cost_summary
+            : response;
+    }
+    /**
+     * Get aggregated spend summary with optional filtering and grouping
+     */
+    async getSpendSummary(options) {
+        const params = new URLSearchParams();
+        if (options?.tenantId)
+            params.append('tenant_id', options.tenantId);
+        if (options?.workflowId)
+            params.append('workflow_id', options.workflowId);
+        if (options?.startTime)
+            params.append('start_time', options.startTime);
+        if (options?.endTime)
+            params.append('end_time', options.endTime);
+        if (options?.groupBy)
+            params.append('group_by', options.groupBy);
+        const query = params.toString();
+        const path = query ? `/v1/spend?${query}` : '/v1/spend';
+        return this.request('GET', path);
+    }
+    /**
+     * Get detailed status for a budget including usage percentages
+     */
+    async getBudgetStatus(budgetId) {
+        const response = await this.request('GET', `/v1/budgets/${budgetId}/status`);
+        if (response.status) {
+            return response.status;
+        }
+        // If response doesn't have status wrapper, treat response as the status itself
+        return response;
+    }
+    /**
+     * Predict cost for a planned execution
+     */
+    async predictCost(request) {
+        const response = await this.request('POST', '/v1/costs/predict', request);
+        return 'prediction' in response && response.prediction
+            ? response.prediction
+            : response;
+    }
+}
+exports.BudgetClient = BudgetClient;
+class BudgetClientError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'BudgetClientError';
+    }
+}
+exports.BudgetClientError = BudgetClientError;

package/dist/clients/checkpoint.d.ts

@@ -0,0 +1,191 @@
+/**
+ * CheckpointClient - REST-based client for checkpoint management operations
+ *
+ * Works with the Fulcrum API for managing execution checkpoints and context.
+ */
+export type CheckpointType = 'UNSPECIFIED' | 'MANUAL' | 'AUTO' | 'PRE_TERMINATE' | 'ERROR' | 'MILESTONE';
+export type ContextScope = 'UNSPECIFIED' | 'EXECUTION' | 'WORKFLOW' | 'TENANT';
+export type MergeStrategy = 'UNSPECIFIED' | 'LAST_WRITE_WINS' | 'FAIL_ON_CONFLICT' | 'MERGE_RECURSIVE' | 'CUSTOM';
+export interface CheckpointMetadata {
+    type: CheckpointType;
+    framework_type: string;
+    framework_version: string;
+    execution_status: string;
+    step_count: number;
+    current_node: string;
+    cost_snapshot_usd: number;
+    tokens_consumed: number;
+    tags: Record<string, string>;
+    description: string;
+    compressed: boolean;
+    compression_algorithm: string;
+}
+export interface Checkpoint {
+    checkpoint_id: string;
+    envelope_id: string;
+    execution_id: string;
+    tenant_id: string;
+    version: number;
+    parent_version: string;
+    metadata?: CheckpointMetadata;
+    data: Record<string, unknown>;
+    created_at: string;
+    expires_at?: string;
+    size_bytes: number;
+    save_duration_ms: number;
+}
+export interface CheckpointVersion {
+    checkpoint_id: string;
+    version: number;
+    parent_version: string;
+    created_at: string;
+    metadata?: CheckpointMetadata;
+    size_bytes: number;
+}
+export interface ExecutionContext {
+    execution_id: string;
+    tenant_id: string;
+    workflow_id: string;
+    scope: ContextScope;
+    data: Record<string, unknown>;
+    parent_execution_id: string;
+    inherited_keys: string[];
+    version: number;
+    updated_at: string;
+}
+export interface CheckpointData {
+    envelope_id: string;
+    execution_id: string;
+    tenant_id: string;
+    data: Record<string, unknown>;
+    metadata?: Partial<CheckpointMetadata>;
+}
+export interface SaveCheckpointRequest {
+    checkpoint: CheckpointData;
+    auto_version?: boolean;
+    max_versions?: number;
+}
+export interface SaveCheckpointResponse {
+    checkpoint_id: string;
+    version: number;
+    created_at: string;
+}
+export interface CheckpointQuery {
+    tenant_ids?: string[];
+    envelope_ids?: string[];
+    execution_ids?: string[];
+    types?: CheckpointType[];
+    created_after?: string;
+    created_before?: string;
+    framework_types?: string[];
+    tags?: Record<string, string>;
+    min_cost_usd?: number;
+    max_cost_usd?: number;
+    min_size_bytes?: number;
+    max_size_bytes?: number;
+}
+export interface ListCheckpointsOptions {
+    tenant_id?: string;
+    envelope_id?: string;
+    execution_id?: string;
+    page_size?: number;
+    page_token?: string;
+    order_by?: string;
+}
+export interface ListCheckpointsResponse {
+    checkpoints: Checkpoint[];
+    next_page_token: string;
+    total_count: number;
+}
+export interface ListVersionsResponse {
+    versions: CheckpointVersion[];
+    next_page_token: string;
+    total_count: number;
+}
+export interface UpdateContextRequest {
+    updates: Record<string, unknown>;
+    delete_keys?: string[];
+    expected_version?: number;
+    merge_strategy?: MergeStrategy;
+}
+export interface UpdateContextResponse {
+    context: ExecutionContext | null;
+    conflict_detected: boolean;
+    conflict_resolution: string;
+}
+export interface CheckpointClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    timeoutMs?: number;
+}
+export declare class CheckpointClient {
+    private baseUrl;
+    private apiKey?;
+    private timeoutMs;
+    constructor(options: CheckpointClientOptions);
+    private request;
+    /**
+     * Save a new checkpoint
+     */
+    saveCheckpoint(request: SaveCheckpointRequest): Promise<SaveCheckpointResponse>;
+    /**
+     * Get a checkpoint by ID
+     */
+    getCheckpoint(checkpointId: string, version?: number): Promise<Checkpoint>;
+    /**
+     * List checkpoints with optional filtering
+     */
+    listCheckpoints(options?: ListCheckpointsOptions): Promise<ListCheckpointsResponse>;
+    /**
+     * Delete a checkpoint
+     */
+    deleteCheckpoint(checkpointId: string, options?: {
+        softDelete?: boolean;
+        deleteAllVersions?: boolean;
+    }): Promise<{
+        success: boolean;
+        versions_deleted: number;
+    }>;
+    /**
+     * List all versions of checkpoints for an execution
+     */
+    listCheckpointVersions(executionId: string, options?: {
+        pageSize?: number;
+        pageToken?: string;
+    }): Promise<ListVersionsResponse>;
+    /**
+     * Get a specific version of a checkpoint
+     */
+    getCheckpointVersion(executionId: string, version: number): Promise<Checkpoint>;
+    /**
+     * Query checkpoints with advanced filtering
+     */
+    queryCheckpoints(query: CheckpointQuery, options?: {
+        pageSize?: number;
+        pageToken?: string;
+        orderBy?: string;
+    }): Promise<ListCheckpointsResponse>;
+    /**
+     * Get execution context (shared state)
+     */
+    getExecutionContext(executionId: string, options?: {
+        keys?: string[];
+        includeInherited?: boolean;
+    }): Promise<ExecutionContext>;
+    /**
+     * Update execution context with merge/conflict handling
+     */
+    updateExecutionContext(executionId: string, request: UpdateContextRequest): Promise<UpdateContextResponse>;
+    /**
+     * Get the most recent checkpoint for an execution
+     */
+    getLatestCheckpoint(executionId: string): Promise<Checkpoint | null>;
+    /**
+     * Check if any checkpoint exists for an execution
+     */
+    checkpointExists(executionId: string): Promise<boolean>;
+}
+export declare class CheckpointClientError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}

package/dist/clients/checkpoint.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * CheckpointClient - REST-based client for checkpoint management operations
+ *
+ * Works with the Fulcrum API for managing execution checkpoints and context.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckpointClientError = exports.CheckpointClient = void 0;
+class CheckpointClient {
+    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 CheckpointClientError(errorData.error || `Request failed with status ${response.status}`, response.status);
+            }
+            const text = await response.text();
+            return text ? JSON.parse(text) : {};
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * Save a new checkpoint
+     */
+    async saveCheckpoint(request) {
+        return this.request('POST', '/v1/checkpoints', request);
+    }
+    /**
+     * Get a checkpoint by ID
+     */
+    async getCheckpoint(checkpointId, version) {
+        const params = new URLSearchParams();
+        if (version !== undefined)
+            params.append('version', version.toString());
+        const query = params.toString();
+        const path = query
+            ? `/v1/checkpoints/${checkpointId}?${query}`
+            : `/v1/checkpoints/${checkpointId}`;
+        const response = await this.request('GET', path);
+        return 'checkpoint' in response && response.checkpoint
+            ? response.checkpoint
+            : response;
+    }
+    /**
+     * List checkpoints with optional filtering
+     */
+    async listCheckpoints(options) {
+        const params = new URLSearchParams();
+        if (options?.tenant_id)
+            params.append('tenant_id', options.tenant_id);
+        if (options?.envelope_id)
+            params.append('envelope_id', options.envelope_id);
+        if (options?.execution_id)
+            params.append('execution_id', options.execution_id);
+        if (options?.page_size)
+            params.append('page_size', options.page_size.toString());
+        if (options?.page_token)
+            params.append('page_token', options.page_token);
+        if (options?.order_by)
+            params.append('order_by', options.order_by);
+        const query = params.toString();
+        const path = query ? `/v1/checkpoints?${query}` : '/v1/checkpoints';
+        return this.request('GET', path);
+    }
+    /**
+     * Delete a checkpoint
+     */
+    async deleteCheckpoint(checkpointId, options) {
+        const params = new URLSearchParams();
+        if (options?.softDelete)
+            params.append('soft_delete', 'true');
+        if (options?.deleteAllVersions)
+            params.append('delete_all_versions', 'true');
+        const query = params.toString();
+        const path = query
+            ? `/v1/checkpoints/${checkpointId}?${query}`
+            : `/v1/checkpoints/${checkpointId}`;
+        const response = await this.request('DELETE', path);
+        return {
+            success: response?.success ?? true,
+            versions_deleted: response?.versions_deleted ?? 1,
+        };
+    }
+    /**
+     * List all versions of checkpoints for an execution
+     */
+    async listCheckpointVersions(executionId, options) {
+        const params = new URLSearchParams();
+        if (options?.pageSize)
+            params.append('page_size', options.pageSize.toString());
+        if (options?.pageToken)
+            params.append('page_token', options.pageToken);
+        const query = params.toString();
+        const path = query
+            ? `/v1/checkpoints/${executionId}/versions?${query}`
+            : `/v1/checkpoints/${executionId}/versions`;
+        return this.request('GET', path);
+    }
+    /**
+     * Get a specific version of a checkpoint
+     */
+    async getCheckpointVersion(executionId, version) {
+        const response = await this.request('GET', `/v1/checkpoints/${executionId}/versions/${version}`);
+        return 'checkpoint' in response && response.checkpoint
+            ? response.checkpoint
+            : response;
+    }
+    /**
+     * Query checkpoints with advanced filtering
+     */
+    async queryCheckpoints(query, options) {
+        const body = {
+            query,
+            page_size: options?.pageSize ?? 20,
+            page_token: options?.pageToken,
+            order_by: options?.orderBy,
+        };
+        return this.request('POST', '/v1/checkpoints:query', body);
+    }
+    /**
+     * Get execution context (shared state)
+     */
+    async getExecutionContext(executionId, options) {
+        const params = new URLSearchParams();
+        if (options?.keys?.length)
+            params.append('keys', options.keys.join(','));
+        if (options?.includeInherited)
+            params.append('include_inherited', 'true');
+        const query = params.toString();
+        const path = query
+            ? `/v1/executions/${executionId}/context?${query}`
+            : `/v1/executions/${executionId}/context`;
+        const response = await this.request('GET', path);
+        return 'context' in response && response.context
+            ? response.context
+            : response;
+    }
+    /**
+     * Update execution context with merge/conflict handling
+     */
+    async updateExecutionContext(executionId, request) {
+        return this.request('PATCH', `/v1/executions/${executionId}/context`, request);
+    }
+    // ===== Convenience Methods =====
+    /**
+     * Get the most recent checkpoint for an execution
+     */
+    async getLatestCheckpoint(executionId) {
+        const response = await this.listCheckpoints({
+            execution_id: executionId,
+            page_size: 1,
+            order_by: 'created_at desc',
+        });
+        return response.checkpoints.length > 0 ? response.checkpoints[0] : null;
+    }
+    /**
+     * Check if any checkpoint exists for an execution
+     */
+    async checkpointExists(executionId) {
+        const response = await this.listCheckpoints({
+            execution_id: executionId,
+            page_size: 1,
+        });
+        return response.total_count > 0;
+    }
+}
+exports.CheckpointClient = CheckpointClient;
+class CheckpointClientError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'CheckpointClientError';
+    }
+}
+exports.CheckpointClientError = CheckpointClientError;

package/dist/clients/envelope.d.ts

@@ -0,0 +1,73 @@
+/**
+ * EnvelopeClient - REST-based client for envelope management
+ *
+ * Works with the Fulcrum API for managing execution envelopes that wrap AI agent operations.
+ */
+export type EnvelopeStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT';
+export interface EnvelopeData {
+    envelope_id: string;
+    tenant_id: string;
+    budget_id?: string;
+    adapter_type: string;
+    workflow_id: string;
+    status: EnvelopeStatus;
+    metadata: Record<string, string>;
+    created_at: string;
+    updated_at: string;
+    completed_at?: string;
+    cost_usd: number;
+    token_count: number;
+    error_message?: string;
+}
+export interface CreateEnvelopeRequest {
+    tenant_id: string;
+    adapter_type: string;
+    workflow_id: string;
+    budget_id?: string;
+    metadata?: Record<string, string>;
+}
+export interface UpdateEnvelopeStatusRequest {
+    envelope_id: string;
+    status: EnvelopeStatus;
+    error_message?: string;
+}
+export interface ListEnvelopesRequest {
+    tenant_id?: string;
+    workflow_id?: string;
+    status?: EnvelopeStatus;
+    limit?: number;
+    offset?: number;
+}
+export declare class EnvelopeClientError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+export interface EnvelopeClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+}
+export declare class EnvelopeClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    constructor(options: EnvelopeClientOptions);
+    private request;
+    /**
+     * Create a new execution envelope.
+     */
+    create(request: CreateEnvelopeRequest): Promise<EnvelopeData>;
+    /**
+     * Get an envelope by ID.
+     */
+    get(envelopeId: string): Promise<EnvelopeData>;
+    /**
+     * Update the status of an envelope.
+     */
+    updateStatus(request: UpdateEnvelopeStatusRequest): Promise<EnvelopeData>;
+    /**
+     * List envelopes with optional filters.
+     */
+    list(request?: ListEnvelopesRequest): Promise<EnvelopeData[]>;
+}