@solvice/routing 0.17.1-beta.0 → 0.17.3-beta.0

package/dist/runs.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/v3.d.ts

@@ -302,13 +302,14 @@ export interface components {
         ConstraintCode: string;
         /**
          * @description What running a vehicle costs, in the request's currency
-         *     (`objective.currency` is only a label). The same type at three levels:
-         *     `objective.costs` prices the fleet, `vehicles[].costs` replaces a field for
-         *     one vehicle, and `shifts[].costs` replaces it for one shift. Each field
-         *     resolves on its own: the shift's value, else the vehicle's, else the
-         *     fleet's, else the default. Nothing is added on top of a fleet rate, and
-         *     every field is reported under the same `score.components` key at every
-         *     level. `0` means priced at zero; absent means inherit.
+         *     (`objective.currency` is only a label). `objective.costs` prices the fleet
+         *     and `vehicles[].costs` replaces a field for one vehicle; `shifts[].costs`
+         *     is the same without `per_used_vehicle` (schema `ShiftCosts`), and replaces
+         *     a field for one shift. Each field resolves on its own: the shift's value,
+         *     else the vehicle's, else the fleet's, else the default. Nothing is added
+         *     on top of a fleet rate, and every field is reported under the same
+         *     `score.components` key at every level. `0` means priced at zero; absent
+         *     means inherit.
          *
          *     Rates are rounded to the internal grid (1/100 000 of a currency unit per
          *     second or per metre); a nonzero rate too small to represent is rejected.
@@ -335,9 +336,11 @@ export interface components {
             /**
              * Format: double
              * @description Flat charge for each used shift (a route with at least one task),
-             *     reported in `score.components.routes`. Default `0`. Pricing vehicles is
-             *     how the solver is made to use fewer of them: the higher it is, the
-             *     more travel it accepts to avoid opening another route.
+             *     reported in `score.components.routes`. Default `0`. The higher it is,
+             *     the more travel the solver accepts to avoid opening another route. It
+             *     counts shifts, not vehicles: a vehicle that works five days pays it five
+             *     times, so it does not prefer one vehicle on two shifts over two vehicles
+             *     on one shift each; use `per_used_vehicle` for that.
              * @example 50
              */
             per_route?: number | null;
@@ -357,6 +360,18 @@ export interface components {
              * @example 0.2
              */
             per_travel_km?: number | null;
+            /**
+             * Format: double
+             * @description Flat charge once per vehicle that serves at least one task, however
+             *     many of its shifts it works. Reported in `score.components.vehicles`.
+             *     Adds to `per_route`: the vehicle's first used shift pays both, later
+             *     shifts only `per_route`. Default `0`. Use it to minimise distinct
+             *     vehicles; use `per_route` to price each working day. Not accepted on
+             *     `shifts[].costs`. When any vehicle has a non-zero rate and any vehicle
+             *     has several shifts, the problem solves without decomposition.
+             * @example 400
+             */
+            per_used_vehicle?: number | null;
             /**
              * Format: double
              * @description Per hour spent waiting for a time window to open, reported in
@@ -716,6 +731,17 @@ export interface components {
              *     Not applied by decomposition: a problem that sets it solves monolithically.
              */
             assignment_costs?: components["schemas"]["AssignmentCost"][] | null;
+            /**
+             * @description Whether a break may pause this job's service. With `true`, a `fixed`
+             *     break, a `windowed` break or a duty-`triggered` break that falls
+             *     inside the service pauses it: the work resumes when the break ends,
+             *     the job departs the break's length later, and the stop reports the
+             *     paused seconds in `break_s`. A drive-`triggered` break never pauses a
+             *     job (it counts driving time only). Default `false`: the whole service
+             *     moves after the break, or the break is taken before the job starts.
+             * @example true
+             */
+            break_interruptible?: boolean | null;
             /**
              * @description Quantity delivered at this visit: comes off the vehicle here, having
              *     been loaded at a depot. Direction is carried by the field itself, never
@@ -742,7 +768,9 @@ export interface components {
              *     On a shipment the drop cost applies to the pair, charged once.
              *
              *     Must be finite, `>= 0` and at most `1e9`; combined with `priority` it
-             *     is rejected with HTTP 400 (`conflicting_fields`).
+             *     is rejected with HTTP 400 (`conflicting_fields`). Also rejected with
+             *     HTTP 400 (`not_supported`) while a positive `objective.per_delay_workday` is set,
+             *     since a droppable task could be dropped to avoid its delay charge.
              * @example 25
              */
             drop_cost?: number | null;
@@ -877,8 +905,9 @@ export interface components {
          *     (the summed `priority` of the required tasks left unassigned is
          *     minimised), then **minimise cost** — the `costs` rates plus every priced
          *     preference, reported as `score.cost`. There is no separate vehicle-count
-         *     step: to use fewer vehicles, price them with `costs.per_route` or
-         *     `vehicles[].costs.per_route`.
+         *     step: to use fewer routes, price them with `costs.per_route`
+         *     (per used shift); to use fewer distinct vehicles when they work several
+         *     shifts, price them with `costs.per_used_vehicle` (once per vehicle).
          * @example {
          *       "costs": {
          *         "per_route_hour": 35,
@@ -902,6 +931,22 @@ export interface components {
             currency?: string | null;
             /** @description Job-proximity cluster cohesion. See the `Grouping` schema. */
             grouping?: null | components["schemas"]["Grouping"];
+            /**
+             * Format: double
+             * @description ASAP scheduling: money charged for each served task per workday its
+             *     shift lies after the earliest workday in the request, in the request's
+             *     currency. A workday is a distinct calendar date, in the shift's own UTC
+             *     offset, on which at least one shift starts; shifts on one date share a
+             *     rank, and a date with no shift adds none. Unserved tasks pay nothing;
+             *     the charge never outranks `priority` and cannot be combined with
+             *     `drop_cost`. Absent or `0` = off; a single-date request is charged
+             *     nothing. A problem that sets it, even on one date, solves without
+             *     decomposition, like `assignment_costs`. Reported as `score.components.delay`. A positive
+             *     rate below `0.00001` is rejected, as is a rate whose total over the
+             *     later workdays exceeds `21474.83647` (`out_of_range`).
+             * @example 5
+             */
+            per_delay_workday?: number | null;
             /**
              * Format: double
              * @description Cost per hour of lateness: the default rate for every task window
@@ -1354,7 +1399,8 @@ export interface components {
          *     Hard. Overlapping `all_or_none` relations chain: one on A and B plus
          *     one on B and C serve all three together or none of them. A group with
          *     a task in a vehicle's locked prefix (`plan.routes[].locked_count`) is
-         *     exempt.
+         *     exempt. A member that could be served but is held back because
+         *     another cannot reports `all_or_none` in `unassigned[].reasons`.
          *
          *     Every task must also be named by a `synchronized` or `time_lag`
          *     relation; a task named by neither is rejected with HTTP 400.
@@ -1858,6 +1904,19 @@ export interface components {
              * @example 2026-07-01T08:10:00+02:00
              */
             arrival: string;
+            /**
+             * Format: int32
+             * @description Seconds of driver break taken inside this stop's service, pausing it:
+             *     a `fixed`, `windowed` or `triggered` break that fell mid-service on a
+             *     job with `break_interruptible: true`. Such a break gets no `break`
+             *     stop of its own; its time is counted here and in the route's
+             *     `time.break_s`. The stop reconciles as
+             *     `departure - service_start == service_s + setup + break_s`, where
+             *     setup is the unscaled `setup_duration_s` when paid, else 0. Present on
+             *     `job` stops only, when non-zero.
+             * @example 3600
+             */
+            break_s?: number | null;
             /**
              * Format: date-time
              * @description Departure. On `end` when the route finishes, after any depot
@@ -1934,10 +1993,10 @@ export interface components {
              *     On task stops, the **effective** on-site service time, not the
              *     nominal `service_duration_s` from the request: it already has the
              *     serving vehicle's `service_factor` applied. `departure -
-             *     service_start - service_s` is the stop's setup time: the request's
-             *     `setup_duration_s` (unscaled) for the first stop of a run at the same
-             *     location (setup is charged when the previous stop is elsewhere), and 0
-             *     for a co-located successor.
+             *     service_start - service_s - break_s` is the stop's setup time: the
+             *     request's `setup_duration_s` (unscaled) for the first stop of a run at
+             *     the same location (setup is charged when the previous stop is
+             *     elsewhere), and 0 for a co-located successor.
              *
              *     On `reload`, the depot's handling time (`departure - service_start
              *     == service_s`). On `start`/`end`, the depot handling time applied
@@ -1952,7 +2011,9 @@ export interface components {
             /**
              * Format: date-time
              * @description When service starts: `arrival + wait_s` plus the duration of any
-             *     windowed break taken on arrival here. On task and `reload` stops only.
+             *     break taken on arrival here (a `windowed` one; on a
+             *     `break_interruptible` job also a `fixed` or duty-`triggered` one that
+             *     falls in the wait). On task and `reload` stops only.
              * @example 2026-07-01T09:00:00+02:00
              */
             service_start?: string | null;
@@ -2006,6 +2067,7 @@ export interface components {
          * @example {
          *       "components": {
          *         "assignment": 0,
+         *         "delay": 0,
          *         "distance": 1.69,
          *         "drop_costs": 0,
          *         "grouping": 0,
@@ -2017,6 +2079,7 @@ export interface components {
          *         "tag_preference": 0,
          *         "target": 0,
          *         "time": 57.1536,
+         *         "vehicles": 0,
          *         "waiting": 0,
          *         "window_choice": 0,
          *         "workload_share": 0
@@ -2062,6 +2125,7 @@ export interface components {
          *     charges lands in exactly one of them.
          * @example {
          *       "assignment": 0,
+         *       "delay": 0,
          *       "distance": 1.69,
          *       "drop_costs": 0,
          *       "grouping": 0,
@@ -2073,6 +2137,7 @@ export interface components {
          *       "tag_preference": 0,
          *       "target": 0,
          *       "time": 57.1536,
+         *       "vehicles": 0,
          *       "waiting": 0,
          *       "window_choice": 0,
          *       "workload_share": 0
@@ -2085,6 +2150,13 @@ export interface components {
              *     default assignment cost), in currency units.
              */
             assignment: number;
+            /**
+             * Format: double
+             * @description Cost of delay, in currency units (`objective.per_delay_workday`): each
+             *     served task pays the rate once per workday its shift lies after the
+             *     earliest workday in the request.
+             */
+            delay: number;
             /**
              * Format: double
              * @description Distance cost, in currency units: each route's distance priced at
@@ -2128,7 +2200,7 @@ export interface components {
             reloads: number;
             /**
              * Format: double
-             * @description Vehicle cost, in currency units: `costs.per_route` once per used shift,
+             * @description Shift cost, in currency units: `costs.per_route` once per used shift,
              *     at the shift's, vehicle's or fleet's rate.
              */
             routes: number;
@@ -2150,6 +2222,13 @@ export interface components {
              *     `costs.per_route_hour` (shift, vehicle or fleet).
              */
             time: number;
+            /**
+             * Format: double
+             * @description Vehicle cost, in currency units: `costs.per_used_vehicle` once per
+             *     vehicle that serves a task, however many of its shifts it works, at the
+             *     vehicle's or fleet's rate.
+             */
+            vehicles: number;
             /**
              * Format: double
              * @description Cost of waiting for time windows to open, in currency units: each
@@ -2281,8 +2360,10 @@ export interface components {
              * @description Costs for this shift only. Each field set here replaces the same
              *     field of the vehicle's `costs` (or, when the vehicle does not set it,
              *     of `objective.costs`) for this shift; fields not set keep that value.
+             *     `per_used_vehicle` is not accepted here: it prices the vehicle, not a
+             *     shift.
              */
-            costs?: null | components["schemas"]["Costs"];
+            costs?: null | components["schemas"]["ShiftCosts"];
             /** @description Where the shift ends. Absent = open end. */
             end?: null | components["schemas"]["ShiftPlace"];
             /**
@@ -2405,6 +2486,51 @@ export interface components {
              */
             to: string;
         };
+        /**
+         * @description The `Costs` fields for one shift, minus `per_used_vehicle`. A shift is one
+         *     of a vehicle's days, so a charge for using the vehicle at all is set on the
+         *     vehicle (or the fleet), where it applies once across its shifts. A field
+         *     set here replaces the vehicle's value (else the fleet's) for this shift
+         *     only; the `Costs` schema says what each field prices.
+         * @example {
+         *       "per_route": 50,
+         *       "per_travel_km": 0.3
+         *     }
+         */
+        ShiftCosts: {
+            /**
+             * Format: double
+             * @description Per hour this route finishes past the shift's `to`, as
+             *     `Costs.per_overtime_hour`.
+             * @example 0
+             */
+            per_overtime_hour?: number | null;
+            /**
+             * Format: double
+             * @description Flat charge for this used shift, as `Costs.per_route`.
+             * @example 50
+             */
+            per_route?: number | null;
+            /**
+             * Format: double
+             * @description Per hour of this route's wall-clock span, as `Costs.per_route_hour`.
+             * @example 35
+             */
+            per_route_hour?: number | null;
+            /**
+             * Format: double
+             * @description Per kilometre driven on this shift, as `Costs.per_travel_km`.
+             * @example 0.2
+             */
+            per_travel_km?: number | null;
+            /**
+             * Format: double
+             * @description Per hour spent waiting for a time window to open on this shift, as
+             *     `Costs.per_wait_hour`.
+             * @example 0
+             */
+            per_wait_hour?: number | null;
+        };
         /**
          * @description Per-shift limits: the route-level `limits` fields a shift may override.
          *     Period limits apply across shifts, so they stay on the vehicle.
@@ -2537,7 +2663,9 @@ export interface components {
              *     On a shipment the drop cost applies to the pair, charged once.
              *
              *     Must be finite, `>= 0` and at most `1e9`; combined with `priority` it
-             *     is rejected with HTTP 400 (`conflicting_fields`).
+             *     is rejected with HTTP 400 (`conflicting_fields`). Also rejected with
+             *     HTTP 400 (`not_supported`) while a positive `objective.per_delay_workday` is set,
+             *     since a droppable task could be dropped to avoid its delay charge.
              * @example 25
              */
             drop_cost?: number | null;
@@ -2723,10 +2851,10 @@ export interface components {
              */
             time_limit_s?: number | null;
             /**
-             * @description What to do when Solvice Maps cannot answer (outage, timeout,
-             *     overload): `estimate` (the default) solves on estimated travel and
-             *     sets `summary.travel_estimated`; `fail` returns the 502/503
-             *     instead. A request Maps rejects as invalid always fails.
+             * @description What to do when travel times cannot be fetched from Solvice Maps:
+             *     `estimate` (the default) solves on estimated travel and sets
+             *     `summary.travel_estimated`; `fail` returns the 502/503 instead.
+             *     Locations that Maps rejects for spanning more than one region are a 400.
              * @default estimate
              */
             travel_fallback?: null | components["schemas"]["TravelFallback"];
@@ -2955,6 +3083,7 @@ export interface components {
          *         "score": {
          *           "components": {
          *             "assignment": 0,
+         *             "delay": 0,
          *             "distance": 1.69,
          *             "drop_costs": 0,
          *             "grouping": 0,
@@ -2966,6 +3095,7 @@ export interface components {
          *             "tag_preference": 0,
          *             "target": 0,
          *             "time": 57.1536,
+         *             "vehicles": 0,
          *             "waiting": 0,
          *             "window_choice": 0,
          *             "workload_share": 0
@@ -3288,6 +3418,7 @@ export interface components {
          *       "score": {
          *         "components": {
          *           "assignment": 0,
+         *           "delay": 0,
          *           "distance": 1.69,
          *           "drop_costs": 0,
          *           "grouping": 0,
@@ -3299,6 +3430,7 @@ export interface components {
          *           "tag_preference": 0,
          *           "target": 0,
          *           "time": 57.1536,
+         *           "vehicles": 0,
          *           "waiting": 0,
          *           "window_choice": 0,
          *           "workload_share": 0
@@ -3361,15 +3493,14 @@ export interface components {
             /** @description Where the request's time went. */
             timings: components["schemas"]["Timings"];
             /**
-             * @description `true` when Solvice Maps could not be reached and the plan was costed
+             * @description `true` when travel times could not be fetched and the plan was costed
              *     on estimated travel: straight-line distance × a detour factor, at a
              *     typical speed for the profile. No one-way streets or traffic, so it
              *     can be tens of percent off: the plan, `unassigned[].reasons` and
-             *     `score.violation_count` hold only against it, and no `routes[].polyline` is
-             *     returned. Solve again once Maps is back if the plan must hold on the
-             *     road; `options.travel_fallback: "fail"` returns the error instead.
-             *     Absent when travel is road-routed, and always absent on `/evaluate`,
-             *     which returns the error rather than estimate.
+             *     `score.violation_count` hold only against it, and no `routes[].polyline`
+             *     is returned. Solve again once Maps is back if the plan must hold on the
+             *     road; on a solve, `options.travel_fallback: "fail"` returns the error
+             *     instead. Absent when travel is road-routed.
              */
             travel_estimated?: boolean;
             /**
@@ -3571,7 +3702,8 @@ export interface components {
         TimeTotals: {
             /**
              * Format: int64
-             * @description Time on driver breaks.
+             * @description Time on driver breaks: the `break` stops plus the breaks that paused
+             *     a job's service (the job stops' `break_s`).
              */
             break_s: number;
             /**
@@ -3722,7 +3854,7 @@ export interface components {
         };
         /**
          * @description `options.travel_fallback`: what a solve does when travel times cannot be
-         *     fetched. `/evaluate` and `/suggest` never estimate: they fail instead.
+         *     fetched. `/evaluate` and `/suggest` always estimate.
          * @example estimate
          * @enum {string}
          */
@@ -3752,8 +3884,9 @@ export interface components {
          */
         UnassignedReason: {
             /**
-             * @description The constraint that refused the task on at least one vehicle, in the
-             *     vocabulary of the evaluate violations' `code`. A task lists one reason
+             * @description The constraint that refused the task on at least one vehicle (or
+             *     `all_or_none`, for a task its group holds back), in the vocabulary of
+             *     the evaluate violations' `code`. A task lists one reason
              *     per constraint, once each, in [`ConstraintCode`] order. Absent on the
              *     single reason of a `time_limit` or `priced_out` task, which names no
              *     constraint.
@@ -3794,8 +3927,9 @@ export interface components {
              * @description Never empty. When `category` is `impossible` or `blocked` there is
              *     one reason per constraint that refused the task on at least one
              *     vehicle, named in `constraint`, once each, `unreachable` first
-             *     (`unknown` when no constraint was recorded). Otherwise there is one
-             *     reason with no `constraint`.
+             *     (`unknown` when no constraint was recorded); a task that fits but
+             *     whose `all_or_none` group holds it back has the one reason
+             *     `all_or_none`. Otherwise there is one reason with no `constraint`.
              */
             reasons: components["schemas"]["UnassignedReason"][];
             /**
@@ -4150,7 +4284,7 @@ export interface components {
          *     reach (the service time of the tasks whose windows overlap it), weighted
          *     by shift length, so a day with no tasks carries none of the share; each
          *     shift is charged on its own part. An empty, non-exempt shift pays for its whole share, so pair the
-         *     term with `costs.fixed` or `per_vehicle` only when both are meant.
+         *     term with `costs.per_route` or `per_used_vehicle` only when both are meant.
          *     See `vehicles[].workload_weight` to give a part-time vehicle a smaller
          *     share. A problem that sets the term solves without decomposition, like
          *     `assignment_costs`.
@@ -4299,38 +4433,6 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorBody"];
                 };
             };
-            /** @description Travel times and distances could not be fetched (`code: travel_provider_error`). The request can be retried. This endpoint never falls back to estimated travel. */
-            502: {
-                headers: {
-                    /** @description The request's `X-Request-Id`, echoed, or a generated `req_…` id. */
-                    "x-request-id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorBody"];
-                };
-            };
-            /** @description Solvice Maps is temporarily refused after repeated failures (`code: overloaded`), so travel times cannot be fetched. Evaluate takes no solver slot, so this is its only 503. Retry after the number of seconds in the `Retry-After` header. */
-            503: {
-                headers: {
-                    /** @description Seconds to wait before retrying. */
-                    "Retry-After"?: number;
-                    /** @description The request's `X-Request-Id`, echoed, or a generated `req_…` id. */
-                    "x-request-id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    /**
-                     * @example {
-                     *       "code": "overloaded",
-                     *       "message": "Circuit breaker is open — Solvice Maps temporarily unavailable",
-                     *       "request_id": "req_7f3a2c90d1e4b5a6",
-                     *       "status": "SERVICE_UNAVAILABLE"
-                     *     }
-                     */
-                    "application/json": components["schemas"]["ErrorBody"];
-                };
-            };
         };
     };
     solve: {
@@ -4450,7 +4552,7 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorBody"];
                 };
             };
-            /** @description Travel times and distances could not be fetched (`code: travel_provider_error`). The request can be retried. If Solvice Maps is only unreachable, this needs `options.travel_fallback: "fail"`; by default the plan is solved on estimated travel and `summary.travel_estimated` is set. */
+            /** @description Travel times and distances could not be fetched (`code: travel_provider_error`). The request can be retried. Only with `options.travel_fallback: "fail"`; by default the plan is solved on estimated travel and `summary.travel_estimated` is set. */
             502: {
                 headers: {
                     /** @description The request's `X-Request-Id`, echoed, or a generated `req_…` id. */
@@ -4601,18 +4703,7 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorBody"];
                 };
             };
-            /** @description Travel times and distances could not be fetched (`code: travel_provider_error`). The request can be retried. This endpoint never falls back to estimated travel. */
-            502: {
-                headers: {
-                    /** @description The request's `X-Request-Id`, echoed, or a generated `req_…` id. */
-                    "x-request-id"?: string;
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorBody"];
-                };
-            };
-            /** @description No capacity right now (`code: overloaded`): every solver slot is busy, the wait for one timed out, or Solvice Maps is temporarily refused after repeated failures. Retry after the number of seconds in the `Retry-After` header. */
+            /** @description No capacity right now (`code: overloaded`): every solver slot is busy, or the wait for one timed out. Retry after the number of seconds in the `Retry-After` header. */
             503: {
                 headers: {
                     /** @description Seconds to wait before retrying. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvice/routing",
-  "version": "0.17.1-beta.0",
+  "version": "0.17.3-beta.0",
   "description": "TypeScript client for the Solvice V3 routing API, generated from its OpenAPI spec.",
   "license": "Apache-2.0",
   "homepage": "https://docs.solvice.io/guides/platform/sdks/typescript",
@@ -28,7 +28,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "generate": "openapi-typescript ../../mintlify/openapi.json -o src/v3.ts --default-non-nullable false",
+    "generate": "openapi-typescript ../../mintlify/openapi.json -o src/v3.ts --default-non-nullable false && openapi-typescript ../../mintlify/openapi-runs.json -o src/runs.ts --default-non-nullable false",
     "build": "tsc",
     "prepack": "npm run build",
     "publish:beta": "npm test && npm publish --tag beta",