@timeback/caliper 0.2.1-beta.20260331191116 → 0.2.1

package/dist/errors.d.ts

@@ -1 +1,144 @@
-export { ApiError as CaliperError, ForbiddenError, InputValidationError, NotFoundError, UnauthorizedError, ValidationError } from '@timeback/internal-client-infra';
+/**
+ * Error Types
+ *
+ * Shared types for error helpers.
+ */
+/**
+ * Validation issue from client-side input validation.
+ */
+interface ValidationIssue {
+    /** Field path (e.g. "sourcedId", "metadata.email") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+}
+
+/**
+ * API Error Classes
+ *
+ * Base error classes for HTTP API failures.
+ * Includes IMS Global error response parsing (OneRoster, QTI, etc.).
+ */
+
+/**
+ * Base error class for all API errors.
+ *
+ * Provides access to the HTTP status code and raw response body.
+ * Includes IMS Global error parsing (minorCodes, details) for
+ * IMS-standard APIs like OneRoster and QTI.
+ *
+ * @example
+     * ```typescript
+     * // Catching and inspecting errors
+     * try {
+ *   await client.users.get('non-existent-id')
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.log(`Error ${error.statusCode}: ${error.message}`)
+ *     console.log('Minor codes:', error.minorCodes)
+ *     console.log('Details:', error.details)
+ *   }
+ * }
+ * ```
+ */
+declare class ApiError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly response?: unknown;
+    readonly name: string;
+    /**
+     * Creates a new ApiError.
+     *
+     * @param message - Human-readable error message
+     * @param statusCode - HTTP status code
+     * @param response - Raw response body (if available)
+     */
+    constructor(message: string, statusCode?: number | undefined, response?: unknown);
+    /**
+     * Minor error codes from IMS Global error response.
+     *
+     * For IMS-standard APIs (OneRoster, QTI), provides specific error codes
+     * like "unknownobject" or "invaliddata".
+     *
+     * @returns Array of field/value pairs, or empty array if not IMS format
+     */
+    get minorCodes(): Array<{
+        field: string;
+        value: string;
+    }>;
+    /**
+     * Additional error details from IMS Global response.
+     *
+     * May contain field-level validation errors or other structured details.
+     *
+     * @returns Array of key-value objects, or empty array if not present
+     */
+    get details(): Array<Record<string, string>>;
+}
+/**
+ * Error thrown when authentication fails (HTTP 401).
+ *
+ * Typically indicates invalid or expired credentials.
+ */
+declare class UnauthorizedError extends ApiError {
+    readonly name = "UnauthorizedError";
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Error thrown when the client lacks permission for the operation (HTTP 403).
+ *
+ * The credentials are valid, but the client is not authorized for this action.
+ */
+declare class ForbiddenError extends ApiError {
+    readonly name = "ForbiddenError";
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Error thrown when a requested resource is not found (HTTP 404).
+ */
+declare class NotFoundError extends ApiError {
+    readonly name = "NotFoundError";
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Error thrown when request data is invalid (HTTP 422).
+ *
+ * Check the `details` property for field-level validation errors.
+ */
+declare class ValidationError extends ApiError {
+    readonly name = "ValidationError";
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Validation issue from client-side input validation.
+ */
+/**
+ * Error thrown when client-side input validation fails.
+ *
+ * This is thrown **before** making a network request, providing fast feedback
+ * with actionable, path-based error messages.
+ *
+ * Uses statusCode 400 (Bad Request) to distinguish from server-side 422 errors.
+ * Formats like IMS errors via `imsx_error_details` so existing error formatters work.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.users.create({}) // missing required fields
+ * } catch (error) {
+ *   if (error instanceof InputValidationError) {
+ *     console.log('Invalid input:', error.issues)
+ *     // [{ path: 'sourcedId', message: 'Required' }]
+ *   }
+ * }
+ * ```
+ */
+declare class InputValidationError extends ApiError {
+    readonly name = "InputValidationError";
+    /**
+     * The validation issues that caused this error.
+     */
+    readonly issues: ValidationIssue[];
+    constructor(message: string, issues: ValidationIssue[]);
+}
+
+export { ApiError as CaliperError, ForbiddenError, InputValidationError, NotFoundError, UnauthorizedError, ValidationError };