@proposeflow/sdk

TypeScript SDK for the ProposeFlow API.

Installation

npm install @proposeflow/sdk
# or
pnpm add @proposeflow/sdk

Quick Start

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:

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

ProposeFlow Client

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.

Schemas

// 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);

Generation

// 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'

Proposals

// 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;
});

Webhooks

// 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);

Webhook Verification

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