Banner Module

HTTP surface for promotional banners attached to catalog entities (categories, brands, tags, ingredients) — admin CRUD + unauthenticated storefront read by entity slug.

Source: api-modules/banner (registered via BannerModule.forRoot() in apps/api/src/app.module.ts).

Banner attaches to one catalog entity via a polymorphic (entity_type, entity_id) pair. The catalog module's admin list endpoints surface a bannerCount so admins can see how many banners are attached before deleting a brand/category.

Conventions

Authentication

Response envelope

Successful responses are wrapped by ResponseInterceptor:

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* optional, e.g. pagination */ }
}

Error envelope

Lifecycle

Banners soft-delete via deletedAt. Hidden from default listings and from the storefront read, but GET /admin/banners?includeDeleted=true (via the generic filters field) returns them.

Domain types

BannerResponse

type BannerEntityType = "category" | "brand" | "tag" | "ingredient";
type Platform = "APP" | "WEB" | "BOTH";

type BannerResponse = {
  id: string;
  entityType: BannerEntityType;
  entityId: string;
  image: string;                       // storage key (S3) — resolve to URL client-side
  url: string;                         // click destination
  platform: Platform;
  isActive: boolean;
  sortOrder: number;                   // ascending; ties broken by createdAt desc
  metadata: Record<string, unknown> | null;
  createdAt: string;                   // ISO
  updatedAt: string;
  deletedAt: string | null;
};

URL rules

url is validated to be either an absolute https:// URL or a relative path that begins with /. Plain http://, javascript:, mailto:, etc. are rejected. The storefront uses banner URLs verbatim — keep them sanitized.

Image storage

image is the S3 key returned by the storage module's presigned-upload flow. The banner module does not validate the key format or that the object exists — it's a length-only check (1..1024 chars). The storefront resolves keys to public URLs via the storage CDN.

Admin

Base path: /admin/banners.

GET /admin/banners — List banners

Required permission: banner: read. Standard QueryDto (page / limit / search / filters) plus first-class banner filters.

Query

Response 200 — paginated envelope of BannerResponse[].

GET /admin/banners/:id

Required permission: banner: read. 404 on unknown id.

POST /admin/banners — Create

Required permission: banner: create.

Body

{
  "entityType": "brand",
  "entityId": "01J9...",            // must reference a non-deleted entity
  "image": "banners/2026-05/festive.jpg",
  "url": "/sale",                   // or "https://example.com/sale"
  "platform": "BOTH",               // default "BOTH"
  "isActive": true,                 // default true
  "sortOrder": 0,                   // default 0
  "metadata": { "campaign": "Q2" }  // optional
}

Response 201 — BannerResponse.

Errors

PUT /admin/banners/:id — Update

Required permission: banner: update. entityType and entityId are immutable — to move a banner to a different entity, soft-delete and re-create. Keeps service-layer validation simple and makes the intent explicit.

Body — partial CreateBannerInput minus entityType / entityId.

Response 200 — BannerResponse.

DELETE /admin/banners/:id — Soft delete

Required permission: banner: delete. Stamps deletedAt. Reversible via POST /:id/restore.

POST /admin/banners/:id/restore — Restore

Required permission: banner: update. Clears deletedAt.

Storefront

GET /store/banners/:entityType/slug/:slug — Active banners for an entity

Unauthenticated. Returns active (isActive=true, deletedAt IS NULL) banners attached to the resolved entity, sorted by sortOrder ASC, createdAt DESC.

Path params

Query

When the entity slug doesn't resolve, the response is an empty array (not 404 — distinguishes "no banners" from "no such category" the same way for the consumer).

Response 200 — array of BannerResponse.

{
  "data": [
    {
      "id": "01J9...",
      "entityType": "brand",
      "entityId": "01J9...",
      "image": "banners/2026-05/festive.jpg",
      "url": "/sale",
      "platform": "BOTH",
      "isActive": true,
      "sortOrder": 0,
      "metadata": null,
      "createdAt": "2026-05-01T08:00:00.000Z",
      "updatedAt": "2026-05-01T08:00:00.000Z",
      "deletedAt": null
    }
  ],
  "message": "Success",
  "statusCode": 200
}

Domain events

Emitted via EventEmitter2 after writes — consumed by the storefront cache invalidator.

Related modules

• catalog — owns the four entity tables (category, brand, tag, ingredient) that banners reference. Admin lists in catalog surface a bannerCount aggregated from this table. See catalog.md.
• storage — provides presigned-upload URLs for banner images and resolves keys to CDN URLs on the storefront.