From aa51f2ef644e51927281989dfc0e46383deee656 Mon Sep 17 00:00:00 2001 From: Hazim Arafa Date: Sun, 5 Jan 2025 10:15:02 -0800 Subject: [PATCH] docs(api-client): more accurate docs (#49) --- api-client/src/client.ts | 76 +++++++++++++++------------------------- api-client/src/errors.ts | 66 ++++++++++++++++++++++++++++------ 2 files changed, 85 insertions(+), 57 deletions(-) diff --git a/api-client/src/client.ts b/api-client/src/client.ts index 3e5afb5..22f6205 100644 --- a/api-client/src/client.ts +++ b/api-client/src/client.ts @@ -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 { @@ -297,31 +292,26 @@ export class LittleHorseUserTasksApiClient { } /** - * Completes a UserTask by submitting the required result values. - * - * @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 + * Completes a user task by submitting the task result. + * + * @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!' } * } * ); * ``` */ - async completeUserTask( - userTask: UserTask, - values: UserTaskResult, - ): Promise { + async completeUserTask(userTask: UserTask, values: UserTaskResult): Promise { await this.fetch(`/tasks/${userTask.wfRunId}/${userTask.id}/result`, { method: "POST", headers: { @@ -355,31 +345,23 @@ 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. - * - * @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 - * + * Assigns a user task to a specific user or group (admin only). + * + * @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' } * ); * ``` */ - async adminAssignUserTask( - userTask: UserTask, - assignTo: { userId?: string; userGroupId?: string }, - ): Promise { + async adminAssignUserTask(userTask: UserTask, assignTo: { userId?: string; userGroupId?: string}): Promise { await this.fetch(`/admin/tasks/${userTask.wfRunId}/${userTask.id}/assign`, { method: "POST", headers: { diff --git a/api-client/src/errors.ts b/api-client/src/errors.ts index 2ca81ba..8956fe9 100644 --- a/api-client/src/errors.ts +++ b/api-client/src/errors.ts @@ -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 { /** @@ -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( @@ -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( @@ -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 { @@ -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 { @@ -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( @@ -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( @@ -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( @@ -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(