@fulcrum-governance/sdk 0.1.1 → 0.1.3

package/dist/clients/agent.d.ts

@@ -0,0 +1,70 @@
+import * as grpc from '@grpc/grpc-js';
+export interface Agent {
+    id: string;
+    tenant_id: string;
+    name: string;
+    description?: string;
+    model: string;
+    status: 'active' | 'paused' | 'error' | 'deleted';
+    environment: string;
+    team: string;
+    config?: Record<string, any>;
+    created_at: Date;
+    updated_at: Date;
+}
+export interface CreateAgentRequest {
+    name: string;
+    description?: string;
+    model: string;
+    environment: string;
+    team: string;
+    config?: Record<string, any>;
+}
+export interface UpdateAgentRequest {
+    id: string;
+    name?: string;
+    description?: string;
+    status?: 'active' | 'paused' | 'error' | 'deleted';
+    config?: Record<string, any>;
+}
+export interface ListAgentsRequest {
+    page_size?: number;
+    page_token?: string;
+    status?: string;
+    environment?: string;
+    team?: string;
+}
+export interface ListAgentsResponse {
+    agents: Agent[];
+    next_page_token: string;
+    total_count: number;
+}
+export declare class AgentClient {
+    private client;
+    constructor(address: string, credentials?: grpc.ChannelCredentials);
+    /**
+     * Creates a new agent for the authenticated tenant.
+     */
+    createAgent(request: CreateAgentRequest, metadata?: grpc.Metadata): Promise<Agent>;
+    /**
+     * Retrieves an agent by ID.
+     */
+    getAgent(id: string, metadata?: grpc.Metadata): Promise<Agent>;
+    /**
+     * Lists all agents for the authenticated tenant.
+     */
+    listAgents(request?: ListAgentsRequest, metadata?: grpc.Metadata): Promise<ListAgentsResponse>;
+    /**
+     * Updates an existing agent.
+     */
+    updateAgent(request: UpdateAgentRequest, metadata?: grpc.Metadata): Promise<Agent>;
+    /**
+     * Deletes an agent by ID (soft delete).
+     */
+    deleteAgent(id: string, metadata?: grpc.Metadata): Promise<boolean>;
+    private transformAgent;
+    /**
+     * Closes the gRPC connection.
+     */
+    close(): void;
+}

package/dist/clients/agent.js

@@ -0,0 +1,127 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentClient = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const util_1 = require("util");
+const path_1 = __importDefault(require("path"));
+const PROTO_PATH = path_1.default.join(__dirname, '../../proto/fulcrum/agent/v1/agent_service.proto');
+const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+    keepCase: true,
+    longs: String,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+});
+const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
+const fulcrumPackage = protoDescriptor.fulcrum;
+const agentPackage = fulcrumPackage.agent;
+const agentV1 = agentPackage.v1;
+class AgentClient {
+    constructor(address, credentials) {
+        const creds = credentials || grpc.credentials.createInsecure();
+        this.client = new agentV1.AgentService(address, creds);
+    }
+    /**
+     * Creates a new agent for the authenticated tenant.
+     */
+    async createAgent(request, metadata) {
+        const createAgentAsync = (0, util_1.promisify)(this.client.createAgent.bind(this.client));
+        const response = await createAgentAsync(request, metadata);
+        return this.transformAgent(response.agent);
+    }
+    /**
+     * Retrieves an agent by ID.
+     */
+    async getAgent(id, metadata) {
+        const getAgentAsync = (0, util_1.promisify)(this.client.getAgent.bind(this.client));
+        const response = await getAgentAsync({ id }, metadata);
+        return this.transformAgent(response.agent);
+    }
+    /**
+     * Lists all agents for the authenticated tenant.
+     */
+    async listAgents(request, metadata) {
+        const listAgentsAsync = (0, util_1.promisify)(this.client.listAgents.bind(this.client));
+        const response = await listAgentsAsync(request || {}, metadata);
+        return {
+            agents: response.agents.map((a) => this.transformAgent(a)),
+            next_page_token: response.next_page_token,
+            total_count: response.total_count,
+        };
+    }
+    /**
+     * Updates an existing agent.
+     */
+    async updateAgent(request, metadata) {
+        const updateAgentAsync = (0, util_1.promisify)(this.client.updateAgent.bind(this.client));
+        const response = await updateAgentAsync(request, metadata);
+        return this.transformAgent(response.agent);
+    }
+    /**
+     * Deletes an agent by ID (soft delete).
+     */
+    async deleteAgent(id, metadata) {
+        const deleteAgentAsync = (0, util_1.promisify)(this.client.deleteAgent.bind(this.client));
+        const response = await deleteAgentAsync({ id }, metadata);
+        return response.success;
+    }
+    transformAgent(agent) {
+        return {
+            id: agent.id,
+            tenant_id: agent.tenant_id,
+            name: agent.name,
+            description: agent.description,
+            model: agent.model,
+            status: agent.status,
+            environment: agent.environment,
+            team: agent.team,
+            config: agent.config,
+            created_at: new Date(agent.created_at),
+            updated_at: new Date(agent.updated_at),
+        };
+    }
+    /**
+     * Closes the gRPC connection.
+     */
+    close() {
+        this.client.close();
+    }
+}
+exports.AgentClient = AgentClient;

package/dist/clients/approval.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ApprovalClient - REST-based client for approval workflow operations
+ *
+ * Works with the Fulcrum Dashboard REST API for managing approval requests.
+ */
+export interface Approval {
+    id: string;
+    envelope_id: string;
+    status: 'PENDING' | 'APPROVED' | 'DENIED';
+    reviewer_id?: string;
+    review_note?: string;
+    created_at?: string;
+    updated_at?: string;
+    policy_id?: string;
+    policy_name?: string;
+    action_type?: string;
+    request_data?: Record<string, unknown>;
+}
+export interface ApprovalFilter {
+    status?: 'PENDING' | 'APPROVED' | 'DENIED';
+    envelope_id?: string;
+}
+export interface ApprovalDecision {
+    approval_id: string;
+    decision: 'APPROVED' | 'DENIED';
+    comment?: string;
+}
+export interface ApprovalClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    timeoutMs?: number;
+}
+export declare class ApprovalClient {
+    private baseUrl;
+    private apiKey?;
+    private timeoutMs;
+    constructor(options: ApprovalClientOptions);
+    private request;
+    /**
+     * List approvals, optionally filtered by status
+     */
+    list(filter?: ApprovalFilter): Promise<Approval[]>;
+    /**
+     * List only pending approvals
+     */
+    listPending(): Promise<Approval[]>;
+    /**
+     * Get a single approval by ID
+     */
+    get(id: string): Promise<Approval>;
+    /**
+     * Submit an approval decision (approve or deny)
+     */
+    decide(decision: ApprovalDecision): Promise<Approval>;
+    /**
+     * Approve a pending action
+     */
+    approve(approvalId: string, comment?: string): Promise<Approval>;
+    /**
+     * Deny a pending action
+     */
+    deny(approvalId: string, comment: string): Promise<Approval>;
+}
+export declare class ApprovalClientError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}

package/dist/clients/approval.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * ApprovalClient - REST-based client for approval workflow operations
+ *
+ * Works with the Fulcrum Dashboard REST API for managing approval requests.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalClientError = exports.ApprovalClient = void 0;
+class ApprovalClient {
+    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 ApprovalClientError(errorData.error || `Request failed with status ${response.status}`, response.status);
+            }
+            return (await response.json());
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * List approvals, optionally filtered by status
+     */
+    async list(filter) {
+        const params = new URLSearchParams();
+        if (filter?.status)
+            params.append('status', filter.status);
+        if (filter?.envelope_id)
+            params.append('envelope_id', filter.envelope_id);
+        const query = params.toString();
+        const path = query ? `/api/approvals?${query}` : '/api/approvals';
+        const response = await this.request('GET', path);
+        return response.approvals;
+    }
+    /**
+     * List only pending approvals
+     */
+    async listPending() {
+        return this.list({ status: 'PENDING' });
+    }
+    /**
+     * Get a single approval by ID
+     */
+    async get(id) {
+        return this.request('GET', `/api/approvals/${id}`);
+    }
+    /**
+     * Submit an approval decision (approve or deny)
+     */
+    async decide(decision) {
+        const response = await this.request('POST', '/api/approvals', decision);
+        return response.approval;
+    }
+    /**
+     * Approve a pending action
+     */
+    async approve(approvalId, comment) {
+        return this.decide({
+            approval_id: approvalId,
+            decision: 'APPROVED',
+            comment,
+        });
+    }
+    /**
+     * Deny a pending action
+     */
+    async deny(approvalId, comment) {
+        return this.decide({
+            approval_id: approvalId,
+            decision: 'DENIED',
+            comment,
+        });
+    }
+}
+exports.ApprovalClient = ApprovalClient;
+class ApprovalClientError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'ApprovalClientError';
+    }
+}
+exports.ApprovalClientError = ApprovalClientError;

package/dist/clients/budget.d.ts

@@ -0,0 +1,221 @@
+/**
+ * BudgetClient - REST-based client for budget management operations
+ *
+ * Works with the Fulcrum Dashboard REST API for managing budgets.
+ */
+export type BudgetScope = 'GLOBAL' | 'TENANT' | 'WORKFLOW' | 'MODEL';
+export type BudgetPeriod = 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY';
+export type BudgetAction = 'WARN' | 'SOFT_LIMIT' | 'HARD_LIMIT';
+export type BudgetStatus = 'active' | 'warning' | 'exceeded' | 'disabled';
+export interface Budget {
+    id: string;
+    org_id: string;
+    name: string;
+    scope: BudgetScope;
+    scope_id: string | null;
+    scope_name?: string;
+    limit_amount: number;
+    period: BudgetPeriod;
+    action: BudgetAction;
+    alert_thresholds: number[];
+    current_spend: number;
+    period_start: string;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+    last_alert_sent: string | null;
+    status: BudgetStatus;
+    percentage: number;
+}
+export interface BudgetSummary {
+    total: number;
+    active: number;
+    exceeded: number;
+    totalLimit: number;
+    totalSpend: number;
+}
+export interface BudgetsResponse {
+    budgets: Budget[];
+    summary: BudgetSummary;
+}
+export interface BudgetFilter {
+    scope?: BudgetScope;
+    status?: BudgetStatus;
+}
+export interface CreateBudgetRequest {
+    name: string;
+    scope: BudgetScope;
+    scope_id?: string;
+    scope_name?: string;
+    limit_amount: number;
+    period: BudgetPeriod;
+    action: BudgetAction;
+    alert_thresholds?: number[];
+}
+export interface UpdateBudgetRequest {
+    name?: string;
+    limit_amount?: number;
+    period?: BudgetPeriod;
+    action?: BudgetAction;
+    alert_thresholds?: number[];
+}
+export interface BudgetClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    timeoutMs?: number;
+}
+export declare class BudgetClient {
+    private baseUrl;
+    private apiKey?;
+    private timeoutMs;
+    constructor(options: BudgetClientOptions);
+    private request;
+    /**
+     * List all budgets with optional filter
+     * Returns budgets and summary statistics
+     */
+    list(filter?: BudgetFilter): Promise<BudgetsResponse>;
+    /**
+     * Get budgets only (without summary)
+     */
+    listBudgets(filter?: BudgetFilter): Promise<Budget[]>;
+    /**
+     * Get budget summary only
+     */
+    getSummary(): Promise<BudgetSummary>;
+    /**
+     * Get a single budget by ID
+     */
+    get(id: string): Promise<Budget>;
+    /**
+     * Create a new budget
+     */
+    create(budget: CreateBudgetRequest): Promise<Budget>;
+    /**
+     * Update an existing budget
+     */
+    update(id: string, updates: UpdateBudgetRequest): Promise<Budget>;
+    /**
+     * Delete a budget
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get budgets that have exceeded their limits
+     */
+    getExceeded(): Promise<Budget[]>;
+    /**
+     * Get budgets in warning state
+     */
+    getWarnings(): Promise<Budget[]>;
+    /**
+     * Calculate spending percentage for a budget
+     */
+    calculatePercentage(budget: Budget): number;
+    /**
+     * Check if budget is at or above a threshold
+     */
+    isAtThreshold(budget: Budget, threshold: number): boolean;
+    /**
+     * Get cost summary for a specific execution envelope
+     */
+    getCostSummary(envelopeId: string): Promise<CostSummary>;
+    /**
+     * Get aggregated spend summary with optional filtering and grouping
+     */
+    getSpendSummary(options?: SpendSummaryOptions): Promise<SpendSummaryResponse>;
+    /**
+     * Get detailed status for a budget including usage percentages
+     */
+    getBudgetStatus(budgetId: string): Promise<BudgetStatusDetail>;
+    /**
+     * Predict cost for a planned execution
+     */
+    predictCost(request: PredictCostRequest): Promise<CostPrediction>;
+}
+export interface CostSummary {
+    total_tokens: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    total_cost_usd: number;
+    total_llm_calls: number;
+    total_tool_calls: number;
+}
+export interface SpendSummary {
+    total_tokens: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    total_cost_usd: number;
+    total_llm_calls: number;
+    total_tool_calls: number;
+    total_executions: number;
+    completed_executions: number;
+    failed_executions: number;
+    terminated_executions: number;
+    total_execution_time_seconds: number;
+    average_execution_time_seconds: number;
+    period_start?: string;
+    period_end?: string;
+}
+export type SpendGroupBy = 'MODEL' | 'DAY' | 'WEEK' | 'MONTH' | 'WORKFLOW';
+export interface SpendSummaryOptions {
+    tenantId?: string;
+    workflowId?: string;
+    startTime?: string;
+    endTime?: string;
+    groupBy?: SpendGroupBy;
+}
+export interface GroupedSpendSummary {
+    group_key: string;
+    summary: SpendSummary;
+}
+export interface SpendSummaryResponse {
+    summary: SpendSummary;
+    grouped_summaries: GroupedSpendSummary[];
+}
+export interface BudgetStatusDetail {
+    budget_id: string;
+    status: string;
+    token_usage_percent: number;
+    cost_usage_percent: number;
+    llm_call_usage_percent: number;
+    tool_call_usage_percent: number;
+    remaining?: {
+        max_tokens?: number;
+        max_cost_usd?: number;
+    };
+    current_spend?: SpendSummary;
+    updated_at?: string;
+}
+export interface PredictCostRequest {
+    tenant_id?: string;
+    workflow_id?: string;
+    input_text?: string;
+    estimated_input_tokens?: number;
+    model_ids?: string[];
+    use_historical_data?: boolean;
+    lookback_days?: number;
+}
+export interface ModelCostPrediction {
+    model_id: string;
+    estimated_tokens: number;
+    estimated_cost_usd: number;
+    estimated_calls: number;
+}
+export interface CostPrediction {
+    estimated_input_tokens: number;
+    estimated_output_tokens: number;
+    estimated_total_tokens: number;
+    estimated_cost_usd: number;
+    estimated_cost_usd_min: number;
+    estimated_cost_usd_max: number;
+    confidence: number;
+    confidence_level: string;
+    estimated_duration_seconds: number;
+    model_predictions: ModelCostPrediction[];
+    historical_based: boolean;
+    sample_size: number;
+}
+export declare class BudgetClientError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}