@onlive.ai/flow-client 0.0.3 → 0.1.34

package/README.md

@@ -0,0 +1,236 @@
+# Onlive Flow Client
+
+The Flow Client package offers a convenient interface for interacting with a multi-step process flow. The client helps you initiate, retrieve, and progress through flow steps while tracking events. It leverages robust type validation and provides a modern TypeScript-first API.
+
+## Installation
+
+### Using pnpm (recommended)
+
+```bash
+pnpm add @onlive.ai/flow-client
+# or
+npm install @onlive.ai/flow-client
+```
+
+## Package Structure
+
+This package is organized into the following main components:
+
+```
+packages/flow-client/
+├── client/                     # Core client implementation
+│   ├── client.service.ts      # Main FlowClient class
+│   ├── client.types.ts        # Type definitions and schemas
+│   └── client.service.spec.ts # Unit tests
+├── tracking/                   # Event tracking functionality
+│   ├── tracking.service.ts    # Tracking service implementation
+│   └── tracking.types.ts      # Tracking-related types
+├── flow.types.ts              # Flow-specific type definitions
+├── index.ts                   # Main package exports
+├── schema-generator.ts        # JSON schema generation utilities
+└── README.md                  # This documentation
+```
+
+### Main Exports
+
+The package exports the following main components:
+
+- **FlowClient**: Main client class for flow interactions
+- **Type definitions**: Comprehensive TypeScript types for flows, steps, actions, and events
+- **Event types**: Types for tracking and event handling from `@onlive.ai/tracker`
+
+## Dependencies
+
+This package depends on:
+
+- **@onlive.ai/tracker**: Event tracking functionality
+- **@onlive.ai/calendar**: Calendar-related utilities
+- **@onlive.ai/common-121**: Shared utilities and types
+- **zod**: Runtime type validation and schema definitions
+
+## Usage
+
+### Basic Import
+
+```typescript
+import { FlowClient } from '@onlive.ai/flow-client';
+// or
+import { FlowClient, type FlowContext, type ClientOptions } from '@onlive.ai/flow-client';
+```
+
+### Initialization
+
+Create an instance of the FlowClient by passing a valid ClientOptions object. The options must conform to the ClientOptionsSchema. The options include:
+
+- **baseUrl**: (string) URL of the service.
+- **flowId**: (string) 24-character identifier.
+- **organizationId**: (string) UUID.
+- **lang**: (string) 2-character language code.
+
+```typescript
+const client = new FlowClient({
+  baseUrl: "https://api.example.com",
+  flowId: "0123456789abcdef01234567",
+  organizationId: "550e8400-e29b-41d4-a716-446655440000",
+  lang: "en",
+});
+```
+
+### API Reference
+
+#### FlowClient Class
+
+The main class for interacting with flows. All methods are type-safe and include runtime validation.
+
+#### Methods
+
+##### firstStep(options?: GetStepOptions): Promise<FlowContext>
+
+Initiates the first step of the flow.
+
+- **Parameters**:
+  - **options** (optional): An object conforming to GetStepOptionsSchema.
+- **Response**:
+  - Returns a `Promise` that resolves to a `FlowContext` object, representing the flow’s status, the current step (as defined in StepSchema), and flow metadata (FlowSchema).
+- **Process**:
+  - Validates the options.
+  - Sends a POST request to `flow/{flowId}/first-step`.
+  - Analyzes and emits "track" events via the tracking service.
+
+##### getStep(stepId: string, options?: GetStepOptions): Promise<FlowContext>
+
+Retrieves a specific step in the flow.
+
+- **Parameters**:
+  - **stepId**: (string) A non-empty string identifier validated by StepIdSchema.
+  - **options** (optional): Additional parameters adhering to GetStepOptionsSchema.
+- **Response**:
+  - Returns a `Promise` resolving to a FlowContext.
+- **Process**:
+  - Validates the stepId.
+  - Sends a POST request to `flow/{flowId}/steps/{stepId}`.
+  - Tracks request and response events.
+
+##### nextStep(trigger: GetStepTrigger, options?: GetStepOptions): Promise<FlowContext>
+
+Proceeds to the next step in the flow based on user actions.
+
+- **Parameters**:
+  - **trigger**: An object conforming to GetStepTriggerSchema containing:
+    - `currentStepId` (string): Current step identifier.
+    - `actionId` (string): Identifier of the action to trigger.
+  - **options** (optional): Configuration for step retrieval following GetStepOptionsSchema.
+- **Response**:
+  - Returns a `Promise` that resolves to an updated FlowContext.
+- **Process**:
+  - Validates the trigger.
+  - Sends a POST request to `flow/{flowId}/steps/{currentStepId}/action/{actionId}`.
+  - Analyzes both request and response by emitting tracking events.
+
+#### Event Handling
+
+##### on(type: EventType, listener: EventListener): void
+
+Registers a listener for specific events.
+
+- **Parameters**:
+  - **type**: A string event type, currently supporting `"track"` as defined by EventTypeSchema.
+  - **listener**: Callback accepting the event type and event data.
+- **Usage**:
+  Register multiple listener functions to react to tracking events.
+
+Internally, FlowClient uses a private `emit` method to deliver events to all registered listeners.
+
+## Types & Schemas
+
+The methods and the overall flow behavior are governed by types and validation schemas defined in the package:
+
+- **FlowContext**: Contains the status of the flow, current step details, and flow metadata.
+- **StepSchema**, **ActionSchema**, **FieldSchema**: Define properties and validation for steps, actions, and form fields.
+- **GetStepOptions** and **GetStepTrigger**: Govern the payload structure for step operations.
+- **EventData**: Structure for tracking events, ensuring consistency with the "track" event type.
+
+## Features
+
+- **Type Safety**: Full TypeScript support with runtime validation using Zod schemas
+- **Event Tracking**: Built-in event tracking for flow interactions
+- **Multi-format Support**: Supports both ESM and CommonJS
+- **Modern API**: Promise-based API with async/await support
+- **Flexible Configuration**: Configurable client options with validation
+- **Error Handling**: Comprehensive error handling with type-safe error responses
+
+## Development
+
+### Building the Package
+
+```bash
+pnpm build:package
+```
+
+### Running Tests
+
+```bash
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm test:coverage
+```
+
+### Cleaning Build Artifacts
+
+```bash
+pnpm clean
+```
+
+## Examples
+
+### Complete Flow Example
+
+```typescript
+import { FlowClient } from '@onlive.ai/flow-client';
+
+const client = new FlowClient({
+  baseUrl: "https://api.example.com",
+  flowId: "0123456789abcdef01234567",
+  organizationId: "550e8400-e29b-41d4-a716-446655440000",
+  lang: "en",
+});
+
+// Set up event tracking
+client.on('track', (eventType, eventData) => {
+  console.log('Flow event:', eventType, eventData);
+});
+
+// Start the flow
+try {
+  const firstStep = await client.firstStep();
+  console.log('First step:', firstStep);
+  
+  // Progress through the flow
+  const nextStep = await client.nextStep({
+    currentStepId: firstStep.step.id,
+    actionId: 'continue'
+  });
+  
+  console.log('Next step:', nextStep);
+} catch (error) {
+  console.error('Flow error:', error);
+}
+```
+
+### Getting a Specific Step
+
+```typescript
+const specificStep = await client.getStep('step-id-123', {
+  // optional additional parameters
+});
+```
+
+## License
+
+This package is part of the Onlive workspace and follows the project's licensing terms.
+
+---
+
+This documentation mirrors common npm package libraries by providing a straightforward interface with strong type validations and event tracking, ensuring that clients can interact with a dynamic flow efficiently.