<!-- source-hash: cd90c6466cd8d12a5c8765efbf35dcb1 -->
Defines the wire-shape types and a pure formatter for investor update entities, used across chat cards and `/api/investor-updates` API reads.

## Key Components

### Interfaces

| Interface | Purpose |
|---|---|
| `MetricEntry` | A single financial or KPI metric with current/previous values and visibility scope |
| `HighlightEntry` | A titled highlight item (milestone, note, etc.) with optional description and visibility |
| `InvestorUpdateHighlights` | Grouped collections of `HighlightEntry` items by category |
| `InvestorUpdate` | Full wire shape for an investor update — covers content, media, SEO, HubSpot, authorship, and visibility |

### Functions

- **`formatInvestorUpdatePeriod`** — Pure formatter that converts `period_start` / `period_end` ISO strings into a human-readable range (e.g. `Mar 2025 - May 2025`). Falls back to `?` for missing endpoints.

## Usage Example

```typescript
import type { InvestorUpdate, MetricEntry } from './investor-update';
import { formatInvestorUpdatePeriod } from './investor-update';

// Format a period range for display
const label = formatInvestorUpdatePeriod('2025-03-01', '2025-05-31');
// → "Mar 2025 - May 2025"

const labelLong = formatInvestorUpdatePeriod('2025-03-01', null, { monthFormat: 'long' });
// → "March 2025 - ?"

// Type-safe metric entry
const mrr: MetricEntry = {
  current: 42000,
  previous: 38000,
  change_pct: 10.5,
  visibility: 'internal',
};
```

## Notes

- Visibility fields (`'public' | 'internal'`) control what surfaces in public-facing vs. internal views — filtering logic stays hub-side.
- `section_visibility` is a freeform record allowing per-section overrides on any `InvestorUpdate`.
- Server-side data utilities and DB access remain in `lib/data/investor-update-utils-shared.ts`; this file exports types and pure functions only.