@softure-ai/core 0.1.11 → 0.2.1

package/src/format.ts

@@ -1,11 +1,12 @@
 // Days, money and percentages as people read them, one way for every module and app. A calendar day
-// is formatted at UTC midnight in UTC, so neither the server's nor the reader's zone moves it.
+// is formatted at UTC midnight in UTC, so neither the server's nor the reader's zone moves it. Every
+// formatter takes any BCP 47 locale tag (an invalid one throws Intl's RangeError); the only built-in
+// copy is English, and an app passes its own words where a formatter writes any.
 import { isCalendarDay } from "./calendar-day.js";
 import { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
-import { formatMessage, selectPlural, type Locale } from "./i18n.js";
-import { coreMessages } from "./messages/index.js";
+import { formatMessage, selectPlural, type PluralForms } from "./i18n.js";
 
-/** `long`: October 4, 2026 (pl names the month in the genitive); `medium`: Oct 4, 2026; `numeric`: 10/04/2026 (pl: 04.10.2026). */
+/** `long`: October 4, 2026; `medium`: Oct 4, 2026; `numeric`: 10/04/2026 (each locale writes its own order and separators). */
 export type CalendarDayStyle = "long" | "medium" | "numeric";
 
 export interface FormatMoneyOptions {
@@ -17,21 +18,49 @@ export interface FormatMoneyOptions {
   readonly compact?: boolean;
 }
 
-/** `long`: October 2026 (pl: the month in the nominative); `genitive`: pl's genitive month, as inside a date; `roman`: X 2026. */
-export type CalendarMonthStyle = "long" | "genitive" | "roman";
+/** `long`: October 2026; `roman`: X 2026. */
+export type CalendarMonthStyle = "long" | "roman";
+
+/** The words `formatDuration` writes: plural forms with `{count}`, and `both` joining `{years}` and `{months}`. */
+export interface DurationMessages {
+  readonly years: PluralForms;
+  readonly months: PluralForms;
+  readonly both: string;
+}
+
+export interface FormatDurationOptions {
+  /** The BCP 47 tag whose plural rules pick a form (default `"en"`). */
+  readonly locale?: string;
+  /** The app's own words (default `DEFAULT_DURATION_MESSAGES`, English). */
+  readonly messages?: DurationMessages;
+}
 
 export interface FormatPercentOptions {
   /** A `+` before a positive value (a `-` before a negative one is always there). Zero has neither in any mode. */
   readonly signed?: boolean;
   /** No space between the number and `%`, whatever the locale's pattern: `12,5%`, not `12,5 %`. */
   readonly tight?: boolean;
+  /**
+   * Exactly this many fraction digits, an integer from 0 to 20: `{ fractionDigits: 2 }` writes 1900 as `19.00%`.
+   * Without it a value has at most two fraction digits and no trailing zeros.
+   */
+  readonly fractionDigits?: number;
 }
 
 const MONTHS_PER_YEAR = 12;
 const MONTH_PATTERN = /^(\d{4})-(\d{2})$/;
 const ROMAN_MONTHS = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X", "XI", "XII"] as const;
+
+/** The built-in, English words of `formatDuration`; any other category falls back to `other`. */
+export const DEFAULT_DURATION_MESSAGES: DurationMessages = {
+  years: { one: "{count} year", other: "{count} years" },
+  months: { one: "{count} month", other: "{count} months" },
+  both: "{years} and {months}",
+};
+
 const BASIS_POINTS_PER_UNIT = 10_000;
 const MAX_PERCENT_FRACTION_DIGITS = 2;
+const FRACTION_DIGITS_LIMIT = 20;
 
 const dayFormatters = new Map<string, Intl.DateTimeFormat>();
 const numberFormatters = new Map<string, Intl.NumberFormat>();
@@ -43,7 +72,7 @@ const DAY_STYLE_OPTIONS: Readonly<Record<CalendarDayStyle, Intl.DateTimeFormatOp
 };
 
 /** A `YYYY-MM-DD` day as `locale` writes it. Throws a `RangeError` for a malformed day. */
-export function formatCalendarDay(day: string, locale: Locale, style: CalendarDayStyle = "long"): string {
+export function formatCalendarDay(day: string, locale: string, style: CalendarDayStyle = "long"): string {
   if (!isCalendarDay(day)) throw new RangeError(`formatCalendarDay: "${String(day)}" is not a YYYY-MM-DD calendar day`);
   return getDayFormatter(`${locale}:${style}`, locale, DAY_STYLE_OPTIONS[style]).format(new Date(`${day}T00:00:00Z`));
 }
@@ -61,28 +90,26 @@ export function isCalendarMonth(value: unknown): value is string {
  * The month of a `YYYY-MM` month or a `YYYY-MM-DD` day, with its year, as `locale` writes it alone. Throws a
  * `RangeError` for anything else.
  */
-export function formatCalendarMonth(month: string, locale: Locale, style: CalendarMonthStyle = "long"): string {
+export function formatCalendarMonth(month: string, locale: string, style: CalendarMonthStyle = "long"): string {
   const firstDay = isCalendarMonth(month) ? `${month}-01` : month;
   if (!isCalendarDay(firstDay)) throw new RangeError(`formatCalendarMonth: "${String(month)}" is not a YYYY-MM month or a YYYY-MM-DD day`);
   const date = new Date(`${firstDay}T00:00:00Z`);
   const year = firstDay.slice(0, 4);
   if (style === "roman") return `${ROMAN_MONTHS[date.getUTCMonth()] ?? ""} ${year}`;
-  if (style === "long") return getDayFormatter(`${locale}:month`, locale, { month: "long", year: "numeric" }).format(date);
-  // The genitive is the form a full date uses, so it is read from a day-month-year date's month part.
-  const parts = getDayFormatter(`${locale}:day-month`, locale, { day: "numeric", month: "long", year: "numeric" }).formatToParts(date);
-  const name = parts.find((part) => part.type === "month")?.value ?? "";
-  return `${name} ${year}`;
+  return getDayFormatter(`${locale}:month`, locale, { month: "long", year: "numeric" }).format(date);
 }
 
 /**
- * Whole months as years and months in `locale`, with its plural forms: 38 is "3 years and 2 months"; a part that is
- * zero is left out, and zero itself is "0 months". Throws a `RangeError` for a negative or fractional count.
+ * Whole months as years and months: 38 is "3 years and 2 months"; a part that is zero is left out, and zero itself is
+ * "0 months". English by default; an app passes its own `messages` and the `locale` whose plural rules pick among
+ * them. Throws a `RangeError` for a negative or fractional count, or an invalid locale tag.
  */
-export function formatDuration(months: number, locale: Locale): string {
+export function formatDuration(months: number, options: FormatDurationOptions = {}): string {
   if (!Number.isSafeInteger(months) || months < 0) {
     throw new RangeError(`formatDuration: ${String(months)} is not a whole, non-negative number of months`);
   }
-  const copy = coreMessages[locale].duration;
+  const locale = options.locale ?? "en";
+  const copy = options.messages ?? DEFAULT_DURATION_MESSAGES;
   const years = Math.floor(months / MONTHS_PER_YEAR);
   const rest = months % MONTHS_PER_YEAR;
   const yearsText = formatMessage(selectPlural(locale, years, copy.years), { count: years });
@@ -94,12 +121,12 @@ export function formatDuration(months: number, locale: Locale): string {
 
 /**
  * An amount in the currency's minor unit (2900 PLN = PLN 29.00) in `locale`'s notation, thousands always
- * grouped (pl writes 1 234,56 where its default would leave four digits together), and zero is never signed (`-0`
+ * grouped (even where a locale's default would leave four digits together), and zero is never signed (`-0`
  * and an amount that rounds to zero show as zero). The minor unit is the pinned ISO
  * 4217 one (`CURRENCY_MINOR_UNIT_DIGITS`); a code outside the table gets `Intl`'s digits. Throws a
  * `RangeError` for an amount that is not a whole number of minor units, or a code `Intl` refuses.
  */
-export function formatMoney(minor: number, currency: string, locale: Locale, options: FormatMoneyOptions = {}): string {
+export function formatMoney(minor: number, currency: string, locale: string, options: FormatMoneyOptions = {}): string {
   if (!Number.isSafeInteger(minor)) throw new RangeError(`formatMoney: ${String(minor)} is not a whole number of minor units`);
   const pinned = Object.hasOwn(CURRENCY_MINOR_UNIT_DIGITS, currency) ? CURRENCY_MINOR_UNIT_DIGITS[currency] : undefined;
   const digits = pinned ?? getNumberFormatter(locale, { style: "currency", currency }).resolvedOptions().maximumFractionDigits ?? 2;
@@ -115,14 +142,15 @@ export function formatMoney(minor: number, currency: string, locale: Locale, opt
 }
 
 /**
- * Basis points as a percentage in `locale`: 1250 is 12.5%, at most two fraction digits, and zero is never signed (`-0`
- * and a value that rounds to zero show as `0%`). Throws a `RangeError` for a non-finite value.
+ * Basis points as a percentage in `locale`: 1250 is 12.5%, at most two fraction digits unless `fractionDigits` fixes
+ * them, and zero is never signed (`-0` and a value that rounds to zero show as `0%`, or `0.0%` at one digit). Throws a
+ * `RangeError` for a non-finite value or an invalid `fractionDigits`.
  */
-export function formatPercent(basisPoints: number, locale: Locale, options: FormatPercentOptions = {}): string {
+export function formatPercent(basisPoints: number, locale: string, options: FormatPercentOptions = {}): string {
   if (!Number.isFinite(basisPoints)) throw new RangeError(`formatPercent: ${String(basisPoints)} is not a finite number of basis points`);
   const format = getNumberFormatter(locale, {
     style: "percent",
-    maximumFractionDigits: MAX_PERCENT_FRACTION_DIGITS,
+    ...getPercentFractionDigits(options.fractionDigits),
     signDisplay: options.signed === true ? "exceptZero" : "negative",
   });
   const value = basisPoints / BASIS_POINTS_PER_UNIT;
@@ -134,11 +162,19 @@ export function formatPercent(basisPoints: number, locale: Locale, options: Form
     .join("");
 }
 
+function getPercentFractionDigits(fractionDigits: number | undefined): Intl.NumberFormatOptions {
+  if (fractionDigits === undefined) return { maximumFractionDigits: MAX_PERCENT_FRACTION_DIGITS };
+  if (!Number.isInteger(fractionDigits) || fractionDigits < 0 || fractionDigits > FRACTION_DIGITS_LIMIT) {
+    throw new RangeError(`formatPercent: fractionDigits ${String(fractionDigits)} is not an integer from 0 to ${String(FRACTION_DIGITS_LIMIT)}`);
+  }
+  return { minimumFractionDigits: fractionDigits, maximumFractionDigits: fractionDigits };
+}
+
 function isNextToPercentSign(parts: readonly Intl.NumberFormatPart[], index: number): boolean {
   return parts[index - 1]?.type === "percentSign" || parts[index + 1]?.type === "percentSign";
 }
 
-function getDayFormatter(key: string, locale: Locale, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+function getDayFormatter(key: string, locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
   let format = dayFormatters.get(key);
   if (format === undefined) {
     format = new Intl.DateTimeFormat(locale, { ...options, timeZone: "UTC" });
@@ -147,7 +183,7 @@ function getDayFormatter(key: string, locale: Locale, options: Intl.DateTimeForm
   return format;
 }
 
-function getNumberFormatter(locale: Locale, options: Intl.NumberFormatOptions): Intl.NumberFormat {
+function getNumberFormatter(locale: string, options: Intl.NumberFormatOptions): Intl.NumberFormat {
   const key = `${locale}:${JSON.stringify(options)}`;
   let format = numberFormatters.get(key);
   if (format === undefined) {

package/src/http-json.ts

@@ -0,0 +1,130 @@
+// A JSON GET to a third-party API, with the details every app's own copy has to get right: a timeout, no redirect
+// followed (a key in a header or the URL never reaches another host), and every failure returned as a code. A caught
+// error's message is never read, since it can quote the URL and some APIs put the key there. The body stays
+// `unknown` unless a zod schema narrows it.
+import type { z } from "zod";
+import { err, ok, type Err, type Ok } from "./result.js";
+
+export type HttpJsonFailureCode =
+  | "core.http_unreachable"
+  | "core.http_refused"
+  | "core.http_rate_limited"
+  | "core.http_unavailable"
+  | "core.http_unexpected_answer";
+
+/** A failed `requestJson`: the code and the HTTP status (`null` when no response arrived). Nothing else. */
+export type HttpJsonFailure = Err<HttpJsonFailureCode> & { readonly status: number | null };
+
+export type FetchFunction = (input: string | URL, init: RequestInit) => Promise<Response>;
+
+export interface RequestJsonOptions {
+  readonly url: string | URL;
+  /** Defaults to the global `fetch`; tests pass a fake. */
+  readonly fetch?: FetchFunction;
+  readonly headers?: HeadersInit;
+  /** Milliseconds before the request (body included) gives up. Defaults to 10 000. */
+  readonly timeoutMs?: number;
+}
+
+export interface RequestJsonSchemaOptions<S extends z.ZodType> extends RequestJsonOptions {
+  readonly schema: S;
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * GET `url` and read its JSON body. Without a schema the value is `unknown`, for the caller to narrow; with one
+ * it is the schema's output. 3xx, 401 and 403 are refused, 429 rate limited, 5xx unavailable, and any other
+ * non-2xx status or a body that is not JSON or fails the schema an unexpected answer.
+ */
+export function requestJson<S extends z.ZodType>(
+  options: RequestJsonSchemaOptions<S>,
+): Promise<Ok<z.output<S>> | HttpJsonFailure>;
+export function requestJson(options: RequestJsonOptions): Promise<Ok<unknown> | HttpJsonFailure>;
+export async function requestJson(
+  options: RequestJsonOptions & { readonly schema?: z.ZodType },
+): Promise<Ok<unknown> | HttpJsonFailure> {
+  const fetchFunction = options.fetch ?? globalThis.fetch;
+
+  let response: Response;
+  try {
+    // Inside the try: an invalid header value throws a message that quotes it.
+    const headers = new Headers(options.headers);
+    if (!headers.has("accept")) {
+      headers.set("accept", "application/json");
+    }
+    response = await fetchFunction(options.url, {
+      method: "GET",
+      headers,
+      redirect: "manual",
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch {
+    // Network error or timeout. The error's text can quote the URL, so it is dropped on purpose.
+    return httpFailure("core.http_unreachable", null);
+  }
+
+  const statusFailure = getStatusFailure(response);
+  if (statusFailure !== null) {
+    // Release the connection; a body that cannot be cancelled changes nothing for the caller.
+    await response.body?.cancel().catch(() => undefined);
+    return statusFailure;
+  }
+
+  let text: string;
+  try {
+    text = await response.text();
+  } catch {
+    // The body broke off, usually the timeout firing mid-body.
+    return httpFailure("core.http_unreachable", response.status);
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return httpFailure("core.http_unexpected_answer", response.status);
+  }
+
+  if (options.schema === undefined) {
+    return ok(body);
+  }
+  // The schema's issues can quote the body's values, so only the code leaves.
+  const parsed = options.schema.safeParse(body);
+  return parsed.success ? ok(parsed.data) : httpFailure("core.http_unexpected_answer", response.status);
+}
+
+/**
+ * The query part of a URL (without `?`) from a flat record, in insertion order. `null` and `undefined` are left
+ * out, so optional parameters can be passed as they are.
+ */
+export function toQueryString(params: Readonly<Record<string, string | number | boolean | null | undefined>>): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== null && value !== undefined) {
+      search.append(key, String(value));
+    }
+  }
+  return search.toString();
+}
+
+function getStatusFailure(response: Response): HttpJsonFailure | null {
+  const { status } = response;
+  if (response.type === "opaqueredirect" || (status >= 300 && status < 400) || status === 401 || status === 403) {
+    return httpFailure("core.http_refused", status);
+  }
+  if (status === 429) {
+    return httpFailure("core.http_rate_limited", status);
+  }
+  if (status >= 500) {
+    return httpFailure("core.http_unavailable", status);
+  }
+  if (status < 200 || status >= 300) {
+    return httpFailure("core.http_unexpected_answer", status);
+  }
+  return null;
+}
+
+function httpFailure(code: HttpJsonFailureCode, status: number | null): HttpJsonFailure {
+  return { ...err(code), status };
+}

package/src/i18n.ts

@@ -1,9 +1,12 @@
-// Copy and localization (docs/02-module-standard.md §6): every module ships complete `en` and
-// `pl` dictionaries, and the app passes partial overrides per locale.
+// Copy and localization (docs/02-module-standard.md §6): every module ships a complete `en`
+// dictionary, the only built-in language. An app that shows another language passes its own
+// translation as overrides for its locale; a key it leaves out reads English.
 
-export const LOCALES = ["en", "pl"] as const;
+/** A BCP 47 language tag (`en`, `de-AT`). */
+export type Locale = string;
 
-export type Locale = (typeof LOCALES)[number];
+/** The language of every built-in dictionary and the fallback for any other locale. */
+export const DEFAULT_LOCALE = "en";
 
 /** A dictionary: nested groups of message strings. */
 export interface MessageTree {
@@ -13,11 +16,14 @@ export interface MessageTree {
 /** The same shape with every key optional, at every depth. */
 export type DeepPartial<T> = { [K in keyof T]?: T[K] extends string ? string : DeepPartial<T[K]> };
 
-/** One complete dictionary per locale. */
-export type Dictionaries<T extends MessageTree> = Readonly<Record<Locale, T>>;
+/** A complete `en` dictionary, plus complete dictionaries for any other locales. */
+export type Dictionaries<T extends MessageTree> = { readonly en: T } & { readonly [locale: string]: T | undefined };
 
-/** Partial overrides an app passes for some locales. */
-export type MessageOverrides<T extends MessageTree> = Partial<Record<Locale, DeepPartial<T>>>;
+/** Partial overrides an app passes per locale: a translation for its own locale, or changed English copy. */
+export type MessageOverrides<T extends MessageTree> = { readonly [locale: string]: DeepPartial<T> | undefined };
+
+/** A text an app writes per locale in its options (a plan name, a label); `en` is the fallback. */
+export type LocalizedText = { readonly [locale: string]: string | undefined };
 
 /** Plural forms named after the `Intl.PluralRules` categories; `other` is the fallback. */
 export interface PluralForms {
@@ -29,24 +35,49 @@ export interface PluralForms {
   readonly other: string;
 }
 
+/** Whether `value` is a well-formed BCP 47 language tag. */
 export function isLocale(value: unknown): value is Locale {
-  return LOCALES.some((locale) => locale === value);
+  if (typeof value !== "string" || value === "") return false;
+  try {
+    return Intl.getCanonicalLocales(value).length === 1;
+  } catch {
+    // RangeError: not a well-formed tag.
+    return false;
+  }
 }
 
 /**
- * The defaults with the overrides applied, per locale. Only keys the defaults have are taken,
- * and a group is never replaced by a string, so an override cannot break the dictionary shape.
- * Inputs are not mutated.
+ * The defaults with the overrides applied, per locale: `en` and every locale the defaults or the
+ * overrides name. A locale without its own defaults is built on `en`, so a key its override leaves
+ * out reads English. Only keys the defaults have are taken, and a group is never replaced by a
+ * string, so an override cannot break the dictionary shape. Inputs are not mutated.
  */
 export function mergeMessages<T extends MessageTree>(
   defaults: Dictionaries<T>,
   overrides: MessageOverrides<T> = {},
 ): Dictionaries<T> {
-  const merged = {} as Record<Locale, T>;
-  for (const locale of LOCALES) {
-    merged[locale] = mergeTree(defaults[locale], overrides[locale]) as T;
+  const merged: Record<string, T> = {};
+  for (const locale of new Set([DEFAULT_LOCALE, ...Object.keys(defaults), ...Object.keys(overrides)])) {
+    merged[locale] = mergeTree(defaults[locale] ?? defaults.en, overrides[locale]) as T;
   }
-  return merged;
+  return merged as Dictionaries<T>;
+}
+
+/**
+ * The dictionary for `locale`: its own, else its language's (`pt-BR` reads `pt`), else `en`.
+ */
+export function selectMessages<T extends MessageTree>(dictionaries: Dictionaries<T>, locale: Locale): T {
+  return dictionaries[locale] ?? dictionaries[getLanguage(locale)] ?? dictionaries.en;
+}
+
+/** The text for `locale` with `selectMessages`' fallback order, or `fallback` when no locale has one. */
+export function pickLocalizedText(text: LocalizedText | undefined, locale: Locale, fallback = ""): string {
+  if (text === undefined) return fallback;
+  return text[locale] ?? text[getLanguage(locale)] ?? text.en ?? fallback;
+}
+
+function getLanguage(locale: Locale): string {
+  return locale.split("-")[0] ?? locale;
 }
 
 /** Fills `{name}` placeholders. A placeholder without a value stays as written. */
@@ -57,10 +88,13 @@ export function formatMessage(template: string, params: Readonly<Record<string,
   });
 }
 
-const pluralRulesByLocale = new Map<Locale, Intl.PluralRules>();
+const pluralRulesByLocale = new Map<string, Intl.PluralRules>();
 
-/** The form for `count` under the plural rules of `locale` ("1 file", "2 files"). */
-export function selectPlural(locale: Locale, count: number, forms: PluralForms): string {
+/**
+ * The form for `count` under the plural rules of `locale`, any BCP 47 tag ("1 file", "2 files"). A category the
+ * forms leave out falls back to `other`.
+ */
+export function selectPlural(locale: string, count: number, forms: PluralForms): string {
   let rules = pluralRulesByLocale.get(locale);
   if (rules === undefined) {
     rules = new Intl.PluralRules(locale);

package/src/index.ts

@@ -11,8 +11,17 @@ export {
   wholeMonthsBetween,
   type EndOfMonth,
 } from "./calendar-day.js";
+export {
+  calendarPeriodSchema,
+  countPeriodDays,
+  doPeriodsOverlap,
+  isDayInPeriod,
+  type CalendarPeriod,
+} from "./calendar-period.js";
+export { getLocalDay, isLocalDateTime, localDateTimeSchema, type LocalDateTime } from "./local-date-time.js";
 export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
 export {
+  DEFAULT_DURATION_MESSAGES,
   formatCalendarDay,
   formatCalendarMonth,
   formatDuration,
@@ -21,21 +30,35 @@ export {
   isCalendarMonth,
   type CalendarDayStyle,
   type CalendarMonthStyle,
+  type DurationMessages,
+  type FormatDurationOptions,
   type FormatMoneyOptions,
   type FormatPercentOptions,
 } from "./format.js";
+export {
+  requestJson,
+  toQueryString,
+  type FetchFunction,
+  type HttpJsonFailure,
+  type HttpJsonFailureCode,
+  type RequestJsonOptions,
+  type RequestJsonSchemaOptions,
+} from "./http-json.js";
 export { memoizeByContent, type MemoizeByContentOptions, type MemoizedFunction } from "./memoize.js";
 export { createTestClock, systemClock, type Clock, type TestClock } from "./clock.js";
 export {
   formatMessage,
   getMessage,
+  DEFAULT_LOCALE,
   isLocale,
-  LOCALES,
   mergeMessages,
+  pickLocalizedText,
+  selectMessages,
   selectPlural,
   type DeepPartial,
   type Dictionaries,
   type Locale,
+  type LocalizedText,
   type MessageOverrides,
   type MessageTree,
   type PluralForms,

package/src/local-date-time.ts

@@ -0,0 +1,30 @@
+// A local wall-clock date-time, `YYYY-MM-DDTHH:mm` with no time zone: a time that is local at a place
+// (a departure, a booking slot), independent of the server's zone. Zero-padded, so it sorts as text.
+import { z } from "zod";
+import { isCalendarDay } from "./calendar-day.js";
+
+const LOCAL_DATE_TIME_PATTERN = /^(\d{4}-\d{2}-\d{2})T([01]\d|2[0-3]):[0-5]\d$/;
+
+/** A string checked by `isLocalDateTime` or `localDateTimeSchema`; a plain string is not one. */
+export type LocalDateTime = string & z.$brand<"LocalDateTime">;
+
+/** Whether `value` is a `YYYY-MM-DDTHH:mm` local date-time on a real day (`2026-02-30T10:00` and `…T24:00` are not). */
+export function isLocalDateTime(value: unknown): value is LocalDateTime {
+  if (typeof value !== "string") return false;
+  const match = LOCAL_DATE_TIME_PATTERN.exec(value);
+  return match !== null && isCalendarDay(match[1]);
+}
+
+/** A `YYYY-MM-DDTHH:mm` local date-time in tool and form input, parsed into the branded `LocalDateTime`. */
+export const localDateTimeSchema = z
+  .string()
+  .refine(isLocalDateTime, "must be a YYYY-MM-DDTHH:mm local date-time on a real day, e.g. 2026-10-04T09:30")
+  .brand<"LocalDateTime">();
+
+/** The calendar day (`YYYY-MM-DD`) of a local date-time. Throws a `RangeError` for a malformed value. */
+export function getLocalDay(value: LocalDateTime): string {
+  if (!isLocalDateTime(value)) {
+    throw new RangeError(`getLocalDay: "${String(value)}" is not a YYYY-MM-DDTHH:mm local date-time`);
+  }
+  return value.slice(0, "YYYY-MM-DD".length);
+}

package/src/messages/en.ts

@@ -2,10 +2,10 @@ export const en = {
   errors: {
     database_failed: "Something went wrong while saving or loading data. Please try again.",
     unexpected: "Something went wrong. Please try again.",
-  },
-  duration: {
-    years: { one: "{count} year", few: "{count} years", many: "{count} years", other: "{count} years" },
-    months: { one: "{count} month", few: "{count} months", many: "{count} months", other: "{count} months" },
-    both: "{years} and {months}",
+    http_unreachable: "The service could not be reached. Please try again later.",
+    http_refused: "The service refused the request.",
+    http_rate_limited: "The service is receiving too many requests. Please try again later.",
+    http_unavailable: "The service is unavailable right now. Please try again later.",
+    http_unexpected_answer: "The service sent an answer that could not be read.",
   },
 };

package/src/messages/index.ts

@@ -1,8 +1,7 @@
 import type { Dictionaries } from "../i18n.js";
 import { en } from "./en.js";
-import { pl } from "./pl.js";
 
 export type CoreMessages = typeof en;
 
-/** Copy for core's own error codes (`core.<key>` → `errors.<key>`) and formatters (`duration`). */
-export const coreMessages: Dictionaries<CoreMessages> = { en, pl };
+/** Copy for core's own error codes (`core.<key>` → `errors.<key>`). */
+export const coreMessages: Dictionaries<CoreMessages> = { en };

package/dist/messages/pl.d.ts

@@ -1,3 +0,0 @@
-import type { en } from "./en.js";
-export declare const pl: typeof en;
-//# sourceMappingURL=pl.d.ts.map

package/dist/messages/pl.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pl.d.ts","sourceRoot":"","sources":["../../src/messages/pl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC,eAAO,MAAM,EAAE,EAAE,OAAO,EAUvB,CAAC"}

package/dist/messages/pl.js

@@ -1,12 +0,0 @@
-export const pl = {
-    errors: {
-        database_failed: "Coś poszło nie tak przy zapisie lub odczycie danych. Spróbuj ponownie.",
-        unexpected: "Coś poszło nie tak. Spróbuj ponownie.",
-    },
-    duration: {
-        years: { one: "{count} rok", few: "{count} lata", many: "{count} lat", other: "{count} roku" },
-        months: { one: "{count} miesiąc", few: "{count} miesiące", many: "{count} miesięcy", other: "{count} miesiąca" },
-        both: "{years} i {months}",
-    },
-};
-//# sourceMappingURL=pl.js.map

package/dist/messages/pl.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"pl.js","sourceRoot":"","sources":["../../src/messages/pl.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,EAAE,GAAc;IAC3B,MAAM,EAAE;QACN,eAAe,EAAE,wEAAwE;QACzF,UAAU,EAAE,uCAAuC;KACpD;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,EAAE;QAC9F,MAAM,EAAE,EAAE,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,kBAAkB,EAAE;QAChH,IAAI,EAAE,oBAAoB;KAC3B;CACF,CAAC"}

package/src/messages/pl.ts

@@ -1,13 +0,0 @@
-import type { en } from "./en.js";
-
-export const pl: typeof en = {
-  errors: {
-    database_failed: "Coś poszło nie tak przy zapisie lub odczycie danych. Spróbuj ponownie.",
-    unexpected: "Coś poszło nie tak. Spróbuj ponownie.",
-  },
-  duration: {
-    years: { one: "{count} rok", few: "{count} lata", many: "{count} lat", other: "{count} roku" },
-    months: { one: "{count} miesiąc", few: "{count} miesiące", many: "{count} miesięcy", other: "{count} miesiąca" },
-    both: "{years} i {months}",
-  },
-};