@solvice/routing 0.17.0-beta.0 → 0.17.2-beta.0

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
@@ -877,8 +892,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,
@@ -1354,7 +1370,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.
@@ -2017,6 +2034,7 @@ export interface components {
          *         "tag_preference": 0,
          *         "target": 0,
          *         "time": 57.1536,
+         *         "vehicles": 0,
          *         "waiting": 0,
          *         "window_choice": 0,
          *         "workload_share": 0
@@ -2073,6 +2091,7 @@ export interface components {
          *       "tag_preference": 0,
          *       "target": 0,
          *       "time": 57.1536,
+         *       "vehicles": 0,
          *       "waiting": 0,
          *       "window_choice": 0,
          *       "workload_share": 0
@@ -2128,7 +2147,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 +2169,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 +2307,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 +2433,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.
@@ -2723,10 +2796,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"];
@@ -2966,6 +3039,7 @@ export interface components {
          *             "tag_preference": 0,
          *             "target": 0,
          *             "time": 57.1536,
+         *             "vehicles": 0,
          *             "waiting": 0,
          *             "window_choice": 0,
          *             "workload_share": 0
@@ -3299,6 +3373,7 @@ export interface components {
          *           "tag_preference": 0,
          *           "target": 0,
          *           "time": 57.1536,
+         *           "vehicles": 0,
          *           "waiting": 0,
          *           "window_choice": 0,
          *           "workload_share": 0
@@ -3361,15 +3436,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;
             /**
@@ -3722,7 +3796,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 +3826,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 +3869,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 +4226,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 +4375,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 +4494,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 +4645,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.0-beta.0",
+  "version": "0.17.2-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",