@onlive.ai/flow-client 0.1.31 → 0.1.35

package/README.md

@@ -1,8 +1,64 @@
 # 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 from [client.types.ts](#file:client.types.ts-context).
+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.
 
-## Initialization
+## 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:
 
@@ -20,9 +76,15 @@ const client = new FlowClient({
 });
 ```
 
-## Methods
+### 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>
+##### firstStep(options?: GetStepOptions): Promise<FlowContext>
 
 Initiates the first step of the flow.
 
@@ -35,7 +97,7 @@ Initiates the first step of the flow.
   - 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>
+##### getStep(stepId: string, options?: GetStepOptions): Promise<FlowContext>
 
 Retrieves a specific step in the flow.
 
@@ -49,7 +111,7 @@ Retrieves a specific step in the flow.
   - Sends a POST request to `flow/{flowId}/steps/{stepId}`.
   - Tracks request and response events.
 
-### nextStep(trigger: GetStepTrigger, options?: GetStepOptions): Promise<FlowContext>
+##### nextStep(trigger: GetStepTrigger, options?: GetStepOptions): Promise<FlowContext>
 
 Proceeds to the next step in the flow based on user actions.
 
@@ -65,9 +127,9 @@ Proceeds to the next step in the flow based on user actions.
   - Sends a POST request to `flow/{flowId}/steps/{currentStepId}/action/{actionId}`.
   - Analyzes both request and response by emitting tracking events.
 
-## Event Handling
+#### Event Handling
 
-### on(type: EventType, listener: EventListener): void
+##### on(type: EventType, listener: EventListener): void
 
 Registers a listener for specific events.
 
@@ -81,11 +143,94 @@ Internally, FlowClient uses a private `emit` method to deliver events to all reg
 
 ## Types & Schemas
 
-The methods and the overall flow behavior are governed by types and validation schemas defined in [client.types.ts](#file:client.types.ts-context):
+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.

package/client/client.service.cjs

@@ -26,12 +26,12 @@ __export(client_service_exports, {
   default: () => client_service_default
 });
 module.exports = __toCommonJS(client_service_exports);
-var import_merge2 = require("@packages/common/utils/merge");
+var import_merge2 = require("@onlive.ai/common-121/utils/merge.js");
 
 // tracking/tracking.service.ts
-var import_tracker = require("@onlive.site/tracker");
-var import_merge = require("@packages/common/utils/merge");
-var import_browser_preferences = require("@packages/common/utils/browser-preferences.js");
+var import_tracker = require("@onlive.ai/tracker");
+var import_merge = require("@onlive.ai/common-121/utils/merge.js");
+var import_browser_preferences = require("@onlive.ai/common-121/utils/browser-preferences.js");
 
 // tracking/tracking.types.ts
 var import_zod = require("zod");
@@ -237,12 +237,12 @@ var TrackingService = class {
 var tracking_service_default = TrackingService;
 
 // client/client.types.ts
-var import_calendar = require("@onlive.site/calendar");
+var import_calendar = require("@onlive.ai/calendar");
 var import_zod2 = require("zod");
 var DEFAULT_CLIENT_OPTIONS = {
   tracking: {
     removeExtraneousValues: true,
-    apiUrl: "https://srvless.onlive.site/tracking",
+    apiUrl: "https://srvless.onlive.ai/tracking",
     data: {
       widget_type: "OnliveAppFlow"
     }

package/client/client.service.d.cts

@@ -1,5 +1,5 @@
-import '@onlive.site/tracker';
-import { TrackingService } from '../tracking/tracking.service.cjs';
+import '@onlive.ai/tracker';
+import TrackingService from '../tracking/tracking.service.cjs';
 import { ClientOptions, GetStepOptions, FlowContext, GetStepTrigger } from './client.types.cjs';
 import '../tracking/tracking.types.cjs';
 import 'zod';

package/client/client.service.d.ts

@@ -1,5 +1,5 @@
-import '@onlive.site/tracker';
-import { TrackingService } from '../tracking/tracking.service.js';
+import '@onlive.ai/tracker';
+import TrackingService from '../tracking/tracking.service.js';
 import { ClientOptions, GetStepOptions, FlowContext, GetStepTrigger } from './client.types.js';
 import '../tracking/tracking.types.js';
 import 'zod';

package/client/client.service.js

@@ -3,12 +3,12 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // client/client.service.ts
-import { merge as merge2 } from "@packages/common/utils/merge";
+import { merge as merge2 } from "@onlive.ai/common-121/utils/merge.js";
 
 // tracking/tracking.service.ts
-import { Session, Tracker } from "@onlive.site/tracker";
-import { merge } from "@packages/common/utils/merge";
-import { browserPreferences } from "@packages/common/utils/browser-preferences.js";
+import { Session, Tracker } from "@onlive.ai/tracker";
+import { merge } from "@onlive.ai/common-121/utils/merge.js";
+import { browserPreferences } from "@onlive.ai/common-121/utils/browser-preferences.js";
 
 // tracking/tracking.types.ts
 import { z } from "zod";
@@ -214,12 +214,12 @@ var TrackingService = class {
 var tracking_service_default = TrackingService;
 
 // client/client.types.ts
-import { GetAvailabilityFilters, GetAvailabilityOptions } from "@onlive.site/calendar";
+import { GetAvailabilityFilters, GetAvailabilityOptions } from "@onlive.ai/calendar";
 import { z as z2 } from "zod";
 var DEFAULT_CLIENT_OPTIONS = {
   tracking: {
     removeExtraneousValues: true,
-    apiUrl: "https://srvless.onlive.site/tracking",
+    apiUrl: "https://srvless.onlive.ai/tracking",
     data: {
       widget_type: "OnliveAppFlow"
     }

package/client/client.service.spec.cjs

@@ -8,12 +8,12 @@ var import_vitest = require("vitest");
 var import_zod3 = require("zod");
 
 // client/client.service.ts
-var import_merge2 = require("@packages/common/utils/merge");
+var import_merge2 = require("@onlive.ai/common-121/utils/merge.js");
 
 // tracking/tracking.service.ts
-var import_tracker = require("@onlive.site/tracker");
-var import_merge = require("@packages/common/utils/merge");
-var import_browser_preferences = require("@packages/common/utils/browser-preferences.js");
+var import_tracker = require("@onlive.ai/tracker");
+var import_merge = require("@onlive.ai/common-121/utils/merge.js");
+var import_browser_preferences = require("@onlive.ai/common-121/utils/browser-preferences.js");
 
 // tracking/tracking.types.ts
 var import_zod = require("zod");
@@ -219,12 +219,12 @@ var TrackingService = class {
 var tracking_service_default = TrackingService;
 
 // client/client.types.ts
-var import_calendar = require("@onlive.site/calendar");
+var import_calendar = require("@onlive.ai/calendar");
 var import_zod2 = require("zod");
 var DEFAULT_CLIENT_OPTIONS = {
   tracking: {
     removeExtraneousValues: true,
-    apiUrl: "https://srvless.onlive.site/tracking",
+    apiUrl: "https://srvless.onlive.ai/tracking",
     data: {
       widget_type: "OnliveAppFlow"
     }

package/client/client.service.spec.js

@@ -7,12 +7,12 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { ZodError } from "zod";
 
 // client/client.service.ts
-import { merge as merge2 } from "@packages/common/utils/merge";
+import { merge as merge2 } from "@onlive.ai/common-121/utils/merge.js";
 
 // tracking/tracking.service.ts
-import { Session, Tracker } from "@onlive.site/tracker";
-import { merge } from "@packages/common/utils/merge";
-import { browserPreferences } from "@packages/common/utils/browser-preferences.js";
+import { Session, Tracker } from "@onlive.ai/tracker";
+import { merge } from "@onlive.ai/common-121/utils/merge.js";
+import { browserPreferences } from "@onlive.ai/common-121/utils/browser-preferences.js";
 
 // tracking/tracking.types.ts
 import { z } from "zod";
@@ -218,12 +218,12 @@ var TrackingService = class {
 var tracking_service_default = TrackingService;
 
 // client/client.types.ts
-import { GetAvailabilityFilters, GetAvailabilityOptions } from "@onlive.site/calendar";
+import { GetAvailabilityFilters, GetAvailabilityOptions } from "@onlive.ai/calendar";
 import { z as z2 } from "zod";
 var DEFAULT_CLIENT_OPTIONS = {
   tracking: {
     removeExtraneousValues: true,
-    apiUrl: "https://srvless.onlive.site/tracking",
+    apiUrl: "https://srvless.onlive.ai/tracking",
     data: {
       widget_type: "OnliveAppFlow"
     }

package/client/client.types.cjs

@@ -37,7 +37,7 @@ __export(client_types_exports, {
   StepId: () => StepId
 });
 module.exports = __toCommonJS(client_types_exports);
-var import_calendar = require("@onlive.site/calendar");
+var import_calendar = require("@onlive.ai/calendar");
 var import_zod2 = require("zod");
 
 // tracking/tracking.types.ts
@@ -60,7 +60,7 @@ var TrackingOptionsSchema = import_zod.z.object({
 var DEFAULT_CLIENT_OPTIONS = {
   tracking: {
     removeExtraneousValues: true,
-    apiUrl: "https://srvless.onlive.site/tracking",
+    apiUrl: "https://srvless.onlive.ai/tracking",
     data: {
       widget_type: "OnliveAppFlow"
     }