SDK Configuration

Configure the ProposeFlow SDK for your environment and customize its behavior.

Basic Configuration

Initialize the ProposeFlow client with your API key.

lib/proposeflow.ts

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

const pf = new ProposeFlow({
  apiKey: process.env.PROPOSEFLOW_API_KEY!,
});

Configuration Options

Configuration

interface ProposeFlowConfig {
  // Required: Your API key
  apiKey: string;

  // Optional: API base URL (for self-hosted instances)
  baseUrl?: string;  // Default: 'https://api.proposeflow.dev'

  // Optional: Schema registry for type-safe proposals
  schemas?: Record<string, ZodSchema>;

  // Optional: Schema resolution mode
  schemaSync?: 'live' | 'hash';  // Default: 'live'

  // Optional: Auto-register schemas by hash when missing
  autoRegisterSchemas?: boolean;  // Default: false

  // Optional: Client identifier for usage tracking
  client?: string;  // e.g., 'web-app', 'mobile-app'
}

Client Identification

Use the client option to identify the source of API requests. This helps track usage across different platforms and surfaces in your application.

Use Cases

Multi-platform apps — Track usage across web, mobile, and backend services
A/B testing — Compare proposal acceptance rates between different UI surfaces
Cost allocation — Attribute credit usage to specific teams or features
Debugging — Identify which client is making problematic requests
Usage analytics — Understand how different parts of your application use AI generation

Multi-Platform Example

Create separate SDK instances for each platform in your application:

Web Frontend

// apps/web/lib/proposeflow.ts
import { ProposeFlow } from '@proposeflow/sdk';

export const pf = new ProposeFlow({
  apiKey: process.env.PROPOSEFLOW_API_KEY!,
  client: 'web-app',
});

Mobile App (React Native)

// apps/mobile/lib/proposeflow.ts
import { ProposeFlow } from '@proposeflow/sdk';

export const pf = new ProposeFlow({
  apiKey: Config.PROPOSEFLOW_API_KEY,
  client: 'mobile-ios',  // or 'mobile-android'
});

Backend Service

// services/recipe-importer/lib/proposeflow.ts
import { ProposeFlow } from '@proposeflow/sdk';

export const pf = new ProposeFlow({
  apiKey: process.env.PROPOSEFLOW_API_KEY!,
  client: 'backend-importer',
});

Naming Conventions

Use consistent, descriptive names for your client identifiers:

Pattern	Example	Use Case
`platform-name`	`web-app`, `mobile-ios`	Platform identification
`service-function`	`backend-importer`, `worker-notifications`	Backend services
`feature-surface`	`web-recipe-creator`, `web-quick-add`	Feature-level tracking
`env-service`	`staging-web`, `prod-api`	Environment separation

Best practices:

Use lowercase with hyphens (web-app) for consistency
Keep identifiers short but descriptive (under 32 characters)
Include platform or environment when relevant
Use the same identifier across all instances of the same surface

Schema Sync Modes

The schemaSync option controls how schemas are resolved when generating proposals.

Mode	Description
`live`	Uses the schema pointer to get the current "live" version. Best for development.
`hash`	Uses content-based hashing to lock to a specific schema version. Best for production reproducibility.

lib/proposeflow.ts

import { ProposeFlow } from '@proposeflow/sdk';
import { z } from 'zod';

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

export const pf = new ProposeFlow({
  apiKey: process.env.PROPOSEFLOW_API_KEY!,
  schemas: {
    recipe: recipeSchema,
  },
  // Use hash-based versioning for reproducible generations
  schemaSync: 'hash',
  // Automatically register schemas if they don't exist
  autoRegisterSchemas: true,
});

With autoRegisterSchemas: true, the SDK automatically registers new schema versions with the API when you call generate(). This eliminates the need to manually register schemas before using them.

Full Configuration Example

lib/proposeflow.ts

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

export const pf = new ProposeFlow({
  apiKey: process.env.PROPOSEFLOW_API_KEY!,

  // Use a self-hosted instance
  baseUrl: 'https://proposeflow.example.com',

  // Increase timeout for long-running generations
  timeout: 60000,

  // Retry up to 5 times on transient failures
  maxRetries: 5,

  // Add custom headers
  headers: {
    'X-Custom-Header': 'my-value',
  },
});

Environment Variables

The SDK automatically reads certain environment variables if not explicitly configured.

Variable	Description
`PROPOSEFLOW_API_KEY`	Your ProposeFlow API key
`PROPOSEFLOW_BASE_URL`	Custom API base URL

Model Tiers and Credits

ProposeFlow uses a credit-based system to normalize costs across different AI model quality tiers. This lets you choose the right quality/speed/cost tradeoff for each use case.

Available Model Tiers

Tier	Use Case	Credit Rate
`fast`	Quick suggestions, simple tasks, high-volume use cases	0.1x (cheapest)
`balanced`	Default tier, good for most use cases	1.0x (baseline)
`quality`	Complex reasoning, high-stakes content, best output	5.0x (premium)

Setting Model Tier

Model tier can be configured at multiple levels, with higher specificity taking precedence:

Per-generation - Override for a specific generate() call
Per-schema - Default for all generations using that schema
Per-application - Default for your entire application
System default - Falls back to balanced

model-tier.ts

// Per-generation override
const { proposal } = await pf.generate('recipe', {
  input: 'A quick pasta dish',
  modelTier: 'fast',  // Use fast for this generation only
});

// Schema-level default (when registering)
await pf.schemas.register('recipe', {
  version: '1.0.0',
  modelTier: 'balanced',  // Default tier for all recipe generations
});

// Application-level default is set in the dashboard

Credit Calculation

Credits are calculated based on tokens consumed and the model tier rate:

credit-formula.ts

// Credits = (tokens / 1000) × tierRate
// Example: 5000 tokens with 'quality' tier
// Credits = (5000 / 1000) × 5.0 = 25 credits

// The generation response includes credits consumed
const { generation } = await pf.generate('blogPost', {
  input: 'Write a detailed analysis',
  modelTier: 'quality',
});

console.log(generation.credits);  // e.g., 25.5
console.log(generation.modelTier);  // 'quality'

Error Handling

The SDK throws typed errors that you can catch and handle appropriately.

error-handling.ts

import { ProposeFlow, ProposeFlowError, RateLimitError } from '@proposeflow/sdk';

try {
  const proposal = await pf.schemas.blogPost.generate({
    prompt: 'Write a blog post',
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    console.log(`Rate limited. Retry after ${error.retryAfter}ms`);
  } else if (error instanceof ProposeFlowError) {
    // Handle API errors
    console.error(`API Error: ${error.message}`, error.code);
  } else {
    // Handle unexpected errors
    throw error;
  }
}