# payload-contracts

Shared TypeScript types, API client, and block registry for Payload CMS multi-tenant frontends.

## Purpose

This package is the single source of truth for TypeScript types between the CMS (sv-payload) and all frontend sites (sv-frontend / Plesk production servers). It prevents type drift and provides a consistent API client across all frontends.

## Architecture

```
CMS (payload-cms)                    Contracts (this repo)                Frontends
━━━━━━━━━━━━━━━━                    ━━━━━━━━━━━━━━━━━━━━                ━━━━━━━━━
payload-types.ts ──extract-types──→  src/types/payload-types.ts
                                     src/types/collections.ts    ←────  import { Page, Post }
                                     src/types/blocks.ts         ←────  import { Block, BlockByType }
                                     src/types/media.ts          ←────  import { getImageUrl }
                                     src/types/api.ts            ←────  import { PaginatedResponse }
                                     src/api-client/             ←────  import { createPayloadClient }
                                     src/blocks/registry.ts      ←────  import { createBlockRenderer }
```

## Commands

```bash
pnpm install          # Install dependencies
pnpm build            # Compile TypeScript
pnpm typecheck        # Type-check without emitting
pnpm extract          # Re-extract types from CMS (run on sv-payload)
```

## Updating Types

When CMS collections or blocks change:

1. On sv-payload: `cd ~/payload-cms && pnpm payload generate:types`
2. On sv-payload: `cd ~/payload-contracts && pnpm extract`
3. Review changes, commit, push
4. Write a work order in `work-orders/` if frontends need updating

## Key Files

| File | Purpose |
|------|---------|
| `src/types/payload-types.ts` | Full auto-generated types from CMS |
| `src/types/collections.ts` | Curated frontend collection re-exports |
| `src/types/blocks.ts` | Block union type + BlockByType helper |
| `src/types/media.ts` | Media type + image URL helpers |
| `src/types/api.ts` | PaginatedResponse, query params, error types |
| `src/api-client/index.ts` | `createPayloadClient()` factory |
| `src/blocks/registry.ts` | `createBlockRenderer()` factory |
| `src/constants/tenants.ts` | Tenant IDs and slugs |
| `scripts/extract-types.ts` | Type extraction from payload-types.ts |

## Tenants

| ID | Slug | Site |
|----|------|------|
| 1 | porwoll | porwoll.de |
| 4 | c2s | complexcaresolutions.de |
| 5 | gunshin | gunshin.de |
| 9 | blogwoman | blogwoman.de |

## Work Orders

The `work-orders/` directory contains coordination files for propagating CMS changes to frontends. See `work-orders/_template.md` for the format.

## Git Workflow

- `main` branch only — tag releases as `v1.x.x`
- Frontends consume via Git dependency in package.json