@d19n/youfibre-odin-sdk 2.0.151 → 2.0.156

package/dist/wholesale-provider/index.d.ts

@@ -25,7 +25,7 @@
  *
  * Linked: T-20260508-009 / T-20260508-010
  */
-export type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, ReserveAppointmentArgs, ListAppointmentsArgs, ScheduleServiceWorkOrderArgs, RescheduleServiceWorkOrderArgs, AmendAppointmentArgs, SyncWorkOrderToSupplierArgs, UpdateOrderExternalRefArgs, } from './interface';
+export type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, CancelServiceWorkOrderArgs, ReserveAppointmentArgs, ListAppointmentsArgs, ScheduleServiceWorkOrderArgs, RescheduleServiceWorkOrderArgs, AmendAppointmentArgs, SyncWorkOrderToSupplierArgs, UpdateOrderExternalRefArgs, } from './interface';
 export type { WholesaleResult, WholesaleSyncResponse, WholesaleRejectionResponse, WholesaleRejectionMessage, WholesaleBUS, WholesaleSYS, ISO8601DateTime, ISODate, TransactionId, UPRN, UUID, SwitchOrderReference, } from './types/wholesale';
 export { NetomniaProvider, AggregateNotificationError } from './providers/netomnia-provider';
 export type { NetomniaProviderDeps } from './providers/netomnia-provider';

package/dist/wholesale-provider/interface.d.ts

@@ -30,7 +30,7 @@
  * full types are available).
  */
 import type { VMO2OrderNotification, VMO2SMRNotification } from './types/vmo2';
-import type { FibreCafeServiceAvailability200, FibreCafeAvailableAppointments200, FibreCafeReserveAppointment201, FibreCafeScheduleServiceWorkOrder201, FibreCafeRescheduleServiceWorkOrder200, FibreCafeOrderCreate202, FibreCafeOrderAmendAccept202, FibreCafeKciDto } from './types/fibrecafe';
+import type { FibreCafeServiceAvailability200, FibreCafeAvailableAppointments200, FibreCafeReserveAppointment201, FibreCafeScheduleServiceWorkOrder201, FibreCafeRescheduleServiceWorkOrder200, FibreCafeOrderCreate202, FibreCafeOrderAmendAccept202, FibreCafeKciDto, FibreCafeServiceProblemCancellationReasonCode } from './types/fibrecafe';
 /**
  * Reasons a cancellation request can be made (NET wire-level enum value
  * passed through to the FibreCafe gateway).
@@ -107,6 +107,33 @@ export interface UpdateOrderExternalRefArgs {
     oldYfId: string;
     newYfId: string;
 }
+/**
+ * Args for the tenant-initiated cancellation of an inflight SERVICE WO
+ * (REPAIR). Structurally identical to `RescheduleServiceWorkOrderArgs` —
+ * cancel is the same action shape as reschedule, just a terminal
+ * transition instead of a slot move. Same flat primitive fields; only
+ * delta is `reasonCode` in place of the timeslot fields (mirrors how
+ * `cancelOrder` carries a `reasonCode` while `createOrder` doesn't).
+ *
+ * The provider impl posts to
+ * `POST /WholesaleGateway/v1.0/gateway/service-work-orders/cancel`. NET
+ * looks up its SERVICE WO by `externalId = yfWorkOrderId` (NET stamps
+ * the YF WO uuid as externalId at create time per
+ * `scheduleServiceWorkOrder`), then drives the NET WO to Cancelled via
+ * NET field-service `/cancel-action-apply` with a tenant-originated
+ * ChangeReason. The existing SERVICE WO stage-update handler emits the
+ * UPDATE+`NETOMNIA_SERVICE_WORK_ORDER_CANCELLED` KCI back to YF.
+ *
+ * YF only commits its own SERVICE WO → Cancelled transition after this
+ * call resolves successfully (NET-first semantics — see
+ * `CancelServiceWorkOrderTenantService` in field-service module).
+ */
+export interface CancelServiceWorkOrderArgs {
+    yfWorkOrderId: string;
+    uprn: number;
+    yfOrderId: string;
+    reasonCode: FibreCafeServiceProblemCancellationReasonCode;
+}
 /**
  * Capability-shaped interface to a wholesale supplier. Method NAMES align
  * with VMO2 spec where it makes sense; ARGS match existing NET module
@@ -154,6 +181,20 @@ export interface WholesaleProvider<TPrincipal = unknown> {
     cancelOrder(yfOrderId: string, reasonCode: CancellationReasonCode): Promise<FibreCafeOrderCreate202>;
     /** Active-customer cease (post-Active churn / OTS-losing). */
     ceaseOrder(yfOrderId: string, serviceId: string): Promise<FibreCafeOrderCreate202>;
+    /**
+     * Tenant-initiated cancel of an inflight SERVICE WO. Structurally
+     * parallel to `rescheduleServiceWorkOrder` — same flat-primitive args,
+     * same response envelope shape, just a terminal transition instead of
+     * a slot move.
+     *
+     * **YF must NOT transition its SERVICE WO to Cancelled until this call
+     * resolves successfully** — the call site (`CancelServiceWorkOrderTenant
+     * Service` in field-service module) is responsible for gating the YF
+     * stage change on the response. The inbound UPDATE+CANCELLED KCI from
+     * NET (walker row `repair-update-service-cancelled`) is the secondary
+     * cure when YF didn't already advance.
+     */
+    cancelServiceWorkOrder(args: CancelServiceWorkOrderArgs): Promise<FibreCafeRescheduleServiceWorkOrder200>;
     /**
      * Inbound supplier KCI handler — the ONE inbound channel from supplier
      * to YF. KCIs drive (a) OrderKci persistence and (b) WO state changes

package/dist/wholesale-provider/kci-effect-bridge.d.ts

@@ -24,7 +24,25 @@
  * Linked: T-20260508-010 Step 3 followup (receiveKci 100% typed + handled).
  */
 import type { FibreCafeKciDto, FibreCafeKciReasonCode } from './types/fibrecafe';
-export declare type KciServiceOrderKind = 'PROVIDE' | 'CEASE' | 'MODIFY' | 'UNSOLICITED_CEASE';
+/**
+ * Discriminator for the BUSINESS KIND of a KCI — not the wire envelope shape.
+ *
+ *   PROVIDE / CEASE / MODIFY / UNSOLICITED_CEASE — typed by the populated
+ *     sub-body field on the FibreCafe envelope (`provideServiceOrder` etc.).
+ *
+ *   REPAIR — SERVICE WorkOrder state changes. NET emits these on the parent
+ *     PROVIDE envelope (the SERVICE WO is a child of the PROVIDE order in
+ *     the data model) but the semantic kind is REPAIR, discriminated by a
+ *     `NETOMNIA_SERVICE_WORK_ORDER_*` value in `supplierCodes[]`. The
+ *     envelope wire shape is a data-model artifact; the BP vocabulary is
+ *     what consumers reason about (SERVICE WO = repair / service visit).
+ *
+ * `detectKciKind()` returns REPAIR when ANY supplier code matches the
+ * `NETOMNIA_SERVICE_WORK_ORDER_*` prefix, taking precedence over the
+ * envelope-field-based PROVIDE detection so service-WO KCIs route to the
+ * REPAIR-marked bridge rows.
+ */
+export declare type KciServiceOrderKind = 'PROVIDE' | 'CEASE' | 'MODIFY' | 'UNSOLICITED_CEASE' | 'REPAIR';
 export declare type YfKciEffectKind = 'LOG_KCI_ONLY' | 'WO_FLOW_ACTION' | 'WO_SCHEDULE_APPOINTMENT' | 'PROPERTY_WRITE' | 'NO_OP_DOCUMENTED';
 export declare type YfKciTargetEntity = 'OrderModule:Order' | 'CrmModule:Address' | 'FieldServiceModule:WorkOrder';
 /**

package/dist/wholesale-provider/kci-effect-bridge.js

@@ -321,11 +321,19 @@ exports.KCI_EFFECT_ROWS = [
         },
         logAgainstOrder: true,
     },
-    // SERVICE WO
-    {
-        id: 'provide-update-service-scheduled',
+    // ═══════════════════════════════════════════════════════════════════
+    //  REPAIR — SERVICE WO state changes (post-install fault / service visit)
+    //
+    //  NET emits these on the parent PROVIDE envelope (data-model artifact:
+    //  SERVICE WO is a child of the PROVIDE order). The semantic kind is
+    //  REPAIR — discriminated by a `NETOMNIA_SERVICE_WORK_ORDER_*` value in
+    //  `supplierCodes[]`. `detectKciKind()` recognises that prefix and
+    //  returns REPAIR ahead of the envelope-field-based PROVIDE detection.
+    // ═══════════════════════════════════════════════════════════════════
+    {
+        id: 'repair-update-service-scheduled',
         reasonCode: 'UPDATE',
-        serviceOrderKind: 'PROVIDE',
+        serviceOrderKind: 'REPAIR',
         supplierCodes: ['NETOMNIA_SERVICE_WORK_ORDER_SCHEDULED'],
         yfEffect: {
             kind: 'LOG_KCI_ONLY',
@@ -334,9 +342,9 @@ exports.KCI_EFFECT_ROWS = [
         logAgainstOrder: true,
     },
     {
-        id: 'provide-update-service-en-route',
+        id: 'repair-update-service-en-route',
         reasonCode: 'UPDATE',
-        serviceOrderKind: 'PROVIDE',
+        serviceOrderKind: 'REPAIR',
         supplierCodes: ['NETOMNIA_SERVICE_WORK_ORDER_EN_ROUTE'],
         yfEffect: {
             kind: 'WO_FLOW_ACTION',
@@ -346,9 +354,9 @@ exports.KCI_EFFECT_ROWS = [
         logAgainstOrder: true,
     },
     {
-        id: 'provide-update-service-in-progress',
+        id: 'repair-update-service-in-progress',
         reasonCode: 'UPDATE',
-        serviceOrderKind: 'PROVIDE',
+        serviceOrderKind: 'REPAIR',
         supplierCodes: ['NETOMNIA_SERVICE_WORK_ORDER_IN_PROGRESS'],
         yfEffect: {
             kind: 'WO_FLOW_ACTION',
@@ -448,12 +456,38 @@ exports.KCI_EFFECT_ROWS = [
         },
         logAgainstOrder: true,
     },
+    // SERVICE-WO cancel — same REPAIR-kind UPDATE-with-supplierCode pattern
+    // as the scheduled / en-route / in-progress rows above. NET enum value:
+    // NETOMNIA_SERVICE_WORK_ORDER_CANCELLED (netomnia-supplier-code.enum.ts).
+    // Dispatcher resolves the cancel semanticOp per WO.type —
+    // SERVICE → CancelServiceWorkOrderFlowSupplier.
+    {
+        id: 'repair-update-service-cancelled',
+        reasonCode: 'UPDATE',
+        serviceOrderKind: 'REPAIR',
+        supplierCodes: ['NETOMNIA_SERVICE_WORK_ORDER_CANCELLED'],
+        yfEffect: {
+            kind: 'WO_FLOW_ACTION',
+            semanticOp: 'cancel',
+            notes: 'SERVICE WO cancelled by supplier — advance YF SERVICE WO Accepted/Scheduled/EnRoute/InProgress → Cancelled via CancelServiceWorkOrderFlowSupplier. Also the inbound confirmation when YF tenant-initiated the cancel via /service-problem-cancellations; YF WO usually already at Cancelled, action is idempotent on the WO stage.',
+        },
+        logAgainstOrder: true,
+    },
 ];
 /**
  * Determine which serviceOrder kind the KCI is about by inspecting which
  * sub-body field is populated.
  */
 function detectKciKind(dto) {
+    var _a;
+    // REPAIR check first — SERVICE WO state changes use the NETOMNIA_SERVICE_
+    // WORK_ORDER_* supplier-code discriminator, regardless of which sub-body
+    // field is populated (it's typically `provideServiceOrder` because the
+    // SERVICE WO is a child of a PROVIDE order in the data model).
+    const codes = (_a = dto.supplierCodes) !== null && _a !== void 0 ? _a : [];
+    if (codes.some((c) => c.startsWith('NETOMNIA_SERVICE_WORK_ORDER_'))) {
+        return 'REPAIR';
+    }
     if (dto.provideServiceOrder)
         return 'PROVIDE';
     if (dto.ceaseServiceOrder)

package/dist/wholesale-provider/providers/netomnia-provider.d.ts

@@ -27,7 +27,7 @@
  * invokes `dispatchOrderNotification` / `dispatchSMRNotification` after
  * envelope-mapping; registered handlers are fanned out.
  */
-import type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, ReserveAppointmentArgs, ListAppointmentsArgs, ScheduleServiceWorkOrderArgs, RescheduleServiceWorkOrderArgs, AmendAppointmentArgs, SyncWorkOrderToSupplierArgs, UpdateOrderExternalRefArgs } from '../interface';
+import type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, CancelServiceWorkOrderArgs, ReserveAppointmentArgs, ListAppointmentsArgs, ScheduleServiceWorkOrderArgs, RescheduleServiceWorkOrderArgs, AmendAppointmentArgs, SyncWorkOrderToSupplierArgs, UpdateOrderExternalRefArgs } from '../interface';
 import type { VMO2OrderNotification, VMO2SMRNotification } from '../types/vmo2';
 import type { FibreCafeServiceAvailability200, FibreCafeAvailableAppointments200, FibreCafeReserveAppointment201, FibreCafeScheduleServiceWorkOrder201, FibreCafeRescheduleServiceWorkOrder200, FibreCafeOrderCreate202, FibreCafeOrderAmendAccept202, FibreCafeKciDto } from '../types/fibrecafe';
 /**
@@ -60,6 +60,7 @@ export interface NetomniaProviderDeps<TPrincipal = unknown, TKci = FibreCafeKciD
     amendOrder: (principal: TPrincipal, yfOrderId: string) => Promise<FibreCafeOrderCreate202 | null>;
     cancelOrder: (yfOrderId: string, reasonCode: CancellationReasonCode) => Promise<FibreCafeOrderCreate202>;
     ceaseOrder: (yfOrderId: string, serviceId: string) => Promise<FibreCafeOrderCreate202>;
+    cancelServiceWorkOrder: (args: CancelServiceWorkOrderArgs) => Promise<FibreCafeRescheduleServiceWorkOrder200>;
     receiveKci: (principal: TPrincipal, dto: FibreCafeKciDto) => Promise<void>;
     syncWorkOrderToSupplier: (args: SyncWorkOrderToSupplierArgs<TPrincipal>) => Promise<void>;
     retrieveServiceIdByUprn: (uprn: number) => Promise<string | null>;
@@ -82,6 +83,7 @@ export declare class NetomniaProvider<TPrincipal = unknown> implements Wholesale
     amendOrder(principal: TPrincipal, yfOrderId: string): Promise<FibreCafeOrderCreate202>;
     cancelOrder(yfOrderId: string, reasonCode: CancellationReasonCode): Promise<FibreCafeOrderCreate202>;
     ceaseOrder(yfOrderId: string, serviceId: string): Promise<FibreCafeOrderCreate202>;
+    cancelServiceWorkOrder(args: CancelServiceWorkOrderArgs): Promise<FibreCafeRescheduleServiceWorkOrder200>;
     receiveKci(principal: TPrincipal, dto: FibreCafeKciDto): Promise<void>;
     syncWorkOrderToSupplier(args: SyncWorkOrderToSupplierArgs<TPrincipal>): Promise<void>;
     retrieveServiceIdByUprn(uprn: number): Promise<string>;

package/dist/wholesale-provider/providers/netomnia-provider.js

@@ -47,6 +47,9 @@ class NetomniaProvider {
     ceaseOrder(yfOrderId, serviceId) {
         return this.deps.ceaseOrder(yfOrderId, serviceId);
     }
+    cancelServiceWorkOrder(args) {
+        return this.deps.cancelServiceWorkOrder(args);
+    }
     receiveKci(principal, dto) {
         return this.deps.receiveKci(principal, dto);
     }

package/dist/wholesale-provider/test/netomnia-provider.spec.js

@@ -71,6 +71,7 @@ function buildDeps() {
         amendOrder: {},
         cancelOrder: {},
         ceaseOrder: {},
+        cancelServiceWorkOrder: { workOrderId: 'WO-CANC-1', appointmentId: '' },
     };
     const deps = {
         searchAddress: (uprn) => {
@@ -113,6 +114,10 @@ function buildDeps() {
             log.push({ method: 'ceaseOrder', args: [yfOrderId, serviceId] });
             return Promise.resolve(stubs.ceaseOrder);
         },
+        cancelServiceWorkOrder: (args) => {
+            log.push({ method: 'cancelServiceWorkOrder', args: [args] });
+            return Promise.resolve(stubs.cancelServiceWorkOrder);
+        },
         receiveKci: (principal, dto) => {
             log.push({ method: 'receiveKci', args: [principal, dto] });
             return Promise.resolve();

package/dist/wholesale-provider/types/fibrecafe.d.ts

@@ -430,6 +430,21 @@ export interface FibreCafeModifyServiceOrder {
     serviceOrderCancellationId?: string | number;
     serviceOrderCancellationReference?: string;
 }
+/**
+ * Codes representing the reason for cancelling an inflight service problem
+ * (FibreCafe `POST /service-problem-cancellations` request body). Used on
+ * the OUTBOUND (YF → NET) side for the tenant-initiated SERVICE WO cancel.
+ *
+ * The corresponding INBOUND state-change (NET → YF) confirming the
+ * cancellation is emitted by NET as an `UPDATE` KCI with
+ * `supplierCodes: [NETOMNIA_SERVICE_WORK_ORDER_CANCELLED]` — see the
+ * `provide-update-service-cancelled` row in kci-effect-bridge.ts.
+ *
+ * Mirrors NET's `ServiceProblemCancellationReasonCode` enum verbatim.
+ *
+ * @see {@link https://docs.thefibrecafe.net/openapi/supplier/operation/handleCancelProblem/#!path=reasonCode&t=request | FibreCafe ServiceProblemCancellationReasonCode}
+ */
+export declare type FibreCafeServiceProblemCancellationReasonCode = 'ISSUE_RESOLVED' | 'CUSTOMER_NETWORK_ISSUE' | 'NO_LONGER_REQUIRED' | 'OTHER';
 /** Unsolicited cease — supplier-initiated, surfaced via KCI. */
 export interface FibreCafeUnsolicitedCeaseServiceOrder {
     orderType?: FibreCafeCeaseOrderType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d19n/youfibre-odin-sdk",
-  "version": "2.0.151",
+  "version": "2.0.156",
   "description": "",
   "author": "@d19n",
   "license": "UNLICENSED",