@northguild/gmt 1.16.0 → 1.18.0

package/dist/instant/convert/toOffsetInstant.js

@@ -1,32 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { formatUtcOffset, isoStringBody, parseInstantNanoseconds, zonedDateTimeFrom, } from "../../internal/index.js";
+import { formatUtcOffset, isoStringBody, parseInstantNanoseconds, TIME_ZONE_ANNOTATION, zonedDateTimeFrom, } from "../../internal/index.js";
 import { utcOffset } from "../../regex/index.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
-/**
- * An absolute instant paired with the local UTC offset in force where the event happened.
- *
- * @remarks Members:
- *
- * | Member | Type | Description |
- * | --- | --- | --- |
- * | `instant` | `string` | UTC instant, ISO 8601 ending in `Z` (e.g. `2024-07-15T16:00:00Z`). Orders events globally. |
- * | `offset` | `string` | UTC offset in force where the event happened, `±HH:MM` (or `±HH:MM:SS` for a pre-1972 zone that did not run on a whole minute). Renders the event as the human on the ground saw it. |
- * | `timeZone` | `string \| undefined` | IANA zone identifier, when one is known. Absent from most feeds, so absent from most pairs. |
- *
- * Neither `instant` nor `offset` derives from the other, which is why both are stored. It is
- * the shape GS1 EPCIS 2.0 (`eventTime` + a required `eventTimeZoneOffset`), UN/EDIFACT DTM
- * (qualifier `303`/`304`) and DICOM (`DT` + `&ZZXX`) all exchange.
- *
- * @example
- * import { OffsetInstant } from "@northguild/gmt/instant";
- * const pair: OffsetInstant = {
- *   instant: "2024-07-15T16:00:00Z",
- *   offset: "-04:00",
- *   timeZone: "America/New_York",
- * };
- */
 /** A leading RFC 9557 time zone annotation: `[zone]` or `[!zone]`, with no `=`. */
-const timeZoneAnnotation = /^\[!?[^\]=]+\]/;
+const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
 /**
  * Split an ISO 8601 instant string into the instant-plus-offset pair the world exchanges.
  *
@@ -69,10 +46,15 @@ const timeZoneAnnotation = /^\[!?[^\]=]+\]/;
  *   rounding it would put the pair 30 seconds from the event it describes. Such a zone's
  *   *string* still carries the rounded `-00:45`, because RFC 9557 caps a written offset at
  *   minutes; the bracketed zone is what resolves it, so the instant stays exact.
+ * - A bracketed zone is checked as `Temporal.ZonedDateTime.from` checks it, which also rejects
+ *   a local date of −271821-04-19. A zone west of Greenwich shows that date for the first hours
+ *   of the instant range, so a zoned string written there
+ *   (`-271821-04-19T23:59:00-00:01[Europe/London]`) returns null, although `isValidInstant`
+ *   accepts it. Pass the instant in `Z` form with `timeZone` instead.
  * - Returns null on invalid input, not a zero-offset pair — `+00:00` is a real offset.
  *
  * @param value ISO 8601 instant string, with an offset designator and optionally a bracketed zone
- * @param timeZone optional IANA zone identifier to read the offset in
+ * @param timeZone optional IANA name or UTC offset to read the offset in
  * @returns `{ instant, offset, timeZone? }`, or null on invalid input
  *
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
@@ -84,6 +66,8 @@ const timeZoneAnnotation = /^\[!?[^\]=]+\]/;
  * @example toOffsetInstant("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" } — the zone, not the rounded offset, fixes the instant
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[-04:00]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — a bracketed offset is not a zone, so no timeZone field
  * @example toOffsetInstant("2024-07-15T12:00:00-05:00[America/New_York]") // null (offset contradicts the bracketed zone)
+ * @example toOffsetInstant("-271821-04-19T23:59:00-00:01[Europe/London]") // null (a bracketed zone on a local date before Temporal's date range)
+ * @example toOffsetInstant("-271821-04-20T00:00:15Z", "Europe/London") // { instant: "-271821-04-20T00:00:15Z", offset: "-00:01:15", timeZone: "Europe/London" }
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[foo=bar]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an elective annotation is ignored
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[!foo=bar]") // null (an unknown critical annotation)
  * @example toOffsetInstant("2024-07-15T12:00:00") // null (no offset designator)
@@ -103,8 +87,8 @@ export function toOffsetInstant(value, timeZone) {
         return null;
     }
     try {
-        // `parseInstantNanoseconds` reads the offset and ignores the bracket, so a self-
-        // contradictory string parses fine as an instant. `ZonedDateTime.from` is what checks
+        // `parseInstantNanoseconds` does not validate the bracket, so a self-contradictory string
+        // parses fine as an instant. `ZonedDateTime.from` is what checks
         // the two agree, and it runs even when `timeZone` overrides the bracketed zone.
         // Only a time zone annotation makes the string zoned: it is the first annotation, and the
         // only kind with no `=` (RFC 9557 §4.1). A calendar or elective annotation alone leaves an

package/dist/intermodal/calculate/billingTimeline.d.ts

@@ -0,0 +1,114 @@
+/** The dates a billing timeline is counted from: the anchor, and the invoice and request once they exist. */
+export interface BillingDates {
+    /**
+     * The date the issue window is counted from, as an ISO date, such as the date the charge was
+     * last incurred or, for a re-bill, the issuance date of the invoice received.
+     */
+    anchorOn: string;
+    /**
+     * The date the invoice was issued, once it has been, as an ISO date.
+     *
+     * @defaultValue None. `issuedByDeadline` and `disputeDeadline` are `null`.
+     */
+    invoiceIssuedOn?: string;
+    /**
+     * The date the dispute request was received, once it has been, as an ISO date. It needs
+     * `invoiceIssuedOn` and may not precede it.
+     *
+     * @defaultValue None. `requestedByDeadline` and `resolutionDeadline` are `null`.
+     */
+    requestReceivedOn?: string;
+}
+/** The three windows the caller supplies, in calendar days, none defaulted, and an optional agreed resolution date. */
+export interface BillingWindows {
+    /** The days from `anchorOn` within which the invoice must be issued. */
+    issueDays: number;
+    /** The days from `invoiceIssuedOn` within which a dispute may be raised. */
+    disputeDays: number;
+    /** The days from `requestReceivedOn` within which the dispute must be resolved. */
+    resolutionDays: number;
+    /**
+     * A resolution date the parties agreed instead, as an ISO date on or after `requestReceivedOn`;
+     * it replaces the computed one.
+     *
+     * @defaultValue None. `resolutionDeadline` is `requestReceivedOn + resolutionDays`.
+     */
+    agreedResolutionOn?: string;
+}
+/** What `billingTimeline` returns: each deadline as an ISO date, and each comparison once its date exists. */
+export interface BillingDeadlines {
+    /** The last date the invoice may be issued: `anchorOn + issueDays`. */
+    invoiceDeadline: string;
+    /** Whether `invoiceIssuedOn` is on or before `invoiceDeadline`; `null` until an invoice date exists. */
+    issuedByDeadline: boolean | null;
+    /**
+     * The last date a dispute may be raised: `invoiceIssuedOn + disputeDays`; `null` until an invoice
+     * date exists.
+     */
+    disputeDeadline: string | null;
+    /** Whether `requestReceivedOn` is on or before `disputeDeadline`; `null` until a request date exists. */
+    requestedByDeadline: boolean | null;
+    /**
+     * The last date the dispute must be resolved: `requestReceivedOn + resolutionDays`, or
+     * `agreedResolutionOn`; `null` until a request date exists.
+     */
+    resolutionDeadline: string | null;
+}
+/**
+ * Lay out the deadline chain around a demurrage or detention invoice: the last date it may be
+ * issued, the last date it may be disputed, and the last date the dispute must be resolved.
+ *
+ * A billing regime or service contract can set up to three windows around an invoice: one to
+ * issue it, one to dispute it, and one to resolve the dispute. The number of days in each is the
+ * caller's fact; GMT carries none of them. The arithmetic is this function's: each deadline is a
+ * date, counted in calendar days from a date, with the anchor as day zero and the deadline day
+ * itself inside the window.
+ *
+ * - **Day zero is the anchor and the deadline is `anchor + days`** on the ISO 8601 calendar
+ *   (`Temporal.PlainDate.add`); a date is "by the deadline" when
+ *   `Temporal.PlainDate.compare(date, deadline) <= 0`. That is this function's stated contract,
+ *   not a reading of any rule; a regime that counts differently passes a different number.
+ * - **Deadlines are dates, never instants.** Reduce an instant to the billing party's local date
+ *   first with `convertUtcToPlainDate(instant, { timeZone })`; this function does not guess a
+ *   zone. `anchorOn` is whatever date the caller counts from, such as the last charged date
+ *   (`chargeableDays(...).chargedDates.at(-1)`) or, for a party re-billing a charge it was
+ *   itself billed, the issuance date of the invoice it received.
+ * - **Windows have no defaults.** Each is a safe integer of at least `0`; a missing, negative or
+ *   non-integer window returns `null`, because a silently defaulted window is a wrong deadline.
+ * - **The chain fills in as its dates exist.** With only `anchorOn` the result is a forecast:
+ *   `invoiceDeadline` is set and every other field is `null`. An invoice date sets
+ *   `issuedByDeadline` and `disputeDeadline`; a request date sets `requestedByDeadline` and
+ *   `resolutionDeadline`. An explicit `undefined` is an omission; any other value must be a
+ *   valid ISO date.
+ * - **The booleans compare dates and say nothing else.** Whether a charge is payable, whether a
+ *   dispute must be heard, and any consequence are the consumer's. GMT computes dates, not
+ *   liability.
+ * - **`agreedResolutionOn` replaces the computed `resolutionDeadline`** when given. It must be a
+ *   valid date on or after `requestReceivedOn`, else `null`; it is validated even when no
+ *   request exists, but cannot act without one.
+ * - **A request cannot precede the invoice it disputes.** `requestReceivedOn` without
+ *   `invoiceIssuedOn`, or earlier than it, is a data error and returns `null`. An invoice earlier
+ *   than the anchor is allowed: an invoice may be issued while charges still accrue.
+ * - Every emitted date is canonical bare ISO (`Temporal.PlainDate#toString()`), so an input
+ *   annotation such as `[u-ca=iso8601]` does not reach the output, as `addDate` behaves.
+ * - Returns `null` when `dates` or `windows` is not an object, `anchorOn` or a given optional
+ *   date is not a valid ISO date, a window is missing or not a safe integer of at least `0`, a
+ *   request exists without an invoice or before it, `agreedResolutionOn` is before the request,
+ *   or a deadline would leave Temporal's range.
+ *
+ * @param dates The anchor date, and the invoice and request dates once they exist
+ * @param windows The three calendar-day windows, none defaulted, and an agreed resolution date
+ * @returns { invoiceDeadline, issuedByDeadline, disputeDeadline, requestedByDeadline, resolutionDeadline }, or null on invalid input
+ *
+ * @example billingTimeline({ anchorOn: "2026-03-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (no invoice yet: a forecast)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-30", requestedByDeadline: null, resolutionDeadline: null } (day 30 is the last day by the deadline)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-04-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: false, disputeDeadline: "2026-05-01", requestedByDeadline: null, resolutionDeadline: null } (day 31)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-19" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19", requestedByDeadline: true, resolutionDeadline: "2026-05-19" }
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-20" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30, agreedResolutionOn: "2026-06-01" }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19", requestedByDeadline: false, resolutionDeadline: "2026-06-01" } (an agreed date replaces the computed one)
+ * @example billingTimeline({ anchorOn: "2026-03-10", invoiceIssuedOn: "2026-04-05" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-04-09", issuedByDeadline: true, disputeDeadline: "2026-05-05", requestedByDeadline: null, resolutionDeadline: null } (a re-bill anchored on the invoice it received, not on the charge)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-05", requestReceivedOn: "2026-03-18" }, { issueDays: 14, disputeDays: 14, resolutionDays: 45 }) // { invoiceDeadline: "2026-03-15", issuedByDeadline: true, disputeDeadline: "2026-03-19", requestedByDeadline: true, resolutionDeadline: "2026-05-02" } (a service contract's own windows)
+ * @example billingTimeline({ anchorOn: "2028-01-30" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2028-02-29", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (calendar days across a leap day)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { disputeDays: 30, resolutionDays: 30 }) // null (issueDays has no default)
+ * @example billingTimeline({ anchorOn: "2026-03-01", requestReceivedOn: "2026-04-19" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // null (a request cannot precede the invoice it disputes)
+ */
+export declare function billingTimeline(dates: BillingDates, windows: BillingWindows): BillingDeadlines | null;

package/dist/intermodal/calculate/billingTimeline.js

@@ -0,0 +1,168 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject } from "../../internal/index.js";
+import { isValidDate } from "../../plain/validate/isValidDate.js";
+/**
+ * Lay out the deadline chain around a demurrage or detention invoice: the last date it may be
+ * issued, the last date it may be disputed, and the last date the dispute must be resolved.
+ *
+ * A billing regime or service contract can set up to three windows around an invoice: one to
+ * issue it, one to dispute it, and one to resolve the dispute. The number of days in each is the
+ * caller's fact; GMT carries none of them. The arithmetic is this function's: each deadline is a
+ * date, counted in calendar days from a date, with the anchor as day zero and the deadline day
+ * itself inside the window.
+ *
+ * - **Day zero is the anchor and the deadline is `anchor + days`** on the ISO 8601 calendar
+ *   (`Temporal.PlainDate.add`); a date is "by the deadline" when
+ *   `Temporal.PlainDate.compare(date, deadline) <= 0`. That is this function's stated contract,
+ *   not a reading of any rule; a regime that counts differently passes a different number.
+ * - **Deadlines are dates, never instants.** Reduce an instant to the billing party's local date
+ *   first with `convertUtcToPlainDate(instant, { timeZone })`; this function does not guess a
+ *   zone. `anchorOn` is whatever date the caller counts from, such as the last charged date
+ *   (`chargeableDays(...).chargedDates.at(-1)`) or, for a party re-billing a charge it was
+ *   itself billed, the issuance date of the invoice it received.
+ * - **Windows have no defaults.** Each is a safe integer of at least `0`; a missing, negative or
+ *   non-integer window returns `null`, because a silently defaulted window is a wrong deadline.
+ * - **The chain fills in as its dates exist.** With only `anchorOn` the result is a forecast:
+ *   `invoiceDeadline` is set and every other field is `null`. An invoice date sets
+ *   `issuedByDeadline` and `disputeDeadline`; a request date sets `requestedByDeadline` and
+ *   `resolutionDeadline`. An explicit `undefined` is an omission; any other value must be a
+ *   valid ISO date.
+ * - **The booleans compare dates and say nothing else.** Whether a charge is payable, whether a
+ *   dispute must be heard, and any consequence are the consumer's. GMT computes dates, not
+ *   liability.
+ * - **`agreedResolutionOn` replaces the computed `resolutionDeadline`** when given. It must be a
+ *   valid date on or after `requestReceivedOn`, else `null`; it is validated even when no
+ *   request exists, but cannot act without one.
+ * - **A request cannot precede the invoice it disputes.** `requestReceivedOn` without
+ *   `invoiceIssuedOn`, or earlier than it, is a data error and returns `null`. An invoice earlier
+ *   than the anchor is allowed: an invoice may be issued while charges still accrue.
+ * - Every emitted date is canonical bare ISO (`Temporal.PlainDate#toString()`), so an input
+ *   annotation such as `[u-ca=iso8601]` does not reach the output, as `addDate` behaves.
+ * - Returns `null` when `dates` or `windows` is not an object, `anchorOn` or a given optional
+ *   date is not a valid ISO date, a window is missing or not a safe integer of at least `0`, a
+ *   request exists without an invoice or before it, `agreedResolutionOn` is before the request,
+ *   or a deadline would leave Temporal's range.
+ *
+ * @param dates The anchor date, and the invoice and request dates once they exist
+ * @param windows The three calendar-day windows, none defaulted, and an agreed resolution date
+ * @returns { invoiceDeadline, issuedByDeadline, disputeDeadline, requestedByDeadline, resolutionDeadline }, or null on invalid input
+ *
+ * @example billingTimeline({ anchorOn: "2026-03-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (no invoice yet: a forecast)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-30", requestedByDeadline: null, resolutionDeadline: null } (day 30 is the last day by the deadline)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-04-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: false, disputeDeadline: "2026-05-01", requestedByDeadline: null, resolutionDeadline: null } (day 31)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-19" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19", requestedByDeadline: true, resolutionDeadline: "2026-05-19" }
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-20" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30, agreedResolutionOn: "2026-06-01" }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19", requestedByDeadline: false, resolutionDeadline: "2026-06-01" } (an agreed date replaces the computed one)
+ * @example billingTimeline({ anchorOn: "2026-03-10", invoiceIssuedOn: "2026-04-05" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-04-09", issuedByDeadline: true, disputeDeadline: "2026-05-05", requestedByDeadline: null, resolutionDeadline: null } (a re-bill anchored on the invoice it received, not on the charge)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-05", requestReceivedOn: "2026-03-18" }, { issueDays: 14, disputeDays: 14, resolutionDays: 45 }) // { invoiceDeadline: "2026-03-15", issuedByDeadline: true, disputeDeadline: "2026-03-19", requestedByDeadline: true, resolutionDeadline: "2026-05-02" } (a service contract's own windows)
+ * @example billingTimeline({ anchorOn: "2028-01-30" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2028-02-29", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (calendar days across a leap day)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { disputeDays: 30, resolutionDays: 30 }) // null (issueDays has no default)
+ * @example billingTimeline({ anchorOn: "2026-03-01", requestReceivedOn: "2026-04-19" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // null (a request cannot precede the invoice it disputes)
+ */
+export function billingTimeline(dates, windows) {
+    try {
+        return layOutDeadlines(dates, windows);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}
+/** A window is a whole number of calendar days, zero or more. */
+function isWindow(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** An optional date is absent (`undefined`) or a valid ISO date; anything else is invalid. */
+function optionalDate(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return typeof value === "string" && isValidDate(value) ? value : null;
+}
+/** `date + days` on the ISO calendar, canonical. Throws `RangeError` past Temporal's range. */
+function plusDays(date, days) {
+    return Temporal.PlainDate.from(date).add({ days }).toString();
+}
+/** Whether `date` is on or before `deadline`. */
+function byDeadline(date, deadline) {
+    return (Temporal.PlainDate.compare(Temporal.PlainDate.from(date), Temporal.PlainDate.from(deadline)) <= 0);
+}
+/** The dates, each a valid ISO date, with no request before its invoice; `null` otherwise. */
+function readDates(dates) {
+    const { anchorOn } = dates;
+    if (typeof anchorOn !== "string" || !isValidDate(anchorOn)) {
+        return null;
+    }
+    const invoiceIssuedOn = optionalDate(dates.invoiceIssuedOn);
+    const requestReceivedOn = optionalDate(dates.requestReceivedOn);
+    if (invoiceIssuedOn === null || requestReceivedOn === null) {
+        return null;
+    }
+    // A request cannot precede the invoice it disputes.
+    if (requestReceivedOn !== undefined &&
+        (invoiceIssuedOn === undefined ||
+            !byDeadline(invoiceIssuedOn, requestReceivedOn))) {
+        return null;
+    }
+    return { anchorOn, invoiceIssuedOn, requestReceivedOn };
+}
+/** The three windows, each present and valid, and the agreed date if given; `null` otherwise. */
+function readWindows(windows) {
+    const { issueDays, disputeDays, resolutionDays } = windows;
+    if (!isWindow(issueDays) ||
+        !isWindow(disputeDays) ||
+        !isWindow(resolutionDays)) {
+        return null;
+    }
+    const agreedResolutionOn = optionalDate(windows.agreedResolutionOn);
+    if (agreedResolutionOn === null) {
+        return null;
+    }
+    return { issueDays, disputeDays, resolutionDays, agreedResolutionOn };
+}
+/** The agreed date when given, else `requestReceivedOn + resolutionDays`; `null` with no request. */
+function resolutionDeadline(requestReceivedOn, windows) {
+    if (requestReceivedOn === undefined) {
+        return null;
+    }
+    return windows.agreedResolutionOn === undefined
+        ? plusDays(requestReceivedOn, windows.resolutionDays)
+        : Temporal.PlainDate.from(windows.agreedResolutionOn).toString();
+}
+/** Whether `date` is on or before `deadline`; `null` until both exist. */
+function onOrBefore(date, deadline) {
+    return date === undefined || deadline === null
+        ? null
+        : byDeadline(date, deadline);
+}
+/** An agreed resolution date cannot precede the request it resolves. */
+function agreedAfterRequest(requestReceivedOn, agreedResolutionOn) {
+    return (requestReceivedOn === undefined ||
+        agreedResolutionOn === undefined ||
+        byDeadline(requestReceivedOn, agreedResolutionOn));
+}
+/** `billingTimeline` without the guard; every read of its arguments happens here. */
+function layOutDeadlines(dates, windows) {
+    if (!isObject(dates) || !isObject(windows)) {
+        return null;
+    }
+    const read = readDates(dates);
+    const counts = readWindows(windows);
+    if (read === null ||
+        counts === null ||
+        !agreedAfterRequest(read.requestReceivedOn, counts.agreedResolutionOn)) {
+        return null;
+    }
+    const { anchorOn, invoiceIssuedOn, requestReceivedOn } = read;
+    const invoiceDeadline = plusDays(anchorOn, counts.issueDays);
+    const disputeDeadline = invoiceIssuedOn === undefined
+        ? null
+        : plusDays(invoiceIssuedOn, counts.disputeDays);
+    return {
+        invoiceDeadline,
+        issuedByDeadline: onOrBefore(invoiceIssuedOn, invoiceDeadline),
+        disputeDeadline,
+        requestedByDeadline: onOrBefore(requestReceivedOn, disputeDeadline),
+        resolutionDeadline: resolutionDeadline(requestReceivedOn, counts),
+    };
+}

package/dist/intermodal/calculate/chargeableDays.d.ts

@@ -0,0 +1,100 @@
+import type { FreeTimeBasis, FreeTimeOptions } from "../../types/index.js";
+/** A band of chargeable-day ordinals and how many of the charged days fell in it. */
+export interface TierBand {
+    /** The first chargeable-day ordinal of the band, from 1. */
+    from: number;
+    /** The last ordinal of the band, or `null` for the open final band. */
+    to: number | null;
+    /** The number of charged days that fell in the band. */
+    days: number;
+}
+/** What `chargeableDays` returns: the day count an invoice bills, and the dates that back it. */
+export interface FreeTimeCharges {
+    /** The number of free days the dwell touched, at most the tariff's `freeDays`. */
+    freeDaysUsed: number;
+    /** The number of counted days on or after `expiresAt` the dwell touched. */
+    chargeableDays: number;
+    /** The instant free time ended, as a UTC instant, as `freeTimeExpiry` reports it. */
+    expiresAt: string;
+    /**
+     * The local dates charged, ascending. Carriers' day-numbered tariff grids and progressive tiers
+     * are applied to this list, and its entries are the dates an itemised invoice can list.
+     */
+    chargedDates: string[];
+    /** The charged days split into the `tiers` bands; one open band when no tiers were given. */
+    byTier: TierBand[];
+}
+/** `FreeTimeOptions` plus how charged days are counted, and the optional tier boundaries. */
+export type FreeTimeChargeOptions = FreeTimeOptions & {
+    /**
+     * How days after expiry are charged: `"calendar"` charges every local day, `"working"` only the
+     * working days of `calendar`. No default; see `chargeableDays`.
+     */
+    chargeBasis: FreeTimeBasis;
+    /**
+     * The last chargeable-day ordinal of each band, as strictly ascending positive whole numbers:
+     * `[5, 10]` is days 1–5, 6–10 and 11 onward. They are day bands, not rates. Every band is
+     * returned, an empty one with `days: 0`, and the last is always open.
+     *
+     * @defaultValue None. `byTier` is the single open band `{ from: 1, to: null }`.
+     */
+    tiers?: number[];
+};
+/**
+ * Count the days a container is charged for between the start of its clock and its exit,
+ * and list the dates behind the count.
+ *
+ * Lays out free time with the same walk as `freeTimeExpiry`, then counts the days on or after
+ * the expiry that the half-open dwell `[clockStart, clockEnd)` touched. The result is the
+ * auditable form of a demurrage or detention charge: `chargedDates` lists the days behind the
+ * count, which is the list a day-numbered tariff grid is applied to, and the dates an itemised
+ * invoice can list. No regulation or industry standard fixes how the days are counted; every term
+ * below is the tariff's. GMT computes days, never money: `byTier` says how many days fell in each
+ * band so the caller can apply its rates.
+ *
+ * - **Half-open at the exit.** A day is charged when it started before `clockEnd`, so a
+ *   gate-out at exactly `expiresAt` is `0` chargeable days and one nanosecond later is `1`. A
+ *   zero-length dwell touches the day it sits on, as `dwellTime` counts. On the calendar basis
+ *   with `firstDay: "eventDay"`, `freeDaysUsed + chargeableDays` equals `dwellTime(...).calendarDays`,
+ *   with one exception: a fall-back that re-enters the day before the event day (`America/Goose_Bay`,
+ *   00:01 on 7 November 2010 back into the 6th) is a date `dwellTime` counts as touched, and a
+ *   tariff never counts a date before the event day.
+ * - **The free-time terms are `freeTimeExpiry`'s**: `basis`, `timeZone`, `firstDay` and
+ *   `calendar` mean the same, and `firstDay` has no default.
+ * - **`chargeBasis` says how days after expiry are charged, and has no default.** Many
+ *   tariffs count free time and charges alike in calendar days. Where a tariff grants free time in
+ *   working days, the days after it are mostly charged as calendar days, weekends and holidays
+ *   included (Hapag-Lloyd's tables: "Rate per Calendar day"; ACL: "Once free time expires ...
+ *   charged on calendar days"): `basis: "working", chargeBasis: "calendar"`. Some tariffs charge
+ *   working days only, for free time and charges alike, so neither counts a day the gate is
+ *   closed or a holiday: both `"working"`.
+ *   Either `"working"` needs `calendar`. The two differ by every closed day after expiry, so
+ *   neither is assumed.
+ * - **`freeDays` may be `0`** for a tariff with no free time: `expiresAt` is the start of day one,
+ *   the first day counted on `basis` (under `"nextDay"`, the first after the event day), and days
+ *   before it are neither free nor charged.
+ * - Returns `null` when either instant is invalid, `clockEnd` is before `clockStart` (an
+ *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
+ *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, or the walk would pass
+ *   10,000 local days.
+ *
+ * @param clockStart ISO 8601 instant string of the event that starts the clock
+ * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
+ * @param freeDays whole number of free days the tariff allows, 0 or more
+ * @param options The tariff's counting terms for free time and for charged days, and the tier bands
+ * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
+ *
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] } (one second later is a charged day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-18T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (the other start-day convention: still free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [5, 10] }) // { freeDaysUsed: 3, chargeableDays: 12, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17", "2024-06-18", "2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24", "2024-06-25", "2024-06-26", "2024-06-27", "2024-06-28"], byTier: [{ from: 1, to: 5, days: 5 }, { from: 6, to: 10, days: 5 }, { from: 11, to: null, days: 2 }] }
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { freeDaysUsed: 3, chargeableDays: 6, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24"], byTier: [{ from: 1, to: null, days: 6 }] } (free days in working days, every calendar day after expiry charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { freeDaysUsed: 3, chargeableDays: 3, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-20", "2024-06-21", "2024-06-24"], byTier: [{ from: 1, to: null, days: 3 }] } (working days throughout: closed days after expiry are not charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-15T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 2, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (out on the second free day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-16T15:00:00Z", 0, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 0, chargeableDays: 3, expiresAt: "2024-06-14T04:00:00Z", chargedDates: ["2024-06-14", "2024-06-15", "2024-06-16"], byTier: [{ from: 1, to: null, days: 3 }] } (no free time: every day is charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [10, 5] }) // null (tiers must ascend)
+ * @example chargeableDays("2024-06-17T04:00:01Z", "2024-06-14T19:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (exit before the clock started)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (chargeBasis has no default)
+ */
+export declare function chargeableDays(clockStart: string, clockEnd: string, freeDays: number, options: FreeTimeChargeOptions): FreeTimeCharges | null;

package/dist/intermodal/calculate/chargeableDays.js

@@ -0,0 +1,96 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { bandsByTier, instantFrom, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+/**
+ * Count the days a container is charged for between the start of its clock and its exit,
+ * and list the dates behind the count.
+ *
+ * Lays out free time with the same walk as `freeTimeExpiry`, then counts the days on or after
+ * the expiry that the half-open dwell `[clockStart, clockEnd)` touched. The result is the
+ * auditable form of a demurrage or detention charge: `chargedDates` lists the days behind the
+ * count, which is the list a day-numbered tariff grid is applied to, and the dates an itemised
+ * invoice can list. No regulation or industry standard fixes how the days are counted; every term
+ * below is the tariff's. GMT computes days, never money: `byTier` says how many days fell in each
+ * band so the caller can apply its rates.
+ *
+ * - **Half-open at the exit.** A day is charged when it started before `clockEnd`, so a
+ *   gate-out at exactly `expiresAt` is `0` chargeable days and one nanosecond later is `1`. A
+ *   zero-length dwell touches the day it sits on, as `dwellTime` counts. On the calendar basis
+ *   with `firstDay: "eventDay"`, `freeDaysUsed + chargeableDays` equals `dwellTime(...).calendarDays`,
+ *   with one exception: a fall-back that re-enters the day before the event day (`America/Goose_Bay`,
+ *   00:01 on 7 November 2010 back into the 6th) is a date `dwellTime` counts as touched, and a
+ *   tariff never counts a date before the event day.
+ * - **The free-time terms are `freeTimeExpiry`'s**: `basis`, `timeZone`, `firstDay` and
+ *   `calendar` mean the same, and `firstDay` has no default.
+ * - **`chargeBasis` says how days after expiry are charged, and has no default.** Many
+ *   tariffs count free time and charges alike in calendar days. Where a tariff grants free time in
+ *   working days, the days after it are mostly charged as calendar days, weekends and holidays
+ *   included (Hapag-Lloyd's tables: "Rate per Calendar day"; ACL: "Once free time expires ...
+ *   charged on calendar days"): `basis: "working", chargeBasis: "calendar"`. Some tariffs charge
+ *   working days only, for free time and charges alike, so neither counts a day the gate is
+ *   closed or a holiday: both `"working"`.
+ *   Either `"working"` needs `calendar`. The two differ by every closed day after expiry, so
+ *   neither is assumed.
+ * - **`freeDays` may be `0`** for a tariff with no free time: `expiresAt` is the start of day one,
+ *   the first day counted on `basis` (under `"nextDay"`, the first after the event day), and days
+ *   before it are neither free nor charged.
+ * - Returns `null` when either instant is invalid, `clockEnd` is before `clockStart` (an
+ *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
+ *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, or the walk would pass
+ *   10,000 local days.
+ *
+ * @param clockStart ISO 8601 instant string of the event that starts the clock
+ * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
+ * @param freeDays whole number of free days the tariff allows, 0 or more
+ * @param options The tariff's counting terms for free time and for charged days, and the tier bands
+ * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
+ *
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] } (one second later is a charged day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-18T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (the other start-day convention: still free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [5, 10] }) // { freeDaysUsed: 3, chargeableDays: 12, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17", "2024-06-18", "2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24", "2024-06-25", "2024-06-26", "2024-06-27", "2024-06-28"], byTier: [{ from: 1, to: 5, days: 5 }, { from: 6, to: 10, days: 5 }, { from: 11, to: null, days: 2 }] }
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { freeDaysUsed: 3, chargeableDays: 6, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24"], byTier: [{ from: 1, to: null, days: 6 }] } (free days in working days, every calendar day after expiry charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { freeDaysUsed: 3, chargeableDays: 3, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-20", "2024-06-21", "2024-06-24"], byTier: [{ from: 1, to: null, days: 3 }] } (working days throughout: closed days after expiry are not charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-15T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 2, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (out on the second free day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-16T15:00:00Z", 0, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 0, chargeableDays: 3, expiresAt: "2024-06-14T04:00:00Z", chargedDates: ["2024-06-14", "2024-06-15", "2024-06-16"], byTier: [{ from: 1, to: null, days: 3 }] } (no free time: every day is charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [10, 5] }) // null (tiers must ascend)
+ * @example chargeableDays("2024-06-17T04:00:01Z", "2024-06-14T19:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (exit before the clock started)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (chargeBasis has no default)
+ */
+export function chargeableDays(clockStart, clockEnd, freeDays, options) {
+    try {
+        const terms = parseFreeTimeTerms(options, true);
+        const allowed = parseFreeDays(freeDays, 0);
+        // Read after the terms, so a non-object `options` is never read from.
+        const tiers = terms === null ? null : parseTiers(options.tiers);
+        if (!isValidInstant(clockStart) ||
+            !isValidInstant(clockEnd) ||
+            terms === null ||
+            allowed === null ||
+            tiers === null) {
+            return null;
+        }
+        const start = instantFrom(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const end = instantFrom(clockEnd).toZonedDateTimeISO(terms.timeZone);
+        if (Temporal.ZonedDateTime.compare(start, end) > 0) {
+            return null;
+        }
+        const ledger = walkFreeTime(start, allowed, terms, end);
+        if (ledger === null) {
+            return null;
+        }
+        return {
+            freeDaysUsed: ledger.used,
+            chargeableDays: ledger.charged.length,
+            expiresAt: ledger.expiresAt.toInstant().toString(),
+            chargedDates: ledger.charged.map((day) => day.date),
+            byTier: bandsByTier(tiers, ledger.charged.length),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}