contracts — Examples

Usage examples for the contracts package

All usage examples from the package, aggregated for quick reference.

ExternalTaskProvider

Interface that provider adapters implement to expose their external task system to the reconciliation engine. Provider-specific parsing lives in the adapter — core never sees native formats. Consumers implement this interface to integrate their issue tracker with CLEO.

View in API reference

class LinearAdapter implements ExternalTaskProvider {
  async getExternalTasks(projectDir: string): Promise<ExternalTask[]> {
    const issues = await linearClient.issues({ projectId: '...' });
    return issues.map(issue => ({
      externalId: issue.id,
      title: issue.title,
      status: mapLinearStatus(issue.state),
      description: issue.description,
      priority: mapLinearPriority(issue.priority),
      labels: issue.labels.map(l => l.name),
      url: issue.url,
      providerMeta: { linearId: issue.identifier },
    }));
  }
}

normalizeError()

Normalize any thrown value into a standardized error object. Handles: - Error instances (preserves stack trace info) - Strings (wraps in Error) - Objects with message property - null/undefined (provides fallback)

View in API reference

try {
  await riskyOperation();
} catch (err) {
  const error = normalizeError(err, 'Operation failed');
  console.error(error.message);
}

getErrorMessage()

Extract a human-readable message from any error value. Safe to use on unknown thrown values without type guards.

View in API reference

const message = getErrorMessage(err, 'Unknown error');

formatError()

Format error details for logging or display. Includes stack trace for Error instances when includeStack is true.

View in API reference

console.error(formatError(err, 'Database connection'));
// Output: [Database connection] Connection refused

isErrorType()

Check if an error represents a specific error type by code or name. Useful for conditional error handling based on error types.

View in API reference

if (isErrorType(err, 'E_NOT_FOUND')) {
  // Handle not found specifically
}

createErrorResult()

Create a standardized error result object. Common pattern for operations that return success: boolean, error?: string

View in API reference

return createErrorResult(err);
// Returns: { success: false, error: "Something went wrong" }

createSuccessResult()

Create a standardized success result object.

View in API reference

return createSuccessResult();
// Returns: { success: true }

isErrorResult()

Type guard for error results.

View in API reference

const result = await someOperation();
if (isErrorResult(result)) {
  console.error(result.error);
}

isLafsSuccess()

Type guard for success responses.

View in API reference

const result: LafsEnvelope<Task[]> = await fetchTasks();
if (isLafsSuccess(result)) {
  console.log(result.data); // Task[]
}

isLafsError()

Type guard for error responses.

View in API reference

const result: LafsEnvelope<Task[]> = await fetchTasks();
if (isLafsError(result)) {
  console.error(result.error.message);
}

isGatewayEnvelope()

Type guard for gateway responses (has _meta).

View in API reference

const response: CleoResponse<Task> = await handleRequest();
if (isGatewayEnvelope(response)) {
  console.log(response._meta.gateway);
}