Skip to content

Commit

Permalink
docs(api-client): more accurate docs (#49)
Browse files Browse the repository at this point in the history
  • Loading branch information
@hazimoarafa
hazimoarafa committed Jan 5, 2025
1 parent bf487c1 commit 227bc05
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 45 deletions.
58 changes: 23 additions & 35 deletions api-client/src/client.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ import {
* @interface
*/
export interface ClientConfig {
/** Base URL of the API endpoint (e.g., "https://api.example.com/v1") */
/** Base URL of the API endpoint (e.g., "http://localhost:8089") */
baseUrl: string;
/** Tenant identifier for multi-tenant environments */
tenantId: string;
Expand All @@ -36,26 +36,21 @@ export interface ClientConfig {
}

/**
* Client for interacting with the LittleHorse UserTasks API.
* Client for interacting with the LittleHorse User Tasks API.
*
* This client provides a comprehensive interface for managing user tasks, including:
* - Basic task operations (claim, cancel, complete)
* This client provides methods for managing user tasks in LittleHorse, including:
* - Task operations (claim, complete, cancel)
* - Task listing and filtering
* - Administrative functions
* - Administrative functions (assign, force complete)
* - User and group management
*
* All methods automatically handle authentication and error handling.
*
* @example
* ```typescript
* const client = new LittleHorseUserTasksApiClient({
* baseUrl: 'https://api.example.com',
* tenantId: 'tenant1',
* accessToken: 'oauth-token'
* baseUrl: 'http://localhost:8089', // UserTasks API endpoint
* tenantId: 'default', // Your LittleHorse tenant
* accessToken: 'your-oidc-token' // Valid OIDC access token
* });
*
* // List available tasks
* const tasks = await client.listUserTasks({ limit: 10 });
* ```
*/
export class LittleHorseUserTasksApiClient {
Expand Down Expand Up @@ -297,23 +292,21 @@ export class LittleHorseUserTasksApiClient {
}

/**
* Completes a UserTask by submitting the required result values.
* Completes a user task by submitting the task result.
*
* @param userTask - The UserTask to complete, must contain wfRunId and id
* @param values - The result values for the task fields
* @throws {UnauthorizedError} If the user is not authenticated
* @throws {ForbiddenError} If the user doesn't have permission to complete the task
* @throws {TaskStateError} If the task is already completed or cancelled
* @throws {ValidationError} If the provided values don't match the task's field definitions
* @param userTask - Object containing task identifiers
* @param values - Task result values matching the task's variable definitions
* @throws {UnauthorizedError} If the user doesn't have permission to complete the task
* @throws {NotFoundError} If the task doesn't exist
* @throws {PreconditionFailedError} If the task cannot be completed in its current state
*
* @example
* ```typescript
* await client.completeUserTask(
* { id: 'task-123', wfRunId: 'workflow-456' },
* { id: 'task-123', wfRunId: 'wf-456' },
* {
* approved: { type: 'BOOLEAN', value: true },
* comment: { type: 'STRING', value: 'Looks good!' }
* comment: { type: 'STR', value: 'Looks good!' }
* }
* );
* ```
Expand Down Expand Up @@ -355,24 +348,19 @@ export class LittleHorseUserTasksApiClient {
}

/**
* Administrative method to assign a UserTask to a specific user or group.
* If both userId and userGroupId are provided, the user must be a member of the group but
* the task will be assigned to the user.
* Assigns a user task to a specific user or group (admin only).
*
* @param userTask - The UserTask to assign
* @param assignTo - Object containing userId and/or userGroupId
* @param assignTo.userId - Optional user ID to assign the task to
* @param assignTo.userGroupId - Optional user group ID to assign the task to
* @throws {UnauthorizedError} If the user is not authenticated
* @throws {ForbiddenError} If the user doesn't have administrative permissions
* @throws {ValidationError} If neither userId nor userGroupId is provided
* @throws {NotFoundError} If the task, user, or group doesn't exist
* @param userTask - Object containing task identifiers
* @param assignTo - Object specifying user ID and/or group ID to assign
* @throws {UnauthorizedError} If the caller lacks admin privileges
* @throws {NotFoundError} If the task doesn't exist
* @throws {AssignmentError} If the assignment cannot be completed
*
* @example
* ```typescript
* await client.adminAssignUserTask(
* { id: 'task-123', wfRunId: 'workflow-456' },
* { userId: 'user-789', userGroupId: 'group-101' }
* { id: 'task-123', wfRunId: 'wf-456' },
* { userId: 'user-789', userGroupId: 'group-123' }
* );
* ```
*/
Expand Down
66 changes: 56 additions & 10 deletions api-client/src/errors.ts
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,12 @@
/**
* Base error class for LH User Tasks API errors.
* Provides common functionality and proper stack trace capture for all derived error classes.
*
* @extends Error
* @example
* ```typescript
* throw new LHUserTasksError('Custom error message');
* ```
*/
export class LHUserTasksError extends Error {
/**
Expand All @@ -20,8 +25,13 @@ export class LHUserTasksError extends Error {

/**
* Thrown when the request is malformed or contains invalid parameters.
* Typically corresponds to HTTP 400 Bad Request responses.
* Common cases include:
* - Missing required fields
* - Invalid field formats
* - Incompatible parameter combinations
*
* @extends LHUserTasksError
* @see ValidationError for business logic validation errors
*/
export class BadRequestError extends LHUserTasksError {
constructor(
Expand All @@ -32,9 +42,14 @@ export class BadRequestError extends LHUserTasksError {
}

/**
* Thrown when authentication is required but not provided or is invalid.
* Typically corresponds to HTTP 401 Unauthorized responses.
* Thrown when authentication fails or is missing.
* Common cases include:
* - Missing OIDC token
* - Expired token
* - Invalid token format
*
* @extends LHUserTasksError
* @see ForbiddenError for permission-related errors
*/
export class UnauthorizedError extends LHUserTasksError {
constructor(
Expand All @@ -46,7 +61,11 @@ export class UnauthorizedError extends LHUserTasksError {

/**
* Thrown when the authenticated user lacks necessary permissions.
* Typically corresponds to HTTP 403 Forbidden responses.
* Common cases include:
* - Non-admin user attempting admin operations
* - User not in required group
* - User attempting to access tasks they don't own
*
* @extends LHUserTasksError
*/
export class ForbiddenError extends LHUserTasksError {
Expand All @@ -59,7 +78,11 @@ export class ForbiddenError extends LHUserTasksError {

/**
* Thrown when the requested resource cannot be found.
* Typically corresponds to HTTP 404 Not Found responses.
* Common cases include:
* - Invalid task ID
* - Invalid workflow run ID
* - Deleted or expired tasks
*
* @extends LHUserTasksError
*/
export class NotFoundError extends LHUserTasksError {
Expand All @@ -72,8 +95,13 @@ export class NotFoundError extends LHUserTasksError {

/**
* Thrown when a precondition for the request has not been met.
* Typically corresponds to HTTP 412 Precondition Failed responses.
* Common cases include:
* - Task already claimed by another user
* - Task in wrong state for operation
* - Concurrent modification conflicts
*
* @extends LHUserTasksError
* @see TaskStateError for specific task state transition errors
*/
export class PreconditionFailedError extends LHUserTasksError {
constructor(
Expand All @@ -86,9 +114,14 @@ export class PreconditionFailedError extends LHUserTasksError {
// Business Logic Errors

/**
* Thrown when input validation fails.
* Used for both client-side and server-side validation errors.
* Thrown when input validation fails during business logic processing.
* Common cases include:
* - Invalid task result values
* - Schema validation failures
* - Business rule violations
*
* @extends LHUserTasksError
* @see BadRequestError for HTTP request validation errors
*/
export class ValidationError extends LHUserTasksError {
constructor(
Expand All @@ -100,8 +133,13 @@ export class ValidationError extends LHUserTasksError {

/**
* Thrown when attempting to perform an action on a task in an invalid state.
* For example, trying to complete an already cancelled task.
* Common cases include:
* - Completing a cancelled task
* - Cancelling a completed task
* - Claiming an already assigned task
*
* @extends LHUserTasksError
* @see PreconditionFailedError for general precondition failures
*/
export class TaskStateError extends LHUserTasksError {
constructor(
Expand All @@ -113,8 +151,16 @@ export class TaskStateError extends LHUserTasksError {

/**
* Thrown when task assignment operations fail.
* This could be due to conflicts, permissions, or invalid state transitions.
* Common cases include:
* - Assignment to non-existent user/group
* - Assignment of already claimed task
* - Assignment policy violations
*
* @extends LHUserTasksError
* @example
* ```typescript
* throw new AssignmentError('Cannot assign task: already claimed by another user');
* ```
*/
export class AssignmentError extends LHUserTasksError {
constructor(
Expand Down

0 comments on commit 227bc05

Please sign in to comment.