PriorityLab sync fails when CreateUpdateAppointment response omits confirmation

Objective

• Stop false-failed PriorityLab / Breeze appointment syncs when the vendor returns success-shaped JSON but no usable property identifier for Attik to persist.
• Reduce confusion for ops and support: work orders can still show a PriorityLab property ID from an earlier sync while priorityLab.lastError reports a failure—behavior should be understandable or self-healing where product agrees.
• Improve observability so engineering can tell vendor contract drift from transient responses without guessing.

Background

• Sync uses PriorityLab CreateUpdateAppointment (json: true). Attik treats a top-level or nested response.confirmation string as the property id returned by the vendor.
• After JSON parse, if there is no PriorityLab errors payload to throw on, but confirmation is missing or not a string, the client raises PriorityLabError: message Missing confirmation in PriorityLab response, code missing_confirmation, retryable.
• syncPriorityLabAppointment only persists _priorityLabPropertyId after createOrUpdateAppointment returns a property id; on failure it records priorityLab.lastError and does not clear an existing stored id—so the Integrations tab can still show a property id from a prior successful run while the latest attempt failed.
• Root cause for a given failure is not determined in code alone: the vendor may omit confirmation, return a different shape, or use a non-string value; Decision needed whether to widen parsing, treat no-op updates differently, or escalate to PriorityLab with captured payloads.

Scope

Backend

• attik-backend/src/util/functions/priorityLab/priorityLabApi.ts — parseVendorResponse, createOrUpdateAppointment, and PriorityLabError construction; today confirmation must be a string or the error fires.
• attik-backend/src/util/functions/priorityLab/syncPriorityLabAppointment.ts — upsert path calls createOrUpdateAppointment via tryUpsert; success clears lastError and writes _priorityLabPropertyId; failure records lastError only.
• attik-backend/src/util/functions/priorityLab/buildPriorityLabPayload.ts — payload sent on create vs update (existing propertyId passed through when present); relevant if product wants idempotent behavior when response omits confirmation.
• attik-backend/src/routes/inspection.ts — enqueues queuePriorityLabJob after qualifying inspection saves (see import from ../events/bullmq/priorityLabQueues.js).
• attik-backend/src/events/bullmq/priorityLabQueues.ts — priorityLabAppointment BullMQ queue/worker wiring, retry/backoff defaults, and invocation of syncPriorityLabAppointment; relevant if logging or failure classification should change at the job boundary.
• Decision needed: log sanitized raw response text (or structured fields) on missing_confirmation for support; Decision needed whether retry should differ from other PriorityLabError codes.

Product / partner

• Align with PriorityLab / Breeze on whether confirmation is always returned on success for create and update paths, and whether alternate keys exist in production.

References

• attik-backend/src/util/functions/priorityLab/priorityLabApi.ts
• attik-backend/src/util/functions/priorityLab/syncPriorityLabAppointment.ts
• attik-backend/src/util/functions/priorityLab/buildPriorityLabPayload.ts
• attik-backend/src/routes/inspection.ts
• attik-backend/src/events/bullmq/priorityLabQueues.ts