@cutoptim/engine 1.3.0 → 1.6.0

package/dist/types.gen.d.ts

@@ -402,6 +402,10 @@ export interface Part2D {
     meta?: Record<string, unknown>;
     /** The row's id, so a `matchedSets` layout can name it. Any JSON value is accepted here. Only an id a set REFERS TO is checked: it must be a non-empty string of printable characters, at most 64 long, or a safe integer (`7` and `"7"` are the same id), and it must be on exactly one part. Every other id is ignored, whatever it holds (a float, an object, null, repeated, long, empty): always without a non-empty `matchedSets`, and on the rows no set names with one — so an ERP article number is safe to send. */
     id?: unknown;
+    /** QR payload template for every copy of this row: returned resolved in `labels[].qr` and printed as a QR code (error correction level M) on each of the row's labels in `labelsPdf`. Exactly two tokens are filled in: `{piece}` (the copy, 1-based — the `k` of the `k/n` printed on the label) and `{of}` (the row's `qty`); any other `{…}` stays as sent. At most 300 UTF-8 bytes once filled in, printable characters only (no control characters); not together with `qrs`. A wrong value is a 400 `invalid_request` naming the field, before any quota is used. Metadata only: it never changes the plan or `planHash`. On a small label format a long payload can print below 0.4 mm per module, and `warnings` then says so. 2D only. */
+    qr?: string;
+    /** One QR payload per copy of this row, used verbatim: copy `k` (the `k/n` printed on its label) gets entry `k`, in `labels[].qr` and on `labelsPdf`. Exactly `qty` entries (`qty` defaults to 1), each 1 to 300 UTF-8 bytes of printable characters; not together with `qr`. A wrong value is a 400 `invalid_request` naming the field, before any quota is used. 2D only. */
+    qrs?: Array<string>;
 }
 /** Parts cut out of ONE piece of board, side by side or one above the other, exactly one kerf apart, so the figure of the veneer runs on across them (a drawer front over two doors). The set travels through the optimizer as one rectangle — the block — and comes back as its members. Every refusal is a 400 before the quota is reserved; a size mismatch is a warning (`matchedSets[].warnings`), not an error. At most 24 members per set; a part can be in one set only. Engines `heuristic` and `balanced` (which does not rank `priority`, so under `respectStock` a set can lose its place there); `max` refuses a request with sets (400 `details.unsupported`). */
 export interface MatchedSet {
@@ -477,10 +481,58 @@ export interface Options2D {
     effort?: "fast" | "balanced";
     /** A boolean. With `matchedSets` and the `svg` export: draw the dashed frame and the "SET A" badge of every set instance, in ONE separate group (`<g id="matched-sets" data-role="annotation">`) a laser or CNC import can drop in one move. `false` leaves that group out (the position codes in the part labels stay). Read only in a request with sets — there a value other than `true`, `false` or `null` is a 400; without sets the field is ignored, whatever it holds. */
     setOutlines?: boolean;
+    labels?: LabelOptions;
+}
+/** Label settings — the same settings as the Label format panel of the CutOptim app, under these names. They shape `labelsPdf` and add `piece`, `of`, `sheetNo`, `stockRow` and `sheetMeta` to every `labels[]` entry. Every field is optional; `{}` is valid and only adds those fields. Absent: the label PDF is the A4 sheet and `labels[]` is exactly as without this object. Validated STRICTLY, unlike the rest of `options`: an unknown key, a wrong type or a value out of range is a 400 `invalid_request` with `details.path`, before any call is counted (also on `/v1/validate/2d`). `null` for a field means the field is absent. Sent without `include` `labels` or `labelsPdf`, it changes nothing and the answer says so in `warnings`. 2D only. */
+export interface LabelOptions {
+    /** `sheet` = the A4 sheet of labels (3 columns); `roll` = one label per page, `width` × `height` mm, for a label printer; `apli-03056` = APLI 03056 sheets (24 labels of 64.6 × 33.9 mm on A4, 3 × 8); `brother-dk-11201` = Brother DK-11201 roll labels (29 × 90 mm, one per page). */
+    format?: "sheet" | "roll" | "apli-03056" | "brother-dk-11201";
+    /** Label width in mm, `roll` only. */
+    width?: number;
+    /** Label height in mm, `roll` only. */
+    height?: number;
+    offset?: LabelOffset;
+    /** Size of the dimension text on the label. */
+    dimSize?: "normal" | "large" | "xl";
+    /** Print the part number, top left and largest: the 1-based row of the FIRST `parts` row with that name (rows sharing a name share a number; with unique names it equals `labels[].partNo`). */
+    partNo?: boolean;
+    /** `input` = labels in `parts` order; `cut` = sheet by sheet, in the order the saw plan frees the pieces. */
+    order?: "input" | "cut";
+    /** Work stages printed as a row of circles to tick off by pen; empty or absent = no row. Each entry is a built-in key — `rc` (rough cut), `c2s` (cut to size), `eb` (edge banded, printed only on a banded part), `s` (sanded), `d` (drilled, not printed yet) — or free text of at most 6 characters, printed as sent (keys are lower case: `RC` is free text). Spaces are trimmed; printable characters only. */
+    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). */
+    factoryEdges?: boolean;
+    /** Print the "hidden side" mark. */
+    hiddenFaceHint?: boolean;
+    /** Print only the labels of these part numbers (the numbers `partNo` prints), e.g. to re-print after sanding. Empty or absent = all. */
+    parts?: Array<number>;
+}
+/** 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";
@@ -572,7 +624,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. */
@@ -640,6 +694,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>;
@@ -835,6 +890,18 @@ export interface Label2D {
     };
     /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
     meta?: Record<string, unknown>;
+    /** Which copy of its `parts` row this piece is, 1-based, counted in plan order (sheet, then placement). Present only when the request sends `options.labels`. */
+    piece?: number;
+    /** The `qty` of its `parts` row (the label prints `piece/of`). Present only when the request sends `options.labels`. */
+    of?: number;
+    /** The sheet number printed on the label: `sheet` + 1. Present only when the request sends `options.labels`. */
+    sheetNo?: number;
+    /** Index into the request `stock` array of the row this sheet was cut from. Present only when the request sends `options.labels`. */
+    stockRow?: number;
+    /** The `meta` of that stock row, verbatim (the same as `sheets[sheet].meta`). Present only when the request sends `options.labels` and the stock row has `meta`. */
+    sheetMeta?: Record<string, unknown>;
+    /** The resolved QR payload of this copy (`parts[].qr` with `{piece}` / `{of}` filled in, or its `parts[].qrs` entry) — the text the code on `labelsPdf` encodes. Present only when its `parts` row sends `qr` or `qrs`. */
+    qr?: string;
 }
 /** Linear metres of edge banding the order consumes, grouped by the caller-supplied type reference and reported per part AND as an order total. Present ONLY when at least one part requested banding, so a banding-free response omits the key. Exact geometry, no waste margin — the workshop adds its own. ⚠️ The metres ASSUME MILLIMETRE input: top and bottom edges run the part width, left and right run the height, multiplied by qty, divided by 1000. This is the one response figure named for a unit (edge banding is bought by the metre, and the division only means metres in millimetres); in another unit the raw edge length is w/h × qty and these numbers are that divided by 1000. 2D only. */
 export interface EdgeBanding {

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 e29a45d3c07667cf676ceb46a7c24ec3203683e50f72ba25f0677ac4af140c71 · @cutoptim/engine 1.3.0
+// contract 1 · spec sha256 1beced81a2f12873172a0604149dc98c83a333af239a76adc6dca082be878875 · @cutoptim/engine 1.6.0
 export {};

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.3.0";
+export declare const VERSION = "1.6.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.3.0';
+export const VERSION = '1.6.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cutoptim/engine",
-  "version": "1.3.0",
+  "version": "1.6.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>",