@12-apps/discounts 1.1.0 → 1.3.0

package/src/server/logging.ts

@@ -0,0 +1,135 @@
+import type { WireRequest, WireResponse } from "@12-apps/wiring";
+
+import { ForeignTargetError } from "./collections";
+import type { DiscountsActor } from "./routes";
+import { DiscountValidationError } from "./validate";
+
+/**
+ * What this surface says out loud, and to whom (FUT-244).
+ *
+ * The manifest declares `observability: { namespace: "discounts" }`, which is a
+ * PROMISE: a discounts failure files under `discounts` rather than under the
+ * host app or nowhere. Declaring it bought nothing on its own — the binder
+ * built the namespaced logger, hung it on `assembled.loggers`, and the package
+ * never took it, so for the whole of 1.0.x a refused write and a store that
+ * threw were equally silent. This module is the other half.
+ *
+ * ## Why every line is a STRING, and never an object
+ *
+ * A host's `LoggerPort` is a Winston child in practice, whose formatter runs
+ * `util.inspect(…, { depth: 5 })` over any extra argument. That is not a
+ * theoretical leak in this org: a provider error retains the provider's parsed
+ * response body, buyer name, e-mail and CPF included, so passing the cause as a
+ * second argument is precisely how a buyer's details reach a third party.
+ * {@link errorText} folds the cause into the sentence instead, which is the
+ * same call the origin host's own `errorText` makes and for the same reason.
+ *
+ * ## Why the sentences here are NOT copy config
+ *
+ * Everything below is written for a DEVELOPER reading a log, so it is English
+ * and it is the package's own — the copy-portability rule governs what a USER
+ * reads. Nothing logged here is shown to anyone; the operator's sentence comes
+ * from {@link DiscountsServerCopy} and travels in the response body.
+ */
+
+/**
+ * The three methods a host's logger must offer — the structural twin of
+ * `@12-apps/wiring`'s `LoggerPort` and of `createFeatureLogger`'s return.
+ *
+ * Declared here rather than imported so that the wiring contract stays a
+ * type-only devDependency: a host on no wiring at all still satisfies this by
+ * passing any Winston/pino child, and a host on wiring passes
+ * `assembled.loggers["@12-apps/discounts"]` unchanged.
+ */
+export interface DiscountsLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  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);
+}
+
+/**
+ * What a line may name: the tenant, the route, the discount, the field, the
+ * status. Never a body, never a coupon code, never a name an operator typed —
+ * a log line is read by whoever can read the log, and none of those are needed
+ * to find the failure.
+ */
+function subject(route: string, request: WireRequest<DiscountsActor>): string {
+  const id = request.params.id;
+  return `${route}${id === undefined ? "" : ` [${id}]`} for tenant ${request.actor.clientId}`;
+}
+
+/**
+ * Wrap one descriptor's handler so that nothing it does is silent.
+ *
+ * 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 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
+ *    own failures (a unique clash, a dead connection, a foreign target) belong
+ *    to the host's error mapping, and swallowing one here to make a tidy
+ *    response is how a broken database becomes a 404 nobody investigates;
+ *  - a write that SUCCEEDED is `info`, because a discount is a direct lever on
+ *    what a buyer is charged and "who repriced the menu at 03:12" is a
+ *    question that gets asked.
+ *
+ * The catch is what makes the promise total. Before this, only the two write
+ * routes had any catch at all ({@link DiscountValidationError} → 422) and the
+ * three read routes had none, so a store that threw inside `list` produced a
+ * stack in the host's catch-all with nothing naming discounts.
+ */
+export function observed(
+  logger: DiscountsLogger,
+  route: string,
+  handle: (request: WireRequest<DiscountsActor>) => Promise<WireResponse>,
+): (request: WireRequest<DiscountsActor>) => Promise<WireResponse> {
+  return async (request) => {
+    try {
+      const response = await handle(request);
+      if (response.status >= 400) {
+        logger.warn(`${subject(route, request)} refused with ${response.status}`);
+      }
+      return response;
+    } catch (error) {
+      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)}`);
+      throw error;
+    }
+  };
+}
+
+/** The one line a successful write leaves — see {@link observed}'s third case. */
+export function logWrite(
+  logger: DiscountsLogger,
+  verb: string,
+  request: WireRequest<DiscountsActor>,
+  id: string,
+): void {
+  logger.info(`${verb} discount ${id} for tenant ${request.actor.clientId}`);
+}

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.",
 };

package/src/server/routes.ts

@@ -2,7 +2,15 @@ import type { z } from "zod";
 
 import type { WireRequest, WireResponse, WireRoute } from "@12-apps/wiring";
 
+import {
+  assertCollections,
+  assertTargetsOwned,
+  ForeignTargetError,
+  loadTargetGroups,
+  type DiscountableCollection,
+} from "./collections";
 import { missingServerCopy, type DiscountsServerCopy } from "./copy";
+import { logWrite, observed, type DiscountsLogger } from "./logging";
 import { listDiscountsQuery } from "./mcp";
 import { DISCOUNTS_READ, DISCOUNTS_WRITE } from "./contribution";
 import type { DiscountListInput, DiscountRecord, DiscountStore } from "./store";
@@ -45,6 +53,28 @@ export interface DiscountsApiConfig {
   store: DiscountStore;
   /** Every sentence this surface answers a human with. Required, no defaults. */
   copy: DiscountsServerCopy;
+  /**
+   * Where this surface says what it did. Required, and for the same reason
+   * `copy` is: a default would be a no-op, and a no-op default is exactly the
+   * silence this config exists to end — the manifest declares an
+   * `observability` namespace, so a host adopting through
+   * `@12-apps/wiring/consumer` already HAS the logger and passes
+   * `assembled.loggers["@12-apps/discounts"]`; a host on no wiring passes any
+   * `createFeatureLogger`-shaped child. See `./logging`.
+   */
+  logger: DiscountsLogger;
+  /**
+   * The host tables a discount may be pointed at — see `./collections`.
+   *
+   * OPTIONAL, and the omission is a real configuration rather than an
+   * oversight: a host that sells one undifferentiated thing has no catalog
+   * dimension to register, and ORDER-scoped promotions need none. What it
+   * costs is stated plainly rather than defaulted around — with no collection
+   * registered for a dimension, `GET /discounts/targets` reports nothing for
+   * it and the cross-tenant check on ITS ids does not run here, so the store
+   * remains responsible for refusing a foreign target.
+   */
+  collections?: readonly DiscountableCollection[];
   /**
    * The schema the list query is validated against. Optional ONLY because a
    * mechanical default is portable: the package's own, built from the search
@@ -61,9 +91,10 @@ function ok(body: unknown): WireResponse {
 }
 
 /** The `{ error, issues }` shape a form reads its per-input errors out of. */
-function fieldError(error: DiscountValidationError): WireResponse {
+function fieldError(error: DiscountValidationError | ForeignTargetError): WireResponse {
+  const status = error instanceof DiscountValidationError ? error.status : 422;
   return {
-    status: error.status,
+    status,
     body: { error: error.message, issues: { [error.field]: error.message } },
   };
 }
@@ -74,29 +105,53 @@ function acknowledged(id: string): WireResponse {
 }
 
 /**
- * Fold a validated body into what the store persists.
+ * Fold a validated body into what the store persists, and refuse a target that
+ * is not this tenant's.
  *
  * Both writes go through it, so the rules run exactly once per write and a
- * second caller cannot half-apply them.
+ * second caller cannot half-apply them. The ownership check is here rather than
+ * in each route for the same reason, and it runs AFTER the fold because the
+ * fold is what narrows the targets to the scope — checking the raw body would
+ * reject ids a COMBO-scoped write was about to drop anyway.
  */
-function writeFrom(body: unknown, copy: DiscountsServerCopy) {
+async function prepareWrite(config: DiscountsApiConfig, clientId: string, body: unknown) {
   const input = toDiscountWriteInput(body as DiscountWriteBody);
-  return { scalars: toDiscountScalars(input, copy), targets: targetsForScope(input) };
+  const write = { scalars: toDiscountScalars(input, config.copy), targets: targetsForScope(input) };
+  if (config.collections) {
+    await assertTargetsOwned(config.collections, clientId, write.targets, config.copy.foreignTarget);
+  }
+  return write;
 }
 
 /**
- * Run a write, turning this package's own validation failure into the 422 the
+ * One descriptor's handler, observed and then folded.
+ *
+ * `observed` logs every outcome and changes none of them (see `./logging`);
+ * this fold turns THIS package's own validation failure into the 422 the
  * operator can act on. Everything else — a uniqueness clash, a foreign target,
  * a stale id — is the STORE's to raise, in the host's own error vocabulary,
  * and travels untouched to the host's error mapping.
+ *
+ * Every route goes through it, reads included. A read cannot raise a
+ * `DiscountValidationError`, but it can absolutely throw — and before this the
+ * three read routes had no catch at all, so a store that failed inside `list`
+ * reached the host's catch-all with nothing in the log naming discounts.
  */
-async function attempt(run: () => Promise<WireResponse>): Promise<WireResponse> {
-  try {
-    return await run();
-  } catch (error) {
-    if (error instanceof DiscountValidationError) return fieldError(error);
-    throw error;
-  }
+function endpoint(
+  config: DiscountsApiConfig,
+  route: string,
+  handle: (request: WireRequest<DiscountsActor>) => Promise<WireResponse>,
+): (request: WireRequest<DiscountsActor>) => Promise<WireResponse> {
+  const observedHandle = observed(config.logger, route, handle);
+  return async (request) => {
+    try {
+      return await observedHandle(request);
+    } catch (error) {
+      const refusal = error instanceof DiscountValidationError || error instanceof ForeignTargetError;
+      if (refusal) return fieldError(error);
+      throw error;
+    }
+  };
 }
 
 function listRoute(config: DiscountsApiConfig): DiscountRoute {
@@ -105,7 +160,7 @@ function listRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "GET",
     path: "/discounts",
     permission: DISCOUNTS_READ,
-    handle: async ({ actor, query }: WireRequest<DiscountsActor>) => {
+    handle: endpoint(config, "GET /discounts", async ({ actor, query }) => {
       const parsed = schema.safeParse(query);
       if (!parsed.success) {
         return { status: 400, body: { error: config.copy.invalidQuery } };
@@ -114,7 +169,36 @@ function listRoute(config: DiscountsApiConfig): DiscountRoute {
       // pagination }` envelope the advertised response describes, and wrapping
       // it again would nest it under a second `data`.
       return ok(await config.store.list(actor.clientId, parsed.data));
-    },
+    }),
+  };
+}
+
+/**
+ * What an operator may point a discount at: every registered collection's rows,
+ * in one round trip.
+ *
+ * It exists so the FORM stops assembling its own reference data. The origin
+ * host's page side-loaded the tenant's whole category list and whole product
+ * list from two unrelated admin endpoints, at a page size it had to know
+ * (`?pageSize=500`), and gated its own render on both — three coupled decisions
+ * in a screen that only wanted "what can I tick".
+ *
+ * The route exists even with NO collection registered, answering an empty list.
+ * A route table that varied with config would make the advertised tool surface
+ * vary with it too, and "which endpoints does this package have" must be
+ * answerable without knowing how one host wired it.
+ *
+ * `discounts:write` rather than `discounts:read`: the grid needs none of this,
+ * only the editor does, and the narrower gate is the one that says so.
+ */
+function targetsRoute(config: DiscountsApiConfig): DiscountRoute {
+  return {
+    method: "GET",
+    path: "/discounts/targets",
+    permission: DISCOUNTS_WRITE,
+    handle: endpoint(config, "GET /discounts/targets", async ({ actor }) =>
+      ok({ data: await loadTargetGroups(config.collections ?? [], actor.clientId) }),
+    ),
   };
 }
 
@@ -123,11 +207,11 @@ function readRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "GET",
     path: "/discounts/:id",
     permission: DISCOUNTS_READ,
-    handle: async ({ actor, params }: WireRequest<DiscountsActor>) => {
+    handle: endpoint(config, "GET /discounts/:id", async ({ actor, params }) => {
       const record = await config.store.get(actor.clientId, String(params.id));
       if (record === null) return { status: 404, body: { error: config.copy.notFound } };
       return ok({ data: record as DiscountRecord });
-    },
+    }),
   };
 }
 
@@ -136,10 +220,13 @@ function createRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "POST",
     path: "/discounts",
     permission: DISCOUNTS_WRITE,
-    handle: ({ actor, body }: WireRequest<DiscountsActor>) =>
-      attempt(async () =>
-        ok({ data: await config.store.create(actor.clientId, writeFrom(body, config.copy)) }),
-      ),
+    handle: endpoint(config, "POST /discounts", async (request) => {
+      const { actor, body } = request;
+      const write = await prepareWrite(config, actor.clientId, body);
+      const created = await config.store.create(actor.clientId, write);
+      logWrite(config.logger, "created", request, created.id);
+      return ok({ data: created });
+    }),
   };
 }
 
@@ -148,12 +235,14 @@ function updateRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "PATCH",
     path: "/discounts/:id",
     permission: DISCOUNTS_WRITE,
-    handle: ({ actor, params, body }: WireRequest<DiscountsActor>) =>
-      attempt(async () => {
-        const id = String(params.id);
-        await config.store.update(actor.clientId, id, writeFrom(body, config.copy));
-        return acknowledged(id);
-      }),
+    handle: endpoint(config, "PATCH /discounts/:id", async (request) => {
+      const { actor, params, body } = request;
+      const id = String(params.id);
+      const write = await prepareWrite(config, actor.clientId, body);
+      await config.store.update(actor.clientId, id, write);
+      logWrite(config.logger, "re-stated", request, id);
+      return acknowledged(id);
+    }),
   };
 }
 
@@ -162,21 +251,39 @@ function archiveRoute(config: DiscountsApiConfig): DiscountRoute {
     method: "DELETE",
     path: "/discounts/:id",
     permission: DISCOUNTS_WRITE,
-    handle: async ({ actor, params }: WireRequest<DiscountsActor>) => {
+    handle: endpoint(config, "DELETE /discounts/:id", async (request) => {
+      const { actor, params } = request;
       const id = String(params.id);
       await config.store.archive(actor.clientId, id);
+      logWrite(config.logger, "archived", request, id);
       return acknowledged(id);
-    },
+    }),
   };
 }
 
+/** The three methods `observed` calls — asserted before any request arrives. */
+function assertLogger(logger: DiscountsLogger | undefined): void {
+  const complete =
+    typeof logger?.info === "function" &&
+    typeof logger.warn === "function" &&
+    typeof logger.error === "function";
+  if (complete) return;
+  throw new Error(
+    "@12-apps/discounts: createApiDiscounts needs a logger with info/warn/error — " +
+      "the manifest declares an observability namespace, so a wiring host passes " +
+      'assembled.loggers["@12-apps/discounts"]; there is no silent default.',
+  );
+}
+
 /**
  * The five descriptors, config asserted at construction.
  *
- * Copy is checked HERE rather than at first request, because a missing
- * sentence is a wiring mistake and it should fail where the wiring is written
- * — the report-builder doctrine: required fields, no defaults, asserted at
- * assembly.
+ * Copy and the logger are checked HERE rather than at first request, because a
+ * missing sentence or a missing logger is a wiring mistake and it should fail
+ * where the wiring is written — the report-builder doctrine: required fields,
+ * no defaults, asserted at assembly. The logger earned that treatment the hard
+ * way: for the whole of 1.0.x the manifest promised these routes logged, the
+ * host built the namespaced logger, and nothing connected the two.
  */
 export function createApiDiscounts(config: DiscountsApiConfig): {
   routes: readonly DiscountRoute[];
@@ -188,9 +295,15 @@ export function createApiDiscounts(config: DiscountsApiConfig): {
         "every sentence this surface answers a human with is host config, with no defaults.",
     );
   }
+  assertLogger(config.logger);
+  assertCollections(config.collections ?? []);
   return {
     routes: [
       listRoute(config),
+      // BEFORE the `:id` read, because `/discounts/targets` would otherwise be
+      // matched by it in any router that resolves in declaration order — and
+      // the answer would be a 404 for a discount named "targets".
+      targetsRoute(config),
       readRoute(config),
       createRoute(config),
       updateRoute(config),

package/src/server/targets.ts

@@ -0,0 +1,102 @@
+import type { DiscountTargetType } from "../engine/kinds";
+import type { ComboRequirement } from "../engine/types";
+import type { DiscountTargets } from "./validate";
+
+/**
+ * The fold between what this package SPEAKS and what the schema STORES.
+ *
+ * The wire, the validator and the evaluator all speak id ARRAYS — `categoryIds`,
+ * `menuItemIds`, and a `ComboRequirement` carrying one of each. The partial
+ * stores by-value ROWS: `(target_type, target_id)`, with a nullable `slot_id`
+ * telling a scope target from a combo slot's.
+ *
+ * Both shapes are right for their side. Arrays are what a form binds to and
+ * what a matcher iterates; rows are what makes the schema shippable and the
+ * reverse read ("which rules touch this row") an index. What is NOT right is
+ * each host writing the translation by hand, because it is exactly the kind of
+ * mechanical mapping where a dropped `slotId` produces a combo whose slots have
+ * silently merged — a discount that still saves, still lists, and prices the
+ * wrong thing.
+ *
+ * So it lives here, in one place, tested in both directions. The host's store
+ * stays persistence: it hands these rows to Prisma and hands Prisma's rows back.
+ */
+
+/** One row of `discount_targets`, minus the ids the database assigns. */
+export interface DiscountTargetRow {
+  targetType: DiscountTargetType;
+  targetId: string;
+}
+
+/** One row of `discount_combo_slots`, with the targets that belong to it. */
+export interface DiscountComboSlotRow {
+  /** The operator's order — also the order a card describes the combo in. */
+  position: number;
+  quantity: number;
+  targets: readonly DiscountTargetRow[];
+}
+
+/** Everything a write persists BESIDE the discount's own columns. */
+export interface DiscountTargetRows {
+  /** What a CATEGORY- or ITEM-scoped rule covers (`slot_id IS NULL`). */
+  scopeTargets: readonly DiscountTargetRow[];
+  /** The combo's slots, each with its own targets. Empty unless COMBO-scoped. */
+  comboSlots: readonly DiscountComboSlotRow[];
+}
+
+function rowsFor(
+  categoryIds: readonly string[],
+  menuItemIds: readonly string[],
+): DiscountTargetRow[] {
+  return [
+    ...categoryIds.map((targetId) => ({ targetType: "CATEGORY" as const, targetId })),
+    ...menuItemIds.map((targetId) => ({ targetType: "ITEM" as const, targetId })),
+  ];
+}
+
+/**
+ * Fold a validated write's targets into the rows the schema stores.
+ *
+ * The slots keep their INDEX as `position` rather than being handed an
+ * arbitrary order: the list an operator built is the list a card reads out, and
+ * two slots of the same size are otherwise indistinguishable once stored.
+ */
+export function toTargetRows(targets: DiscountTargets): DiscountTargetRows {
+  return {
+    scopeTargets: rowsFor(targets.categoryIds, targets.menuItemIds),
+    comboSlots: targets.comboRequirements.map((requirement, index) => ({
+      position: index,
+      quantity: requirement.quantity,
+      targets: rowsFor(requirement.categoryIds, requirement.menuItemIds),
+    })),
+  };
+}
+
+function idsOf(rows: readonly DiscountTargetRow[], type: DiscountTargetType): string[] {
+  return rows.filter((row) => row.targetType === type).map((row) => row.targetId);
+}
+
+/**
+ * Fold stored rows back into the id arrays a record and a rule are built from.
+ *
+ * The slots are sorted by `position` HERE rather than left to the caller's
+ * `orderBy`: the order is part of what the combo means, and a store that
+ * forgot the clause would produce a subtly different offer on every read
+ * depending on how the database felt like returning the rows.
+ */
+export function fromTargetRows(rows: DiscountTargetRows): {
+  categoryIds: string[];
+  menuItemIds: string[];
+  comboRequirements: ComboRequirement[];
+} {
+  const slots = [...rows.comboSlots].sort((left, right) => left.position - right.position);
+  return {
+    categoryIds: idsOf(rows.scopeTargets, "CATEGORY"),
+    menuItemIds: idsOf(rows.scopeTargets, "ITEM"),
+    comboRequirements: slots.map((slot) => ({
+      menuItemIds: idsOf(slot.targets, "ITEM"),
+      categoryIds: idsOf(slot.targets, "CATEGORY"),
+      quantity: slot.quantity,
+    })),
+  };
+}