@12-apps/discounts 1.0.0

package/src/server/index.ts

@@ -0,0 +1,54 @@
+/**
+ * `@12-apps/discounts/server` — the admin CRUD surface.
+ *
+ * Behind its own subpath so a browser bundle that only prices a cart (the
+ * package root) never resolves zod or the search engine. The wiring manifest
+ * for these capabilities is `@12-apps/discounts/manifest/server`.
+ */
+
+export {
+  createApiDiscounts,
+  type DiscountRoute,
+  type DiscountsActor,
+  type DiscountsApiConfig,
+} from "./routes";
+
+export { missingServerCopy, type DiscountsServerCopy } from "./copy";
+
+export {
+  DISCOUNTS_PERMISSIONS,
+  DISCOUNTS_READ,
+  DISCOUNTS_WRITE,
+} from "./contribution";
+
+export type {
+  DiscountListInput,
+  DiscountPage,
+  DiscountRecord,
+  DiscountStore,
+  DiscountWrite,
+} from "./store";
+
+export {
+  DiscountValidationError,
+  targetsForScope,
+  toDiscountScalars,
+  toDiscountWriteInput,
+  type DiscountScalars,
+  type DiscountTargets,
+  type DiscountWriteBody,
+  type DiscountWriteInput,
+} from "./validate";
+
+export { discountSearchConfig } from "./search";
+
+export {
+  createDiscountBody,
+  createDiscountListQuery,
+  discountCollectionParams,
+  discountItemParams,
+  discountSchema,
+  DISCOUNTS_MCP_TOOLS,
+  listDiscountsQuery,
+  updateDiscountBody,
+} from "./mcp";

package/src/server/mcp.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+
+import {
+  createSearchInput,
+  createSearchOutput,
+  searchConfigSchema,
+  type SearchConfig,
+} from "@12-apps/shared-helpers/search";
+import type { WireMcpTool } from "@12-apps/wiring";
+
+import { DISCOUNT_SCOPES, DISCOUNT_TRIGGERS, DISCOUNT_TYPES, MAX_PERCENT_OFF_BP } from "../engine/kinds";
+import { discountSearchConfig } from "./search";
+
+/**
+ * The discounts tool surface — authored ONCE, beside the route descriptors it
+ * proxies to, and reused as the runtime validators. The advertised schema and
+ * what the handler accepts are the same objects, so they cannot drift.
+ *
+ * Every enum comes from `../engine/kinds` rather than being spelled out as
+ * literals: those same arrays back a host's CHECK constraints, so a value an
+ * agent can send is by construction a value the database will store.
+ *
+ * Paths are RELATIVE to the http capability's mount — the wiring consumer
+ * prefixes the adoption's `mountPath`, so a tool's URL and its route's URL
+ * cannot disagree.
+ */
+
+/** Path params for the tenant-scoped discounts collection. */
+export const discountCollectionParams = z.object({
+  tenantSlug: z.string().min(1),
+});
+
+/** Path params for a single discount. */
+export const discountItemParams = z.object({
+  tenantSlug: z.string().min(1),
+  id: z.string().min(1),
+});
+
+/**
+ * A calendar date (`YYYY-MM-DD`), read at UTC midnight by the API.
+ *
+ * No custom message: a sentence here would be a default in one language, and
+ * the schema's own path is what a client renders. The SEMANTIC failure — a
+ * date that is not a date — is reported by `toDiscountScalars` with the host's
+ * `invalidDate` copy and the field to paint.
+ */
+const calendarDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+
+/**
+ * A discount as the API returns it (JSON-serialized: dates become ISO
+ * strings). The two join tables are flattened into id arrays.
+ */
+export const discountSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.enum(DISCOUNT_TYPES),
+  /** Basis points off (1..10000). Non-null iff `type = PERCENTAGE`. */
+  percentOffBp: z.number().int().nullable(),
+  /** Cents off. Non-null iff `type = FIXED_AMOUNT`. */
+  amountOffCents: z.number().int().nullable(),
+  scope: z.enum(DISCOUNT_SCOPES),
+  trigger: z.enum(DISCOUNT_TRIGGERS),
+  code: z.string().nullable(),
+  startsAt: z.string().nullable(),
+  endsAt: z.string().nullable(),
+  minSubtotalCents: z.number().int().nullable(),
+  usageLimit: z.number().int().nullable(),
+  perBuyerLimit: z.number().int().nullable(),
+  usageCount: z.number().int(),
+  stackable: z.boolean(),
+  active: z.boolean(),
+  categoryIds: z.array(z.string()),
+  menuItemIds: z.array(z.string()),
+  createdAt: z.string(),
+});
+
+/**
+ * The list query, from the same config the store's engine reads.
+ *
+ * A host that tunes its page-size ceilings by environment, or that adds a pill
+ * of its own vocabulary, builds its own with this factory and hands the result
+ * to BOTH `createApiDiscounts({ listQuery })` and the adoption's
+ * `mcpOverrides.listDiscounts.query` — one schema, advertised and enforced.
+ */
+export function createDiscountListQuery<E extends Record<string, z.ZodTypeAny>>(
+  config: SearchConfig,
+  extraShape?: E,
+) {
+  return createSearchInput(discountSearchConfig, config, extraShape);
+}
+
+/**
+ * The package's own list query: the search config's DEFAULTS, not the
+ * environment's. This module is imported by an offline tool generator and by
+ * browsers; reading `process.env` at module scope would make the advertised
+ * surface depend on where it was generated.
+ */
+export const listDiscountsQuery = createDiscountListQuery(searchConfigSchema.parse({}));
+
+/**
+ * The write body, shared by create and update: a discount is always saved
+ * WHOLE (the form re-states every field), so there is no partial-patch shape
+ * to diverge from. The cross-field rules — a rate iff PERCENTAGE, a code iff
+ * CODE, a target iff CATEGORY/ITEM, `endsAt` strictly after `startsAt` — are
+ * enforced in `./validate`, where they produce a sentence naming the field
+ * instead of a Zod path.
+ */
+const discountWriteShape = {
+  name: z.string().min(2).max(120),
+  type: z.enum(DISCOUNT_TYPES),
+  percentOffBp: z.number().int().min(1).max(MAX_PERCENT_OFF_BP).nullable().optional(),
+  amountOffCents: z.number().int().positive().nullable().optional(),
+  scope: z.enum(DISCOUNT_SCOPES),
+  trigger: z.enum(DISCOUNT_TRIGGERS),
+  code: z.string().min(1).max(64).nullable().optional(),
+  startsAt: calendarDateSchema.nullable().optional(),
+  endsAt: calendarDateSchema.nullable().optional(),
+  minSubtotalCents: z.number().int().positive().nullable().optional(),
+  usageLimit: z.number().int().positive().nullable().optional(),
+  perBuyerLimit: z.number().int().positive().nullable().optional(),
+  stackable: z.boolean(),
+  active: z.boolean(),
+  categoryIds: z.array(z.string().min(1)).optional(),
+  menuItemIds: z.array(z.string().min(1)).optional(),
+};
+
+/** Body for creating a discount. */
+export const createDiscountBody = z.object(discountWriteShape);
+
+/** Body for updating a discount (every field re-stated). */
+export const updateDiscountBody = z.object(discountWriteShape);
+
+/** `{ data: { id } }` acknowledgement for update/delete. */
+const discountIdResponse = z.object({ data: z.object({ id: z.string() }) });
+
+/**
+ * The tools, one per route descriptor. `annotations` travel WITH the tool —
+ * the package knows perfectly well that `listDiscounts` only reads and that
+ * `deleteDiscount` is the destructive one, and a host's policy table would
+ * otherwise restate all five by hand.
+ */
+export const DISCOUNTS_MCP_TOOLS: readonly WireMcpTool<z.ZodType>[] = [
+  {
+    operationId: "listDiscounts",
+    method: "GET",
+    path: "/discounts",
+    summary:
+      "List a store's discounts and promotions (admin). Backend filter (`q` over name and coupon code, `type_in` PERCENTAGE|FIXED_AMOUNT, `scope_in` ORDER|CATEGORY|ITEM, `trigger_in` AUTOMATIC|CODE, `active`), `sort` (field:asc|desc), and pagination (`page`/`pageSize`). Returns the page plus `pagination` (total, pageCount, hasNextPage).",
+    tags: ["discounts"],
+    params: discountCollectionParams,
+    query: listDiscountsQuery,
+    response: createSearchOutput(discountSchema),
+    annotations: { readOnly: true },
+  },
+  {
+    operationId: "getDiscount",
+    method: "GET",
+    path: "/discounts/{id}",
+    summary: "Read one of a store's discounts by id (admin).",
+    tags: ["discounts"],
+    params: discountItemParams,
+    response: z.object({ data: discountSchema }),
+    annotations: { readOnly: true },
+  },
+  {
+    operationId: "createDiscount",
+    method: "POST",
+    path: "/discounts",
+    summary:
+      "Create a discount for a store (admin). A percentage is basis points (1..10000); a fixed amount is integer cents. A CODE-triggered discount needs a coupon code, unique within the store; a CATEGORY/ITEM-scoped one needs at least one target.",
+    tags: ["discounts"],
+    params: discountCollectionParams,
+    body: createDiscountBody,
+    response: z.object({ data: discountSchema }),
+  },
+  {
+    operationId: "updateDiscount",
+    method: "PATCH",
+    path: "/discounts/{id}",
+    summary: "Update a store's discount (every field is re-stated, targets included).",
+    tags: ["discounts"],
+    params: discountItemParams,
+    body: updateDiscountBody,
+    response: discountIdResponse,
+  },
+  {
+    operationId: "deleteDiscount",
+    method: "DELETE",
+    path: "/discounts/{id}",
+    summary:
+      "Delete a store's discount (admin). Soft-delete: the discount stops applying and leaves the list, while the orders that already redeemed it keep their snapshot and its redemption counter is preserved.",
+    tags: ["discounts"],
+    params: discountItemParams,
+    response: discountIdResponse,
+    annotations: { destructive: true },
+  },
+];

package/src/server/pt-BR.ts

@@ -0,0 +1,26 @@
+import type { DiscountsServerCopy } from "./copy";
+
+/**
+ * The pt-BR pack — a NAMED export a host passes by hand
+ * (`copy: PT_BR_DISCOUNTS_SERVER_COPY`), never a default. The filename is what
+ * exempts this file from the copy-portability gate: Portuguese may ship, it
+ * may not be silent.
+ *
+ * Every sentence names what the operator must change, because these are form
+ * errors: the route reports them with the offending FIELD alongside, so an
+ * admin form can paint that input rather than only flashing a banner.
+ */
+export const PT_BR_DISCOUNTS_SERVER_COPY: DiscountsServerCopy = {
+  invalidQuery: "Parâmetros de consulta inválidos.",
+  notFound: "Desconto não encontrado.",
+  invalidPercent: "Informe uma porcentagem maior que 0 e no máximo 100.",
+  invalidAmount: "Informe um valor de desconto maior que zero.",
+  codeRequired: "Informe o código do cupom que o cliente vai digitar.",
+  categoryTargetRequired: "Selecione ao menos uma categoria para este desconto.",
+  itemTargetRequired: "Selecione ao menos um produto para este desconto.",
+  invalidDate: "Data inválida. Use o formato AAAA-MM-DD.",
+  endsBeforeStarts: "A data de término deve ser posterior à data de início.",
+  invalidMinSubtotal: "O pedido mínimo deve ser maior que zero (ou deixe em branco).",
+  invalidUsageLimit: "O limite de usos deve ser maior que zero (ou deixe em branco).",
+  invalidPerBuyerLimit: "O limite por cliente deve ser maior que zero (ou deixe em branco).",
+};

package/src/server/routes.ts

@@ -0,0 +1,200 @@
+import type { z } from "zod";
+
+import type { WireRequest, WireResponse, WireRoute } from "@12-apps/wiring";
+
+import { missingServerCopy, type DiscountsServerCopy } from "./copy";
+import { listDiscountsQuery } from "./mcp";
+import { DISCOUNTS_READ, DISCOUNTS_WRITE } from "./contribution";
+import type { DiscountListInput, DiscountRecord, DiscountStore } from "./store";
+import {
+  DiscountValidationError,
+  targetsForScope,
+  toDiscountScalars,
+  toDiscountWriteInput,
+  type DiscountWriteBody,
+} from "./validate";
+
+/**
+ * The admin discounts HTTP surface (FUT-244), as framework-neutral wiring
+ * descriptors: tenant-scoped CRUD over the promotions an operator manages.
+ *
+ * What is NOT here is as deliberate as what is. There is no lifecycle or
+ * approval branch (FUT-235 D7) — a pricing rule with a live redemption counter
+ * is not versioned catalog content, so a write applies immediately or fails.
+ * There is no authentication, no tenant resolution and no RBAC: each
+ * descriptor DECLARES the permission it needs and the host's guard answers it,
+ * because which tier a route requires is host policy, and the actor arrives
+ * already resolved.
+ *
+ * Delete is a SOFT archive rather than a row removal, and that is a product
+ * decision rather than an implementation detail: the orders that already
+ * redeemed this discount keep their snapshot, and its redemption counter stays
+ * readable for reporting.
+ */
+
+/** Whoever the host resolved: the tenant this request may act inside. */
+export interface DiscountsActor {
+  /** The tenant's id — every store call is scoped to it. */
+  clientId: string;
+}
+
+export type DiscountRoute = WireRoute<DiscountsActor>;
+
+export interface DiscountsApiConfig {
+  /** Where the rows are — see {@link DiscountStore}. */
+  store: DiscountStore;
+  /** Every sentence this surface answers a human with. Required, no defaults. */
+  copy: DiscountsServerCopy;
+  /**
+   * The schema the list query is validated against. Optional ONLY because a
+   * mechanical default is portable: the package's own, built from the search
+   * config's defaults. A host that tunes page-size ceilings by environment, or
+   * that adds a pill of its own vocabulary, passes the schema it also
+   * advertises through `mcpOverrides.listDiscounts.query` — one object, so the
+   * advertised surface and the enforced one cannot drift.
+   */
+  listQuery?: z.ZodType<DiscountListInput>;
+}
+
+function ok(body: unknown): WireResponse {
+  return { status: 200, body };
+}
+
+/** The `{ error, issues }` shape a form reads its per-input errors out of. */
+function fieldError(error: DiscountValidationError): WireResponse {
+  return {
+    status: error.status,
+    body: { error: error.message, issues: { [error.field]: error.message } },
+  };
+}
+
+/** The id acknowledgement update and delete answer with. */
+function acknowledged(id: string): WireResponse {
+  return ok({ data: { id } });
+}
+
+/**
+ * Fold a validated body into what the store persists.
+ *
+ * Both writes go through it, so the rules run exactly once per write and a
+ * second caller cannot half-apply them.
+ */
+function writeFrom(body: unknown, copy: DiscountsServerCopy) {
+  const input = toDiscountWriteInput(body as DiscountWriteBody);
+  return { scalars: toDiscountScalars(input, copy), targets: targetsForScope(input) };
+}
+
+/**
+ * Run a write, turning 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.
+ */
+async function attempt(run: () => Promise<WireResponse>): Promise<WireResponse> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof DiscountValidationError) return fieldError(error);
+    throw error;
+  }
+}
+
+function listRoute(config: DiscountsApiConfig): DiscountRoute {
+  const schema = config.listQuery ?? (listDiscountsQuery as z.ZodType<DiscountListInput>);
+  return {
+    method: "GET",
+    path: "/discounts",
+    permission: DISCOUNTS_READ,
+    handle: async ({ actor, query }: WireRequest<DiscountsActor>) => {
+      const parsed = schema.safeParse(query);
+      if (!parsed.success) {
+        return { status: 400, body: { error: config.copy.invalidQuery } };
+      }
+      // Returned as-is rather than wrapped: the page IS the `{ data,
+      // 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));
+    },
+  };
+}
+
+function readRoute(config: DiscountsApiConfig): DiscountRoute {
+  return {
+    method: "GET",
+    path: "/discounts/:id",
+    permission: DISCOUNTS_READ,
+    handle: async ({ actor, params }: WireRequest<DiscountsActor>) => {
+      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 });
+    },
+  };
+}
+
+function createRoute(config: DiscountsApiConfig): DiscountRoute {
+  return {
+    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)) }),
+      ),
+  };
+}
+
+function updateRoute(config: DiscountsApiConfig): DiscountRoute {
+  return {
+    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);
+      }),
+  };
+}
+
+function archiveRoute(config: DiscountsApiConfig): DiscountRoute {
+  return {
+    method: "DELETE",
+    path: "/discounts/:id",
+    permission: DISCOUNTS_WRITE,
+    handle: async ({ actor, params }: WireRequest<DiscountsActor>) => {
+      const id = String(params.id);
+      await config.store.archive(actor.clientId, id);
+      return acknowledged(id);
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+export function createApiDiscounts(config: DiscountsApiConfig): {
+  routes: readonly DiscountRoute[];
+} {
+  const missing = missingServerCopy(config.copy);
+  if (missing.length > 0) {
+    throw new Error(
+      `@12-apps/discounts: createApiDiscounts is missing copy for ${missing.join(", ")} — ` +
+        "every sentence this surface answers a human with is host config, with no defaults.",
+    );
+  }
+  return {
+    routes: [
+      listRoute(config),
+      readRoute(config),
+      createRoute(config),
+      updateRoute(config),
+      archiveRoute(config),
+    ],
+  };
+}

package/src/server/search.ts

@@ -0,0 +1,45 @@
+import { defineSearchConfig } from "@12-apps/shared-helpers/search";
+
+import { DISCOUNT_SCOPES, DISCOUNT_TRIGGERS, DISCOUNT_TYPES } from "../engine/kinds";
+
+/**
+ * The admin discounts-list search contract (FUT-244): the backend equivalent of
+ * a promotions grid's search box, pills and sort. Search is case-insensitive
+ * over the discount name AND its coupon code, because an operator hunting for
+ * `BEMVINDO10` types the code, not the promotion's marketing name.
+ *
+ * The three closed sets come from `../engine/kinds` rather than being spelled
+ * out again here: the same arrays back a host's CHECK constraints and the MCP
+ * enums, so a value this config would accept is by construction a value the
+ * database will store.
+ *
+ * The grid's fourth pill — the VIGÊNCIA one (running / scheduled / ended) — is
+ * deliberately ABSENT. It is a comparison between two nullable columns and the
+ * current instant, which `filterableFields` cannot express at all, so it rides
+ * as a separate `window` parameter the store resolves into its own predicate.
+ * The parameter's VALUES are host words, which is why the store owns them: see
+ * `DiscountListInput` in `./store`.
+ */
+export const discountSearchConfig = defineSearchConfig({
+  searchableFields: ["name", "code"],
+  searchMode: "insensitive",
+  filterableFields: {
+    type: { type: "string", operators: ["in"], allowedValues: [...DISCOUNT_TYPES] },
+    scope: { type: "string", operators: ["in"], allowedValues: [...DISCOUNT_SCOPES] },
+    trigger: { type: "string", operators: ["in"], allowedValues: [...DISCOUNT_TRIGGERS] },
+    active: { type: "boolean", operators: ["eq"] },
+  },
+  sortableFields: [
+    "name",
+    "code",
+    "type",
+    "scope",
+    "startsAt",
+    "endsAt",
+    "usageCount",
+    "createdAt",
+  ],
+  // Newest first: a promotions list is a working queue, and the thing an
+  // operator just created is the thing they want to see.
+  defaultSort: { field: "createdAt", direction: "desc" },
+});

package/src/server/store.ts

@@ -0,0 +1,101 @@
+import type { PaginatedResult, ParsedSearchInput } from "@12-apps/shared-helpers/search";
+
+import type { DiscountScope, DiscountTrigger, DiscountType } from "../engine/kinds";
+import type { DiscountScalars, DiscountTargets } from "./validate";
+
+/**
+ * The persistence seam — the ONE thing this package does not do.
+ *
+ * A discount's rows relate to a host's own catalog and orders: targets point
+ * at its categories and items, redemptions at its orders and its buyers. A
+ * shipped Prisma partial would therefore only compile inside a host that
+ * already has those tables under those names, which is why the manifest
+ * declares no `db` capability and this interface exists instead. The host
+ * owns the schema, the tenant scoping, the transactions and the uniqueness
+ * conflicts; the package owns the rules and the wire.
+ *
+ * Everything here is `clientId`-first for the same reason the origin
+ * implementation is: a discount is a direct lever on what a buyer is charged,
+ * so a query that forgot its tenant would not merely leak a row — it would let
+ * one store edit another store's prices.
+ */
+
+/** One discount as the admin API returns it, before JSON serialization. */
+export interface DiscountRecord {
+  id: string;
+  name: string;
+  type: DiscountType | string;
+  percentOffBp: number | null;
+  amountOffCents: number | null;
+  scope: DiscountScope | string;
+  trigger: DiscountTrigger | string;
+  code: string | null;
+  startsAt: Date | null;
+  endsAt: Date | null;
+  minSubtotalCents: number | null;
+  usageLimit: number | null;
+  perBuyerLimit: number | null;
+  usageCount: number;
+  stackable: boolean;
+  active: boolean;
+  /**
+   * The join tables flattened into plain id arrays: a form's target pickers
+   * bind to ids, and a client has no business knowing there are two joins.
+   */
+  categoryIds: string[];
+  menuItemIds: string[];
+  createdAt: Date;
+}
+
+/**
+ * What a write persists: the validated columns and the scope-narrowed targets.
+ *
+ * The store receives them ALREADY folded, never the raw body — every rule
+ * (`toDiscountScalars`) has run, the unused half of each either/or pair is
+ * NULL, and the targets are de-duplicated. So a store implementation is
+ * persistence and nothing else, and the rules cannot be half-applied by a
+ * second caller that forgot one.
+ */
+export interface DiscountWrite {
+  scalars: DiscountScalars;
+  targets: DiscountTargets;
+}
+
+/**
+ * The list query as the store receives it: the shared search engine's parsed
+ * input, widened so a host can carry pills of its OWN vocabulary through.
+ *
+ * The widening is the point. A promotions grid usually wants a validity pill
+ * — running / scheduled / ended — which compares two nullable columns against
+ * "now" and no `filterableField` can express; its VALUES are words a host
+ * chose, in a language this package does not have. So the host extends the
+ * advertised query schema (an `mcpOverrides` entry, the same object it hands
+ * `createApiDiscounts` as `listQuery`), and reads its own key back out here.
+ */
+export type DiscountListInput = ParsedSearchInput & Readonly<Record<string, unknown>>;
+
+/** One backend-paginated page of the admin discounts grid. */
+export type DiscountPage = PaginatedResult<DiscountRecord>;
+
+export interface DiscountStore {
+  /** One page of this tenant's LIVE discounts, filtered/sorted/paginated. */
+  list(clientId: string, input: DiscountListInput): Promise<DiscountPage>;
+  /** One LIVE discount owned by `clientId`, or null (stale, foreign, archived). */
+  get(clientId: string, id: string): Promise<DiscountRecord | null>;
+  /**
+   * Persist a new discount and its targets. Implementations raise their own
+   * host error for a uniqueness clash (name or coupon code within the tenant)
+   * and for a target id that belongs to another tenant — both are database
+   * facts this package cannot see, and both must reach the operator naming the
+   * offending field.
+   */
+  create(clientId: string, write: DiscountWrite): Promise<DiscountRecord>;
+  /** Re-state a discount whole. Raises the host's not-found for a stale id. */
+  update(clientId: string, id: string, write: DiscountWrite): Promise<void>;
+  /**
+   * SOFT-delete. The row survives: its redemption snapshots are order history
+   * and its counter is reporting history, so removing it would either orphan
+   * redemptions or reset a number the store may still be asked to explain.
+   */
+  archive(clientId: string, id: string): Promise<void>;
+}