@cutoptim/engine 1.5.0 → 1.8.0

package/dist/types.gen.d.ts

@@ -190,6 +190,10 @@ export interface NestStock {
     exclusions?: Array<NestZone>;
     /** Echoed on every sheet cut from this stock row. */
     meta?: Record<string, unknown>;
+    /** Marker mode: this row is a ROLL of width `w` and free length (fabric, leather, film, any roll good). Give `w` only — no `h`, `polygon` or `exclusions` — and make it the only stock row. The answer is ONE sheet `w` wide whose `h` is the shortest length found (also `metrics.length`), edge gap included at both ends. Both engines: `lbf` answers synchronously; `max` (async) starts from that marker and spends `options.timeBudgetMs` on a strip search that may shorten it, never lengthen it. */
+    roll?: boolean;
+    /** With `roll` only: the longest the marker may be (at most 200000). Parts that do not fit within it are returned in `unplaced` — a roll never becomes a second sheet. Omit it and the length is unbounded up to 200000. */
+    maxLength?: number;
 }
 /** Solve options. All optional. */
 export interface NestOptions {
@@ -288,6 +292,8 @@ export interface NestMetrics {
     cutLength: number;
     /** Σ `sheets[].pierces`. */
     pierces: number;
+    /** Present only for a `roll` (marker mode): the marker length — the `h` of the one sheet, from the roll start to the far edge gap, rounded up to 0.001, in your unit. 0 when no part fits the roll width. */
+    length?: number;
 }
 /** Sheets used per request stock ROW ("quantity per sheet size"). The unit is the row, not the size: two rows with the same w × h but a different price or meta are two entries. */
 export interface NestStockUsage {
@@ -313,6 +319,17 @@ export interface UnplacedNest {
     name: string;
     /** How many copies could not be placed. */
     qty: number;
+    /** Only in `unplaced`, and only when the engine can tell. `too_large`: the part alone fits no rectangular sheet of its material — its bounding box plus the edge gap (`edgeClearance`, else `minSeparation`) on both sides is bigger than the sheet at every allowed rotation; `minSheet` says what would fit. `no_room`: it fits a sheet on its own, but no sheet had room left (limited stock with `respectStock`, spacing, the other parts). Absent when the job has a polygon sheet the part does not obviously fit. */
+    reason?: "too_large" | "no_room";
+    /** With `reason: "too_large"` only: the smallest rectangular sheet that holds this part alone, edge gap included on both sides, at the allowed rotation with the smallest bounding box. Rounded up to 0.001. */
+    minSheet?: {
+        /** Minimum sheet width. */
+        w: number;
+        /** Minimum sheet height (length). */
+        h: number;
+        /** The rotation, in degrees, these dimensions are for. */
+        rotation: number;
+    };
 }
 /** One material's totals across the sheets cut from it. */
 export interface NestMaterialSummary {
@@ -502,10 +519,15 @@ export interface LabelOptions {
     stages?: Array<string>;
     /** Your own word for a built-in stage key, at most 6 characters; empty or absent = the English abbreviation (RC, C2S, EB, S, D). */
     stageWords?: {
+        /** Your word for `rc` (rough cut); default RC. */
         rc?: string;
+        /** Your word for `c2s` (cut to size); default C2S. */
         c2s?: string;
+        /** Your word for `eb` (edge banded); default EB. */
         eb?: string;
+        /** Your word for `s` (sanded); default S. */
         s?: string;
+        /** Your word for `d` (drilled); default D. */
         d?: string;
     };
     /** Mark FE on the edges of a piece that lie on a sheet edge with no `trim` on that side (the board's factory edge). */
@@ -517,12 +539,17 @@ export interface LabelOptions {
 }
 /** Printer offset in mm: moves everything printed on the label right (`x`) and down (`y`); negative values move it back. Applied rounded to 0.1 mm. */
 export interface LabelOffset {
+    /** Shift right in mm (negative = left). */
     x?: number;
+    /** Shift down in mm (negative = up). */
     y?: number;
 }
 export interface Optimize2DRequest {
+    /** The rectangular parts to cut, one row per part type (`w`, `h`, optional `qty`, `name`, grain, edge banding). */
     parts: Array<Part2D>;
+    /** The sheet sizes to cut from, one row per size (`w`, `h`, optional `qty`, `price`). */
     stock: Array<Stock2D>;
+    /** Kerf, trim, first-cut direction, cost and stock rules, effort and label output; every field is optional. */
     options?: Options2D;
     /** Which optimizer to run. `heuristic` is the guillotine multi-strategy packer: highest yield, every layout edge-to-edge saw-cuttable, always a full `cutPlan`. `balanced` is a MaxRects free-nesting packer: much faster on large jobs for a small yield cost, but its layouts are often not guillotine (`guillotineValid: false`, `cutPlan: null`), and it does not model `tolerance`, `minimizeCost`, `grainGroup`, `maxCutStages` or `minimizeRotations` — set one of those and a string in `warnings` tells you it was ignored. `max` is the ASYNCHRONOUS tree-search tier (2D only): it reaches the proven optimum on far more jobs at the cost of seconds-to-a-minute per solve, so instead of a plan it returns **202** with a `jobId` — poll `GET /v1/jobs/{id}` for the result. Still deterministic and guillotine-valid. Where the tier is not enabled on a deployment, `engine: "max"` fails closed with **503**. **What `max` models.** It packs ONE stock format at full sheet size with unlimited supply and a fixed 3-stage guillotine pattern. Anything that would make the returned plan physically WRONG is therefore REFUSED with **400** at submission — before a call is reserved and before you wait for the solve: a second `stock` row, `options.trim`, `options.respectStock`, any `material`, any `grainGroup`, a non-empty `matchedSets` (an empty one is fine). Options that only make the plan less tuned are accepted and listed in `warnings`: `tolerance`, `minimizeCost`, `maxCutStages` (fixed at 3), `minimizeRotations`, `firstCut`, `effort`. A `max` result reports no `offcuts`. Send those jobs to `heuristic`. The default never changes silently. */
     engine?: "heuristic" | "balanced" | "max";
@@ -614,7 +641,9 @@ export interface Options1D {
     mitrePairing?: boolean;
 }
 export interface Optimize1DRequest {
+    /** The lengths to cut, one row per part type (`length`, optional `qty`, `name`, mitred `ends`). */
     parts: Array<Part1D>;
+    /** The bar lengths to cut from, one row per length (`length`, optional `qty`, `price`). */
     stock: Array<Stock1D>;
     options?: Options1D;
     /** `max` is not offered here: it is a 2D (and, separately, nesting) tier, and `engine: "max"` on this path is a **400** before a call is charged. In 1D `balanced` resolves to the same packer as `heuristic` — the linear packer is already a best-of-multiple-strategies search, so there is no separate balanced mode. The value is accepted and echoed back so a single client can send one engine id for both endpoints. */
@@ -682,6 +711,7 @@ export interface OptionsWood {
     mitrePairing?: boolean;
 }
 export interface OptimizeWoodRequest {
+    /** The timber parts to cut, one row per part type: cross-section `sw` × `sh`, `length`, optional `qty`. */
     parts: Array<PartWood>;
     /** At most 50 rows. Since every cross-section needs at least one stock row, this is also the practical ceiling on cross-sections in a single job; a wider catalogue should be split into several requests. */
     stock: Array<StockWood>;
@@ -1171,6 +1201,24 @@ export interface UsageResponse {
     env?: "test";
     /** Present (`"tenant"`) only for a key CutOptim issues to its own first-party service. Absent for every key you create in the dashboard. */
     keyClass?: "tenant";
+    trial?: UsageTrial;
+}
+/** Present only for a TEST key of an account without an Engine API subscription: such a key runs inside a free trial. While it is present, `used`, `limit` and `remaining` count the whole trial (not a calendar month) and `periodEnd` is the trial's last day. After `endsAt` every call answers 403 `key_revoked` with a message that names the trial. Absent for live keys and for test keys of a subscribed account. */
+export interface UsageTrial {
+    /** When the trial ends (UTC timestamp). */
+    endsAt: string;
+    /** Calls allowed in the whole trial, across all the account's test keys. */
+    callsLimit: number;
+    /** Calls counted since the trial started. Refused and refunded calls are not counted. */
+    callsUsed: number;
+    /** `callsLimit` − `callsUsed`, never negative. */
+    callsRemaining: number;
+    /** Asynchronous engine `max` jobs allowed in the trial. Failed jobs are not counted. */
+    maxJobsLimit: number;
+    /** Engine `max` jobs submitted since the trial started (queued, running or succeeded). */
+    maxJobsUsed: number;
+    /** `maxJobsLimit` − `maxJobsUsed`, never negative. At 0 a new `max` job answers 402 `quota_exceeded`; engine `lbf` keeps working. */
+    maxJobsRemaining: number;
 }
 export interface HealthResponse {
     /** Always `"healthy"` when the process answers. */

package/dist/types.gen.js

@@ -1,3 +1,3 @@
 // GENERATED by scripts/gen-sdks.ts from the CutOptim Engine API OpenAPI document — DO NOT EDIT.
-// contract 1 · spec sha256 57abd7b68ca9e86fe7040dd2e979516274a2bdea5394258959f21bbefc28f624 · @cutoptim/engine 1.5.0
+// contract 1 · spec sha256 3ee9cdfbd131610871eac13aacdd1739434688a0e4743ab71c9373d089ea232c · @cutoptim/engine 1.8.0
 export {};

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.5.0";
+export declare const VERSION = "1.8.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The package version — rewritten by scripts/gen-sdks.ts together with package.json (sent as the User-Agent).
-export const VERSION = '1.5.0';
+export const VERSION = '1.8.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cutoptim/engine",
-  "version": "1.5.0",
+  "version": "1.8.0",
   "description": "Official client for the CutOptim Engine API — cutting optimization (2D panels, 1D linear, timber, true-shape nesting) over HTTPS.",
   "license": "MIT",
   "author": "CutOptim <support@cutoptim.com>",