@proposeflow/sdk

TypeScript SDK for the ProposeFlow API.

Installation

``bash
npm install @proposeflow/sdk


or


pnpm add @proposeflow/sdk
`

Quick Start

`typescript
import { ProposeFlow } from '@proposeflow/sdk';

const pf = new ProposeFlow({
apiKey: process.env.PROPOSEFLOW_API_KEY,
baseUrl: 'http://localhost:3001', // or production URL
});

// Register a schema
await pf.schemas.create({
name: 'recipe',
version: '1.0.0',
jsonSchema: {
type: 'object',
properties: {
title: { type: 'string' },
ingredients: { type: 'array', items: { type: 'string' } },
steps: { type: 'array', items: { type: 'string' } },
},
required: ['title', 'ingredients', 'steps'],
},
});

// Generate an object from natural language
const { proposal } = await pf.generate({
schema: 'recipe',
input: 'A quick pasta dish with chicken',
});

console.log(proposal.generatedObject);
// { title: "Chicken Alfredo", ingredients: [...], steps: [...] }

// User reviews and approves
const decision = await pf.proposals.decide(proposal.id, {
action: 'approve',
edits: { servings: 4 }, // optional modifications
});
`

Type-Safe Schemas with Auto-Registration

Use Zod schemas with automatic registration - no manual schema setup needed:

`typescript
import { ProposeFlow, z } from '@proposeflow/sdk';

const RecipeSchema = z.object({
title: z.string(),
ingredients: z.array(z.string()),
steps: z.array(z.string()),
});

const pf = new ProposeFlow({
apiKey: process.env.PROPOSEFLOW_API_KEY,
schemas: {
recipe: RecipeSchema,
},
schemaSync: 'hash', // Use content-based versioning
autoRegisterSchemas: true, // Auto-register on first generate()
});

// Schema is automatically registered on first call
const { proposal } = await pf.generate('recipe', {
input: 'A healthy salad',
});

// proposal.generatedObject is fully typed
console.log(proposal.generatedObject.title);
`

API Reference

$3

`typescript
const pf = new ProposeFlow({
apiKey: string; // Required: API key
baseUrl?: string; // API URL (default: http://localhost:3001)
schemas?: SchemaRegistry; // Optional: Zod schemas for type safety
schemaSync?: 'live' | 'hash'; // Schema resolution mode (default: 'live')
autoRegisterSchemas?: boolean; // Auto-register schemas (default: false)
});
`

#### Schema Sync Modes

- 'live' (default): Uses schema pointers to resolve the current "live" version
- 'hash': Uses content-based hashing to lock to a specific schema version

When autoRegisterSchemas: true, schemas are automatically registered with the API
on the first generate() call. This eliminates the need for manual registration.

$3

`typescript
// Create schema
await pf.schemas.create({
name: string;
version: string;
description?: string;
jsonSchema: object;
});

// List schemas
const { data } = await pf.schemas.list();

// Get schema by ID
const schema = await pf.schemas.get(id);
`

$3

`typescript
// Generate object from prompt
const { proposal, generation } = await pf.generate({
schema: string; // Schema name
input: string; // Natural language prompt
metadata?: object; // Custom metadata
generationMode?: 'llm' | 'mock'; // Default: 'llm'
});

// Use mock generation for testing (no LLM cost)
const { proposal } = await pf.generate({
schema: 'recipe',
input: 'Test input',
generationMode: 'mock',
});
// Returns schema-valid placeholder data with model: 'mock'
`

$3

`typescript
// Get proposal
const proposal = await pf.proposals.get(id);

// List proposals
const { data, nextCursor } = await pf.proposals.list({
status?: 'pending' | 'approved' | 'rejected';
schemaId?: string;
limit?: number;
cursor?: string;
});

// Approve or reject
const decision = await pf.proposals.decide(id, {
action: 'approve' | 'reject';
edits?: object; // For approve: optional modifications
reason?: string; // For reject: reason
});

// Regenerate with feedback
const { proposal } = await pf.proposals.regenerate(id, {
feedback: string;
});
`

$3

`typescript
// Create webhook endpoint
await pf.webhooks.create({
url: string;
events: ('proposal.created' | 'proposal.approved' | 'proposal.rejected')[];
secret: string;
});

// List webhooks
const { data } = await pf.webhooks.list();

// Delete webhook
await pf.webhooks.delete(id);
`

$3

`typescript
import { verifyWebhookSignature } from '@proposeflow/sdk';

const result = verifyWebhookSignature({
body: request.rawBody,
signature: request.headers['x-proposeflow-signature'],
timestamp: request.headers['x-proposeflow-timestamp'],
secret: process.env.WEBHOOK_SECRET,
});

if (result.valid) {
// Process webhook
}
`

Exports

The SDK exports:

- ProposeFlow - Main client class
- z - Zod (re-exported for convenience)
- verifyWebhookSignature - Webhook signature verification
- generateWebhookSignature` - Webhook signature generation (for testing)
- Type definitions for all API resources