# Utils — Shared Utilities

## Overview

This module holds shared helper functions and utilities that are generic enough for use across multiple adapters. It starts minimal and grows organically as common patterns emerge from adapter development.

## Concepts

### What Belongs Here

Utilities are small, self-contained helper functions with no adapter-specific logic. Examples of what fits:

- Date/time parsing helpers for common document formats
- String normalization functions (e.g., cleaning whitespace, normalizing currency formats)
- Validation helpers for common business identifiers (VAT numbers, IBANs)
- Retry/backoff wrappers for external API calls

### What Does NOT Belong Here

- Anything specific to one adapter's business logic — keep in the adapter
- Integration clients for external systems — those are connectors (see `connectors.md`)
- Schema definitions or data models — those belong in `schemas/`
- Configuration classes — those extend `CoreSettings` in the adapter's own code

## Patterns

### Promotion Rule

The same promotion rule as connectors applies: promote a utility to the package after a second adapter needs the same function.

1. First adapter implements the utility locally in its own `utils/` directory
2. Second adapter needs the same thing — promote to the package
3. Extract, generalize (remove tenant assumptions), add docstrings, test, release as minor version

### Structural Convention

Adapter-specific utilities live in the adapter's own `utils/` directory, mirroring the package structure:

```
my-adapter/
└── src/
    └── utils/
        └── vat_validator.py    # Adapter-specific until a second adapter needs it
```

This makes future promotion a straightforward copy + generalize operation.

### Current State

The utils module is empty in the initial v1.0.0 release. The directory structure exists to establish the convention and provide a clear home for shared utilities as they emerge.

## Cross-References

- **Promotion rule**: Same pattern as `connectors.md` — promote after second use
- **Connector utilities**: If a utility is specific to communicating with an external system, it's a connector, not a utility
