@northguild/gmt 1.16.0 → 1.17.0

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ export * from "./duration-string-options.js";
 export * from "./duration-unit.js";
 export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
+export * from "./free-time-options.js";
 export * from "./interval.js";
 export * from "./now-unit.js";
 export * from "./offset.js";

package/dist/types/index.js

@@ -14,6 +14,7 @@ export * from "./duration-string-options.js";
 export * from "./duration-unit.js";
 export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
+export * from "./free-time-options.js";
 export * from "./interval.js";
 export * from "./now-unit.js";
 export * from "./offset.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northguild/gmt",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Temporal-based date and time utilities with timezone support and polyfill integration",
   "keywords": [
     "date",
@@ -85,6 +85,12 @@
       "instant/convert": [
         "./dist/instant/convert/index.d.ts"
       ],
+      "intermodal": [
+        "./dist/intermodal/index.d.ts"
+      ],
+      "intermodal/calculate": [
+        "./dist/intermodal/calculate/index.d.ts"
+      ],
       "interval": [
         "./dist/interval/index.d.ts"
       ],
@@ -163,6 +169,15 @@
       "span/validate": [
         "./dist/span/validate/index.d.ts"
       ],
+      "transport": [
+        "./dist/transport/index.d.ts"
+      ],
+      "transport/calculate": [
+        "./dist/transport/calculate/index.d.ts"
+      ],
+      "transport/convert": [
+        "./dist/transport/convert/index.d.ts"
+      ],
       "types": [
         "./dist/types/index.d.ts"
       ],
@@ -315,6 +330,14 @@
       "types": "./dist/instant/convert/index.d.ts",
       "default": "./dist/instant/convert/index.js"
     },
+    "./intermodal": {
+      "types": "./dist/intermodal/index.d.ts",
+      "default": "./dist/intermodal/index.js"
+    },
+    "./intermodal/calculate": {
+      "types": "./dist/intermodal/calculate/index.d.ts",
+      "default": "./dist/intermodal/calculate/index.js"
+    },
     "./interval": {
       "types": "./dist/interval/index.d.ts",
       "default": "./dist/interval/index.js"
@@ -419,6 +442,18 @@
       "types": "./dist/span/validate/index.d.ts",
       "default": "./dist/span/validate/index.js"
     },
+    "./transport": {
+      "types": "./dist/transport/index.d.ts",
+      "default": "./dist/transport/index.js"
+    },
+    "./transport/calculate": {
+      "types": "./dist/transport/calculate/index.d.ts",
+      "default": "./dist/transport/calculate/index.js"
+    },
+    "./transport/convert": {
+      "types": "./dist/transport/convert/index.d.ts",
+      "default": "./dist/transport/convert/index.js"
+    },
     "./types": {
       "types": "./dist/types/index.d.ts",
       "default": "./dist/types/index.js"

package/skills/gmt-arithmetic/SKILL.md

@@ -32,7 +32,7 @@ sources:
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.16.0'
+  library_version: '1.17.0'
 ---
 
 # GMT Arithmetic

package/skills/gmt-basics/SKILL.md

@@ -24,7 +24,7 @@ sources:
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.16.0'
+  library_version: '1.17.0'
 ---
 
 # GMT Basics

package/skills/gmt-integration/SKILL.md

@@ -17,7 +17,7 @@ sources:
 metadata:
   type: composition
   library: '@northguild/gmt'
-  library_version: '1.16.0'
+  library_version: '1.17.0'
 ---
 
 # GMT Integration

package/skills/gmt-timezone/SKILL.md

@@ -2,16 +2,20 @@
 name: gmt-timezone
 description: >
   Timezone-aware operations — get zoned now, format zoned datetimes/ranges,
-  convert between plain↔zoned↔UTC↔Unix, DST disambiguation control on
-  construction and arithmetic, the instant-plus-offset pair, classifying a
-  zoneless wall time before resolving it, real zone unit boundaries
-  (startOfZoned/endOfZoned/startOfUnix/endOfUnix, never after the input), hours
-  in a local day, and flooring or bucketing instants on local calendar
-  boundaries (floorToZone/bucketRange) instead of roundZoned, calendar-annotated
-  zoned strings, and zoned values exact at the range limits (Australia/Sydney at
-  the maximum, Etc/GMT+12 at the minimum). Reads the installed package README.md
-  and source JSDoc for API details; this skill is a routing pointer, not an API
-  dump.
+  convert between plain↔zoned↔UTC↔Unix, DST disambiguation on construction and
+  arithmetic, the instant-plus-offset pair, classifying a zoneless wall time
+  before resolving it, real zone unit boundaries
+  (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a local day,
+  flooring or bucketing on local boundaries (floorToZone/bucketRange),
+  calendar-annotated zoned strings, zoned values at the range limits, the
+  transport legs transitTime, etaAtZone and dwellTime (local calendar days
+  crossed), intermodal free time — freeTimeExpiry (the free window and its
+  half-open expiry), chargeableDays (the dates charged, with tier bands),
+  demurrageClock (which events a demurrage, detention, storage or combined clock
+  runs between) — and billingTimeline (invoice, dispute and resolution
+  deadlines, windows as caller parameters). Reads the installed package
+  README.md and source JSDoc for API details; this skill is a routing pointer,
+  not an API dump.
 sources:
   - 'northguild/gmt:README.md'
   - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
@@ -30,10 +34,13 @@ sources:
   - 'northguild/gmt:packages/gmt/src/instant/convert/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/calculate/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/transport/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/transport/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/intermodal/calculate/index.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.16.0'
+  library_version: '1.17.0'
 ---
 
 # GMT Timezone
@@ -53,6 +60,12 @@ converting between time zones, or doing arithmetic that must respect DST.
 - The user needs the start or end of a local hour, day, week, month or quarter.
 - The user is grouping or aggregating UTC timestamps by local day, hour, week or
   month — an observability rollup, a chargeable-days count.
+- The user is adding a leg's transit time to a departure, showing an arrival in
+  the zone where it lands, or counting how long cargo, a vessel or a patient sat
+  somewhere in local calendar days.
+- The user is working out when a container's free time ends, how many days of
+  demurrage or detention are chargeable and for which dates, or which events a
+  charge's clock runs between.
 
 ## Core rules
 
@@ -164,7 +177,57 @@ converting between time zones, or doing arithmetic that must respect DST.
     `formatZonedRange` and `formatZonedToParts` return `""`/`[]` for a
     `timeZone` option. To show an instant in another zone, use
     `formatUtc(convertZonedToUtc(value), locale, { timeZone })`.
-15. **Read the README.** This skill is a routing pointer. For the full DST
+15. **Transport legs are exact time; dwell is counted in local days.**
+    `transitTime(departure, duration)` adds hours, minutes and seconds as
+    elapsed time (`P1D` is 24 exact hours) in the departure's own zone, so a leg
+    across a DST transition lands at the wall time the vehicle really arrives;
+    years, months and weeks return `""`, and a bracketed zone that contradicts
+    its offset is rejected rather than reinterpreted. `etaAtZone(instant, zone)`
+    renders a moment in the zone the caller names — no disambiguation arises,
+    the offset in the result tells the two passes of a fall-back hour apart, and
+    GMT never resolves a port, airport or station code to a zone.
+    `dwellTime(entry, exit, targetZone?)` returns `{ duration, enter, exit,
+    calendarDays }`; `calendarDays` is the number of distinct local dates the
+    half-open `[entry, exit)` touches, walked across the zone's real transitions
+    (a skipped date is not counted, a re-entered one only once), and is the
+    library's one "local days crossed" count.
+    Bare instants with no `targetZone` return `null`: an offset is not a place.
+16. **Free time is counted in the terminal's local days; the start day and the
+    basis are tariff terms, never defaults.**
+    `freeTimeExpiry(clockStart, freeDays, { basis, timeZone, firstDay, calendar? })`
+    returns `{ freeTimeStart, lastFreeDay, expiresAt }`: local dates in
+    `timeZone`, and the first instant of the day after the last free day.
+    `firstDay` (`"eventDay"` | `"nextDay"`) has no default because the two
+    differ by a day of charges; `basis: "working"` needs a `BusinessCalendar`
+    and returns `null` without one. `chargeableDays(clockStart, clockEnd,
+    freeDays, options)` also needs `chargeBasis` (no default): many tariffs
+    count both in calendar days; where a tariff grants free time in working
+    days the days after it are mostly charged as calendar days, and some
+    tariffs charge working days only. It counts the days on or after
+    `expiresAt` the half-open dwell touched, lists them as `chargedDates`, and
+    splits them into `tiers` bands; `freeDays: 0` is allowed there.
+    `demurrageClock(events, scope, { direction, startEvent? })` selects the
+    events per leg: import demurrage and storage run discharge (or
+    availability) to gate-out, detention gate-out to empty return; export
+    demurrage gate-in to loaded, detention empty release to gate-in; `combined`
+    runs both as one period. No standard fixes how these days are counted;
+    every term is the tariff's.
+17. **Billing deadlines are dates counted from an anchor, and every window is
+    the caller's.** `billingTimeline({ anchorOn, invoiceIssuedOn?,
+    requestReceivedOn? }, { issueDays, disputeDays, resolutionDays,
+    agreedResolutionOn? })` returns `{ invoiceDeadline, issuedByDeadline,
+    disputeDeadline, requestedByDeadline, resolutionDeadline }`. Day zero is
+    the anchor and each deadline is `date + days` on the ISO calendar; a date
+    is by the deadline when it is on or before it. No window has a default (a
+    missing one returns `null`); fields whose input does not exist yet are
+    `null`, so an anchor alone is a forecast. The anchor is whatever date the
+    caller counts from: the last charged date
+    (`chargedDates.at(-1)`), or for a re-bill the issuance date of the invoice
+    received. Reduce an instant to the billing party's local date first with
+    `convertUtcToPlainDate(instant, { timeZone })`. A request before its
+    invoice, or an agreed date before the request, returns `null`. GMT
+    computes dates, not liability.
+18. **Read the README.** This skill is a routing pointer. For the full DST
     disambiguation walkthrough, code examples, and locale ICU notes, read the
     installed package's `README.md` and the source JSDoc.
 
@@ -190,6 +253,10 @@ converting between time zones, or doing arithmetic that must respect DST.
 - **Local-time resolution**: `classifyLocal`, `resolveLocal`
 - **Zone-aware buckets**: `floorToZone`, `bucketRange`,
   `isValidZoneBucketUnit`
+- **Transport legs and dwell**: `transitTime`, `etaAtZone`, `dwellTime`
+- **Free time and demurrage**: `freeTimeExpiry`, `chargeableDays`,
+  `demurrageClock`
+- **Billing deadlines**: `billingTimeline`
 
 ## References