platform-types 1.10.708 → 1.10.709

package/dist/cjs/serviceOrder.js

@@ -180,6 +180,9 @@ exports.MAX_SERVICE_PICTURES = 20;
  *   someone else wrote the ticket between your read and your write, and nothing
  *   of yours was written. Refetch and let the operator retry against the new
  *   state — the body that lost was built on the old one.
+ *   `_EDIT_CHANGED` also answers a stale `expectedUpdatedAt`
+ *   ({@link ServiceOrderRevisionFence}) and carries the current row as
+ *   {@link ServiceOrderEditChangedRefusal}.
  * - `SERVICE_ORDER_ILLEGAL_TRANSITION` · 409 — the body is
  *   {@link ServiceOrderIllegalTransitionRefusal}; its `allowed[]` is the menu to
  *   offer instead.

package/dist/serviceOrder.d.ts

@@ -1170,6 +1170,109 @@ declare global {
         message: string;
         allowed: readonly ServiceCustody[];
     }
+    /**
+     * Optional revision fence on `POST /services` `mode: 'edit'` and
+     * `mode: 'diagnosis'` — request-only, never persisted or returned.
+     *
+     * Send the `updatedAt` of the {@link ServiceOrder} the operator REVIEWED
+     * (from `GET /services/{id}`, a strong read; for a row carrying no
+     * `updatedAt`, its `createdAt`). The write is refused `409
+     * SERVICE_ORDER_EDIT_CHANGED` — body {@link ServiceOrderEditChangedRefusal},
+     * nothing written — when `updatedAt` has moved since, both at the handler's
+     * read and again at the commit. A refusal at the read uploads and deletes no
+     * photo; one at the commit deletes none, but bytes already uploaded for new
+     * photos stay in storage unreferenced.
+     *
+     * **What the fence sees.** `updatedAt` moves on every write of an
+     * operator-entered field, and only those: every `POST /services` mode that
+     * writes the row — `create`, `edit`, `diagnosis`, `hold`, `quote`, `parts`,
+     * `worklog`, `timer` (the stop that books the hours), `deposit`, `status`
+     * (including the delivery mint) and `disable`. It does NOT see system
+     * bookkeeping that leaves `updatedAt` alone, deliberately so a phone is not
+     * sent back to re-review for it: the appointment link
+     * (`appointmentId`/`appointmentDate`/`appointmentTime`, written by
+     * `/appointments`), the invoice stamp (`invoiceId`, written when a factura
+     * settles or is rejected), and notification bookkeeping (`notifiedAt`,
+     * appended by `status` and `renotify`). Those fields can differ from what the
+     * client reviewed while its fenced write still succeeds.
+     *
+     * **Chained writes.** A follow-up write in the same submission — a diagnosis
+     * then a photo edit — fences on the PREVIOUS write's success response,
+     * `data.updatedAt`, never on the revision first reviewed: the first write
+     * moved it, so echoing the original value refuses the second. Both success
+     * bodies carry it — `diagnosis` returns the committed row, `edit` the row
+     * with the `updatedAt` it committed.
+     *
+     * On `diagnosis` a TERMINAL ticket still answers its own codes first
+     * (`SERVICE_ORDER_TERMINAL` at the read, `SERVICE_ORDER_STATUS_CHANGED` when
+     * it closed mid-request), and the stored `diagnosedBy`/`diagnosedAt` stay
+     * server-stamped.
+     *
+     * Absent means today's behaviour: the handler's own read is the lock (`edit`)
+     * or no revision is asserted at all (`diagnosis`).
+     */
+    interface ServiceOrderRevisionFence {
+        expectedUpdatedAt?: number;
+    }
+    /**
+     * The `409 SERVICE_ORDER_EDIT_CHANGED` body of `POST /services`
+     * `mode: 'edit'` and `mode: 'diagnosis'`. `data.current` is the stored row as
+     * a strong read returns it now — without the read-time derivations
+     * (`customer`, `depositBalance`, `slaStatus`); refetch the point read for
+     * those.
+     *
+     * `data` is absent when the row could not be re-read (both modes), and on
+     * `edit` also when the row no longer exists — refetch the point read. A
+     * fenced `diagnosis` whose row is gone answers `SERVICE_ORDER_STATUS_CHANGED`
+     * instead, as it does unfenced.
+     */
+    interface ServiceOrderEditChangedRefusal {
+        error: 'SERVICE_ORDER_EDIT_CHANGED';
+        message: string;
+        data?: {
+            current: ServiceOrder;
+        };
+    }
+    /**
+     * The body of `POST /services` `mode: 'diagnosis'`: it REPLACES the stored
+     * `diagnosis` whole. `diagnosedBy`/`diagnosedAt` are not accepted — the api
+     * stamps the authorizer user and the server time. Success answers the
+     * committed {@link ServiceOrder} as `data`.
+     *
+     * Tied to the handler's schema by `AssertServiceOrderDiagnosisRequestMatchesSchema`
+     * (`stacks/lambdas/services/_diagnosis.ts`).
+     */
+    interface ServiceOrderDiagnosisRequest extends ServiceOrderRevisionFence {
+        mode: 'diagnosis';
+        serviceOrderId: string;
+        /** Internal technician notes, 1–4000 characters. Operator-only. */
+        notes: string;
+        /** What was actually wrong, as told to the customer — at most 4000 characters. */
+        faultFound?: string;
+    }
+    /**
+     * The photo-only body of `POST /services` `mode: 'edit'` — the edit a
+     * technician's phone sends. The mode accepts more fields; this names only the
+     * photo half, so a client typed on it cannot send anything else by accident.
+     *
+     * `pictures` ABSENT means "don't touch", `[]` means "clear"; it is the WHOLE
+     * array, at most {@link MAX_SERVICE_PICTURES} entries. An entry with `base64`
+     * is a new upload (its `url` is a placeholder the api replaces); one without
+     * is a pointer to a photo already on THIS ticket, and may not change its
+     * `stage`. `removePictures` names stored photos to delete after the commit.
+     * Success answers the updated {@link ServiceOrder} as `data`.
+     *
+     * Tied to the handler's schema by `AssertServiceOrderEditPicturesRequestMatchesSchema`
+     * (`stacks/lambdas/services/_edit.ts`).
+     */
+    interface ServiceOrderEditPicturesRequest extends ServiceOrderRevisionFence {
+        mode: 'edit';
+        serviceOrderId: string;
+        pictures?: ServiceOrderPicture[];
+        removePictures?: {
+            url: string;
+        }[];
+    }
 }
 /**
  * The legal moves on a service order. Exhaustive over `ServiceStatus` by
@@ -1294,6 +1397,9 @@ export declare const MAX_SERVICE_PICTURES = 20;
  *   someone else wrote the ticket between your read and your write, and nothing
  *   of yours was written. Refetch and let the operator retry against the new
  *   state — the body that lost was built on the old one.
+ *   `_EDIT_CHANGED` also answers a stale `expectedUpdatedAt`
+ *   ({@link ServiceOrderRevisionFence}) and carries the current row as
+ *   {@link ServiceOrderEditChangedRefusal}.
  * - `SERVICE_ORDER_ILLEGAL_TRANSITION` · 409 — the body is
  *   {@link ServiceOrderIllegalTransitionRefusal}; its `allowed[]` is the menu to
  *   offer instead.

package/dist/serviceOrder.js

@@ -177,6 +177,9 @@ export const MAX_SERVICE_PICTURES = 20;
  *   someone else wrote the ticket between your read and your write, and nothing
  *   of yours was written. Refetch and let the operator retry against the new
  *   state — the body that lost was built on the old one.
+ *   `_EDIT_CHANGED` also answers a stale `expectedUpdatedAt`
+ *   ({@link ServiceOrderRevisionFence}) and carries the current row as
+ *   {@link ServiceOrderEditChangedRefusal}.
  * - `SERVICE_ORDER_ILLEGAL_TRANSITION` · 409 — the body is
  *   {@link ServiceOrderIllegalTransitionRefusal}; its `allowed[]` is the menu to
  *   offer instead.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.708",
+	"version": "1.10.709",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",