@softure-ai/core 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,45 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`core@x.y.z`).
 
+## 0.2.2
+
+- `requestJson` writes (#635): `method` (`"GET"` by default, `"POST" | "PUT" | "PATCH" | "DELETE"`), `body` sent as
+  JSON with `Content-Type: application/json` unless the caller sets its own, and `idempotencyKey` sent as
+  `Idempotency-Key`. A write answered with an empty body (204, or 200 with nothing) returns `ok(undefined)`, so a
+  write with a schema returns `Ok<T | undefined>`; a non-empty answer still goes through the schema. A GET takes no
+  body, and its empty answer stays `core.http_unexpected_answer`. New types `HttpJsonMethod`, `HttpJsonWriteMethod`,
+  `RequestJsonReadOptions`, `RequestJsonWriteOptions`.
+- New code `core.http_conflict` for 409 and 412 (a stale version or sha), for every method, with English copy in
+  `coreMessages` (`errors.http_conflict`).
+  - Migrate: a caller that switched on `core.http_unexpected_answer` to spot a 409 or 412 switches on
+    `core.http_conflict` instead; an exhaustive `switch` over `HttpJsonFailureCode` gets the new case. An app with
+    its own write helper replaces it with `requestJson({ method, body })` and handles `ok(undefined)` for 204s.
+
+## 0.2.1
+
+- New (#599): calendar periods and local wall-clock date-times next to calendar days.
+  - `CalendarPeriod` (`{ from, to }`, both ends included) and `calendarPeriodSchema`, which refuses `to` before
+    `from` on the path `["to"]` with `must not come before from`.
+  - `isDayInPeriod(day, period)`, `doPeriodsOverlap(a, b)` (one shared day overlaps, adjacent periods do not),
+    `countPeriodDays(period)` (1 for a single day).
+  - `LocalDateTime`, a branded `YYYY-MM-DDTHH:mm` string with no zone, made by `localDateTimeSchema` or
+    `isLocalDateTime(value)`; its day part goes through `isCalendarDay`, so `2026-02-30T10:00` is refused.
+    `getLocalDay(value)` returns the day.
+  - Migrate: an app that defined its own period or local date-time drops its schema, type and helpers and imports
+    these. Check two differences: overlap counts a single shared day, and a period's error sits on `to`. An app
+    that typed a local date-time as `string` passes values through `localDateTimeSchema` (or `isLocalDateTime`)
+    before using them as `LocalDateTime`.
+- `requestJson({ url, fetch?, headers?, timeoutMs?, schema? })`: a JSON GET for third-party APIs (#598). A timeout
+  (default 10 000 ms), no redirect followed, `Accept: application/json` by default, and every failure returned as an
+  `HttpJsonFailure` with a code and the status, never the URL or the error text: `core.http_unreachable`,
+  `core.http_refused` (3xx, 401, 403), `core.http_rate_limited` (429), `core.http_unavailable` (5xx),
+  `core.http_unexpected_answer` (other status, not JSON, fails the schema). The body is `unknown` without a zod
+  `schema` and the schema's output with one. `toQueryString(record)` builds a query string, skipping `null` and
+  `undefined`. English copy for the five codes in `coreMessages` (`errors.http_*`).
+  - Migrate (optional): an app with its own request helper replaces it with `requestJson`, passes the same headers
+    and timeout, moves its response check into `schema`, and maps the five codes to its own codes and messages
+    (`result.error`, `result.status`). The helper's own timeout, redirect and error-scrubbing code can go.
+
 ## 0.2.0
 
 - **Breaking (#446):** English is the only built-in language.

package/README.md

@@ -277,7 +277,7 @@ None. Tokens, slots and styles live in `@softure-ai/ui`.
   locale and reused. `locale` is any BCP 47 tag; a category the forms leave out falls back to `other`.
 - `getMessage(dictionary, "errors.unexpected")` reads a dotted path.
 - Core's own keys (`coreMessages`): `errors.database_failed`, `errors.unexpected`, the copy for
-  the `core.database_failed` and `core.unexpected` codes.
+  the `core.database_failed` and `core.unexpected` codes, and `errors.http_*` for `requestJson`'s codes.
 
 **Errors as values.** `Result<T, E>` is `{ ok: true, value } | { ok: false, error }`, built with
 `ok(value)` / `ok()` and `err("module.code")`. Codes are namespaced by module id
@@ -305,6 +305,65 @@ if (plan.endedAt !== null) throw new PublicError("This plan has ended; pick anot
 `isPublicError` recognises one from another copy of core too (a registry symbol, not `instanceof`).
 `safeError` itself still answers `core.unexpected` for it, since callers switch on its two codes.
 
+**External JSON APIs.** `requestJson({ url, method?, body?, idempotencyKey?, fetch?, headers?, timeoutMs?, schema? })`
+calls a third-party JSON API (a GET by default) and returns `Ok<value>` or an `HttpJsonFailure` (`{ ok: false, error, status }`). It sets the details a hand-written
+helper tends to miss:
+
+- a timeout, `AbortSignal.timeout(timeoutMs)` (default 10 000 ms), body included;
+- `redirect: "manual"`, so a key in a header or the URL never follows a redirect to another host;
+- `Accept: application/json` unless `headers` sets its own;
+- every failure is a code plus the status (`null` when no response arrived), never the URL, a header or the caught
+  error's text (some APIs put the key in the URL, and a fetch error can quote it).
+
+| Code | When |
+|---|---|
+| `core.http_unreachable` | network error, timeout, a body that breaks off |
+| `core.http_refused` | 3xx, an opaque redirect, 401, 403 |
+| `core.http_conflict` | 409, 412 (a stale version or sha: re-read, then retry) |
+| `core.http_rate_limited` | 429 |
+| `core.http_unavailable` | 5xx |
+| `core.http_unexpected_answer` | any other non-2xx status, a body that is not JSON or fails the schema |
+
+Without `schema` the value is `unknown`, to be narrowed at the boundary; with a zod schema it is the schema's
+output. `fetch` defaults to the global one; tests pass a fake. `toQueryString(record)` builds the query part
+(without `?`) from strings, numbers and booleans, leaving out `null` and `undefined`:
+
+```ts
+import { err, requestJson, toQueryString } from "@softure-ai/core";
+import { z } from "zod";
+
+const rateSchema = z.object({ rates: z.array(z.object({ mid: z.number() })) });
+
+const result = await requestJson({
+  url: `https://api.example.com/rates?${toQueryString({ currency, date, page: undefined })}`,
+  headers: { Authorization: `Bearer ${env.RATES_API_KEY}` },
+  timeoutMs: 5_000,
+  schema: rateSchema,
+});
+if (!result.ok) {
+  return err(result.error === "core.http_rate_limited" ? "rates.busy" : "rates.unavailable"); // the app's own codes
+}
+```
+
+Writes take `method: "POST" | "PUT" | "PATCH" | "DELETE"` and a `body`, sent as JSON with
+`Content-Type: application/json` unless `headers` sets its own; a value JSON cannot represent (a cycle, a BigInt)
+throws before anything is sent. `idempotencyKey` is sent as `Idempotency-Key`. A write answered with an empty body
+(a 204, or a 200 with nothing) is `ok(undefined)`, schema or not, so a write's value is `T | undefined`; a non-empty
+answer still goes through the schema. A GET carries no body, and an empty answer to it stays an unexpected answer.
+
+```ts
+const saved = await requestJson({
+  url: `https://api.example.com/tasks/${task.id}`,
+  method: "PUT",
+  body: { title: task.title, version: task.version },
+  headers: { Authorization: `Bearer ${env.TASKS_API_KEY}` },
+  schema: z.object({ version: z.number() }),
+});
+if (!saved.ok && saved.error === "core.http_conflict") {
+  // someone else changed the task: read it again and retry the write
+}
+```
+
 **Time.** Server code receives a `Clock` (`ModuleContext.clock`) instead of calling `new Date()`.
 `systemClock` is the real one; `createTestClock(start)` has `advance(ms)` and `set(date)`.
 A whole test run can also move to another day without code changes: `TEST_TODAY=YYYY-MM-DD` with the
@@ -335,6 +394,35 @@ or a fractional count.
 
 `calendarDaySchema` is `isCalendarDay` as a zod schema, for tool and form inputs that take a day.
 
+**Calendar periods.** A `CalendarPeriod` is `{ from, to }`, two calendar days with **both ends included**:
+one day is `{ from: d, to: d }`. `calendarPeriodSchema` parses one from input and refuses `to` before `from`
+with the message `must not come before from` on the path `["to"]`, so a form shows it next to the end field;
+a malformed day gets only its own `calendarDaySchema` issue.
+
+| Function | Semantics |
+| --- | --- |
+| `isDayInPeriod(day, period)` | `day` lies in `period`, either end included. |
+| `doPeriodsOverlap(a, b)` | The periods share at least one day: `12-01..12-31` and `12-31..01-05` overlap, `12-01..12-31` and `01-01..01-31` do not. |
+| `countPeriodDays(period)` | Days in the period, both ends counted: 1 for a single day, 31 for December. |
+
+They throw a `RangeError` for a malformed day or a period that ends before it starts.
+
+```ts
+const input = z.object({ stay: calendarPeriodSchema }).parse(body);
+countPeriodDays(input.stay); // 7
+```
+
+**Local date-times.** A `LocalDateTime` is `YYYY-MM-DDTHH:mm` with no time zone: a time that is local at a
+place, such as a departure or a booking slot, read the same whatever the server's zone. The day part must be a
+real calendar day (`2026-02-30T10:00` is refused), the hour 00-23 and the minute 00-59; no seconds, no offset.
+It is a branded string, so only `localDateTimeSchema` (input) or `isLocalDateTime(value)` (a guard) make one,
+and it sorts as text in time order. `getLocalDay(value)` returns its `YYYY-MM-DD` day.
+
+```ts
+const departure = localDateTimeSchema.parse("2026-12-01T06:45"); // LocalDateTime
+isDayInPeriod(getLocalDay(departure), trip); // true when the departure falls on a day of the trip
+```
+
 **Display.** One way to show days, money and percentages in every module and app, in `config.locale`:
 
 ```ts

package/dist/calendar-period.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/** Calendar days from `from` to `to`, both included; `to` never comes before `from`. */
+export interface CalendarPeriod {
+    readonly from: string;
+    readonly to: string;
+}
+/** A `CalendarPeriod` in tool and form input: two calendar days, `to` refused (path `["to"]`) when it comes first. */
+export declare const calendarPeriodSchema: z.ZodObject<{
+    from: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    to: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+}, z.core.$strip>;
+/** Whether `day` lies in `period`, both ends included. Throws a `RangeError` for a malformed day or period. */
+export declare function isDayInPeriod(day: string, period: CalendarPeriod): boolean;
+/** Whether `a` and `b` share at least one day; adjacent periods do not. Throws a `RangeError` for a malformed period. */
+export declare function doPeriodsOverlap(a: CalendarPeriod, b: CalendarPeriod): boolean;
+/** The number of days in `period`, both ends included: 1 for a single day. Throws a `RangeError` for a malformed period. */
+export declare function countPeriodDays(period: CalendarPeriod): number;
+//# sourceMappingURL=calendar-period.d.ts.map

package/dist/calendar-period.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar-period.d.ts","sourceRoot":"","sources":["../src/calendar-period.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,sHAAsH;AACtH,eAAO,MAAM,oBAAoB;;;iBAO7B,CAAC;AAEL,+GAA+G;AAC/G,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAK1E;AAED,yHAAyH;AACzH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,GAAG,OAAO,CAK9E;AAED,4HAA4H;AAC5H,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAG9D"}

package/dist/calendar-period.js

@@ -0,0 +1,44 @@
+// A calendar period: two calendar days (`YYYY-MM-DD`) with both ends included, so one day is
+// `{ from: d, to: d }`. Zero-padded days sort as text in calendar order, so comparisons work on the strings.
+import { z } from "zod";
+import { calendarDaysBetween, calendarDaySchema, isCalendarDay } from "./calendar-day.js";
+/** A `CalendarPeriod` in tool and form input: two calendar days, `to` refused (path `["to"]`) when it comes first. */
+export const calendarPeriodSchema = z
+    .object({ from: calendarDaySchema, to: calendarDaySchema })
+    // A malformed end already has its own issue, and zod still runs the refinement then: skip it, so the
+    // order is checked only between two real days.
+    .refine((period) => !isCalendarDay(period.from) || !isCalendarDay(period.to) || period.from <= period.to, {
+    message: "must not come before from",
+    path: ["to"],
+});
+/** Whether `day` lies in `period`, both ends included. Throws a `RangeError` for a malformed day or period. */
+export function isDayInPeriod(day, period) {
+    const operation = "isDayInPeriod";
+    assertCalendarDay(operation, day);
+    assertPeriod(operation, period);
+    return period.from <= day && day <= period.to;
+}
+/** Whether `a` and `b` share at least one day; adjacent periods do not. Throws a `RangeError` for a malformed period. */
+export function doPeriodsOverlap(a, b) {
+    const operation = "doPeriodsOverlap";
+    assertPeriod(operation, a);
+    assertPeriod(operation, b);
+    return a.from <= b.to && b.from <= a.to;
+}
+/** The number of days in `period`, both ends included: 1 for a single day. Throws a `RangeError` for a malformed period. */
+export function countPeriodDays(period) {
+    assertPeriod("countPeriodDays", period);
+    return calendarDaysBetween(period.from, period.to) + 1;
+}
+function assertPeriod(operation, period) {
+    assertCalendarDay(operation, period.from);
+    assertCalendarDay(operation, period.to);
+    if (period.to < period.from) {
+        throw new RangeError(`${operation}: the period ends ("${period.to}") before it starts ("${period.from}")`);
+    }
+}
+function assertCalendarDay(operation, day) {
+    if (!isCalendarDay(day))
+        throw new RangeError(`${operation}: "${String(day)}" is not a YYYY-MM-DD calendar day`);
+}
+//# sourceMappingURL=calendar-period.js.map

package/dist/calendar-period.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar-period.js","sourceRoot":"","sources":["../src/calendar-period.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,6GAA6G;AAC7G,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAQ1F,sHAAsH;AACtH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,EAAE,iBAAiB,EAAE,CAAC;IAC3D,qGAAqG;IACrG,+CAA+C;KAC9C,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,EAAE,EAAE;IACxG,OAAO,EAAE,2BAA2B;IACpC,IAAI,EAAE,CAAC,IAAI,CAAC;CACb,CAAC,CAAC;AAEL,+GAA+G;AAC/G,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,MAAsB;IAC/D,MAAM,SAAS,GAAG,eAAe,CAAC;IAClC,iBAAiB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAClC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC,IAAI,IAAI,GAAG,IAAI,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;AAChD,CAAC;AAED,yHAAyH;AACzH,MAAM,UAAU,gBAAgB,CAAC,CAAiB,EAAE,CAAiB;IACnE,MAAM,SAAS,GAAG,kBAAkB,CAAC;IACrC,YAAY,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3B,YAAY,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3B,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC;AAC1C,CAAC;AAED,4HAA4H;AAC5H,MAAM,UAAU,eAAe,CAAC,MAAsB;IACpD,YAAY,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,mBAAmB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,YAAY,CAAC,SAAiB,EAAE,MAAsB;IAC7D,iBAAiB,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1C,iBAAiB,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,UAAU,CAAC,GAAG,SAAS,uBAAuB,MAAM,CAAC,EAAE,yBAAyB,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;IAC7G,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAiB,EAAE,GAAW;IACvD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,SAAS,MAAM,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;AACnH,CAAC"}

package/dist/http-json.d.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+import { 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_conflict" | "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 HttpJsonWriteMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+export type HttpJsonMethod = "GET" | HttpJsonWriteMethod;
+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;
+}
+/** A GET: no body, no idempotency key (a GET is idempotent already). */
+export interface RequestJsonReadOptions extends RequestJsonOptions {
+    readonly method?: "GET";
+    readonly body?: never;
+    readonly idempotencyKey?: never;
+}
+/** A write: the body is sent as JSON, and an answer with no body is `ok(undefined)`. */
+export interface RequestJsonWriteOptions extends RequestJsonOptions {
+    readonly method: HttpJsonWriteMethod;
+    /** Serialised with `JSON.stringify`; `undefined` sends no body. A value JSON cannot represent throws. */
+    readonly body?: unknown;
+    /** Sent as `Idempotency-Key`, for providers that deduplicate retried writes by it. */
+    readonly idempotencyKey?: string;
+}
+/**
+ * Call `url` (a GET unless `method` says otherwise) 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. A write answered with an empty body (a 204) is
+ * `ok(undefined)`, schema or not. 3xx, 401 and 403 are refused, 409 and 412 a conflict, 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 declare function requestJson<S extends z.ZodType>(options: RequestJsonSchemaOptions<S> & RequestJsonReadOptions): Promise<Ok<z.output<S>> | HttpJsonFailure>;
+export declare function requestJson<S extends z.ZodType>(options: RequestJsonSchemaOptions<S> & RequestJsonWriteOptions): Promise<Ok<z.output<S> | undefined> | HttpJsonFailure>;
+export declare function requestJson(options: RequestJsonReadOptions | RequestJsonWriteOptions): Promise<Ok<unknown> | HttpJsonFailure>;
+/**
+ * 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 declare function toQueryString(params: Readonly<Record<string, string | number | boolean | null | undefined>>): string;
+//# sourceMappingURL=http-json.d.ts.map

package/dist/http-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-json.d.ts","sourceRoot":"","sources":["../src/http-json.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAW,KAAK,GAAG,EAAE,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,MAAM,mBAAmB,GAC3B,uBAAuB,GACvB,mBAAmB,GACnB,wBAAwB,GACxB,uBAAuB,GACvB,oBAAoB,GACpB,6BAA6B,CAAC;AAElC,4GAA4G;AAC5G,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC,mBAAmB,CAAC,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE5F,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,mBAAmB,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE1F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAE,SAAQ,kBAAkB;IACvF,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB;AAED,wEAAwE;AACxE,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC;CACjC;AAED,wFAAwF;AACxF,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,yGAAyG;IACzG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC7C,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,sBAAsB,GAC5D,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC;AAC9C,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC7C,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,uBAAuB,GAC7D,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,eAAe,CAAC,CAAC;AAC1D,wBAAgB,WAAW,CACzB,OAAO,EAAE,sBAAsB,GAAG,uBAAuB,GACxD,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC;AAsE1C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,GAAG,MAAM,CAQpH"}

package/dist/http-json.js

@@ -0,0 +1,101 @@
+import { err, ok } from "./result.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+export async function requestJson(options) {
+    const fetchFunction = options.fetch ?? globalThis.fetch;
+    const method = options.method ?? "GET";
+    const isWrite = method !== "GET";
+    // Outside the try on purpose: a body JSON cannot represent is the caller's bug, not an unreachable service.
+    const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+    let 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");
+        }
+        if (body !== undefined && !headers.has("content-type")) {
+            headers.set("content-type", "application/json");
+        }
+        if (options.idempotencyKey !== undefined) {
+            headers.set("idempotency-key", options.idempotencyKey);
+        }
+        response = await fetchFunction(options.url, {
+            method,
+            headers,
+            body,
+            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;
+    try {
+        text = await response.text();
+    }
+    catch {
+        // The body broke off, usually the timeout firing mid-body.
+        return httpFailure("core.http_unreachable", response.status);
+    }
+    if (isWrite && text.trim() === "") {
+        // A 204, or a write that answers 200 with nothing: the write succeeded and there is nothing to read.
+        return ok(undefined);
+    }
+    let answer;
+    try {
+        answer = JSON.parse(text);
+    }
+    catch {
+        return httpFailure("core.http_unexpected_answer", response.status);
+    }
+    if (options.schema === undefined) {
+        return ok(answer);
+    }
+    // The schema's issues can quote the body's values, so only the code leaves.
+    const parsed = options.schema.safeParse(answer);
+    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) {
+    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) {
+    const { status } = response;
+    if (response.type === "opaqueredirect" || (status >= 300 && status < 400) || status === 401 || status === 403) {
+        return httpFailure("core.http_refused", status);
+    }
+    if (status === 409 || status === 412) {
+        return httpFailure("core.http_conflict", 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, status) {
+    return { ...err(code), status };
+}
+//# sourceMappingURL=http-json.js.map

package/dist/http-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-json.js","sourceRoot":"","sources":["../src/http-json.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { addCalendarDays, addCalendarMonths, calendarDaysBetween, calendarDaySchema, getCalendarDay, isCalendarDay, toCalendarDay, 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, formatMoney, formatPercent, 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 HttpJsonMethod, type HttpJsonWriteMethod, type RequestJsonOptions, type RequestJsonReadOptions, type RequestJsonSchemaOptions, type RequestJsonWriteOptions, } 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, mergeMessages, pickLocalizedText, selectMessages, selectPlural, type DeepPartial, type Dictionaries, type Locale, type LocalizedText, type MessageOverrides, type MessageTree, type PluralForms, } from "./i18n.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,8 +1,11 @@
 // Public API of @softure-ai/core: the contract every SOFTURE module stands on
 // (docs/02-module-standard.md). The Next.js registry is a separate entry: `@softure-ai/core/next`.
 export { addCalendarDays, addCalendarMonths, calendarDaysBetween, calendarDaySchema, getCalendarDay, isCalendarDay, toCalendarDay, wholeMonthsBetween, } from "./calendar-day.js";
+export { calendarPeriodSchema, countPeriodDays, doPeriodsOverlap, isDayInPeriod, } from "./calendar-period.js";
+export { getLocalDay, isLocalDateTime, localDateTimeSchema } from "./local-date-time.js";
 export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
 export { DEFAULT_DURATION_MESSAGES, formatCalendarDay, formatCalendarMonth, formatDuration, formatMoney, formatPercent, isCalendarMonth, } from "./format.js";
+export { requestJson, toQueryString, } from "./http-json.js";
 export { memoizeByContent } from "./memoize.js";
 export { createTestClock, systemClock } from "./clock.js";
 export { formatMessage, getMessage, DEFAULT_LOCALE, isLocale, mergeMessages, pickLocalizedText, selectMessages, selectPlural, } from "./i18n.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mGAAmG;AACnG,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,GAEnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,GAOhB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAuD,MAAM,cAAc,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,WAAW,EAA8B,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,YAAY,GAQb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAkD,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,GAQ1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,GAUb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GAIjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAyC,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAmC,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mGAAmG;AACnG,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,GAEnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAsB,MAAM,sBAAsB,CAAC;AAC7G,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,GAOhB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,aAAa,GAUd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAuD,MAAM,cAAc,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,WAAW,EAA8B,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,YAAY,GAQb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAkD,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,GAQ1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,GAUb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GAIjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAyC,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAmC,MAAM,oBAAoB,CAAC"}

package/dist/local-date-time.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+/** 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 declare function isLocalDateTime(value: unknown): value is LocalDateTime;
+/** A `YYYY-MM-DDTHH:mm` local date-time in tool and form input, parsed into the branded `LocalDateTime`. */
+export declare const localDateTimeSchema: z.core.$ZodBranded<z.ZodString & z.ZodType<LocalDateTime, string, z.core.$ZodTypeInternals<LocalDateTime, string>>, "LocalDateTime", "out">;
+/** The calendar day (`YYYY-MM-DD`) of a local date-time. Throws a `RangeError` for a malformed value. */
+export declare function getLocalDay(value: LocalDateTime): string;
+//# sourceMappingURL=local-date-time.d.ts.map

package/dist/local-date-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-date-time.d.ts","sourceRoot":"","sources":["../src/local-date-time.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,iGAAiG;AACjG,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;AAE/D,wHAAwH;AACxH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAItE;AAED,4GAA4G;AAC5G,eAAO,MAAM,mBAAmB,6IAGL,CAAC;AAE5B,yGAAyG;AACzG,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAKxD"}

package/dist/local-date-time.js

@@ -0,0 +1,25 @@
+// 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$/;
+/** 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) {
+    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();
+/** The calendar day (`YYYY-MM-DD`) of a local date-time. Throws a `RangeError` for a malformed value. */
+export function getLocalDay(value) {
+    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);
+}
+//# sourceMappingURL=local-date-time.js.map

package/dist/local-date-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-date-time.js","sourceRoot":"","sources":["../src/local-date-time.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,qGAAqG;AACrG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,uBAAuB,GAAG,+CAA+C,CAAC;AAKhF,wHAAwH;AACxH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,KAAK,KAAK,IAAI,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,4GAA4G;AAC5G,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,EAAE;KACR,MAAM,CAAC,eAAe,EAAE,iFAAiF,CAAC;KAC1G,KAAK,EAAmB,CAAC;AAE5B,yGAAyG;AACzG,MAAM,UAAU,WAAW,CAAC,KAAoB;IAC9C,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,UAAU,CAAC,iBAAiB,MAAM,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/messages/en.d.ts

@@ -2,6 +2,12 @@ export declare const en: {
     errors: {
         database_failed: string;
         unexpected: string;
+        http_unreachable: string;
+        http_refused: string;
+        http_rate_limited: string;
+        http_unavailable: string;
+        http_conflict: string;
+        http_unexpected_answer: string;
     };
 };
 //# sourceMappingURL=en.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,EAAE;;;;;CAKd,CAAC"}
+{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,EAAE;;;;;;;;;;;CAWd,CAAC"}

package/dist/messages/en.js

@@ -2,6 +2,12 @@ export const en = {
     errors: {
         database_failed: "Something went wrong while saving or loading data. Please try again.",
         unexpected: "Something went wrong. Please try again.",
+        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_conflict: "The data changed in the meantime. Please reload it and try again.",
+        http_unexpected_answer: "The service sent an answer that could not be read.",
     },
 };
 //# sourceMappingURL=en.js.map

package/dist/messages/en.js.map

@@ -1 +1 @@
-{"version":3,"file":"en.js","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB,MAAM,EAAE;QACN,eAAe,EAAE,sEAAsE;QACvF,UAAU,EAAE,yCAAyC;KACtD;CACF,CAAC"}
+{"version":3,"file":"en.js","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB,MAAM,EAAE;QACN,eAAe,EAAE,sEAAsE;QACvF,UAAU,EAAE,yCAAyC;QACrD,gBAAgB,EAAE,2DAA2D;QAC7E,YAAY,EAAE,kCAAkC;QAChD,iBAAiB,EAAE,qEAAqE;QACxF,gBAAgB,EAAE,+DAA+D;QACjF,aAAa,EAAE,mEAAmE;QAClF,sBAAsB,EAAE,oDAAoD;KAC7E;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "The SOFTURE AI module contract: app config, module definitions, Result, Clock and messages.",
   "license": "MIT",
   "type": "module",

package/src/calendar-period.ts

@@ -0,0 +1,54 @@
+// A calendar period: two calendar days (`YYYY-MM-DD`) with both ends included, so one day is
+// `{ from: d, to: d }`. Zero-padded days sort as text in calendar order, so comparisons work on the strings.
+import { z } from "zod";
+import { calendarDaysBetween, calendarDaySchema, isCalendarDay } from "./calendar-day.js";
+
+/** Calendar days from `from` to `to`, both included; `to` never comes before `from`. */
+export interface CalendarPeriod {
+  readonly from: string;
+  readonly to: string;
+}
+
+/** A `CalendarPeriod` in tool and form input: two calendar days, `to` refused (path `["to"]`) when it comes first. */
+export const calendarPeriodSchema = z
+  .object({ from: calendarDaySchema, to: calendarDaySchema })
+  // A malformed end already has its own issue, and zod still runs the refinement then: skip it, so the
+  // order is checked only between two real days.
+  .refine((period) => !isCalendarDay(period.from) || !isCalendarDay(period.to) || period.from <= period.to, {
+    message: "must not come before from",
+    path: ["to"],
+  });
+
+/** Whether `day` lies in `period`, both ends included. Throws a `RangeError` for a malformed day or period. */
+export function isDayInPeriod(day: string, period: CalendarPeriod): boolean {
+  const operation = "isDayInPeriod";
+  assertCalendarDay(operation, day);
+  assertPeriod(operation, period);
+  return period.from <= day && day <= period.to;
+}
+
+/** Whether `a` and `b` share at least one day; adjacent periods do not. Throws a `RangeError` for a malformed period. */
+export function doPeriodsOverlap(a: CalendarPeriod, b: CalendarPeriod): boolean {
+  const operation = "doPeriodsOverlap";
+  assertPeriod(operation, a);
+  assertPeriod(operation, b);
+  return a.from <= b.to && b.from <= a.to;
+}
+
+/** The number of days in `period`, both ends included: 1 for a single day. Throws a `RangeError` for a malformed period. */
+export function countPeriodDays(period: CalendarPeriod): number {
+  assertPeriod("countPeriodDays", period);
+  return calendarDaysBetween(period.from, period.to) + 1;
+}
+
+function assertPeriod(operation: string, period: CalendarPeriod): void {
+  assertCalendarDay(operation, period.from);
+  assertCalendarDay(operation, period.to);
+  if (period.to < period.from) {
+    throw new RangeError(`${operation}: the period ends ("${period.to}") before it starts ("${period.from}")`);
+  }
+}
+
+function assertCalendarDay(operation: string, day: string): void {
+  if (!isCalendarDay(day)) throw new RangeError(`${operation}: "${String(day)}" is not a YYYY-MM-DD calendar day`);
+}

package/src/http-json.ts

@@ -0,0 +1,175 @@
+// A JSON call to a third-party API (a GET, or a write with a JSON body), 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_conflict"
+  | "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 HttpJsonWriteMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+export type HttpJsonMethod = "GET" | HttpJsonWriteMethod;
+
+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;
+}
+
+/** A GET: no body, no idempotency key (a GET is idempotent already). */
+export interface RequestJsonReadOptions extends RequestJsonOptions {
+  readonly method?: "GET";
+  readonly body?: never;
+  readonly idempotencyKey?: never;
+}
+
+/** A write: the body is sent as JSON, and an answer with no body is `ok(undefined)`. */
+export interface RequestJsonWriteOptions extends RequestJsonOptions {
+  readonly method: HttpJsonWriteMethod;
+  /** Serialised with `JSON.stringify`; `undefined` sends no body. A value JSON cannot represent throws. */
+  readonly body?: unknown;
+  /** Sent as `Idempotency-Key`, for providers that deduplicate retried writes by it. */
+  readonly idempotencyKey?: string;
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * Call `url` (a GET unless `method` says otherwise) 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. A write answered with an empty body (a 204) is
+ * `ok(undefined)`, schema or not. 3xx, 401 and 403 are refused, 409 and 412 a conflict, 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> & RequestJsonReadOptions,
+): Promise<Ok<z.output<S>> | HttpJsonFailure>;
+export function requestJson<S extends z.ZodType>(
+  options: RequestJsonSchemaOptions<S> & RequestJsonWriteOptions,
+): Promise<Ok<z.output<S> | undefined> | HttpJsonFailure>;
+export function requestJson(
+  options: RequestJsonReadOptions | RequestJsonWriteOptions,
+): Promise<Ok<unknown> | HttpJsonFailure>;
+export async function requestJson(
+  options: (RequestJsonReadOptions | RequestJsonWriteOptions) & { readonly schema?: z.ZodType },
+): Promise<Ok<unknown> | HttpJsonFailure> {
+  const fetchFunction = options.fetch ?? globalThis.fetch;
+  const method = options.method ?? "GET";
+  const isWrite = method !== "GET";
+  // Outside the try on purpose: a body JSON cannot represent is the caller's bug, not an unreachable service.
+  const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+
+  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");
+    }
+    if (body !== undefined && !headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+    if (options.idempotencyKey !== undefined) {
+      headers.set("idempotency-key", options.idempotencyKey);
+    }
+    response = await fetchFunction(options.url, {
+      method,
+      headers,
+      body,
+      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);
+  }
+
+  if (isWrite && text.trim() === "") {
+    // A 204, or a write that answers 200 with nothing: the write succeeded and there is nothing to read.
+    return ok(undefined);
+  }
+
+  let answer: unknown;
+  try {
+    answer = JSON.parse(text);
+  } catch {
+    return httpFailure("core.http_unexpected_answer", response.status);
+  }
+
+  if (options.schema === undefined) {
+    return ok(answer);
+  }
+  // The schema's issues can quote the body's values, so only the code leaves.
+  const parsed = options.schema.safeParse(answer);
+  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 === 409 || status === 412) {
+    return httpFailure("core.http_conflict", 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/index.ts

@@ -11,6 +11,14 @@ 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,
@@ -27,6 +35,19 @@ export {
   type FormatMoneyOptions,
   type FormatPercentOptions,
 } from "./format.js";
+export {
+  requestJson,
+  toQueryString,
+  type FetchFunction,
+  type HttpJsonFailure,
+  type HttpJsonFailureCode,
+  type HttpJsonMethod,
+  type HttpJsonWriteMethod,
+  type RequestJsonOptions,
+  type RequestJsonReadOptions,
+  type RequestJsonSchemaOptions,
+  type RequestJsonWriteOptions,
+} from "./http-json.js";
 export { memoizeByContent, type MemoizeByContentOptions, type MemoizedFunction } from "./memoize.js";
 export { createTestClock, systemClock, type Clock, type TestClock } from "./clock.js";
 export {

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,5 +2,11 @@ export const en = {
   errors: {
     database_failed: "Something went wrong while saving or loading data. Please try again.",
     unexpected: "Something went wrong. Please try again.",
+    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_conflict: "The data changed in the meantime. Please reload it and try again.",
+    http_unexpected_answer: "The service sent an answer that could not be read.",
   },
 };