> ## Documentation Index
> Fetch the complete documentation index at: https://codluv.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/packages/contracts/api/functions#externaltaskprovider)

```typescript theme={null}
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](/packages/contracts/api/functions#normalizeerror)

```typescript theme={null}
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](/packages/contracts/api/functions#geterrormessage)

```typescript theme={null}
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](/packages/contracts/api/functions#formaterror)

```typescript theme={null}
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](/packages/contracts/api/functions#iserrortype)

```typescript theme={null}
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](/packages/contracts/api/functions#createerrorresult)

```typescript theme={null}
return createErrorResult(err);
// Returns: { success: false, error: "Something went wrong" }
```

## `createSuccessResult()`

*Create a standardized success result object.*

[View in API reference](/packages/contracts/api/functions#createsuccessresult)

```typescript theme={null}
return createSuccessResult();
// Returns: { success: true }
```

## `isErrorResult()`

*Type guard for error results.*

[View in API reference](/packages/contracts/api/functions#iserrorresult)

```typescript theme={null}
const result = await someOperation();
if (isErrorResult(result)) {
  console.error(result.error);
}
```

## `isLafsSuccess()`

*Type guard for success responses.*

[View in API reference](/packages/contracts/api/functions#islafssuccess)

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

## `isLafsError()`

*Type guard for error responses.*

[View in API reference](/packages/contracts/api/functions#islafserror)

```ts theme={null}
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](/packages/contracts/api/functions#isgatewayenvelope)

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