# AGENTS.md — marketing-pages

Pages collection + SiteSettings global for site-wide metadata. Provides marketing/landing page content, SEO settings, and site configuration via Payload.

## Overview

`@repo/marketing-pages` owns: Page and SiteSettings domain models, marketing-pages-scoped errors, `IPagesRepository` + `ISiteSettingsRepository` interfaces, two use cases, two controllers, real Payload-backed repositories, and the tRPC `marketingPagesRouter`. Query builders live in `./ui`.

## Layer responsibilities

| Layer                              | Key files                                                                                                                                  |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **entities/models**                | `page.ts` (`Page`, `PageStatus`, `Hero`), `site-settings.ts` (`SiteSettings`) — Zod schemas + types                                        |
| **entities/errors**                | `page.ts` (PageNotFoundError), `common.ts` (InputParseError)                                                                               |
| **application/use-cases**          | `get-page-by-slug.use-case.ts`, `get-site-settings.use-case.ts` — factory functions + exported schemas                                     |
| **application/repositories**       | `pages.repository.interface.ts`, `site-settings.repository.interface.ts`                                                                   |
| **infrastructure/repositories**    | `pages.repository.ts`, `site-settings.repository.ts` (real Payload-backed); `pages.repository.mock.ts`, `site-settings.repository.mock.ts` |
| **interface-adapters/controllers** | `get-page-by-slug.controller.ts`, `get-site-settings.controller.ts` — one file per use case                                                |
| **di**                             | `symbols.ts` (MARKETING_PAGES_SYMBOLS), `module.ts`, `container.ts`, `bind-production.ts`                                                  |
| **integrations/api**               | `procedures.ts` (marketingPagesProcedure), `router.ts` (marketingPagesRouter)                                                              |
| **integrations/cms**               | `collections/pages.ts`, `globals/site-settings.ts` — Payload definitions                                                                   |
| **ui**                             | `src/ui/index.ts` — re-exports `pageBySlugQuery` and `siteSettingsQuery`                                                                   |

## Public exports

| Subpath                       | Contents                                                                                                                                                                                                              |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.`                           | `Page`, `PageStatus`, `Hero`, `SiteSettings` types; `PageNotFoundError`, `InputParseError`; all use-case schemas + input/output types + `IXUseCase` aliases; `IXController` type aliases; `MarketingPagesRouter` type |
| `./ui`                        | `pageBySlugQuery`, `siteSettingsQuery` — React Query option builders                                                                                                                                                  |
| `./api`                       | `marketingPagesRouter` (tRPC router)                                                                                                                                                                                  |
| `./cms`                       | Payload Pages collection + SiteSettings global                                                                                                                                                                        |
| `./di/bind-production`        | `bindProductionMarketingPages(ctx: BindProductionContext)` — swaps mock impls for real Payload-backed ones at app boot                                                                                                |
| `./di/bind-dev-seed`          | `bindDevSeedMarketingPages(ctx: BindContext)` — replaces the default empty mocks with populated ones for dev / Storybook                                                                                              |
| `./di/container`              | `marketingPagesContainer` — the per-feature inversify container (consumed by e2e tests + production Payload event-tasks)                                                                                              |
| `./di/symbols`                | `MARKETING_PAGES_SYMBOLS` — DI symbol registry (consumed by e2e tests + production Payload event-tasks)                                                                                                               |
| `./services/mailer`           | `IMailerService` — interface for the welcome-email seam (ADR-015 proof-of-life)                                                                                                                                       |
| `./services/recording-mailer` | `RecordingMailerService` — test / dev-seed mailer that records calls instead of sending                                                                                                                               |

## Use-case + controller patterns

See `CLAUDE.md` Key Conventions and `docs/architecture/overview.md` for the canonical factory templates.

### Use cases

| Use case                 | Input schema                                                        | Output schema                                           | Notes                                                                                                                                                             |
| ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getPageBySlugUseCase`   | `getPageBySlugInputSchema` — `{ slug }`                             | `getPageBySlugOutputSchema` — `pageSchema \| undefined` | Returns `undefined` for missing pages (preserves existing semantics); `PageNotFoundError` mapping is forward-compatible for if/when the use case changes to throw |
| `getSiteSettingsUseCase` | `getSiteSettingsInputSchema` — `z.object({}).strict()` (void input) | `getSiteSettingsOutputSchema` — `siteSettingsSchema`    | Takes `_input: GetSiteSettingsInput` parameter; always returns settings or throws                                                                                 |

### Controllers

Both controllers use identity presenters — `function presenter(value: XOutput) { return value; }`. `getPageBySlugController` return type is `ReturnType<typeof presenter> | undefined` (preserves the missing-page semantics). Both accept `unknown` input and `safeParse` with the use-case's `xInputSchema`, throwing `InputParseError` on failure.

## Errors → tRPC codes

| Error class         | tRPC code     | Thrown by                                                                              |
| ------------------- | ------------- | -------------------------------------------------------------------------------------- |
| `InputParseError`   | `BAD_REQUEST` | controllers (safeParse failure)                                                        |
| `PageNotFoundError` | `NOT_FOUND`   | forward-compat; current `getPageBySlugUseCase` returns `undefined` instead of throwing |

Defined in `src/integrations/api/procedures.ts` via `marketingPagesProcedure = t.procedure.use(defineErrorMiddleware([...]))`.

## Tests

- **Factories:** `src/__factories__/page.factory.ts`, `src/__factories__/site-settings.factory.ts`
- **Contract suites:** `src/__contracts__/pages-repository.contract.ts`, `src/__contracts__/site-settings-repository.contract.ts`
- **Unit tests:** colocated `*.test.ts` next to each source file
- **Feature integration:** `tests/page-by-slug.feature.test.ts` — full slice: tRPC caller → controller → use case → mock repo
- **R25** (output validation): `get-page-by-slug.use-case.test.ts` has a test injecting a malformed page repository mock asserting `.rejects.toBeInstanceOf(ZodError)`. `get-site-settings.use-case.test.ts` uses an inline malformed repository mock (e.g., `{ siteName: "" }` failing `min(1)`) to assert ZodError.
- **R26** (router error mapping): `router.test.ts` asserts `BAD_REQUEST` on empty input for `pageBySlug`; confirms `undefined` return for missing slug (use case does not throw `PageNotFoundError` today).
- **R27/R28** (presenter shape): both controllers use identity presenters — no reshape test obligation.

```bash
pnpm test --filter @repo/marketing-pages
pnpm test --filter @repo/marketing-pages -- --watch
```

See `docs/guides/tdd-workflow.md` for the full cycle.

## Directory structure

```
src/
  entities/
    models/
      page.ts
      site-settings.ts
    errors/
      page.ts          # PageNotFoundError
      common.ts        # InputParseError
  application/
    repositories/
      pages.repository.interface.ts
      site-settings.repository.interface.ts
    use-cases/
      get-page-by-slug.use-case.ts
      get-site-settings.use-case.ts
  infrastructure/
    repositories/
      pages.repository.ts               # real Payload-backed
      pages.repository.mock.ts
      site-settings.repository.ts       # real Payload-backed
      site-settings.repository.mock.ts
  interface-adapters/
    controllers/
      get-page-by-slug.controller.ts
      get-site-settings.controller.ts
  integrations/
    api/
      procedures.ts    # marketingPagesProcedure
      router.ts        # marketingPagesRouter
    cms/
      collections/
        pages.ts
      globals/
        site-settings.ts
      index.ts
  di/
    symbols.ts
    module.ts
    container.ts
    bind-production.ts
  ui/
    index.ts           # pageBySlugQuery, siteSettingsQuery
    query.ts
  index.ts
  __factories__/
    page.factory.ts
    site-settings.factory.ts
  __contracts__/
    pages-repository.contract.ts
    site-settings-repository.contract.ts
tests/
  page-by-slug.feature.test.ts
```

## What it must NOT import

- Any other feature package (`@repo/auth`, `@repo/blog`, etc.)
- Any app package
- `@repo/core-api`, `@repo/core-cms`, `@repo/core-trpc`, `@repo/core-ui` directly; only `@repo/core-shared`
  > Note: `@repo/core-trpc` and `@repo/core-ui` are optional packages scaffolded via `pnpm turbo gen core-package trpc` / `ui`. If not present, these constraints still apply to any future installation.

## Cross-links

- ADR-012 (`docs/decisions/adr-012-feature-conventions.md`) — factory-style use cases, per-use-case controllers, file-naming conventions
- ADR-013 (`docs/decisions/adr-013-input-output-unification.md`) — schemas-in-use-case, presenter, `./ui` subpath, error middleware
