Keyflow SDK Documentation

This documentation provides detailed requirements and guides for the Keyflow SDK components. The SDK enables developers to define, version, and serve custom blocks that process input data and integrate with external services.

Components

The Keyflow SDK consists of several key components, each with its own detailed documentation:

1. Fields API - Define input fields for blocks using a fluent, chainable API
2. Block API - Create and configure processing blocks with input/output schemas
3. Block Versioning API - Manage multiple versions of blocks
4. Server API - Initialize and configure the HTTP server
5. Oauth Credential Access - Securely access third-party credentials

Quick Start

To get started with the Keyflow SDK, follow these steps:

1. Install the SDK package:

   npm install @keyflow/sdk

2. Create a block file (e.g., blocks/reverse-text.ts):

   import { block, fields } from '@keyflow/sdk';
   
   const reverseText = block('reverse-text')
     .version('v1')
     .title('Reverse Text')
     .description('Reverses a given input string')
     .input({
       text: fields.text().label('Text to reverse').required(),
     })
     .output({
       reversedText: 'string',
     })
     .execute(async ({ input }) => {
       const reversedText = input.text.split('').reverse().join('');
       return { reversedText };
     });
   
   export const blocks = [reverseText];

3. Create a server file (e.g., src/main.ts):

   import { server } from '@keyflow/sdk';
   import { blocks } from '../blocks/reverse-text';
   
   // Start the server
   server({ apiKey: process.env.KEYFLOW_API_KEY })
     .register(...blocks);

4. Create a .env file with your Keyflow API key:

   KEYFLOW_API_KEY=your_keyflow_api_key_here
   NODE_ENV=development

5. Start the server:

   ts-node src/main.ts

Recommended Project Structure

my-keyflow-project/
├── blocks/
│   ├── reverse-text.ts        # v1 and v2 versions
│   ├── uppercase-text.ts      # v1 version
│   └── another-block.ts       # Additional blocks
├── src/
│   └── main.ts                # Server setup and registration
├── .env                       # KEYFLOW_API_KEY, NODE_ENV
├── .gitignore                 # Ignore node_modules, .env, dist
├── package.json               # Dependencies (@keyflow/sdk, dotenv)
├── tsconfig.json              # TypeScript configuration
└── README.md                  # Documentation

Key Concepts

Fluent API

The Keyflow SDK uses a fluent, chainable API style for intuitive development:

block('my-block')
  .title('My Block')
  .description('Does something useful')
  .input({ /* ... */ })
  .output({ /* ... */ })
  .execute(async ({ input, ctx }) => { /* ... */ });

Type Safety

The SDK provides end-to-end type safety with TypeScript:

• Input validation based on field definitions
• Output validation based on output schema
• Type-safe credential access

HTTP Endpoints

Each block is automatically mapped to an HTTP endpoint:

• Format: POST /<block-identifier>/<version>
• Example: POST /reverse-text/v1

Credential Security

Credentials are securely accessed at runtime:

.execute(async ({ input, ctx }) => {
  const token = await ctx.credentials('service_name');
  // Use token securely
});

File Handling

The SDK provides powerful file handling capabilities through the FileObject class:

// Define a block that processes uploaded files
const processFile = block('process-file')
  .input({
    document: fields.file().label('Upload Document'),
    csvData: fields.file().label('CSV Data').optional(),
  })
  .execute(async ({ input }) => {
    // Download files
    const documentBuffer = await input.document.download();
    await input.document.download('saved-document.pdf', './uploads');
    
    // Read file content (automatically parsed by extension)
    const content = await input.document.read(); // string | object | string[]
    
    if (input.csvData) {
      // Read CSV with headers (default)
      const rows = await input.csvData.read(); // Record<string, string>[]
      
      // Read CSV without headers
      const rawData = await input.csvData.read({ headers: false }); // string[][]
      
      // Read CSV with custom delimiter
      const semiColonData = await input.csvData.read({ delimiter: ';' });
    }
    
    return { processed: true };
  });

Supported file types for reading:

• Text files (.txt, .md): Return as string
• JSON files (.json): Return as parsed object
• CSV files (.csv): Return as Record<string, string>[] or string[][]
• XML/HTML files (.xml, .html): Return as string
• Log files (.log): Return as string[] (one entry per line)
• Other files: Return as string

Further Reading

For more detailed information about each component, please refer to the specific documentation sections linked above.