@fulcrum-governance/sdk 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -9,8 +9,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Comprehensive test suite with >90% coverage target
+
+## [0.1.3] - 2026-01-22
+
+### Added
+- AgentClient for agent management operations
+- Support for creating, listing, updating, and deleting agents
+- Agent filtering by status, environment, and team
+- Full TypeScript type definitions for all agent operations
+- Pagination support for agent listing with page tokens
+
+### Changed
+- Enhanced SDK with complete agent management capabilities
+- Improved documentation with agent client usage examples
+
+## [0.1.2] - 2026-01-21
+
+### Added
+- EventStoreClient for event management operations
+- EnvelopeClient for execution envelope lifecycle management
+- TenantClient for API key and tenant management
+- Support for querying events by execution, envelope, workflow, and type
+- Batch event publishing capability
+- Envelope status tracking and updates
+- API key creation, listing, and revocation
+- Full TypeScript type definitions for all new services
+
+### Changed
+- Expanded REST client coverage from 30% to 100% of core services
+- Enhanced type safety across all new service clients
+- Improved SDK documentation with comprehensive examples
+
+## [0.1.1] - 2026-01-06
+
+### Changed
+- Updated package metadata and documentation
 - Improved error messages and stack traces
 
+### Fixed
+- Minor bug fixes and improvements
+
 ## [0.1.0] - 2026-01-01
 
 ### Added
@@ -46,6 +84,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Basic gRPC-web connectivity
 - Policy evaluation stub
 
-[Unreleased]: https://github.com/fulcrum-dev/fulcrum/compare/sdk/typescript/v0.1.0...HEAD
+[Unreleased]: https://github.com/fulcrum-dev/fulcrum/compare/sdk/typescript/v0.1.3...HEAD
+[0.1.3]: https://github.com/fulcrum-dev/fulcrum/compare/sdk/typescript/v0.1.2...sdk/typescript/v0.1.3
+[0.1.2]: https://github.com/fulcrum-dev/fulcrum/compare/sdk/typescript/v0.1.1...sdk/typescript/v0.1.2
+[0.1.1]: https://github.com/fulcrum-dev/fulcrum/compare/sdk/typescript/v0.1.0...sdk/typescript/v0.1.1
 [0.1.0]: https://github.com/fulcrum-dev/fulcrum/compare/sdk/typescript/v0.0.1...sdk/typescript/v0.1.0
 [0.0.1]: https://github.com/fulcrum-dev/fulcrum/releases/tag/sdk/typescript/v0.0.1

package/README.md

@@ -357,20 +357,313 @@ interface Checkpoint {
 }
 ```
 
+## REST Clients
+
+The SDK includes REST-based clients for managing Fulcrum resources through the Dashboard API. These clients are ideal for administrative tasks, dashboards, and browser environments.
+
+### PolicyClient
+
+Manage governance policies programmatically:
+
+```typescript
+import { PolicyClient } from '@fulcrum-governance/sdk';
+
+const policyClient = new PolicyClient({
+  baseUrl: 'https://your-fulcrum-dashboard.com',
+  apiKey: 'your-api-key',
+  timeoutMs: 5000  // optional, default: 5000
+});
+
+// List all policies
+const policies = await policyClient.list();
+
+// List with filters
+const activePolicies = await policyClient.list({
+  status: 'active',
+  priority: 'high'
+});
+
+// Get a specific policy
+const policy = await policyClient.get('policy-id');
+
+// Create a new policy
+const newPolicy = await policyClient.create({
+  name: 'No PII in Responses',
+  description: 'Prevents sensitive data exposure',
+  rules: [{ type: 'semantic', pattern: 'pii_detection' }],
+  priority: 1,
+  enabled: true
+});
+
+// Update a policy
+const updated = await policyClient.update('policy-id', {
+  name: 'Updated Policy Name',
+  priority: 2
+});
+
+// Enable/disable policies
+await policyClient.setEnabled('policy-id', false);
+
+// Delete a policy
+await policyClient.delete('policy-id');
+```
+
+### ApprovalClient
+
+Manage human-in-the-loop approval workflows:
+
+```typescript
+import { ApprovalClient } from '@fulcrum-governance/sdk';
+
+const approvalClient = new ApprovalClient({
+  baseUrl: 'https://your-fulcrum-dashboard.com',
+  apiKey: 'your-api-key'
+});
+
+// List all pending approvals
+const pending = await approvalClient.listPending();
+
+// List with filters
+const approvals = await approvalClient.list({
+  status: 'pending',
+  workflow_id: 'customer-support-bot'
+});
+
+// Get approval details
+const approval = await approvalClient.get('approval-id');
+
+// Approve a request
+await approvalClient.approve('approval-id', 'Looks safe to proceed');
+
+// Deny a request
+await approvalClient.deny('approval-id', 'Contains sensitive information');
+
+// Generic decision method
+await approvalClient.decide('approval-id', {
+  decision: 'approved',  // or 'denied'
+  comment: 'Reviewed and approved'
+});
+```
+
+### BudgetClient
+
+Manage AI spending budgets and limits:
+
+```typescript
+import { BudgetClient } from '@fulcrum-governance/sdk';
+
+const budgetClient = new BudgetClient({
+  baseUrl: 'https://your-fulcrum-dashboard.com',
+  apiKey: 'your-api-key'
+});
+
+// List all budgets with summary
+const { budgets, summary } = await budgetClient.list();
+console.log(`Total budgets: ${summary.total}`);
+console.log(`Active: ${summary.active}, Exceeded: ${summary.exceeded}`);
+
+// Filter by scope or status
+const tenantBudgets = await budgetClient.listBudgets({ scope: 'TENANT' });
+const exceededBudgets = await budgetClient.getExceeded();
+const warningBudgets = await budgetClient.getWarnings();
+
+// Get a specific budget
+const budget = await budgetClient.get('budget-id');
+
+// Create a new budget
+const newBudget = await budgetClient.create({
+  name: 'Marketing Team Monthly',
+  scope: 'TENANT',           // GLOBAL, TENANT, WORKFLOW, MODEL
+  scope_id: 'tenant-123',
+  limit_amount: 1000,        // in dollars
+  period: 'MONTHLY',         // DAILY, WEEKLY, MONTHLY, QUARTERLY
+  action: 'SOFT_LIMIT',      // WARN, SOFT_LIMIT, HARD_LIMIT
+  alert_thresholds: [50, 75, 90]
+});
+
+// Update budget
+await budgetClient.update('budget-id', {
+  limit_amount: 1500,
+  alert_thresholds: [60, 80, 95]
+});
+
+// Helper methods
+const percentage = budgetClient.calculatePercentage(budget);
+const isNearLimit = budgetClient.isAtThreshold(budget, 80);
+
+// Delete a budget
+await budgetClient.delete('budget-id');
+```
+
+### MetricsClient
+
+Access platform metrics and audit logs:
+
+```typescript
+import { MetricsClient } from '@fulcrum-governance/sdk';
+
+const metricsClient = new MetricsClient({
+  baseUrl: 'https://your-fulcrum-dashboard.com',
+  apiKey: 'your-api-key'  // optional for public metrics
+});
+
+// Public metrics (no auth required)
+const metrics = await metricsClient.getPublicMetrics();
+console.log(`Policies evaluated (24h): ${metrics.policiesEvaluated24h}`);
+console.log(`Avg latency: ${metrics.avgLatencyMs}ms`);
+console.log(`Blocked requests: ${metrics.blockedRequests24h}`);
+
+// Cognitive layer metrics
+const cognitive = await metricsClient.getCognitiveMetrics();
+console.log(`Semantic Judge violations: ${cognitive.semanticJudgeViolations}`);
+console.log(`Oracle savings: $${cognitive.oracleSavings}`);
+
+// Audit logs (auth required)
+const { logs, pagination, actors } = await metricsClient.getAuditLogs({
+  resource_type: 'Policy',
+  start_date: '2026-01-01',
+  end_date: '2026-01-31',
+  page: 1,
+  page_size: 50
+});
+
+// Convenience methods for audit logs
+const policyLogs = await metricsClient.getLogsByResourceType('Policy');
+const userLogs = await metricsClient.getLogsByUser('user-id');
+const recentLogs = await metricsClient.getLogsByDateRange(
+  new Date('2026-01-01'),
+  new Date('2026-01-31')
+);
+const searchResults = await metricsClient.searchAuditLogs('budget exceeded');
+```
+
+### REST Client Types
+
+```typescript
+// Policy types
+interface Policy {
+  id: string;
+  org_id: string;
+  name: string;
+  description: string;
+  rules: PolicyRule[];
+  priority: number;
+  enabled: boolean;
+  status: 'active' | 'inactive' | 'draft';
+  created_at: string;
+  updated_at: string;
+}
+
+// Approval types
+interface Approval {
+  id: string;
+  envelope_id: string;
+  workflow_id: string;
+  action_name: string;
+  input_text: string;
+  status: 'pending' | 'approved' | 'denied' | 'expired';
+  requested_at: string;
+  decided_at?: string;
+  decided_by?: string;
+  comment?: string;
+}
+
+// Budget types
+type BudgetScope = 'GLOBAL' | 'TENANT' | 'WORKFLOW' | 'MODEL';
+type BudgetPeriod = 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY';
+type BudgetAction = 'WARN' | 'SOFT_LIMIT' | 'HARD_LIMIT';
+type BudgetStatus = 'active' | 'warning' | 'exceeded' | 'disabled';
+
+interface Budget {
+  id: string;
+  name: string;
+  scope: BudgetScope;
+  scope_id: string | null;
+  limit_amount: number;
+  current_spend: number;
+  period: BudgetPeriod;
+  action: BudgetAction;
+  status: BudgetStatus;
+  percentage: number;
+  alert_thresholds: number[];
+}
+
+// Metrics types
+interface PublicMetrics {
+  lastUpdated: string;
+  policiesEvaluated24h: number;
+  avgLatencyMs: number;
+  budgetAlerts24h: number;
+  activeTenants: number;
+  blockedRequests24h: number;
+  cognitiveLayer: CognitiveLayerMetrics;
+}
+
+interface CognitiveLayerMetrics {
+  semanticJudgeRequests: number;
+  semanticJudgeViolations: number;
+  oraclePredictions: number;
+  oracleSavings: number;
+  immunePoliciesGenerated: number;
+}
+
+type ResourceType = 'User' | 'Policy' | 'Budget' | 'APIKey' | 'Workflow' | 'Envelope' | 'Approval';
+
+interface AuditLogEntry {
+  id: string;
+  timestamp: string;
+  actor_id: string;
+  actor_email: string;
+  action: string;
+  resource_type: ResourceType;
+  resource_id?: string;
+  resource_name?: string;
+  status: 'success' | 'failure';
+  changes?: Record<string, { old: unknown; new: unknown }>;
+}
+```
+
+### Error Handling for REST Clients
+
+Each REST client has its own error class:
+
+```typescript
+import {
+  PolicyClient,
+  PolicyClientError,
+  ApprovalClient,
+  ApprovalClientError,
+  BudgetClient,
+  BudgetClientError,
+  MetricsClient,
+  MetricsClientError
+} from '@fulcrum-governance/sdk';
+
+try {
+  const policy = await policyClient.get('invalid-id');
+} catch (error) {
+  if (error instanceof PolicyClientError) {
+    console.log(`Error: ${error.message}`);
+    console.log(`Status: ${error.statusCode}`);  // e.g., 404, 401, 500
+  }
+}
+```
+
 ## Browser Support
 
-For browser environments, use the REST client:
+For browser environments, use the REST clients which work with the standard `fetch` API:
 
 ```typescript
-import { FulcrumRestClient } from '@fulcrum-governance/sdk/rest';
+import { PolicyClient, BudgetClient, MetricsClient } from '@fulcrum-governance/sdk';
 
-const client = new FulcrumRestClient({
-  baseUrl: 'https://api.fulcrum.dev',
+// REST clients work in browsers
+const policyClient = new PolicyClient({
+  baseUrl: 'https://your-fulcrum-dashboard.com',
   apiKey: 'your-api-key'
 });
 
-// Same API as gRPC client
-const envelope = client.envelope({ workflowId: 'browser-agent' });
+// For real-time governance (gRPC), use the REST envelope wrapper
+// (Coming soon)
 ```
 
 ## Documentation

package/dist/__tests__/clients.test.d.ts

@@ -0,0 +1 @@
+export {};