@12-apps/discounts 1.2.0 → 1.3.0

package/src/react/transport.ts

@@ -0,0 +1,115 @@
+/**
+ * How the discounts screens reach their data — the report-builder transport
+ * doctrine, which `@12-apps/entity-lifecycle` also follows: this is the ONLY
+ * way the surface performs I/O, so a caller supplying one has substituted the
+ * entire backend without stubbing a global. That is what makes the screens
+ * drivable from a story and testable without a server.
+ *
+ * The default is a same-origin `fetch` riding the browser's cookies.
+ */
+
+/** A write outcome the screens BRANCH on, rather than a thrown mutation. */
+export type DiscountsResult<T> =
+  | { ok: true; data: T }
+  | {
+      ok: false;
+      error: string;
+      /** Per-input messages the form paints, keyed by its own field names. */
+      fieldErrors?: Record<string, string>;
+      /** The status behind the failure; absent when nothing answered at all. */
+      status?: number;
+    };
+
+/** A failed read, carrying the status a screen may want to branch on. */
+export class DiscountsHttpError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "DiscountsHttpError";
+    this.status = status;
+    Object.setPrototypeOf(this, DiscountsHttpError.prototype);
+  }
+}
+
+export interface DiscountsTransport {
+  /** A read. Answers the whole JSON payload, envelope included. */
+  get<T>(path: string): Promise<T>;
+  /** A write. Answers a {@link DiscountsResult} rather than rejecting. */
+  send<T>(path: string, method: string, body?: unknown): Promise<DiscountsResult<T>>;
+}
+
+/** The refusal half of the envelope every `createApi*` package answers in. */
+interface ErrorEnvelope {
+  error?: string;
+  issues?: Record<string, string>;
+}
+
+async function readJson<T>(path: string): Promise<T> {
+  const response = await fetch(path, {
+    credentials: "same-origin",
+    headers: { Accept: "application/json" },
+  });
+  if (!response.ok) {
+    const payload = (await response.json().catch(() => null)) as ErrorEnvelope | null;
+    throw new DiscountsHttpError(
+      response.status,
+      payload?.error ?? `HTTP ${response.status} for ${path}`,
+    );
+  }
+  return (await response.json()) as T;
+}
+
+/** The headers and body a write carries — the `Content-Type` only when there is one. */
+function requestInit(method: string, body: unknown): RequestInit {
+  const hasBody = body !== undefined;
+  return {
+    method,
+    credentials: "same-origin",
+    headers: {
+      Accept: "application/json",
+      ...(hasBody ? { "Content-Type": "application/json" } : {}),
+    },
+    ...(hasBody ? { body: JSON.stringify(body) } : {}),
+  };
+}
+
+/** A non-2xx, folded into the shape a form branches on. */
+function refusal<T>(
+  status: number,
+  payload: ErrorEnvelope | null,
+  fallbackError: string,
+): DiscountsResult<T> {
+  return {
+    ok: false,
+    error: payload?.error ?? fallbackError,
+    status,
+    ...(payload?.issues ? { fieldErrors: payload.issues } : {}),
+  };
+}
+
+/**
+ * @param fallbackError What a failed write says when the server sent no
+ * sentence of its own — REQUIRED, the host's words. `createWebDiscounts`
+ * passes its (equally required) `copy.form.saveFailed`; only a host building
+ * the transport by hand writes it here.
+ */
+export function httpDiscountsTransport(fallbackError: string): DiscountsTransport {
+  return {
+    get: readJson,
+    async send<T>(path: string, method: string, body?: unknown): Promise<DiscountsResult<T>> {
+      try {
+        const response = await fetch(path, requestInit(method, body));
+        const payload = (await response.json().catch(() => null)) as
+          | ({ data?: T } & ErrorEnvelope)
+          | null;
+        if (!response.ok) return refusal<T>(response.status, payload, fallbackError);
+        return { ok: true, data: (payload?.data ?? null) as T };
+      } catch (error) {
+        // No `status`, deliberately: its absence is the only thing separating
+        // "the server said no" from "nothing answered", and the two want
+        // different handling.
+        return { ok: false, error: error instanceof Error ? error.message : fallbackError };
+      }
+    },
+  };
+}

package/src/react/use-discounts-data.ts

@@ -0,0 +1,103 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { DiscountsApiClient, DiscountsPage, WireTargetGroup } from "./api";
+
+/**
+ * The screen's two reads, and the three states they can be in.
+ *
+ * A hand-rolled loader rather than a query library, and that is a dependency
+ * decision rather than a preference: a host on TanStack Query, SWR or nothing
+ * at all must all be able to mount this surface, and taking one of them as a
+ * peer would decide for them. What is lost is a shared cache across pages; what
+ * is kept is the one behaviour that actually matters on a server-driven grid —
+ * the PREVIOUS page stays on screen while the next one loads, so paging does
+ * not flash an empty table.
+ *
+ * The two reads are separate on purpose. The page changes on every filter
+ * keystroke; the registered collections change when a host adds one, which is
+ * never during a session. Refetching the catalog per keystroke would be the
+ * origin's mistake — it side-loaded both catalogs on every mount — at a higher
+ * frequency.
+ */
+
+interface DiscountsData {
+  page: DiscountsPage | null;
+  /** Undefined until the collections have loaded — see the menu's `groups`. */
+  groups: readonly WireTargetGroup[] | undefined;
+  /** True only for the FIRST load; a refetch keeps the previous page on screen. */
+  loading: boolean;
+  error: string | null;
+  refresh: () => void;
+}
+
+/**
+ * @param search The owned query params for this render, already serialized. A
+ * string rather than an object so the effect's dependency is a value, not an
+ * identity — an object literal would re-fetch on every render.
+ */
+export function useDiscountsData(
+  api: DiscountsApiClient,
+  search: string,
+  onError: (error: unknown, context: string) => void,
+): DiscountsData {
+  const [page, setPage] = useState<DiscountsPage | null>(null);
+  const [groups, setGroups] = useState<readonly WireTargetGroup[] | undefined>(undefined);
+  const [error, setError] = useState<string | null>(null);
+  const [nonce, setNonce] = useState(0);
+  // Every in-flight read is stamped, and only the LATEST one may write. Two
+  // keystrokes can be in flight at once and they can answer out of order; the
+  // slower one landing last would put an older page on screen with no clue
+  // anything went wrong.
+  const latest = useRef(0);
+
+  const report = useCallback(
+    (cause: unknown, context: string) => {
+      setError(cause instanceof Error ? cause.message : String(cause));
+      onError(cause, context);
+    },
+    [onError],
+  );
+
+  useEffect(() => {
+    const ticket = ++latest.current;
+    api
+      .list(search)
+      .then((next) => {
+        if (ticket !== latest.current) return;
+        setError(null);
+        setPage(next);
+      })
+      .catch((cause: unknown) => {
+        if (ticket !== latest.current) return;
+        report(cause, "discounts.list");
+      });
+  }, [api, search, nonce, report]);
+
+  useEffect(() => {
+    let live = true;
+    api
+      .targets()
+      .then((next) => {
+        if (live) setGroups(next);
+      })
+      .catch((cause: unknown) => {
+        // A failed catalog read is NOT a failed page. The grid is perfectly
+        // readable without it; only the edit form is withheld, which is what
+        // `groups: undefined` already means to the row menu.
+        if (live) onError(cause, "discounts.targets");
+      });
+    return () => {
+      live = false;
+    };
+  }, [api, onError]);
+
+  return {
+    page,
+    groups,
+    loading: page === null && error === null,
+    error,
+    refresh: useCallback(() => setNonce((value) => value + 1), []),
+  };
+}

package/src/server/collections.ts

@@ -0,0 +1,290 @@
+import { DISCOUNT_TARGET_TYPES, type DiscountTargetType } from "../engine/kinds";
+import type { ComboRequirement } from "../engine/types";
+import type { DiscountTargets } from "./validate";
+
+/**
+ * How a host TABLE opts into being discountable (FUT-244).
+ *
+ * A discount points at rows this package will never see: a store's categories,
+ * its products, and — the day a host wants it — its suppliers or its shelves.
+ * Every one of those questions ("which of them exist", "are they this
+ * tenant's", "what is this one filed under") is answerable only by the host,
+ * and until now each host answered them in its own hand-written code beside
+ * its own tables.
+ *
+ * The shape is deliberately {@link LifecycleEntityRegistration}'s, from
+ * `@12-apps/entity-lifecycle`: identity plus a duck-typed ops seam the host
+ * implements against its own tables. The family resemblance is the point — a
+ * reader who knows one knows this one — and so is the difference: entity
+ * lifecycle registers a collection it DRIVES, with write ops, while this
+ * registers a catalog dimension it only QUERIES, so every op here reads.
+ *
+ * ## Why this is not a wiring capability
+ *
+ * `@12-apps/wiring`'s contract folder holds http, web, mcp, db, env, jobs,
+ * email, notifications and permissions — there is no registration or extension
+ * concept, so promoting this would be a genuinely new capability minted on two
+ * instances that differ in the way just described. Abstracting one contract
+ * over both risks fitting neither. It lives here, shaped like its sibling, and
+ * a third consumer is what would earn it a place in the contract.
+ */
+
+/** One selectable row of a host collection, as a picker renders it. */
+export interface DiscountTarget {
+  id: string;
+  /** The operator-facing name. Host vocabulary, host language. */
+  name: string;
+  /**
+   * The parent row, for a collection that NESTS (a category tree). A picker
+   * uses it to render a tree instead of a flat list, and the evaluator's
+   * category path is built from the same edges. Absent or null at the root.
+   */
+  parentId?: string | null;
+}
+
+/**
+ * The three reads this package needs of a host's table. Every one is scoped by
+ * tenant, and none of them writes: a discount never creates, renames or
+ * deletes a category — it only ever asks about one.
+ */
+export interface DiscountableOps {
+  /**
+   * Every row of this collection the tenant owns, for the target picker.
+   *
+   * The whole collection, not a page: a picker that paginated would let an
+   * operator save a discount whose existing targets were never on screen, and
+   * silently drop them. A host with a catalog too large to hand over caps it
+   * and says so in its own surface — which is a host decision, not this
+   * package's.
+   */
+  list(clientId: string): Promise<readonly DiscountTarget[]>;
+  /**
+   * Whether EVERY id names a live row of this collection owned by `clientId`.
+   *
+   * This is the cross-tenant guard, and it is the reason the op is not
+   * optional. Without it a crafted write could point one store's promotion at
+   * another store's catalog, and the reverse menu-badge lookup would then
+   * advertise it there.
+   */
+  ownsAll(clientId: string, ids: readonly string[]): Promise<boolean>;
+  /**
+   * `child id → parent id` for the whole collection, for the ancestry walk a
+   * nesting collection needs (see {@link buildTargetPath}).
+   *
+   * Separate from {@link list} even though `list` carries `parentId`, because
+   * the two are read on different paths: `list` feeds an admin picker once,
+   * while this runs on the MONEY path — every cart mutation and every menu
+   * page's badge preview — where a host wants two indexed columns rather than
+   * the picker's whole payload. A flat collection omits it.
+   */
+  parents?(clientId: string): Promise<ReadonlyMap<string, string | null>>;
+}
+
+/** One host table, declared discountable. */
+export interface DiscountableCollection {
+  /**
+   * Which dimension this collection answers for. Closed at two today; see
+   * {@link DISCOUNT_TARGET_TYPES} for what widening it would take.
+   */
+  targetType: DiscountTargetType;
+  /** The picker's URL segment and its `data-testid` stem, e.g. `"categories"`. */
+  slug: string;
+  /**
+   * What an operator calls this collection ("Categorias", "Produtos"). Host
+   * vocabulary in the host's language, and therefore host config — the same
+   * rule the copy ports follow, answered here rather than in a copy pack
+   * because a pack keyed by a host-chosen collection could not be typed.
+   */
+  label: string;
+  /** Whether a target covers the rows filed UNDER it. `parents` must be set. */
+  nests?: boolean;
+  ops: DiscountableOps;
+}
+
+/** The picker's payload for one collection: what it is, and what is in it. */
+export interface DiscountTargetGroup {
+  targetType: DiscountTargetType;
+  slug: string;
+  label: string;
+  nests: boolean;
+  targets: readonly DiscountTarget[];
+}
+
+/**
+ * Raised when a write names a target that is not this tenant's.
+ *
+ * Its own class rather than a `DiscountValidationError` so that the sentence
+ * stays the host's while the FIELD stays the package's: a form paints
+ * `targets`, and `routes.ts` folds this into the same 422 envelope.
+ */
+export class ForeignTargetError extends Error {
+  readonly field = "targets";
+  constructor(message: string) {
+    super(message);
+    this.name = "ForeignTargetError";
+  }
+}
+
+/** Every id a write points at, per dimension — the top-level pair AND the slots. */
+export function targetIdsByType(
+  targets: DiscountTargets,
+): Readonly<Record<DiscountTargetType, string[]>> {
+  const categoryIds = new Set(targets.categoryIds);
+  const menuItemIds = new Set(targets.menuItemIds);
+  addSlotIds(targets.comboRequirements, categoryIds, menuItemIds);
+  return { CATEGORY: [...categoryIds], ITEM: [...menuItemIds] };
+}
+
+/**
+ * Fold the combo slots' own targets in.
+ *
+ * A separate function because it is where the gap was: the origin host checked
+ * `categoryIds` and `menuItemIds` and nothing else, so a crafted COMBO whose
+ * slots named another store's products would have passed — invisibly, because
+ * a combo scope drops the top-level pair and carries its targets in the slots.
+ * It was never live only because the slots were not yet persisted anywhere.
+ */
+function addSlotIds(
+  requirements: readonly ComboRequirement[],
+  categoryIds: Set<string>,
+  menuItemIds: Set<string>,
+): void {
+  for (const requirement of requirements) {
+    requirement.categoryIds.forEach((id) => categoryIds.add(id));
+    requirement.menuItemIds.forEach((id) => menuItemIds.add(id));
+  }
+}
+
+/**
+ * Refuse a write pointing at a row this tenant does not own, before it reaches
+ * the store.
+ *
+ * ## Why OUTSIDE the store's transaction is enough
+ *
+ * The origin host ran this check inside the write transaction, which reads as
+ * the safer arrangement, and for the leak that matters it makes no difference:
+ * a catalog row's tenant never changes, so an id that belongs to this tenant
+ * now cannot belong to another one by the time the write lands. The only race
+ * left is a target DELETED between the check and the write — whose outcome is a
+ * discount pointing at a row that no longer exists, which the evaluator already
+ * tolerates (an unmatched target simply covers nothing). Cross-tenant, the
+ * thing this exists to stop, is impossible either way.
+ *
+ * A dimension with no registered collection is NOT checked here, and the store
+ * is left to enforce it — see {@link DiscountsApiConfig.collections}.
+ */
+export async function assertTargetsOwned(
+  collections: readonly DiscountableCollection[],
+  clientId: string,
+  targets: DiscountTargets,
+  message: string,
+): Promise<void> {
+  const byType = targetIdsByType(targets);
+  const checks = collections.map(async (collection) => {
+    const ids = byType[collection.targetType];
+    if (ids.length === 0) return true;
+    return collection.ops.ownsAll(clientId, ids);
+  });
+  const results = await Promise.all(checks);
+  if (results.some((owned) => !owned)) throw new ForeignTargetError(message);
+}
+
+/** Every registered collection's rows, as the target picker reads them. */
+export async function loadTargetGroups(
+  collections: readonly DiscountableCollection[],
+  clientId: string,
+): Promise<readonly DiscountTargetGroup[]> {
+  return Promise.all(
+    collections.map(async (collection) => ({
+      targetType: collection.targetType,
+      slug: collection.slug,
+      label: collection.label,
+      nests: collection.nests ?? false,
+      targets: await collection.ops.list(clientId),
+    })),
+  );
+}
+
+/**
+ * A row's own id followed by its ancestors, nearest first — the path R3
+ * intersects a scoped discount's targets against, so a discount on a top-level
+ * category automatically covers items filed under its subcategories.
+ *
+ * The `seen` set is a cycle guard, and it is not decoration: this runs on the
+ * money path, so a pre-existing bad row must cost a truncated path and never an
+ * infinite loop inside a checkout.
+ *
+ * Pure, and exported, because the host builds the cart lines this package then
+ * prices — it needs the same walk on its side of the seam, and a second
+ * implementation of it is how the two would disagree about what a discount
+ * covers.
+ */
+export function buildTargetPath(
+  targetId: string | null,
+  parentById: ReadonlyMap<string, string | null>,
+): string[] {
+  const path: string[] = [];
+  const seen = new Set<string>();
+  let cursor = targetId;
+  while (cursor !== null && !seen.has(cursor)) {
+    seen.add(cursor);
+    path.push(cursor);
+    cursor = parentById.get(cursor) ?? null;
+  }
+  return path;
+}
+
+/**
+ * The ancestry walk for one nesting collection, loaded ONCE per evaluation.
+ *
+ * Returned as a resolver rather than as a map so the caller cannot be tempted
+ * to walk the edges by hand and lose the cycle guard. A collection that does
+ * not nest — or one whose host declared no `parents` — resolves every id to
+ * itself, which is exactly what a flat dimension means.
+ */
+export async function targetPathResolver(
+  collection: DiscountableCollection,
+  clientId: string,
+): Promise<(targetId: string | null) => string[]> {
+  if (!collection.nests || !collection.ops.parents) {
+    return (targetId) => (targetId === null ? [] : [targetId]);
+  }
+  const parents = await collection.ops.parents(clientId);
+  return (targetId) => buildTargetPath(targetId, parents);
+}
+
+/**
+ * Assert a registration set is usable, at construction rather than at the
+ * first request that trips over it.
+ *
+ * Two rules, both of which produce a surface that looks live and quietly does
+ * the wrong thing: two collections for one dimension means one of them silently
+ * never runs, and a nesting collection with no `parents` op means every target
+ * resolves to itself — a discount on a top-level category covering nothing
+ * filed beneath it, which reads as a pricing bug and not as a wiring one.
+ */
+export function assertCollections(collections: readonly DiscountableCollection[]): void {
+  const seen = new Set<string>();
+  for (const collection of collections) {
+    if (!DISCOUNT_TARGET_TYPES.some((type) => type === collection.targetType)) {
+      throw new Error(
+        `@12-apps/discounts: "${collection.targetType}" is not a discountable dimension — ` +
+          `expected one of ${DISCOUNT_TARGET_TYPES.join(", ")}.`,
+      );
+    }
+    if (seen.has(collection.targetType)) {
+      throw new Error(
+        `@12-apps/discounts: two collections registered for ${collection.targetType} — ` +
+          "one of them would never be read.",
+      );
+    }
+    seen.add(collection.targetType);
+    if (collection.nests && !collection.ops.parents) {
+      throw new Error(
+        `@12-apps/discounts: the ${collection.targetType} collection nests but declares no ` +
+          "parents op — every target would resolve to itself and a discount on a parent " +
+          "would cover nothing filed under it.",
+      );
+    }
+  }
+}

package/src/server/copy.ts

@@ -56,6 +56,17 @@ export interface DiscountsServerCopy {
   readonly freeUnitsExceedCombo: string;
   /** 422 — a per-cart combo cap of zero or less. */
   readonly invalidMaxComboApplications: string;
+  /**
+   * 422 — a target id that is not this tenant's, or no longer exists.
+   *
+   * Reported against `targets` whichever dimension it came from, and whether
+   * it arrived as a scope target or inside a combo slot: an operator picks
+   * from a list this surface handed them, so the only way to reach this is a
+   * crafted request or a row deleted while the form was open. One sentence
+   * covers both, and it must not name WHICH id — an id the caller did not
+   * already have is a fact about another store's catalog.
+   */
+  readonly foreignTarget: string;
 }
 
 const COPY_KEYS: readonly (keyof DiscountsServerCopy)[] = [
@@ -79,6 +90,7 @@ const COPY_KEYS: readonly (keyof DiscountsServerCopy)[] = [
   "invalidFreeUnits",
   "freeUnitsExceedCombo",
   "invalidMaxComboApplications",
+  "foreignTarget",
 ];
 
 /** Every key present and non-blank — checked at assembly, like the rest. */

package/src/server/index.ts

@@ -17,6 +17,20 @@ export { missingServerCopy, type DiscountsServerCopy } from "./copy";
 
 export { errorText, type DiscountsLogger } from "./logging";
 
+export {
+  assertCollections,
+  assertTargetsOwned,
+  buildTargetPath,
+  ForeignTargetError,
+  loadTargetGroups,
+  targetIdsByType,
+  targetPathResolver,
+  type DiscountableCollection,
+  type DiscountableOps,
+  type DiscountTarget,
+  type DiscountTargetGroup,
+} from "./collections";
+
 export {
   DISCOUNTS_PERMISSIONS,
   DISCOUNTS_READ,
@@ -44,10 +58,19 @@ export {
 
 export { comboRequirementsForScope, toComboColumns, type ComboColumns } from "./validate-combo";
 
+export {
+  fromTargetRows,
+  toTargetRows,
+  type DiscountComboSlotRow,
+  type DiscountTargetRow,
+  type DiscountTargetRows,
+} from "./targets";
+
 export { discountSearchConfig } from "./search";
 
 export {
   comboRequirementSchema,
+  discountTargetGroupSchema,
   createDiscountBody,
   createDiscountListQuery,
   discountCollectionParams,

package/src/server/logging.ts

@@ -1,5 +1,6 @@
 import type { WireRequest, WireResponse } from "@12-apps/wiring";
 
+import { ForeignTargetError } from "./collections";
 import type { DiscountsActor } from "./routes";
 import { DiscountValidationError } from "./validate";
 
@@ -46,6 +47,21 @@ export interface DiscountsLogger {
   error(message: string): void;
 }
 
+/**
+ * The form input a refusal names, or null when the throw was not one.
+ *
+ * Two classes rather than one shared base: a validation failure carries its own
+ * HTTP status and a foreign target is always a 422, and folding them into one
+ * error type to save this function would put a status field on a class that has
+ * exactly one. What they share is the FIELD, which is the only half a log line
+ * wants.
+ */
+function refusedField(error: unknown): string | null {
+  if (error instanceof DiscountValidationError) return error.field;
+  if (error instanceof ForeignTargetError) return error.field;
+  return null;
+}
+
 /** The cause as a log line — never the object. See the module note. */
 export function errorText(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
@@ -68,7 +84,7 @@ function subject(route: string, request: WireRequest<DiscountsActor>): string {
  * Three outcomes, three levels, and the split is about who has to act:
  *
  *  - a REFUSAL the package itself decided (a 4xx it returned, or the 422 a
- *    {@link DiscountValidationError} folds into) is `warn` — the operator
+ *    {@link refusedField} error folds into) is `warn` — the operator
  *    typed something the rules do not allow, which is worth seeing when a
  *    store reports "it will not let me save" and worth nobody's pager;
  *  - anything else THROWN is `error` and is re-thrown unchanged: the store's
@@ -97,8 +113,9 @@ export function observed(
       }
       return response;
     } catch (error) {
-      if (error instanceof DiscountValidationError) {
-        logger.warn(`${subject(route, request)} refused with 422 on field "${error.field}"`);
+      const field = refusedField(error);
+      if (field !== null) {
+        logger.warn(`${subject(route, request)} refused with 422 on field "${field}"`);
         throw error;
       }
       logger.error(`${subject(route, request)} failed: ${errorText(error)}`);

package/src/server/mcp.ts

@@ -10,6 +10,7 @@ import type { WireMcpTool } from "@12-apps/wiring";
 
 import {
   DISCOUNT_SCOPES,
+  DISCOUNT_TARGET_TYPES,
   DISCOUNT_TRIGGERS,
   DISCOUNT_TYPES,
   MAX_COMBO_SLOTS,
@@ -164,6 +165,27 @@ export const createDiscountBody = z.object(discountWriteShape);
 /** Body for updating a discount (every field re-stated). */
 export const updateDiscountBody = z.object(discountWriteShape);
 
+/**
+ * One collection of things a discount may be pointed at, and its rows.
+ *
+ * `targets` is the WHOLE collection rather than a page, deliberately: a picker
+ * that paginated would let an operator save a discount whose existing targets
+ * were never on screen. See `DiscountableOps.list`.
+ */
+export const discountTargetGroupSchema = z.object({
+  targetType: z.enum(DISCOUNT_TARGET_TYPES),
+  slug: z.string(),
+  label: z.string(),
+  nests: z.boolean(),
+  targets: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      parentId: z.string().nullable().optional(),
+    }),
+  ),
+});
+
 /** `{ data: { id } }` acknowledgement for update/delete. */
 const discountIdResponse = z.object({ data: z.object({ id: z.string() }) });
 
@@ -186,6 +208,17 @@ export const DISCOUNTS_MCP_TOOLS: readonly WireMcpTool<z.ZodType>[] = [
     response: createSearchOutput(discountSchema),
     annotations: { readOnly: true },
   },
+  {
+    operationId: "listDiscountTargets",
+    method: "GET",
+    path: "/discounts/targets",
+    summary:
+      "List what a discount can be pointed at in this store: every registered collection (categories, products) with its rows. Read this before creating or updating a CATEGORY- or ITEM-scoped discount, or a combo slot — an id from anywhere else is refused as not belonging to the store.",
+    tags: ["discounts"],
+    params: discountCollectionParams,
+    response: z.object({ data: z.array(discountTargetGroupSchema) }),
+    annotations: { readOnly: true },
+  },
   {
     operationId: "getDiscount",
     method: "GET",

package/src/server/pt-BR.ts

@@ -32,4 +32,5 @@ export const PT_BR_DISCOUNTS_SERVER_COPY: DiscountsServerCopy = {
   freeUnitsExceedCombo: "O combo precisa cobrar por pelo menos um item.",
   invalidMaxComboApplications:
     "O limite de combos por carrinho deve ser maior que zero (ou deixe em branco).",
+  foreignTarget: "Selecione categorias e produtos desta loja.",
 };