@fulcrum-governance/sdk 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-06-03
+
+### Fixed
+- Update `PolicyClient` to use the hosted gateway's `/api/v1/policies`
+  path and unwrap `{ policies, total_count }` list responses.
+- Update `EnvelopeClient` to use the `/api/v1/envelopes/*` gateway paths and
+  handle unwrapped REST gateway responses.
+- Allow REST envelope creation without a tenant ID because the hosted gateway
+  derives tenant context from the API key.
+
 ## [0.1.4] - 2026-02-06
 
 ### Changed
@@ -86,7 +96,8 @@ 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-Governance/fulcrum-io/compare/sdk/typescript/v0.1.4...HEAD
+[Unreleased]: https://github.com/Fulcrum-Governance/fulcrum-io/compare/sdk/typescript/v0.1.5...HEAD
+[0.1.5]: https://github.com/Fulcrum-Governance/fulcrum-io/compare/sdk/typescript/v0.1.4...sdk/typescript/v0.1.5
 [0.1.4]: https://github.com/Fulcrum-Governance/fulcrum-io/compare/sdk/typescript/v0.1.3...sdk/typescript/v0.1.4
 [0.1.3]: https://github.com/Fulcrum-Governance/fulcrum-io/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

package/README.md

@@ -14,33 +14,45 @@ npm install @fulcrum-governance/sdk
 
 ## Quick Start
 
+Hosted Fulcrum uses the REST API and `X-API-Key` authentication:
+
 ```typescript
-import { FulcrumClient } from '@fulcrum-governance/sdk';
+import {
+  PolicyClient,
+  EnvelopeClient,
+} from '@fulcrum-governance/sdk';
 
-// Initialize client
-const client = new FulcrumClient({
-  host: 'your-fulcrum-server:50051',
-  apiKey: 'your-api-key',
-  onFailure: 'FAIL_OPEN' // or 'FAIL_CLOSED'
+const apiBase = process.env.FULCRUM_API_BASE || 'https://api.fulcrumlayer.io';
+const apiKey = process.env.FULCRUM_API_KEY!;
+
+const policyClient = new PolicyClient({
+  baseUrl: apiBase,
+  apiKey,
 });
 
-// Wrap agent executions in governance envelopes
-const envelope = client.envelope({
-  workflowId: 'customer-support-bot',
-  tenantId: 'your-tenant-id'
+const policies = await policyClient.list();
+console.log(`Visible policies: ${policies.length}`);
+
+const envelopes = new EnvelopeClient({
+  baseUrl: apiBase,
+  apiKey,
 });
 
-// Check if action is allowed before executing
-const allowed = await envelope.guard('send_email', userMessage);
+const envelope = await envelopes.create({
+  workflow_id: 'customer-support-bot',
+  metadata: { example: 'typescript-sdk' },
+});
 
-if (allowed) {
-  // Action approved - proceed
-  const result = await sendEmail(userMessage);
-  envelope.log('email_sent', { recipient: email, status: 'success' });
-} else {
-  // Action blocked by policy
-  envelope.log('action_blocked', { reason: 'policy_violation' });
-}
+await envelopes.updateStatus({
+  envelope_id: envelope.envelope_id,
+  status: 'RUNNING',
+});
+
+// Run your agent work here, then close the envelope.
+await envelopes.updateStatus({
+  envelope_id: envelope.envelope_id,
+  status: 'COMPLETED',
+});
 ```
 
 ## Features
@@ -72,16 +84,14 @@ const client = new FulcrumClient({
 ### Environment Variables
 
 ```bash
-export FULCRUM_HOST="localhost:50051"
 export FULCRUM_API_KEY="your-api-key"
-export FULCRUM_TENANT_ID="your-tenant-id"
+export FULCRUM_API_BASE="https://api.fulcrumlayer.io"
 export FULCRUM_TIMEOUT_MS="500"
 ```
 
-```typescript
-// Client auto-discovers from environment
-const client = FulcrumClient.fromEnv();
-```
+The lower-level `FulcrumClient` gRPC API is still available for compatible
+self-hosted or direct gRPC deployments. The hosted first-run path uses the REST
+clients above.
 
 ## API Reference
 
@@ -363,13 +373,14 @@ The SDK includes REST-based clients for managing Fulcrum resources through the D
 
 ### PolicyClient
 
-Manage governance policies programmatically:
+List governance policies visible to your API key. Create and edit hosted
+policies in the Fulcrum dashboard before using the API-key gateway.
 
 ```typescript
 import { PolicyClient } from '@fulcrum-governance/sdk';
 
 const policyClient = new PolicyClient({
-  baseUrl: 'https://your-fulcrum-dashboard.com',
+  baseUrl: 'https://api.fulcrumlayer.io',
   apiKey: 'your-api-key',
   timeoutMs: 5000  // optional, default: 5000
 });
@@ -379,33 +390,11 @@ const policies = await policyClient.list();
 
 // List with filters
 const activePolicies = await policyClient.list({
-  status: 'active',
-  priority: 'high'
+  status: 'ACTIVE'
 });
 
 // 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

package/dist/__tests__/clients.test.js

@@ -36,15 +36,35 @@ describe('PolicyClient', () => {
     describe('list', () => {
         it('should fetch policies successfully', async () => {
             const mockPolicies = [
-                { id: '1', name: 'Policy 1', policy_type: 'cost', enabled: true },
-                { id: '2', name: 'Policy 2', policy_type: 'rate', enabled: false },
+                {
+                    id: '1',
+                    name: 'Policy 1',
+                    policy_type: 'cost',
+                    rules: {},
+                    enabled: true,
+                    priority: 0,
+                    status: 'ACTIVE',
+                    created_at: '',
+                    updated_at: '',
+                },
+                {
+                    id: '2',
+                    name: 'Policy 2',
+                    policy_type: 'rate',
+                    rules: {},
+                    enabled: false,
+                    priority: 0,
+                    status: 'ACTIVE',
+                    created_at: '',
+                    updated_at: '',
+                },
             ];
             mockFetch.mockResolvedValueOnce({
                 ok: true,
-                json: async () => mockPolicies,
+                json: async () => ({ policies: mockPolicies, total_count: 2 }),
             });
             const policies = await client.list();
-            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/policies`, expect.objectContaining({
+            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/policies`, expect.objectContaining({
                 method: 'GET',
                 headers: { 'Content-Type': 'application/json' },
             }));
@@ -59,7 +79,7 @@ describe('PolicyClient', () => {
             expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('status=ACTIVE'), expect.any(Object));
             expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('policy_type=cost'), expect.any(Object));
         });
-        it('should include Authorization header when apiKey is set', async () => {
+        it('should include X-API-Key header when apiKey is set', async () => {
             const authedClient = new clients_1.PolicyClient({ baseUrl, apiKey: 'my-key' });
             mockFetch.mockResolvedValueOnce({
                 ok: true,
@@ -68,10 +88,38 @@ describe('PolicyClient', () => {
             await authedClient.list();
             expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
                 headers: expect.objectContaining({
-                    Authorization: 'Bearer my-key',
+                    'X-API-Key': 'my-key',
                 }),
             }));
         });
+        it('should normalize hosted gateway policy records', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({
+                    policies: [
+                        {
+                            policy_id: 'policy-gateway-1',
+                            name: 'Gateway Policy',
+                            status: 'POLICY_STATUS_ACTIVE',
+                            priority: 7,
+                        },
+                    ],
+                    total_count: 1,
+                }),
+            });
+            const policies = await client.list();
+            expect(policies).toEqual([
+                expect.objectContaining({
+                    id: 'policy-gateway-1',
+                    name: 'Gateway Policy',
+                    policy_type: 'governance',
+                    rules: {},
+                    enabled: true,
+                    status: 'ACTIVE',
+                    priority: 7,
+                }),
+            ]);
+        });
         it('should throw PolicyClientError on failure', async () => {
             mockFetch.mockResolvedValueOnce({
                 ok: false,
@@ -95,13 +143,19 @@ describe('PolicyClient', () => {
                 id: '123',
                 name: 'Test Policy',
                 policy_type: 'cost',
+                rules: {},
+                enabled: true,
+                priority: 0,
+                status: 'ACTIVE',
+                created_at: '',
+                updated_at: '',
             };
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => mockPolicy,
             });
             const policy = await client.get('123');
-            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/policies/123`, expect.objectContaining({ method: 'GET' }));
+            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/policies/123`, expect.objectContaining({ method: 'GET' }));
             expect(policy).toEqual(mockPolicy);
         });
         it('should throw on 404', async () => {
@@ -120,13 +174,21 @@ describe('PolicyClient', () => {
                 policy_type: 'cost',
                 rules: { max_cost: 100 },
             };
-            const createdPolicy = { id: '456', ...newPolicy, enabled: true };
+            const createdPolicy = {
+                id: '456',
+                ...newPolicy,
+                enabled: true,
+                priority: 0,
+                status: 'ACTIVE',
+                created_at: '',
+                updated_at: '',
+            };
             mockFetch.mockResolvedValueOnce({
                 ok: true,
                 json: async () => createdPolicy,
             });
             const result = await client.create(newPolicy);
-            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/policies`, expect.objectContaining({
+            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/policies`, expect.objectContaining({
                 method: 'POST',
                 body: JSON.stringify(newPolicy),
             }));
@@ -159,7 +221,7 @@ describe('PolicyClient', () => {
                 json: async () => ({ id: '123', ...updates }),
             });
             const result = await client.update('123', updates);
-            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/policies/123`, expect.objectContaining({
+            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/policies/123`, expect.objectContaining({
                 method: 'PATCH',
                 body: JSON.stringify(updates),
             }));
@@ -173,7 +235,7 @@ describe('PolicyClient', () => {
                 json: async () => ({}),
             });
             await expect(client.delete('123')).resolves.toBeUndefined();
-            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/policies/123`, expect.objectContaining({ method: 'DELETE' }));
+            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/policies/123`, expect.objectContaining({ method: 'DELETE' }));
         });
     });
     describe('setEnabled', () => {
@@ -183,7 +245,7 @@ describe('PolicyClient', () => {
                 json: async () => ({ id: '123', enabled: true }),
             });
             const result = await client.setEnabled('123', true);
-            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/policies/123`, expect.objectContaining({
+            expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/policies/123`, expect.objectContaining({
                 method: 'PATCH',
                 body: JSON.stringify({ enabled: true }),
             }));
@@ -586,6 +648,59 @@ describe('BudgetClient', () => {
         });
     });
 });
+describe('EnvelopeClient', () => {
+    const baseUrl = 'http://localhost:3000';
+    let client;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        client = new clients_1.EnvelopeClient({ baseUrl, apiKey: 'test-key' });
+    });
+    it('should create envelope through the REST gateway path', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                envelope_id: 'env-1',
+                status: 'ENVELOPE_STATUS_AUTHORIZED',
+            }),
+        });
+        const envelope = await client.create({
+            adapter_type: 'typescript-sdk',
+            workflow_id: 'quickstart-agent',
+            metadata: { source: 'test' },
+        });
+        expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/envelopes/create`, expect.objectContaining({ method: 'POST' }));
+        expect(envelope.envelope_id).toBe('env-1');
+    });
+    it('should update envelope status through the REST gateway path', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                envelope_id: 'env-1',
+                status: 'ENVELOPE_STATUS_COMPLETED',
+            }),
+        });
+        const envelope = await client.updateStatus({
+            envelope_id: 'env-1',
+            status: 'COMPLETED',
+            error_message: 'quickstart complete',
+        });
+        expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/envelopes/status`, expect.objectContaining({ method: 'POST' }));
+        expect(envelope.status).toBe('ENVELOPE_STATUS_COMPLETED');
+    });
+    it('should fetch one envelope through the REST gateway query path', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                envelope_id: 'env-1',
+                status: 'ENVELOPE_STATUS_RUNNING',
+                metadata: {},
+            }),
+        });
+        const envelope = await client.get('env-1');
+        expect(mockFetch).toHaveBeenCalledWith(`${baseUrl}/api/v1/envelopes/get?envelope_id=env-1`, expect.objectContaining({ method: 'GET' }));
+        expect(envelope.envelope_id).toBe('env-1');
+    });
+});
 describe('Error classes', () => {
     describe('PolicyClientError', () => {
         it('should have correct name and properties', () => {

package/dist/clients/agent.js

@@ -42,21 +42,27 @@ 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;
+let agentV1;
+function getAgentV1() {
+    if (!agentV1) {
+        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;
+        agentV1 = agentPackage.v1;
+    }
+    return agentV1;
+}
 class AgentClient {
     constructor(address, credentials) {
         const creds = credentials || grpc.credentials.createInsecure();
-        this.client = new agentV1.AgentService(address, creds);
+        this.client = new (getAgentV1()).AgentService(address, creds);
     }
     /**
      * Creates a new agent for the authenticated tenant.

package/dist/clients/approval.js

@@ -20,7 +20,7 @@ class ApprovalClient {
                 '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 ApprovalClient {
             });
             if (!response.ok) {
                 const errorData = (await response.json().catch(() => ({})));
-                throw new ApprovalClientError(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 ApprovalClientError(errorMessage, response.status);
             }
             return (await response.json());
         }

package/dist/clients/budget.js

@@ -20,7 +20,7 @@ class BudgetClient {
                 '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 BudgetClient {
             });
             if (!response.ok) {
                 const errorData = (await response.json().catch(() => ({})));
-                throw new BudgetClientError(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 BudgetClientError(errorMessage, response.status);
             }
             return (await response.json());
         }

package/dist/clients/checkpoint.js

@@ -20,7 +20,7 @@ class CheckpointClient {
                 '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 CheckpointClient {
             });
             if (!response.ok) {
                 const errorData = (await response.json().catch(() => ({})));
-                throw new CheckpointClientError(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 CheckpointClientError(errorMessage, response.status);
             }
             const text = await response.text();
             return text ? JSON.parse(text) : {};

package/dist/clients/envelope.d.ts

@@ -3,7 +3,7 @@
  *
  * Works with the Fulcrum API for managing execution envelopes that wrap AI agent operations.
  */
-export type EnvelopeStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT';
+export type EnvelopeStatus = 'PENDING' | 'AUTHORIZED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TERMINATED' | 'TIMEOUT' | 'ENVELOPE_STATUS_AUTHORIZED' | 'ENVELOPE_STATUS_RUNNING' | 'ENVELOPE_STATUS_COMPLETED' | 'ENVELOPE_STATUS_FAILED' | 'ENVELOPE_STATUS_TERMINATED';
 export interface EnvelopeData {
     envelope_id: string;
     tenant_id: string;
@@ -20,9 +20,9 @@ export interface EnvelopeData {
     error_message?: string;
 }
 export interface CreateEnvelopeRequest {
-    tenant_id: string;
-    adapter_type: string;
-    workflow_id: string;
+    tenant_id?: string;
+    adapter_type?: string;
+    workflow_id?: string;
     budget_id?: string;
     metadata?: Record<string, string>;
 }
@@ -54,6 +54,7 @@ export declare class EnvelopeClient {
     private timeout;
     constructor(options: EnvelopeClientOptions);
     private request;
+    private unwrapEnvelope;
     /**
      * Create a new execution envelope.
      */

package/dist/clients/envelope.js

@@ -43,8 +43,21 @@ class EnvelopeClient {
                 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);
+                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 EnvelopeClientError(errorMessage, response.status, errorData);
             }
             return await response.json();
         }
@@ -52,27 +65,43 @@ class EnvelopeClient {
             clearTimeout(timeoutId);
         }
     }
+    unwrapEnvelope(response) {
+        return 'envelope' in response ? response.envelope : response;
+    }
     /**
      * Create a new execution envelope.
      */
     async create(request) {
-        const response = await this.request('POST', '/v1/envelopes', request);
-        return response.envelope;
+        const metadata = { ...(request.metadata || {}) };
+        if (request.workflow_id) {
+            metadata.workflow_id = metadata.workflow_id || request.workflow_id;
+        }
+        const body = {
+            adapter_type: request.adapter_type || 'typescript-sdk',
+            ...(request.budget_id ? { budget_id: request.budget_id } : {}),
+            metadata,
+        };
+        const response = await this.request('POST', '/api/v1/envelopes/create', body);
+        return this.unwrapEnvelope(response);
     }
     /**
      * Get an envelope by ID.
      */
     async get(envelopeId) {
-        const response = await this.request('GET', `/v1/envelopes/${envelopeId}`);
-        return response.envelope;
+        const response = await this.request('GET', '/api/v1/envelopes/get', undefined, { envelope_id: envelopeId });
+        return this.unwrapEnvelope(response);
     }
     /**
      * 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;
+        const body = {
+            envelope_id: request.envelope_id,
+            status: request.status,
+            ...(request.error_message ? { reason: request.error_message } : {}),
+        };
+        const response = await this.request('POST', '/api/v1/envelopes/status', body);
+        return this.unwrapEnvelope(response);
     }
     /**
      * List envelopes with optional filters.
@@ -88,7 +117,7 @@ class EnvelopeClient {
             params.workflow_id = request.workflow_id;
         if (request.status)
             params.status = request.status;
-        const response = await this.request('GET', '/v1/envelopes', undefined, params);
+        const response = await this.request('GET', '/api/v1/envelopes', undefined, params);
         return response.envelopes;
     }
 }

package/dist/clients/eventstore.js

@@ -43,8 +43,21 @@ class EventStoreClient {
                 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);
+                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 EventStoreClientError(errorMessage, response.status, errorData);
             }
             return await response.json();
         }