/**
 * Payload 3 CollectionConfig starter — copy into src/collections/<Name>.ts and adapt.
 *
 * ADAPT-POINTS are marked with  // ADAPT:
 * Register the export in src/payload.config.ts under `collections: [ ... ]`.
 * After editing schema, run `payload generate:types`.
 *
 * Verified against payloadcms.com/docs (Payload 3.x, Next.js-native). 2026-06.
 */
import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  // ADAPT: URL-safe identifier; also the REST/GraphQL route base + relationTo target.
  slug: 'posts',

  admin: {
    useAsTitle: 'title', // ADAPT: which field labels rows in the admin list
    defaultColumns: ['title', 'status', 'updatedAt'],
    group: 'Content', // optional sidebar grouping
  },

  // Draft/publish + revision history. Remove if you don't need drafts.
  versions: { drafts: true },

  /**
   * Access control runs uniformly across Local API, REST, and GraphQL.
   * Return a boolean OR a `where` query constraint (row-level filtering).
   * A `read` returning `true` exposes EVERY row — return a constraint to scope.
   */
  access: {
    read: ({ req }) => {
      if (req.user?.role === 'admin') return true
      if (req.user) return { author: { equals: req.user.id } } // ADAPT: ownership rule
      return { _status: { equals: 'published' } } // anon: published only
    },
    create: ({ req }) => Boolean(req.user),
    update: ({ req }) =>
      req.user?.role === 'admin' ? true : { author: { equals: req.user?.id } },
    delete: ({ req }) => req.user?.role === 'admin', // ADAPT: who may delete
  },

  hooks: {
    beforeChange: [
      ({ data, req, operation }) => {
        if (operation === 'create' && req.user) data.author = req.user.id
        return data
      },
    ],
    afterChange: [
      async ({ doc }) => {
        // Bust the Next.js front-end cache on publish/edit.
        //
        // Next.js 16 signature: revalidateTag(tag, cacheLifeProfile). 'max' gives
        // stale-while-revalidate - readers keep getting the old page while the
        // rebuild runs. Use { expire: 0 } instead when the edit must be visible
        // on the very next request and a blocking revalidate is acceptable.
        //
        // NOT updateTag(): that is Server-Actions-only and throws elsewhere.
        // Payload mounts its REST/GraphQL under a Route Handler, so a hook fired
        // from the admin panel or the REST API is not in a Server Action.
        //
        // On Next.js 15, drop the second argument - the two-arg call is a
        // TypeScript error there (the single-arg form is what 15 ships).
        const { revalidateTag } = await import('next/cache')
        revalidateTag('posts', 'max') // ADAPT: tag your front end reads with
        return doc
      },
    ],
  },

  fields: [
    { name: 'title', type: 'text', required: true },
    {
      name: 'slug',
      type: 'text',
      unique: true,
      index: true,
      hooks: {
        beforeValidate: [
          ({ value, data }) =>
            value || data?.title?.toLowerCase().replace(/\s+/g, '-'),
        ],
      },
    },
    { name: 'content', type: 'richText' },
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'users', // ADAPT: must match your auth collection slug
    },
    // Field-level access: lock a field independent of the document.
    {
      name: 'internalNotes',
      type: 'textarea',
      access: {
        read: ({ req }) => req.user?.role === 'admin',
        update: ({ req }) => req.user?.role === 'admin',
      },
    },
  ],
}

# Access Control — deep dive (Payload 3)

Load when designing authorization: RBAC, multi-tenant isolation, or field-level locks.

Access functions run uniformly across the Local API, REST, and GraphQL. They return either
a `boolean` (can the user do this operation at all?) or a **query constraint** object
(row-level: *which* documents). Returning a constraint from `read`/`update`/`delete` is the
mechanism for per-tenant / per-owner data isolation — `true` alone means "all rows".

## Operation-level (collection) access

```typescript
import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  access: {
    read:   ({ req }) => {
      if (!req.user) return { status: { equals: 'published' } } // anon sees published only
      if (req.user.role === 'admin') return true
      return { author: { equals: req.user.id } }                // authors see their own
    },
    create: ({ req }) => Boolean(req.user),
    update: ({ req }) => req.user?.role === 'admin'
      ? true
      : { author: { equals: req.user?.id } },
    delete: ({ req }) => req.user?.role === 'admin',
  },
  fields: [/* ... */],
}
```

| Access fn | Controls | Returns |
|-----------|----------|---------|
| `read` | Listing + reading docs | bool or `where` constraint |
| `create` | New docs | bool |
| `update` | Editing | bool or `where` constraint |
| `delete` | Removal | bool or `where` constraint |
| `admin` | Whether user can access the admin panel (auth collection) | bool |
| `unlock`, `readVersions` | Auth/versioning specifics | bool |

## Field-level access

Lock or hide individual fields independent of the document:

```typescript
{
  name: 'internalNotes',
  type: 'textarea',
  access: {
    read:   ({ req }) => req.user?.role === 'admin',
    update: ({ req }) => req.user?.role === 'admin',
    create: ({ req }) => req.user?.role === 'admin',
  },
}
```

Field-level `read` false → field omitted from output. `update`/`create` false → field is
read-only / cannot be set even if the document is writable.

## RBAC pattern

Store a `role` (or `roles` hasMany) on the Users (auth) collection, then branch in access
functions. Centralize predicates so they're reused, not copy-pasted:

```typescript
// access/isAdmin.ts
import type { Access } from 'payload'
export const isAdmin: Access = ({ req }) => req.user?.role === 'admin'
export const isAdminOrSelf: Access = ({ req }) =>
  req.user?.role === 'admin' ? true : { author: { equals: req.user?.id } }
```

## Multi-tenant isolation

Two routes:

1. **`@payloadcms/plugin-multi-tenant`** — adds a tenant field + scoping automatically.
   Prefer this for standard cases.
2. **Custom constraints** — add a `tenant` relationship field, then enforce in every
   collection's access:

   ```typescript
   read: ({ req }) => ({ tenant: { equals: req.user?.tenant } }),
   ```

   Apply the same constraint to `create` (force-set tenant in a `beforeChange` hook),
   `update`, and `delete`. Test that a user from tenant A genuinely cannot read/modify
   tenant B's rows — this is the #1 access bug.

## Rules

- **Never bypass access control in custom endpoints.** Route through the Local API with
  access enabled. Reserve `overrideAccess: true` for trusted server-side jobs that
  *intentionally* run as system.
- A `read` that returns `true` exposes every row. If data should be scoped, return a
  constraint, not a boolean.
- Field access runs *in addition* to collection access — both must pass.
- Access functions can be async (e.g. look up tenant membership) — return a Promise.

# Hooks & Fields — deep dive (Payload 3)

Load when wiring lifecycle side effects (cache revalidation, derived data, notifications)
or composing non-trivial field structures (blocks, arrays, conditional/localized fields).

## Hooks

Hooks are arrays of functions run at lifecycle points. They exist at four levels:
**collection**, **field**, **global**, and **auth**.

### Collection hooks

| Hook | Fires | Typical use |
|------|-------|-------------|
| `beforeValidate` | Before validation | Normalize/derive input |
| `beforeChange` | Before create/update write | Mutate `data`, set derived fields |
| `afterChange` | After write | Revalidate cache, send notifications, sync external |
| `beforeRead` | Before a doc is read | Inject query context |
| `afterRead` | After read, before return | Shape outgoing doc, computed fields |
| `beforeDelete` / `afterDelete` | Around deletion | Cascade cleanup, remove files |
| `afterOperation` | After any operation | Generic post-processing |

```typescript
hooks: {
  beforeChange: [
    ({ data, req, operation }) => {
      if (operation === 'create') data.createdBy = req.user?.id
      return data
    },
  ],
  afterChange: [
    async ({ doc, req }) => {
      // bust Next.js cache for this content on publish (Next 16 two-arg form)
      const { revalidateTag } = await import('next/cache')
      revalidateTag(`posts`, 'max')
      return doc
    },
  ],
}
```

### Field hooks

Same `beforeValidate / beforeChange / afterChange / afterRead` lifecycle but scoped to a
single field — use for per-field derivation (e.g. auto-slug from title):

```typescript
{
  name: 'slug',
  type: 'text',
  hooks: {
    beforeValidate: [({ value, data }) =>
      value || data?.title?.toLowerCase().replace(/\s+/g, '-')],
  },
}
```

### Auth hooks

`beforeLogin`, `afterLogin`, `afterLogout`, `afterMe`, `afterRefresh`, `afterForgotPassword`
— hook into the auth collection's session lifecycle.

### Cache-invalidation pattern (the canonical Next.js use)

1. Tag the front-end read: `'use cache'` + `cacheTag('posts')` on Next 16, or
   `unstable_cache(..., { tags: ['posts'] })` on 15 (`unstable_cache` still runs
   on 16, but the docs now point at `use cache`).
2. In the collection's `afterChange` (and `afterDelete`), call
   `revalidateTag('posts', 'max')`.
3. Publish/edit now busts exactly the affected cache entry.

#### Which Next.js major (verified against nextjs.org, Next 16.3.3, 2026-08)

`revalidateTag` takes a **cacheLife profile as a second argument since Next.js 16**.
The single-argument form still runs but is deprecated.

| Next.js | Call | Behaviour |
|---|---|---|
| 16 | `revalidateTag('posts', 'max')` | Stale-while-revalidate — readers are served the old page for up to a year while the rebuild runs. The recommended default. |
| 16 | `revalidateTag('posts', { expire: 0 })` | No stale content; the next request blocks on a fresh fetch. Use when the edit must be visible immediately. |
| 15 | `revalidateTag('posts')` | The only signature 15 has. Passing a second argument is a **TypeScript error** on 15, so don't ship the two-arg form to a 15 app. |

**Do not reach for `updateTag()` here.** It is the Next 16 read-your-own-writes API,
but it can *only* be called from inside a Server Action and throws anywhere else.
Payload mounts its REST and GraphQL surface under a Route Handler, so an
`afterChange` triggered by the admin panel or an API write is not in a Server
Action — `revalidateTag` is the correct call in a Payload hook. `updateTag` only
applies when *your own* Server Action calls the Local API directly.

Payload 3 does not pin a Next.js major, so check the host app's `next` version
before copying either form. The `nextjs-ops` skill carries the full caching model.

## Fields — composition patterns

### Blocks (flexible content)

```typescript
{
  name: 'layout',
  type: 'blocks',
  blocks: [
    {
      slug: 'hero',
      fields: [
        { name: 'heading', type: 'text' },
        { name: 'image', type: 'upload', relationTo: 'media' },
      ],
    },
    {
      slug: 'richText',
      fields: [{ name: 'content', type: 'richText' }],
    },
  ],
}
```

Each row stores a `blockType`; branch on it when rendering. This is Payload's equivalent
of flexible page builders.

### Array fields

```typescript
{
  name: 'features',
  type: 'array',
  minRows: 1,
  fields: [
    { name: 'label', type: 'text' },
    { name: 'icon', type: 'text' },
  ],
}
```

### Conditional display

```typescript
{
  name: 'externalUrl',
  type: 'text',
  admin: { condition: (data) => data.linkType === 'external' },
}
```

### Localization (i18n)

Set `localized: true` on any field; Payload stores per-locale values. Configure `locales`
in `payload.config.ts`. Query a locale via Local API `locale` param.

### Field access & validation

Every field accepts:
- `access: { read, create, update }` — field-level authorization (see access-control.md)
- `validate: (value, { data, req }) => true | 'error message'`
- `defaultValue`, `required`, `unique`, `index`
- `hooks` — field-scoped lifecycle (above)

## Generated types

Run `payload generate:types` after schema changes to produce a typed `payload-types.ts`.
Import the generated interfaces in front-end code so Local API results are fully typed.