@keyflow/sdk v0.1.3

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

Further Reading

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