@onlive.ai/flow-client 0.0.3 → 0.1.31

package/README.md

@@ -0,0 +1,91 @@
+# 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).
+
+## 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",
+});
+```
+
+## 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 [client.types.ts](#file:client.types.ts-context):
+
+- **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.
+
+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.