@eco-foundation/api-schemas 0.12.0 → 0.13.0

package/README.md

@@ -4,7 +4,7 @@ Zod-first schemas, error catalog, golden fixtures, and generated OpenAPI 3.1 for
 API. The Zod schemas are the source of truth; everything else (OpenAPI, fixtures, plain types)
 is generated from or gated against them.
 
-Today the package covers **13 endpoints across 12 paths**, **39 error codes** (51 namespaced
+Today the package covers **13 endpoints across 12 paths**, **40 error codes** (51 namespaced
 legacy references), and **21 golden fixtures**.
 
 ## Install
@@ -14,13 +14,13 @@ While the package is 0.x, pin the patch range or the exact version:
 ```json
 {
   "dependencies": {
-    "@eco-foundation/api-schemas": "~0.10.0"
+    "@eco-foundation/api-schemas": "~0.13.0"
   }
 }
 ```
 
 **Never write `^0`.** npm resolves `^0.x` as `>=0.0.0 <1.0.0`, so it silently accepts every
-future breaking `0.y` — it is not a pin at all. Use `~0.10.0` or the exact `0.10.0`.
+future breaking `0.y` — it is not a pin at all. Use `~0.13.0` or the exact `0.13.0`.
 
 A matching version string is not evidence of a matching artifact: also compare
 `V1_SCHEMA_DIGEST` (see [Invariants](#invariants-enforced-in-ci)). Two builds both called
@@ -30,6 +30,55 @@ A matching version string is not evidence of a matching artifact: also compare
 zod-bearing entry point. Which case you are in is decided entirely by your imports; see
 [Consumers](#consumers).
 
+## Migrating 0.12.0 -> 0.13.0
+
+**BREAKING under 0.x semver only for exhaustive handling of `V1ErrorCode`.** Nothing on the wire
+that `0.12.0` accepted is rejected and no response shape changes. The release adds one error code,
+one config schema, and one fixture file for scheduled maintenance windows (PER-673).
+
+**`V1_SCHEMA_DIGEST` MOVES** to
+`e5a684f678f80135ddf7241029d965d2a206b3b573a9969ad1352610d1b4abc9`, because both digest inputs
+changed (`errors/catalog.lock.json` gained one code and `openapi/v1.json` its `x-error-catalog`
+entry). Every consumer running `assertNoSkew` moves in the same rollout.
+
+**1. New error code `maintenance` (503, audience `all`, no legacy codes).** It is a planned stop,
+distinct from `service-unavailable` (an outage). eco-router, eco-quotes and deposit-addresses
+return it from every quote-creating and address-creating endpoint while a configured window is
+active, with `startsAt`/`endsAt` in the body and a `Retry-After` header. `V1ProblemSchema` now
+checks a `maintenance` body's `status`/`type` against the catalog, and an exhaustive `switch`
+over `V1ErrorCode` stops compiling until it handles the new member. That is the breaking item.
+
+**2. New config schemas `MaintenanceWindowSchema` and `MaintenanceConfigSchema`** (on the `v1`
+namespace, with types `MaintenanceWindow`, `MaintenanceConfig`, `MaintenanceConfigInput`). A
+window is `{ startsAt, endsAt, message }`: `startsAt` inclusive, `endsAt` exclusive, both
+ISO-8601 UTC strings ending in `Z` with at most three fractional digits (offsets and impossible
+dates such as `2026-02-30` are rejected), `message` 1-200 characters and not blank (whitespace-only
+is rejected — it is echoed verbatim to partners), and `endsAt` must be after `startsAt`. `windows`
+defaults to `[]`. Both schemas reject any key not in their shape (e.g. a `window` typo for
+`windows`) at parse time, naming the key — this is scoped to the raw input's own enumerable
+properties, so a config object read through node-config (whose hidden, non-enumerable `get`/`has`/
+`util` helpers are unaffected) still parses. Overlapping windows are allowed; past windows are valid
+(services drop them at boot). **Quote the timestamps in YAML**: an unquoted
+`2026-10-04T02:00:00Z` is loaded as a `Date` and fails with "quote it in YAML". There is no
+`./v1/maintenance` subpath, because the schemas need zod anyway, so import them from the root
+`v1` namespace.
+
+**3. New fixture `fixtures/maintenance-boundaries.json`** (served by the existing `./fixtures/*`
+subpath). Each entry service implements its own resolver (the package deliberately ships none)
+and asserts it against every vector: active when `startsAt <= now < endsAt`; with several
+active, the latest `endsAt` wins and a tie goes to the first in the list;
+`retryAfterSeconds = max(1, ceil((endsAt - now) / 1000))`.
+
+**4. Consumers** pin `~0.13.0` (never `^0`) and re-run `assertNoSkew`. No golden fixture under
+`src/fixtures/v1` changed.
+
+**5. The `zod` peer range rises to `^4.4.0`** (from `^4.3.0`), still optional. The maintenance
+schemas' exported types (`MaintenanceWindowSchema`, `MaintenanceConfigSchema`) use
+`z.ZodPreprocess`, which zod only exports from 4.4 — on zod 4.3.x those `.d.ts` types silently
+collapse to `any` under `skipLibCheck` (and fail `TS2724` without it). A consumer that imports
+zod-bearing entry points must upgrade to zod `^4.4.0`+ before adopting `0.13.0`; the two
+zod-free subpaths (`./v1/signature`, `./v1/types`) are unaffected.
+
 ## Migrating 0.11.0 -> 0.12.0
 
 **Non-breaking for callers, a new version for consumers.** `GET /v1/intents/status` now accepts
@@ -989,7 +1038,7 @@ must: it is the artifact identity, not the version string.
 declared optional (`peerDependenciesMeta: { zod: { optional: true } }`), because for two of the
 published entry points it is genuinely not needed:
 
-- **Needs `zod` (`^4.3.0`):** the bare package name `.`, `./testing`, and anything reached
+- **Needs `zod` (`^4.4.0`):** the bare package name `.`, `./testing`, and anything reached
   through the `v1` namespace on either. These load schema modules, and their `.d.ts` names zod
   types.
 - **Needs NO `zod`:** `./v1/signature` (runtime code importing `@noble/hashes` and nothing else)
@@ -998,8 +1047,8 @@ published entry points it is genuinely not needed:
 
 Read `optional` narrowly: it says zod **may be absent**, not that any zod version works. pnpm
 suppresses the unmet-peer warning only when zod is MISSING (verified against pnpm 10.16); a
-consumer that HAS a zod outside `^4.3.0` — solver-v2, on zod 3 — still sees
-`unmet peer zod@^4.3.0: found <version>`, since that is a version mismatch rather than a missing
+consumer that HAS a zod outside `^4.4.0` — solver-v2, on zod 3 — still sees
+`unmet peer zod@^4.4.0: found <version>`, since that is a version mismatch rather than a missing
 peer. Suppressing that one is the consumer's own call
 (`pnpm.peerDependencyRules.allowedVersions`), and it is safe exactly while its imports are
 limited to the two zod-free subpaths above. The range itself cannot be widened — the schemas
@@ -1007,14 +1056,16 @@ require Zod 4.
 
 Zod-major compatibility is the reason there are two interfaces, not one:
 
-- **Zod-4 consumers** (eco-router `^4.4.3`, deposit-addresses `^4.3.5`) import the schemas
-  directly. Since `0.2.0`, `zod` is a **`peerDependency` with a range (`^4.3.0`)** — optional
+- **Zod-4 consumers** (eco-router `^4.4.3`) import the schemas directly. Since `0.2.0`, `zod` is
+  a **`peerDependency` with a range (`^4.4.0` since `0.13.0`, raised from `^4.3.0`)** — optional
   since `0.3.1` — not a hard-pinned dependency: the consumer's own single copy satisfies it. For
-  these consumers optional changes nothing; they must still install zod. The previous exact
-  `dependencies` pin at `4.4.3` materialised a SECOND nested zod for every consumer not on that
-  exact version, and two zod instances in one type graph is the documented failure — `TS2345` on
+  these consumers optional changes nothing; they must still install zod. deposit-addresses'
+  prior `^4.3.5` install is now below the floor and must upgrade to `^4.4.0`+ to consume `0.13.0`
+  — see [Migrating 0.12.0 -> 0.13.0](#migrating-0120---0130). The previous exact `dependencies`
+  pin at `4.4.3` materialised a SECOND nested zod for every consumer not on that exact version,
+  and two zod instances in one type graph is the documented failure — `TS2345` on
   `_zod.version.minor` when a package schema is passed to a local `z.ZodType<T>`, and `tsc`
-  OOMing at 4 GB with no message. A consumer therefore installs zod itself (any `4.3.x`+ `4.x`);
+  OOMing at 4 GB with no message. A consumer therefore installs zod itself (any `4.4.x`+ `4.x`);
   the package keeps an exact `4.4.3` **devDependency** so its own build and its generated
   OpenAPI stay byte-stable.
 - **solver-v2 is on Zod 3 and must never be forced to Zod 4.** It consumes the zod-free
@@ -1041,6 +1092,7 @@ Zod-major compatibility is the reason there are two interfaces, not one:
 | `./openapi/v1.json`                        | the generated OpenAPI 3.1 document                                                                                             |
 | `./fixtures/signature-hash/vectors.json`   | cross-repo `signatureHash` vectors                                                                                             |
 | `./fixtures/quote-signature/vector-*.json` | cross-repo F3 quote-signature (EIP-712) vectors                                                                                |
+| `./fixtures/maintenance-boundaries.json`   | cross-repo maintenance-window (PER-673) resolver boundary vectors                                                              |
 
 ## Fixtures
 
@@ -1057,7 +1109,10 @@ There are two fixture locations and they serve different jobs — do not conflat
   `fixtures/signature-hash/vectors.json` (the `signatureHash` canonicalization contract) and
   `fixtures/quote-signature/vector-*.json` (the F3 EIP-712 `EcoQuoteV1` vectors, each with its
   `digest`, `signature`, and `signer`; the signing key is derived from a public domain string,
-  so this repo ships no private-key bytes).
+  so this repo ships no private-key bytes), and `fixtures/maintenance-boundaries.json` (the
+  PER-673 maintenance-window boundary vectors: `{ name, windows, nowIso, expected }`, which each
+  entry service's local resolver asserts; this package's own suite checks every vector against a
+  reference resolver kept in the spec file, so a wrong `expected` fails here first).
 
 `routes.list` is the one fixture tagged `stability: 'draft'`. A live-replay consumer skips it
 with the reason `draft endpoint (x-stability: draft) — not served at launch` instead of

package/dist/generated/build-digest.json

@@ -1,5 +1,5 @@
 {
-    "digest": "85d2717c541b52f668574f045ddc3f3722813bbdcee9e8f5d15bed5cfc927561",
+    "digest": "e5a684f678f80135ddf7241029d965d2a206b3b573a9969ad1352610d1b4abc9",
     "inputs": [
         "errors/catalog.lock.json",
         "openapi/v1.json"

package/dist/v1/errors/catalog.d.ts

@@ -280,6 +280,13 @@ export declare const V1_ERROR_CATALOG: readonly [{
     readonly type: string;
     readonly audience: "read" | "write" | "all";
     readonly legacyCodes: readonly LegacyCodeRef[];
+}, {
+    readonly code: "maintenance";
+    readonly status: number;
+    readonly title: string;
+    readonly type: string;
+    readonly audience: "read" | "write" | "all";
+    readonly legacyCodes: readonly LegacyCodeRef[];
 }];
 export type V1ErrorCode = (typeof V1_ERROR_CATALOG)[number]['code'];
 export declare function getErrorDefinition(code: V1ErrorCode): V1ErrorDefinition;

package/dist/v1/errors/catalog.js

@@ -109,6 +109,7 @@ exports.V1_ERROR_CATALOG = [
     ]),
     define('solver-error', 502, 'An upstream solver rejected or failed the quote request', 'all'),
     define('service-unavailable', 503, 'Service temporarily unavailable', 'all'),
+    define('maintenance', 503, 'Scheduled maintenance: new quotes and deposit addresses are paused until the window ends', 'all'),
 ];
 const BY_CODE = new Map(exports.V1_ERROR_CATALOG.map((e) => [e.code, e]));
 function getErrorDefinition(code) {

package/dist/v1/errors/catalog.js.map

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

package/dist/v1/index.d.ts

@@ -9,6 +9,7 @@ export * from './endpoints/tokens';
 export * from './enums';
 export * from './errors/catalog';
 export * from './errors/problem';
+export * from './maintenance/schema';
 export * from './primitives';
 export * from './signature';
 export declare const V1_API_VERSION: "v1";

package/dist/v1/index.js

@@ -26,6 +26,7 @@ __exportStar(require("./endpoints/tokens"), exports);
 __exportStar(require("./enums"), exports);
 __exportStar(require("./errors/catalog"), exports);
 __exportStar(require("./errors/problem"), exports);
+__exportStar(require("./maintenance/schema"), exports);
 __exportStar(require("./primitives"), exports);
 __exportStar(require("./signature"), exports);
 exports.V1_API_VERSION = 'v1';

package/dist/v1/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/v1/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,gEAA8C;AAC9C,qDAAmC;AACnC,uDAAqC;AACrC,qDAAmC;AACnC,qDAAmC;AACnC,qDAAmC;AACnC,qDAAmC;AACnC,0CAAwB;AACxB,mDAAiC;AACjC,mDAAiC;AACjC,+CAA6B;AAC7B,8CAA4B;AAEf,QAAA,cAAc,GAAG,IAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/v1/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,gEAA8C;AAC9C,qDAAmC;AACnC,uDAAqC;AACrC,qDAAmC;AACnC,qDAAmC;AACnC,qDAAmC;AACnC,qDAAmC;AACnC,0CAAwB;AACxB,mDAAiC;AACjC,mDAAiC;AACjC,uDAAqC;AACrC,+CAA6B;AAC7B,8CAA4B;AAEf,QAAA,cAAc,GAAG,IAAa,CAAC"}

package/dist/v1/maintenance/schema.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+export declare const MAINTENANCE_MESSAGE_MAX_LENGTH = 200;
+declare const MaintenanceWindowShape: z.ZodObject<{
+    startsAt: z.ZodString;
+    endsAt: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare const MaintenanceWindowSchema: z.ZodPreprocess<z.ZodObject<{
+    startsAt: z.ZodString;
+    endsAt: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>>;
+export type MaintenanceWindow = z.infer<typeof MaintenanceWindowShape>;
+declare const MaintenanceConfigShape: z.ZodObject<{
+    windows: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
+        startsAt: z.ZodString;
+        endsAt: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export declare const MaintenanceConfigSchema: z.ZodPreprocess<z.ZodObject<{
+    windows: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
+        startsAt: z.ZodString;
+        endsAt: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>>;
+export type MaintenanceConfig = z.infer<typeof MaintenanceConfigShape>;
+export type MaintenanceConfigInput = z.input<typeof MaintenanceConfigShape>;
+export {};

package/dist/v1/maintenance/schema.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaintenanceConfigSchema = exports.MaintenanceWindowSchema = exports.MAINTENANCE_MESSAGE_MAX_LENGTH = void 0;
+const zod_1 = require("zod");
+const ISO_UTC_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+function isRealUtcInstant(value) {
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms))
+        return false;
+    return new Date(ms).toISOString().slice(0, 19) === value.slice(0, 19);
+}
+function utcMillis(value) {
+    return ISO_UTC_PATTERN.test(value) && isRealUtcInstant(value) ? Date.parse(value) : undefined;
+}
+const IsoUtcTimestamp = zod_1.z
+    .string({
+    error: 'must be an ISO-8601 UTC timestamp string; quote it in YAML',
+})
+    .regex(ISO_UTC_PATTERN, 'must be an ISO-8601 UTC timestamp ending in Z, e.g. 2026-10-04T02:00:00Z')
+    .refine((value) => !ISO_UTC_PATTERN.test(value) || utcMillis(value) !== undefined, 'is not a real calendar instant');
+exports.MAINTENANCE_MESSAGE_MAX_LENGTH = 200;
+function rejectUnknownKeys(allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return (raw, ctx) => {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+            return raw;
+        const extra = Object.keys(raw).filter((key) => !allowed.has(key));
+        if (extra.length === 0)
+            return raw;
+        const quoted = extra.map((key) => `"${key}"`).join(', ');
+        ctx.addIssue({
+            code: 'custom',
+            message: extra.length === 1 ? `Unrecognized key: ${quoted}` : `Unrecognized keys: ${quoted}`,
+        });
+        return raw;
+    };
+}
+const MaintenanceWindowShape = zod_1.z
+    .object({
+    startsAt: IsoUtcTimestamp,
+    endsAt: IsoUtcTimestamp,
+    message: zod_1.z
+        .string()
+        .max(exports.MAINTENANCE_MESSAGE_MAX_LENGTH)
+        .refine((value) => value.trim().length > 0, 'must not be blank'),
+})
+    .superRefine((window, ctx) => {
+    const startsMs = utcMillis(window.startsAt);
+    const endsMs = utcMillis(window.endsAt);
+    if (startsMs === undefined || endsMs === undefined)
+        return;
+    if (endsMs <= startsMs) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['endsAt'],
+            message: `endsAt ${window.endsAt} must be after startsAt ${window.startsAt}`,
+        });
+    }
+});
+exports.MaintenanceWindowSchema = zod_1.z.preprocess(rejectUnknownKeys(['startsAt', 'endsAt', 'message']), MaintenanceWindowShape);
+const MaintenanceConfigShape = zod_1.z.object({
+    windows: zod_1.z.array(exports.MaintenanceWindowSchema).default([]),
+});
+exports.MaintenanceConfigSchema = zod_1.z.preprocess(rejectUnknownKeys(['windows']), MaintenanceConfigShape);
+//# sourceMappingURL=schema.js.map

package/dist/v1/maintenance/schema.js.map

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

package/errors/catalog.lock.json

@@ -258,5 +258,10 @@
     "code": "service-unavailable",
     "status": 503,
     "legacyCodes": []
+  },
+  {
+    "code": "maintenance",
+    "status": 503,
+    "legacyCodes": []
   }
 ]

package/fixtures/maintenance-boundaries.json

@@ -0,0 +1,405 @@
+[
+  {
+    "name": "empty window list",
+    "windows": [],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "one millisecond before startsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T01:59:59.999Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "exactly startsAt (start is inclusive)",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T02:00:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 7200
+    }
+  },
+  {
+    "name": "mid-window",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 3600
+    }
+  },
+  {
+    "name": "one millisecond before endsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:59:59.999Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 1
+    }
+  },
+  {
+    "name": "exactly endsAt (end is exclusive)",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T04:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "fractional remainder rounds up: 1.5 s before endsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:59:58.500Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 2
+    }
+  },
+  {
+    "name": "whole-second remainder does not round up: 2 s before endsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:59:58.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 2
+    }
+  },
+  {
+    "name": "past-only window",
+    "windows": [
+      {
+        "startsAt": "2026-10-01T02:00:00Z",
+        "endsAt": "2026-10-01T04:00:00Z",
+        "message": "Last week's maintenance"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "future-only window",
+    "windows": [
+      {
+        "startsAt": "2026-10-11T02:00:00Z",
+        "endsAt": "2026-10-11T04:00:00Z",
+        "message": "Next week's maintenance"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "past and future windows, now between them",
+    "windows": [
+      {
+        "startsAt": "2026-10-01T02:00:00Z",
+        "endsAt": "2026-10-01T04:00:00Z",
+        "message": "Last week's maintenance"
+      },
+      {
+        "startsAt": "2026-10-11T02:00:00Z",
+        "endsAt": "2026-10-11T04:00:00Z",
+        "message": "Next week's maintenance"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "overlapping windows, only the first active",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T05:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T02:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "A: database upgrade",
+      "retryAfterSeconds": 5400
+    }
+  },
+  {
+    "name": "overlapping windows, both active: latest endsAt wins",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T05:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T03:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T05:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 5400
+    }
+  },
+  {
+    "name": "overlapping windows, both active, list reversed: latest endsAt still wins",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T05:00:00Z",
+        "message": "B: key rotation"
+      },
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T05:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 5400
+    }
+  },
+  {
+    "name": "overlapping windows, after the first ends",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T05:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T04:00:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T05:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 3600
+    }
+  },
+  {
+    "name": "overlapping windows with equal endsAt: first in list wins",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T03:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "A: database upgrade",
+      "retryAfterSeconds": 1800
+    }
+  },
+  {
+    "name": "overlapping windows with equal endsAt, list reversed: first in list wins",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "B: key rotation"
+      },
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 1800
+    }
+  },
+  {
+    "name": "adjacent windows, one millisecond before the handoff",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T03:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T02:59:59.999Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T03:00:00Z",
+      "message": "A: database upgrade",
+      "retryAfterSeconds": 1
+    }
+  },
+  {
+    "name": "adjacent windows at the handoff instant: the second window",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T03:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 3600
+    }
+  },
+  {
+    "name": "sub-second bounds, one millisecond before startsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00.250Z",
+        "endsAt": "2026-10-04T02:00:01.750Z",
+        "message": "Sub-second window"
+      }
+    ],
+    "nowIso": "2026-10-04T02:00:00.249Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "sub-second bounds, exactly startsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00.250Z",
+        "endsAt": "2026-10-04T02:00:01.750Z",
+        "message": "Sub-second window"
+      }
+    ],
+    "nowIso": "2026-10-04T02:00:00.250Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00.250Z",
+      "endsAt": "2026-10-04T02:00:01.750Z",
+      "message": "Sub-second window",
+      "retryAfterSeconds": 2
+    }
+  },
+  {
+    "name": "sub-second bounds, exactly endsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00.250Z",
+        "endsAt": "2026-10-04T02:00:01.750Z",
+        "message": "Sub-second window"
+      }
+    ],
+    "nowIso": "2026-10-04T02:00:01.750Z",
+    "expected": {
+      "active": false
+    }
+  }
+]

package/openapi/v1.json

@@ -6465,6 +6465,14 @@
       "type": "https://api.eco.com/v1/errors/service-unavailable",
       "audience": "all",
       "legacyCodes": []
+    },
+    {
+      "code": "maintenance",
+      "status": 503,
+      "title": "Scheduled maintenance: new quotes and deposit addresses are paused until the window ends",
+      "type": "https://api.eco.com/v1/errors/maintenance",
+      "audience": "all",
+      "legacyCodes": []
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eco-foundation/api-schemas",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Zod-first schemas, error catalog, golden fixtures, and generated OpenAPI 3.1 for the Eco /v1 API",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -63,7 +63,7 @@
     "@scure/base": "^1.2.6"
   },
   "peerDependencies": {
-    "zod": "^4.3.0"
+    "zod": "^4.4.0"
   },
   "peerDependenciesMeta": {
     "zod": {