@12-apps/discounts 1.11.0 → 1.13.0

package/src/server/validate.ts

@@ -5,6 +5,7 @@ import {
   type DiscountTrigger,
   type DiscountType,
 } from "../engine/kinds";
+import { isUsableSchedule, type DiscountSchedule } from "../engine/schedule";
 import type { ComboRequirement } from "../engine/types";
 import type { DiscountsServerCopy } from "./copy";
 import { comboRequirementsForScope, toComboColumns } from "./validate-combo";
@@ -50,6 +51,15 @@ export interface DiscountWriteInput {
   /** Calendar dates (`YYYY-MM-DD`) as the form sends them, or null. */
   startsAt: string | null;
   endsAt: string | null;
+  /**
+   * The WEEKLY schedule inside that window (FUT-996), or null for "always".
+   * Validated here rather than trusted: it is stored as JSON, so the database
+   * cannot check its shape and this is the only gate in front of it.
+   *
+   * Optional so a caller assembling a write input by hand — a test, a script,
+   * an older adopter — does not have to name a field it has no opinion about.
+   */
+  schedule?: DiscountSchedule | null;
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;
@@ -168,6 +178,32 @@ function assertWindow(
   return { startsAt, endsAt };
 }
 
+/**
+ * The weekly schedule, or null (FUT-996).
+ *
+ * Every failure here is ONE message rather than a per-window field error,
+ * because the operator does not edit this as fields: they edit a row of day
+ * chips and two clocks, and "a linha 2 não tem dias" points at something the
+ * form can highlight while `schedule.windows[1].days` does not.
+ *
+ * A `to` earlier than `from` is NOT an error — it is a bar shutting at 02:00,
+ * which is the most common happy hour there is. The only refusals are the ones
+ * that cannot mean anything: no windows at all, a row naming no day, a day off
+ * the Monday-first axis, a malformed clock, and a zero-length window.
+ */
+function assertSchedule(
+  input: DiscountWriteInput,
+  copy: DiscountsServerCopy,
+): DiscountSchedule | null {
+  const { schedule } = input;
+  // `== null` catches BOTH, deliberately: the field is required on the type,
+  // but a caller assembling a write input by hand omits what it does not use,
+  // and "absent" and "explicitly none" are the same promotion.
+  if (schedule == null) return null;
+  if (!isUsableSchedule(schedule)) throw invalid("schedule", copy.invalidSchedule);
+  return { windows: schedule.windows.map((w) => ({ days: [...w.days], from: w.from, to: w.to })) };
+}
+
 /** A cap of zero is not a cap, it is a discount that can never be used. */
 function assertPositiveOrNull(value: number | null, field: string, message: string): void {
   if (value === null) return;
@@ -194,6 +230,8 @@ export interface DiscountScalars {
   code: string | null;
   startsAt: Date | null;
   endsAt: Date | null;
+  /** The weekly schedule, or null. Persisted as a JSON column. */
+  schedule: DiscountSchedule | null;
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;
@@ -233,6 +271,7 @@ export function toDiscountScalars(
   const code = assertTrigger(input, copy);
   assertTargets(input, copy);
   const { startsAt, endsAt } = assertWindow(input, copy);
+  const schedule = assertSchedule(input, copy);
   assertLimits(input, copy);
   const combo = toComboColumns(input, copy);
 
@@ -249,6 +288,7 @@ export function toDiscountScalars(
     code,
     startsAt,
     endsAt,
+    schedule,
     minSubtotalCents: input.minSubtotalCents,
     usageLimit: input.usageLimit,
     perBuyerLimit: input.perBuyerLimit,
@@ -277,6 +317,8 @@ export interface DiscountWriteBody {
   code?: string | null;
   startsAt?: string | null;
   endsAt?: string | null;
+  /** The weekly schedule, or null/omitted for "always" (FUT-996). */
+  schedule?: DiscountSchedule | null;
   minSubtotalCents?: number | null;
   usageLimit?: number | null;
   perBuyerLimit?: number | null;
@@ -311,6 +353,7 @@ export function toDiscountWriteInput(body: DiscountWriteBody): DiscountWriteInpu
     code: orNull(body.code),
     startsAt: orNull(body.startsAt),
     endsAt: orNull(body.endsAt),
+    schedule: orNull(body.schedule),
     minSubtotalCents: orNull(body.minSubtotalCents),
     usageLimit: orNull(body.usageLimit),
     perBuyerLimit: orNull(body.perBuyerLimit),

package/src/timezone.ts

@@ -0,0 +1,96 @@
+import type { LocalClock } from "./engine/schedule";
+
+/**
+ * Resolve an instant into a store's own wall clock (FUT-996).
+ *
+ * Deliberately NOT part of the engine, and exported from its own subpath rather
+ * than the root. The engine's contract is that it reaches no clock and no
+ * locale data — it runs in an offline tool generator, a browser bundle and a
+ * worker — and this function reads `Intl`, which is exactly the dependency that
+ * contract exists to keep out. Everything here produces the two integers the
+ * engine consumes; nothing here decides anything about a discount.
+ *
+ * It lives in the PACKAGE rather than in each host because there must be one
+ * implementation. The admin grid's "ativa agora" dot runs in a browser, the
+ * price a shopper is charged is computed on a server, and a second copy of
+ * "which weekday is it in São Paulo at 23:50" is how those two start
+ * disagreeing about the same minute — silently, and only for the hour that
+ * matters.
+ */
+
+/**
+ * `Intl` reports a Sunday-first weekday; the schedule axis is Monday-first, the
+ * same one `WeekHours` and every hours screen uses. This table is the whole
+ * conversion, written as data so it cannot be got subtly wrong by arithmetic.
+ */
+const MONDAY_FIRST: Readonly<Record<string, number>> = {
+  Mon: 0,
+  Tue: 1,
+  Wed: 2,
+  Thu: 3,
+  Fri: 4,
+  Sat: 5,
+  Sun: 6,
+};
+
+/**
+ * The store's weekday and minute-of-day at `instant`, or null when the zone is
+ * not one this runtime knows.
+ *
+ * NULL rather than a fallback, and the CALLER decides what that means — which
+ * is the only honest split, because the two callers need opposite things. A
+ * cart must keep pricing (a scheduled rule fires; see `scheduleCovers`), and a
+ * teaser must stay quiet rather than promise an hour it cannot name. A default
+ * chosen here would silently impose one of those on both.
+ */
+export function resolveLocalClock(instant: Date, timeZone: string): LocalClock | null {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      weekday: "short",
+      hour: "2-digit",
+      minute: "2-digit",
+      hour12: false,
+    }).formatToParts(instant);
+    const read = (type: string): string =>
+      parts.find((part) => part.type === type)?.value ?? "";
+    const weekday = MONDAY_FIRST[read("weekday")];
+    const hour = Number(read("hour"));
+    const minute = Number(read("minute"));
+    if (weekday === undefined || !Number.isFinite(hour) || !Number.isFinite(minute)) return null;
+    // `hour12: false` yields 24 for midnight in some ICU versions — a real,
+    // once-a-day discrepancy that would put every midnight instant outside
+    // every window.
+    return { weekday, minutes: (hour % 24) * 60 + minute };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The zone as a PERSON would read it, in their own language — "Horário Padrão
+ * de Brasília", "Brasilia Standard Time".
+ *
+ * Derived rather than configured, and that is the point: a host passing a
+ * display name would be passing COPY, which this repo's own rules say must
+ * ship bilingual. `Intl` already knows every zone's name in every locale, so
+ * asking it is both less to maintain and correct in languages nobody here
+ * speaks.
+ *
+ * Falls back to the IANA id with its separators softened ("America/Sao_Paulo"
+ * → "Sao Paulo"), which is wrong-looking but never blank — a caption is not
+ * worth an exception for.
+ */
+export function timeZoneLabel(timeZone: string, locale: string): string {
+  try {
+    const parts = new Intl.DateTimeFormat(locale, {
+      timeZone,
+      timeZoneName: "longGeneric",
+    }).formatToParts(new Date());
+    const name = parts.find((part) => part.type === "timeZoneName")?.value;
+    if (name !== undefined && name !== "") return name;
+  } catch {
+    // fall through
+  }
+  return (timeZone.split("/").pop() ?? timeZone).replace(/_/g, " ");
+}