Integration diagnostics

Provider-neutral diagnostic contracts shared by Hub and Admin. Requires the API integration diagnostics migrations and endpoints from the coordinated feature. The package does not replace the native integration-issue or order-export APIs.

import {
  GetDiagnosticProblems,
  GetDiagnosticProblemDetails,
  VerifyDiagnosticProblem,
  PreviewDiagnosticRecovery,
  RequestDiagnosticRecovery,
  describeDiagnostic,
} from '@deliverart/sdk-js-integration-diagnostics'

const page = await client.call(new GetDiagnosticProblems(posId, {
  query: { state: 'open', page: 1, itemsPerPage: 30 },
}))
const problem = await client.call(new GetDiagnosticProblemDetails(problemId))
const explanation = describeDiagnostic(problem.operations[0]?.evidence ?? null, 'it')
const checked = await client.call(new VerifyDiagnosticProblem(problemId))

// Build this list from the operator's explicit selection, never every open row.
const input = { requestKey: crypto.randomUUID(), operations: selectedOperations }
const preview = await client.call(new PreviewDiagnosticRecovery(posId, input))
// Display eligibility before requesting recovery. The API revalidates again.
const receipt = await client.call(new RequestDiagnosticRecovery(posId, input))

Keep the same request key when retrying a submission whose HTTP response was lost. A submitted receipt or published queue message is not business success; refresh the affected operation to observe its outcome.

GetDiagnosticOverview separates problem counts from unique affected operation counts. Never add them together. Problem summaries separately report verified success, manual handling and outstanding work: 17 successes out of 20 leave 3 operations outstanding even when the original cause has been corrected.

VerifyDiagnosticProblem performs a bounded local check with a shared cooldown. Respect scope, checked/expiry times and fresh. A present local mapping does not prove remote availability or order delivery. Refresh does not retry work.

CloseDiagnosticOperation requires the current revision and a non-blank reason. Manual handling is distinct from success and blocks future export redispatch; this initial API does not expose reopening. Do not invoke it for a whole problem when the operator has only selected one affected operation.

Unknown finding schemas become null evidence and clear evidenceComplete. Unknown recovery actions become null and ineligible previews, so newer server capabilities cannot accidentally execute through an older client. Known evidence preserves cause/affected/context roles. Resource names and authored narratives are plain text; render with normal escaping, never as HTML. Application routes, authorization, controls and realtime refresh remain owned by each consumer.

describeDiagnostic, describeVerification and diagnosticResourceName provide shared Italian/English presentation without requiring React or a MUI version. Unrecognized codes receive an incomplete-diagnosis explanation. These initial messages cover missing Cassa modifier mappings and Elephant import interruptions or partial failures, plus staged synchronization timeouts, partial errors and unconfirmed completion. These explanations describe known process outcomes without claiming a confirmed root cause. Add authored narratives alongside future contributor coverage rather than parsing technical exception strings.

Operation rows include optional native context, validated independently from failure evidence. Unknown context kinds become null; clients must not construct resource links from unrecognized shapes. describeDiagnosticOperation provides Italian/English labels for orders, staged sync scopes and imports. Order labels use the authorized native reference; routes use resourceId, never the export UUID or an arbitrary provider URL. Missing context keeps legacy rows readable. Staged sync context may include direction: inbound | outbound | null, relative to Deliverart. Labels spell out the source and destination; missing legacy values remain "Direction not recorded". Direction is descriptive and never grants retry eligibility or changes native synchronization settings.

diagnosticInvalidationRevision accepts only the diagnostic event envelope for its requested POS. Revisions are decimal strings to preserve PostgreSQL bigint precision. This event carries no findings or totals: use it to coalesce rereads, not to mutate counters locally. Reconcile snapshots after reconnects and missed messages even when revisions have already been seen.

Local menu validation findings provide field-specific, authored Italian/English explanations for names, descriptions, prices, tax, selection limits, images and references. They identify publication resources without assuming composite provider IDs are local catalog UUIDs. Incomplete evidence has its own explicit explanation. Pre-submission validation must not be presented as remote publication confirmation.

The publication_validation operation context identifies version-owned local validation. Delivery/collection context resources have localized labels. Field explanations allow partial submission: another menu portion may succeed while the reported portion was excluded. Validation success is never publication success.

Problem assistance

Assistance is a human conversation attached to a diagnostic problem. Completing assistance does not resolve the technical cause, close an operation, or retry it. GetDiagnosticAssistanceHistory returns bounded public request summaries; GetDiagnosticAssistanceDetails returns a separately paginated public timeline. Use RequestDiagnosticAssistance with a stable requestKey, and ReplyDiagnosticAssistance with a stable actionKey and the current revision. Reuse the same key and payload after an uncertain HTTP result. A conflict requires reloading the request; do not silently generate a fresh key and repeat an action.

Administrative consumers use GetDiagnosticAssistanceInternal for private notes and operator identities, and UpdateDiagnosticAssistance for assignment, public questions, completion, and notes. Notes default to internal; a customer question requires audience: 'public' and a non-empty body. Customer replies cannot choose an audience. API permissions remain authoritative; importing an administrative request class grants no access. Public schemas strip unexpected identity fields, but the API must exclude private events before pagination and serialization.

These endpoints return explicit bounded objects rather than generic API Platform collections. All read requests accept page and itemsPerPage (at most 100).

GetDiagnosticAssistanceQueue is the separate global super-admin metadata queue. It defaults to open requests, supports state/assignment/POS/integration filters, and uses standard paginated SDK results. assignment: 'mine' is resolved by the API from the current user. Queue rows contain no conversation bodies. Individual conversation reads and actions retain their own source-access requirements; a queue row must not be treated as an authorization capability.

Glovo structured remote pre-upload validation uses remote_menu_resource_*_invalid narratives. These identify provider validation, not local validation or successful publication. remote_menu_validation_details_unavailable explicitly reports incomplete evidence; neither clients nor shared copy infer an item from free text.

publication_receipt operation context names a native asynchronous menu upload. menu_publication_* guidance distinguishes rejected content, access/fetch/configuration problems, provider errors, limits and exhausted polling. Unknown outcomes explicitly require verification before another send. These descriptions do not imply successful publication for another transaction or offer an unsupported retry capability.

Common integration_* issue codes have Italian/English explanations for authentication, permission, missing references, menu validation, rejected data, daily limits and generic process failures. A known classification is described even when its precise cause remains unconfirmed. Guidance does not invent broken credentials/resources or promise automatic recovery. Unknown codes retain the safe incomplete-diagnosis fallback. diagnosticResourceName accepts an optional source service for a readable integration label and translates known operation scopes; recorded names/translations retain priority over fallback labels.

Operation action availability

Operation actions contains independent recovery/manual-closure decisions and evaluatedAt. describeDiagnosticActionAvailability translates known reasons into Italian/English. Unknown or malformed executable metadata parses as null; clients must disable actions until availability is verified. An available read is advisory: native submission still checks permissions, revision and state.

Product mapping narratives and regional resource names

Confirmed catalog_product_mapping_missing findings have Italian/English explanations distinct from modifier failures and from unverified generic codes. Names prefer the requested language, then a matching regional catalog locale (underscore and BCP-47 separators are accepted), before the existing name/language fallbacks. Regional names such as it_IT and en_GB must not degrade to UUIDs. Local mapping correction is not remote availability or automatic recovery.

Confirmed top-level variant and sales-mode mapping failures have separate shared Italian/English narratives. They do not infer product, payment or nested bundle errors. Unverified legacy codes retain the incomplete-diagnosis fallback. Operator selection remains explicit after any local correction.

Confirmed catalog_choice_mapping_missing findings have shared Italian/English explanations distinguishing the affected selected choice from its mapped modifier group. Resource snapshots identify the group and order rows, and recovery remains an explicit operator selection. Unknown or unconfirmed evidence keeps the generic incomplete-diagnosis fallback.

Bundle diagnostics distinguish missing and ambiguous component mappings using the exact owning bundle plus modifier. Removed modifier/component definitions retain historical order-group names and use separate narratives; a blind retry is not presented as a repair. These explanations are shared by Hub/Admin in Italian and English, with generic fallback for unconfirmed evidence.

describeDiagnosticResourcePath renders recorded parent relationships using the same localized resource names as the main evidence list. It returns no path for missing, ambiguous, cyclic, unnamed or excessively deep ancestry. Hub and Admin render the returned plain text through React, without interpreting resource names as HTML or guessing catalog links.

Local verification copy distinguishes a confirmed continuing mapping ambiguity from inconclusive duplicate mappings. Current checked results also explain missing mappings, unavailable resources, insufficient evidence, unsupported/unavailable checks and changed evidence. Unknown reasons keep the generic safe fallback and never expose the raw reason. Missing timestamps and stale evidence take priority over all specific advice. None of these explanations selects or submits recovery.

Requested Deliveroo menu work uses the common narrative entry point with separate codes for paused preparation, failed delivery, upload rejection, request limits, uncertain outcomes, earlier submissions still pending, and positive publication evidence requiring review. Italian and English copy never equates a matching read with completed recovery while native state or other unresolved submissions remain unverified. These explanations do not enable a retry capability; clients must keep using the API's action guards.

Staged synchronization evidence can include process_step context resources, parented to the native process. These contain only recorded allowlisted stage identifiers. Shared labels translate all CassaInCloud/Tilby steps; unknown future steps show a neutral fallback. A recorded stage is not a causal resource or a complete list of affected products, and does not grant recovery capability.

CassaInCloud inbound customer recovery uses sync_current_state. Its Italian and English confirmation explains that this creates a new full import, updates linked customers, imports missing customers and preserves the previous attempt. It also warns that local customer updates can trigger other configured synchronizations. The explanation never selects or submits an operation; current server eligibility and an explicit customer confirmation remain required. Outbound customer recovery and other staged sync kinds must not inherit this capability from their labels.

Resource labels reuse the closed synchronization-scope vocabulary for native configuration context. Unnamed process resources use a localized process label and a short reference; persisted resource names/translations still take priority. This avoids exposing a bare process UUID or an English scope key as customer copy.

Elephant lifecycle diagnostics expose integration_lifecycle operation context with integration/restaurant scope. Shared Italian/English narratives explain only an allowlisted operational code and the recorded phase. Unknown remote codes never become authored advice. The copy does not equate a cleared error with successful activation or enable retries unsupported by the API. Phase labels come from the closed native enum and remain distinct from a verified cause.

Tilby pre-send order findings use the stable tilby_seller_missing, tilby_department_mapping_missing, tilby_product_mapping_missing_for_variant, tilby_variant_mapping_missing, tilby_modifier_mapping_missing and tilby_choice_mapping_missing codes. describeDiagnostic supplies shared English and Italian recovery guidance. Resource labels preserve saved catalog/order names; configuration identifiers have shared names. These findings do not authorize a retry, certify remote existence or override uncertain-send reconciliation.

Local Tilby verification uses the same common verification envelope as other providers. Seller checks distinguish configuration_missing from local_configuration_present; the shared IT/EN presentation states explicitly that a local correction neither retries work nor proves remote configuration. Mapping checks keep the existing mapping reasons. Only fresh local results with the matching outcome/reason pair receive this explanation; unknown, stale or remote results retain their own fallback. Consumers must preserve separate operation outcomes and explicit operator selection.

Selected Tilby fiscal recovery describes its full inbound VAT/department import, preserved manual mapping resolutions, immutable prior history and separate order recovery. The explanation is gated by the exact native source/action pair.

Provider labels use diagnosticServiceName and the optional service argument of describeDiagnosticOperation. Unknown services are not echoed. Receipt service metadata is nullable and permission-scoped.

Tilby fiscal affected-resource identities use tilby:vat:<integer> for tax resources and tilby:departments:<integer> for configuration resources. The shared narrative renders their complete external ID with an IT/EN label, without treating the ID as a local entity or a confirmed cause.

Recorded Tilby menu resource labels support tilby:categories:<integer>, tilby:components:<integer> and tilby:products:<integer> with category, configuration and product kinds respectively. Components deliberately use a neutral label rather than guessing whether the local mapping is an item or modifier.

Selected Tilby customer recovery uses the tilby_sync_customers / sync_current_state narrative in IT/EN: a full customer import, retained history, possible configured downstream updates and separate order recovery.

Recorded inbound Cassa menu resources use cassa_in_cloud:<step>:<uuid> identifiers. Shared resource presentation supports category, product, composite-product, option, department and sales-mode references in Italian and English, validates kind/step pairs and keeps the full external UUID visible. These identifiers must not be used as local catalog links or treated as proof of a root cause.

Recorded Tilby menu causes

describeDiagnostic translates the stable inbound tilby_menu_* codes into Italian/English titles, historical explanations and operator next steps. Product references identify affected remote items, not local catalog links. Unsupported variation/component cases do not infer an exact modifier or choice. Guidance keeps current-state verification separate and asks operators to choose recovery actions explicitly after correcting the cause. Unknown codes retain the shared fallback.

Captured Tilby product names are displayed alongside the provider label and exact external ID. These names come from the recorded failed attempt, not a current mapping lookup. Legacy unnamed evidence remains ID-only. Labels are rendered as text; markup in provider names never becomes HTML. Newer failures for the same product/reason can update the displayed snapshot while retaining native history.

Verification may include optional findings (at most 100 typed findings). Render these under the verification timestamp, separately from historical operation evidence. An unknown/current_local_blockers result describes current local configuration and does not reconstruct the historical failure. An unknown/local_validation_passed result confirms neither historical correction nor remote delivery. Old responses without findings remain readable.

Just Eat selected recovery uses justeat_menu_submission with sync_current_state. The shared Italian/English confirmation explains full current catalog publication, preserved historical evidence, and the distinction between request acceptance, menu generation and provider-confirmed publication. Unknown publication outcomes must remain ineligible for another submission; the API owns eligibility and clients must not infer permission from this explanatory copy.

Shared publication diagnostics use provider-neutral wording for codes emitted by multiple integrations. menu_publication_queue_delivery_failed describes an unconfirmed internal delivery, not a remote rejection; its recovery guidance asks support to verify the operation before another submission.

Kitchen access preparation failures use kitchen_access_setup_failed and the integration_lifecycle context with access_setup scope. Shared Italian/English copy explains exhausted setup attempts without asserting a technical root cause or live device connectivity. Public evidence must never contain credential values. Unknown codes continue to use the common safe fallback.

Tilby department selection uses the tax rate saved in the order. A valid explicit product department takes precedence; percentage fallback requires exactly one resolved department belonging to the integration. tilby_department_mapping_ambiguous explains the operator action when multiple departments match. Verification only checks local evidence; it never retries an export or proves delivery.

Tilby order diagnostics include tilby_product_mapping_ambiguous for retained product mappings whose IDs cannot safely authorize a sale write. Display the shared narrative and the local mapping_ambiguous verification reason. A corrected local cause does not prove sale delivery or authorize an automatic retry; preserve explicit operation selection and recovery authorization in every consumer.

tilby_ingredient_mapping_unresolved identifies a raw ingredient/component association independently of a variation/value association. Use the shared narrative to name the saved ingredient, explain that it cannot be replaced by a same-name variation, and keep any recovery explicitly selected and authorized.

Remote investigations

Problem details optionally expose remoteVerification: queued/running/completed/superseded state, request/check timestamps, freshness, and bounded typed checks. VerifyDiagnosticProblem queues supported read-only investigations; existing clients and unsupported errors retain local verification. Remote checks describe current observations, never historical causation, successful order delivery, or automatic recovery. Use describeRemoteDiagnosticCheck for Italian/English explanations. Unknown check codes must remain explicitly unsupported.

Runtime and compiler libraries

The existing diagnostics runtime uses Object.hasOwn; the consuming runtime must provide it or a compatible polyfill. The ES2021 TypeScript target controls emitted syntax and does not supply built-ins. Type checking preserves the original ES2021 default libraries and adds only ES2022.Object declarations; this compiler alignment adds no runtime polyfill.