@naisys/erp-shared 3.0.0-beta.24 → 3.0.0-beta.25

package/dist/admin-types.js

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { HateoasActionSchema, HateoasLinkSchema } from "./hateoas-types.js";
+import { paginationQuery } from "./pagination-types.js";
 export const AdminInfoResponseSchema = z.object({
     erpVersion: z.string(),
     erpDbPath: z.string(),
@@ -17,8 +18,7 @@ export const AdminAttachmentItemSchema = z.object({
     createdAt: z.string(),
 });
 export const AdminAttachmentListRequestSchema = z.object({
-    page: z.coerce.number().optional().default(1),
-    pageSize: z.coerce.number().optional().default(50),
+    ...paginationQuery(50),
 });
 export const AdminAttachmentListResponseSchema = z.object({
     attachments: z.array(AdminAttachmentItemSchema),

package/dist/error-types.js

@@ -3,4 +3,10 @@ export const ErrorResponseSchema = z.object({
     statusCode: z.number().int(),
     error: z.string(),
     message: z.string(),
+    /**
+     * For 403 responses raised by a permission check, the name of the
+     * missing permission. Lets clients react structurally without having
+     * to parse the human-readable `message`.
+     */
+    missingPermission: z.string().optional(),
 });

package/dist/index.js

@@ -18,6 +18,7 @@ export * from "./operation-types.js";
 export * from "./order-revision-types.js";
 export * from "./order-run-types.js";
 export * from "./order-types.js";
+export * from "./pagination-types.js";
 export * from "./revision-diff-types.js";
 export * from "./step-run-types.js";
 export * from "./step-types.js";

package/dist/inventory-types.js

@@ -1,9 +1,9 @@
 import { z } from "zod/v4";
 import { HateoasActionTemplateSchema, HateoasLinkSchema, } from "./hateoas-types.js";
+import { paginationQuery } from "./pagination-types.js";
 // Query params for inventory list (all item instances across all items)
 export const InventoryListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).optional().default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).optional().default(20),
+    ...paginationQuery(),
     search: z.string().optional(),
 });
 // Flattened inventory item for the list

package/dist/item-instance-types.js

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { HateoasActionSchema, HateoasActionTemplateSchema, HateoasLinkSchema, HateoasLinkTemplateSchema, } from "./hateoas-types.js";
+import { paginationQuery } from "./pagination-types.js";
 import { FieldValueEntrySchema } from "./step-run-types.js";
 // Full item instance response shape
 export const ItemInstanceSchema = z.object({
@@ -36,8 +37,7 @@ export const UpdateItemInstanceSchema = z
     .strict();
 // Query params for listing item instances
 export const ItemInstanceListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).optional().default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).optional().default(20),
+    ...paginationQuery(),
     search: z.string().optional(),
 });
 // List response

package/dist/item-types.js

@@ -1,6 +1,7 @@
 import { z } from "zod/v4";
 import { FieldListResponseSchema } from "./field-types.js";
 import { HateoasActionSchema, HateoasLinkSchema, HateoasLinkTemplateSchema, } from "./hateoas-types.js";
+import { paginationQuery } from "./pagination-types.js";
 // Full item response shape
 export const ItemSchema = z.object({
     id: z.number(),
@@ -39,8 +40,7 @@ export const UpdateItemSchema = z
     .strict();
 // Query params for listing items
 export const ItemListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).optional().default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).optional().default(20),
+    ...paginationQuery(),
     search: z.string().optional(),
 });
 // List response

package/dist/order-revision-types.js

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { HateoasActionSchema, HateoasLinkSchema, HateoasLinkTemplateSchema, } from "./hateoas-types.js";
+import { paginationQuery } from "./pagination-types.js";
 // Operation summary embedded in revision GET responses
 export const RevisionOperationSummarySchema = z.object({
     seqNo: z.number(),
@@ -40,8 +41,7 @@ export const UpdateOrderRevisionSchema = z
     .strict();
 // Query params for listing revisions
 export const OrderRevisionListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).optional().default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).optional().default(20),
+    ...paginationQuery(),
     status: RevisionStatusEnum.optional(),
     includeObsolete: z
         .enum(["true", "false"])

package/dist/order-run-types.js

@@ -1,6 +1,7 @@
 import { z } from "zod/v4";
 import { HateoasActionSchema, HateoasActionTemplateSchema, HateoasLinkSchema, HateoasLinkTemplateSchema, } from "./hateoas-types.js";
 import { OperationRunStatusEnum } from "./operation-run-types.js";
+import { paginationQuery } from "./pagination-types.js";
 // Operation summary embedded in order run GET responses
 export const OperationRunSummarySchema = z.object({
     seqNo: z.number(),
@@ -65,14 +66,18 @@ export const UpdateOrderRunSchema = z
     releaseNote: z.string().max(2000).nullable().optional(),
 })
     .strict();
-// Input for completing an order run (creates item instance + closes run)
+// Input for completing an order run (creates item instance + closes run).
+// `fieldValues[].fieldSeqNo` is the per-item field sequence number — matches
+// the field-update endpoint at /items/{key}/instances/{instanceId}/fields/{fieldSeqNo}.
+// If any required item field is empty, the endpoint returns 400 with the
+// missing field labels rather than creating an invalid instance.
 export const CompleteOrderRunSchema = z
     .object({
     instanceKey: z.string().max(200).optional(),
     quantity: z.number().nullable().optional(),
     fieldValues: z
         .array(z.object({
-        fieldId: z.number().int(),
+        fieldSeqNo: z.number().int(),
         value: z.string().max(2000),
         setIndex: z.number().int().min(0).optional(),
     }))
@@ -81,8 +86,7 @@ export const CompleteOrderRunSchema = z
     .strict();
 // Query params for listing order runs
 export const OrderRunListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).optional().default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).optional().default(20),
+    ...paginationQuery(),
     status: OrderRunStatusEnum.optional(),
     priority: OrderRunPriorityEnum.optional(),
     search: z.string().optional(),
@@ -99,8 +103,7 @@ export const OrderRunListResponseSchema = z.object({
 });
 // Query params for dispatch view (operation runs across open orders)
 export const DispatchListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).optional().default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).optional().default(20),
+    ...paginationQuery(),
     status: OperationRunStatusEnum.optional(),
     priority: OrderRunPriorityEnum.optional(),
     search: z.string().optional(),

package/dist/order-types.js

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { HateoasActionSchema, HateoasLinkSchema, HateoasLinkTemplateSchema, } from "./hateoas-types.js";
+import { paginationQuery } from "./pagination-types.js";
 export const OrderStatusEnum = z.enum(["active", "archived"]);
 export const OrderStatus = OrderStatusEnum.enum;
 // Full order response shape
@@ -9,6 +10,7 @@ export const OrderSchema = z.object({
     description: z.string(),
     status: OrderStatusEnum,
     itemKey: z.string().nullable(),
+    latestApprovedRevNo: z.number().int().nullable().optional(),
     createdBy: z.string(),
     createdAt: z.iso.datetime(),
     updatedBy: z.string(),
@@ -44,8 +46,7 @@ export const UpdateOrderSchema = z
     .strict();
 // Query params for listing orders
 export const OrderListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).optional().default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).optional().default(20),
+    ...paginationQuery(),
     status: z.enum(["active", "archived"]).optional(),
     search: z.string().optional(),
 });

package/dist/pagination-types.js

@@ -0,0 +1,52 @@
+import { z } from "zod/v4";
+/**
+ * Maximum allowed pageSize for any list endpoint.
+ *
+ * Callers may request a larger pageSize, but it will be silently clamped
+ * to this value. This is documented in the OpenAPI spec via the schema
+ * description so callers can discover the limit.
+ */
+export const MAX_PAGE_SIZE = 100;
+/**
+ * Build a `pageSize` query-param schema with a documented cap.
+ *
+ * Behaviour:
+ *  - Coerces strings → numbers (querystrings are always strings).
+ *  - Rejects values < 1 (floor of 1, then defaults).
+ *  - Silently clamps oversized values to {@link MAX_PAGE_SIZE}.
+ *  - Defaults to {@link defaultValue} when omitted.
+ *
+ * Apply via the shared {@link paginationQuery} helper rather than per-route.
+ */
+export function pageSizeSchema(defaultValue = 20) {
+    return z.coerce
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .default(defaultValue)
+        .transform((n) => Math.min(n, MAX_PAGE_SIZE))
+        .describe(`Items per page. Values above ${MAX_PAGE_SIZE} are silently clamped to ${MAX_PAGE_SIZE}.`);
+}
+/**
+ * Page-number schema — coerced int >= 1, defaulting to 1.
+ */
+export function pageSchema() {
+    return z.coerce.number().int().min(1).optional().default(1);
+}
+/**
+ * Standard pagination query fields. Spread into a list-query Zod object:
+ *
+ * ```ts
+ * export const InventoryListQuerySchema = z.object({
+ *   ...paginationQuery(),
+ *   search: z.string().optional(),
+ * });
+ * ```
+ */
+export function paginationQuery(defaultPageSize = 20) {
+    return {
+        page: pageSchema(),
+        pageSize: pageSizeSchema(defaultPageSize),
+    };
+}

package/dist/user-types.js

@@ -1,4 +1,5 @@
 import { z } from "zod/v4";
+import { paginationQuery } from "./pagination-types.js";
 export const ErpPermissionEnum = z.enum([
     "erp_admin",
     "order_planner",
@@ -73,7 +74,6 @@ export const UserListResponseSchema = z.object({
     _actions: z.array(z.any()).optional(),
 });
 export const UserListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).default(20),
+    ...paginationQuery(),
     search: z.string().optional(),
 });

package/dist/work-center-types.js

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { HateoasActionSchema, HateoasLinkSchema, HateoasLinkTemplateSchema, } from "./hateoas-types.js";
+import { paginationQuery } from "./pagination-types.js";
 // Work center user assignment (embedded in detail response)
 export const WorkCenterUserSchema = z.object({
     userId: z.number(),
@@ -52,8 +53,7 @@ export const AssignWorkCenterUserSchema = z
     .strict();
 // Query params for listing work centers
 export const WorkCenterListQuerySchema = z.object({
-    page: z.coerce.number().int().min(1).optional().default(1),
-    pageSize: z.coerce.number().int().min(1).max(100).optional().default(20),
+    ...paginationQuery(),
     search: z.string().optional(),
 });
 // Work center list item (lighter response)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naisys/erp-shared",
-  "version": "3.0.0-beta.24",
+  "version": "3.0.0-beta.25",
   "description": "[internal] NAISYS ERP shared types and validation schemas",
   "type": "module",
   "files": [
@@ -20,7 +20,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@naisys/common": "3.0.0-beta.24",
+    "@naisys/common": "3.0.0-beta.25",
     "zod": "^4.3.6"
   },
   "exports": {