@12-apps/discounts 1.1.0 → 1.2.0

package/README.md

@@ -131,7 +131,7 @@ bundle, if a host wants one, stays the host's.
 
 ## The admin surface
 
-`createApiDiscounts({ store, copy })` returns five `WireRoute` descriptors —
+`createApiDiscounts({ store, copy, logger })` returns five `WireRoute` descriptors —
 list, read, create, re-state, archive — each **declaring the permission it
 needs** (`discounts:read` / `discounts:write`), so a host's coverage gates can
 read the policy off the assembled table instead of scanning route files.
@@ -140,7 +140,11 @@ read the policy off the assembled table instead of scanning route files.
 import { createApiDiscounts } from "@12-apps/discounts/server";
 import { PT_BR_DISCOUNTS_SERVER_COPY } from "@12-apps/discounts/server/pt-BR";
 
-const { routes } = createApiDiscounts({ store, copy: PT_BR_DISCOUNTS_SERVER_COPY });
+const { routes } = createApiDiscounts({
+  store,
+  copy: PT_BR_DISCOUNTS_SERVER_COPY,
+  logger: createFeatureLogger("discounts"),
+});
 ```
 
 Or, through the contract:
@@ -152,7 +156,9 @@ import { discountsServerManifest } from "@12-apps/discounts/manifest/server";
 host.adoptServer({
   manifest: discountsManifest,
   server: discountsServerManifest,
-  bindings: { http: { mountPath: "/api/admin/:tenantSlug", config: { store, copy } } },
+  bindings: {
+    http: { mountPath: "/api/admin/:tenantSlug", config: { store, copy, logger } },
+  },
 });
 ```
 
@@ -160,6 +166,41 @@ Delete is a **soft archive**, and that is a product decision: the orders that
 already redeemed a discount keep their snapshot, and its redemption counter
 stays readable for reporting.
 
+### Nothing it does is silent
+
+`logger` is **required config, with no default**, for the reason `copy` is: the
+default would be a no-op, and a no-op is the exact silence it exists to end.
+Every route is wrapped, and there are three outcomes:
+
+| outcome | level | what the line names |
+|---|---|---|
+| a write that succeeded | `info` | the verb, the discount id, the tenant |
+| a refusal this package decided (400 / 404 / 422) | `warn` | the route, the status, and for a 422 the **field** a form paints red |
+| anything thrown — and it is re-thrown unchanged | `error` | the route, the tenant, the cause's message |
+
+Every line is a **string**. A host's logger is a Winston child in practice,
+whose formatter runs `util.inspect(…, { depth: 5 })` over an extra argument —
+which is how a provider error's retained response body, buyer name and CPF
+included, reaches a third party. The cause is folded into the sentence instead.
+A line names the tenant, the route, the discount id and the field; never the
+body, never a coupon code, never a name an operator typed.
+
+The `error` case **re-throws**. A uniqueness clash, a foreign target and a dead
+connection are the store's to raise in the host's own error vocabulary; a
+surface that folded one into a tidy response would turn a broken database into a
+refusal nobody investigates.
+
+A host adopting through `@12-apps/wiring/consumer` already has the logger the
+binder built from this package's declared namespace — pass
+`assembled.loggers["@12-apps/discounts"]`. A host on no wiring passes any
+`createFeatureLogger`-shaped child of its own.
+
+The evaluator is deliberately **not** wired to it. `evaluateCart` is a pure
+function called once per cart render; a logger there would file a line per
+keystroke on the storefront and would need a logger threaded through a browser
+bundle. A rejected coupon is already a `DiscountRejection` in the result, which
+is the host's to report if it wants to.
+
 ## What the host still owns
 
 **The database.** A discount's rows relate to a host's own catalog and orders —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/discounts",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "The discount/promotion domain: a host-agnostic evaluator (percentage or fixed amount, order/category/item scope, automatic or coupon-triggered, stacking and exclusivity, integer-cent allocation) plus the admin CRUD surface as wiring-contract route descriptors over a store port. No database, no framework, no baked user copy.",
   "exports": {
@@ -35,7 +35,7 @@
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
     "@12-apps/typescript-config": "^1.20.1",
-    "@12-apps/wiring": "^1.7.0",
+    "@12-apps/wiring": "^1.10.0",
     "@types/node": "^22.10.6",
     "eslint": "^9.39.1",
     "eslint-plugin-test-flakiness": "^1.4.0",

package/src/manifest/index.ts

@@ -46,6 +46,13 @@ export const discountsManifest = {
    * The server half logs through the binder's namespaced logger, so a
    * discounts failure files under `discounts` rather than under the host app
    * or nowhere.
+   *
+   * `createApiDiscounts` REFUSES to build without one, which is what makes
+   * that sentence a fact rather than an aspiration: for the whole of 1.0.x it
+   * was neither — the binder built the logger, hung it on
+   * `assembled.loggers["@12-apps/discounts"]`, and the package took nothing
+   * and logged nothing. A declared capability nobody consumes is worse than an
+   * undeclared one, because it reads as finished.
    */
   observability: { namespace: "discounts" },
   server: ["http"],

package/src/server/index.ts

@@ -15,6 +15,8 @@ export {
 
 export { missingServerCopy, type DiscountsServerCopy } from "./copy";
 
+export { errorText, type DiscountsLogger } from "./logging";
+
 export {
   DISCOUNTS_PERMISSIONS,
   DISCOUNTS_READ,

package/src/server/logging.ts

@@ -0,0 +1,118 @@
+import type { WireRequest, WireResponse } from "@12-apps/wiring";
+
+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 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 DiscountValidationError} 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) {
+      if (error instanceof DiscountValidationError) {
+        logger.warn(`${subject(route, request)} refused with 422 on field "${error.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/routes.ts

@@ -3,6 +3,7 @@ import type { z } from "zod";
 import type { WireRequest, WireResponse, WireRoute } from "@12-apps/wiring";
 
 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 +46,16 @@ 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 schema the list query is validated against. Optional ONLY because a
    * mechanical default is portable: the package's own, built from the search
@@ -85,18 +96,33 @@ function writeFrom(body: unknown, copy: DiscountsServerCopy) {
 }
 
 /**
- * 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) {
+      if (error instanceof DiscountValidationError) return fieldError(error);
+      throw error;
+    }
+  };
 }
 
 function listRoute(config: DiscountsApiConfig): DiscountRoute {
@@ -105,7 +131,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 +140,7 @@ 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));
-    },
+    }),
   };
 }
 
@@ -123,11 +149,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 +162,12 @@ 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 created = await config.store.create(actor.clientId, writeFrom(body, config.copy));
+      logWrite(config.logger, "created", request, created.id);
+      return ok({ data: created });
+    }),
   };
 }
 
@@ -148,12 +176,13 @@ 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);
+      await config.store.update(actor.clientId, id, writeFrom(body, config.copy));
+      logWrite(config.logger, "re-stated", request, id);
+      return acknowledged(id);
+    }),
   };
 }
 
@@ -162,21 +191,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,6 +235,7 @@ export function createApiDiscounts(config: DiscountsApiConfig): {
         "every sentence this surface answers a human with is host config, with no defaults.",
     );
   }
+  assertLogger(config.logger);
   return {
     routes: [
       listRoute(config),