@d19n/youfibre-odin-sdk 2.0.103-beta.5 → 2.0.103-beta.7

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

@@ -0,0 +1,33 @@
+/**
+ * Wholesale provider — subpath barrel.
+ *
+ * Consumers import from `@d19n/youfibre-odin-sdk/dist/wholesale-provider`:
+ *
+ *   ```ts
+ *   import {
+ *     WholesaleProvider,
+ *     NetomniaProvider,
+ *     NetomniaProviderDeps,
+ *   } from '@d19n/youfibre-odin-sdk/dist/wholesale-provider';
+ *   ```
+ *
+ * **Architecture (Path B / pass-through delegation):**
+ * - `WholesaleProvider` is a strategy-dispatchable interface. Method names
+ *   align with VMO2 spec where it makes sense; args match existing NET
+ *   module method signatures.
+ * - `NetomniaProvider implements WholesaleProvider` — pass-through to deps
+ *   wired by modules to their existing NestJS-injected NET methods. Zero
+ *   transformation at the boundary.
+ * - VMO2-shaped types (`./types/vmo2`) and FibreCafe-shaped types
+ *   (`./types/fibrecafe`) are exported as **reference types** for future
+ *   use (Vmo2Provider implementation, module DTO consolidation). They are
+ *   NOT on the WholesaleProvider public surface in Phase 0.
+ *
+ * Linked: T-20260508-009 / T-20260508-010
+ */
+export type { WholesaleProvider, CreateOrderOptions, CancellationReasonCode, 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';
+export type { VMO2OrderId, VMO2RequestId, VMO2AppointmentKey, VMO2PremiseId, VMO2OrderNotificationType, VMO2SMRNotificationType, VMO2NotificationEnvelope, VMO2OrderNotification, VMO2SMRNotification, VMO2InboundNotification, } from './types/vmo2';
+export * from './types/fibrecafe';

package/dist/wholesale-provider/index.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Wholesale provider — subpath barrel.
+ *
+ * Consumers import from `@d19n/youfibre-odin-sdk/dist/wholesale-provider`:
+ *
+ *   ```ts
+ *   import {
+ *     WholesaleProvider,
+ *     NetomniaProvider,
+ *     NetomniaProviderDeps,
+ *   } from '@d19n/youfibre-odin-sdk/dist/wholesale-provider';
+ *   ```
+ *
+ * **Architecture (Path B / pass-through delegation):**
+ * - `WholesaleProvider` is a strategy-dispatchable interface. Method names
+ *   align with VMO2 spec where it makes sense; args match existing NET
+ *   module method signatures.
+ * - `NetomniaProvider implements WholesaleProvider` — pass-through to deps
+ *   wired by modules to their existing NestJS-injected NET methods. Zero
+ *   transformation at the boundary.
+ * - VMO2-shaped types (`./types/vmo2`) and FibreCafe-shaped types
+ *   (`./types/fibrecafe`) are exported as **reference types** for future
+ *   use (Vmo2Provider implementation, module DTO consolidation). They are
+ *   NOT on the WholesaleProvider public surface in Phase 0.
+ *
+ * Linked: T-20260508-009 / T-20260508-010
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AggregateNotificationError = exports.NetomniaProvider = void 0;
+// ── Provider implementation ───────────────────────────────────────────
+var netomnia_provider_1 = require("./providers/netomnia-provider");
+Object.defineProperty(exports, "NetomniaProvider", { enumerable: true, get: function () { return netomnia_provider_1.NetomniaProvider; } });
+Object.defineProperty(exports, "AggregateNotificationError", { enumerable: true, get: function () { return netomnia_provider_1.AggregateNotificationError; } });
+// ── Reference types (re-exported — not on WholesaleProvider surface) ──
+//
+// FibreCafe wire-format types — useful for module-level DTO consolidation
+// or building the VMO2 wire request inside a future Vmo2Provider. These
+// are NOT used by NetomniaProviderDeps in Path B; the deps shape is YF-
+// context-shaped.
+//
+// Re-exported with `export *` because TS 4.8 doesn't support `export type *`.
+// All declarations in fibrecafe.ts are types/interfaces with no runtime
+// exports, so `export *` re-exports them as types only (no JS code emit).
+__exportStar(require("./types/fibrecafe"), exports);

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

@@ -0,0 +1,112 @@
+import type { VMO2OrderNotification, VMO2SMRNotification } from './types/vmo2';
+/**
+ * Reasons a cancellation request can be made (NET wire-level enum value
+ * passed through to the FibreCafe gateway).
+ */
+export declare type CancellationReasonCode = string;
+export interface CreateOrderOptions {
+    doNotCreateServiceAppointment?: boolean;
+    externalRefBrskFno?: string;
+    externalRefBrskIsp?: string;
+    /** Provider-specific extras — populated as needed per provider. */
+    [extra: string]: unknown;
+}
+export interface ReserveAppointmentArgs {
+    yfAppointmentId: string;
+    uprn: number;
+    startDateTime: string;
+    endDateTime: string;
+    /** 'PROVIDE' / 'REPAIR' / 'MODIFY' or supplier-specific. */
+    purpose: string;
+    yfOrderId: string;
+    woProperties: {
+        ServiceCallReason?: string;
+        WorkOrderExternalReference?: string;
+    };
+}
+export interface ListAppointmentsArgs {
+    uprn: number;
+    /** ISO date the appointment search starts from. */
+    start: string;
+    appointmentPurpose: 'PROVIDE' | 'REPAIR';
+}
+export interface ScheduleServiceWorkOrderArgs {
+    yfWorkOrderId: string;
+    uprn: number;
+    startDateTime: string;
+    endDateTime: string;
+    yfOrderId: string;
+    properties: {
+        ServiceCallReason?: string;
+    };
+}
+export interface RescheduleServiceWorkOrderArgs {
+    yfWorkOrderId: string;
+    uprn: number;
+    startDateTime: string;
+    endDateTime: string;
+    yfOrderId: string;
+}
+export interface AmendAppointmentArgs {
+    yfOrderId: string;
+    yfWorkOrderId: string;
+    supplierAppointmentReference: string;
+}
+export interface SyncWorkOrderToSupplierArgs {
+    principal: unknown;
+    yfOrderId: string;
+    yfWorkOrderId: string;
+    yfChangeReason: {
+        id?: string;
+        externalId: string;
+        entity: string;
+        type: unknown;
+        properties: unknown;
+    };
+}
+export interface UpdateOrderExternalRefArgs {
+    oldYfId: string;
+    newYfId: string;
+}
+/**
+ * Capability-shaped interface to a wholesale supplier. Method NAMES align
+ * with VMO2 spec where it makes sense; ARGS match existing NET module
+ * method signatures. Each provider implementation translates these args
+ * into its supplier wire format internally.
+ *
+ * Returns are typed loosely — modules know the return shape via the dep
+ * function they wire in.
+ */
+export interface WholesaleProvider {
+    searchAddress(uprn: number): Promise<unknown>;
+    listAppointments(args: ListAppointmentsArgs): Promise<unknown>;
+    reserveAppointment(args: ReserveAppointmentArgs): Promise<unknown>;
+    scheduleServiceWorkOrder(args: ScheduleServiceWorkOrderArgs): Promise<unknown>;
+    rescheduleServiceWorkOrder(args: RescheduleServiceWorkOrderArgs): Promise<unknown>;
+    amendAppointment(args: AmendAppointmentArgs): Promise<unknown>;
+    createOrder(principal: unknown, orderId: string, options?: CreateOrderOptions): Promise<unknown>;
+    /** Tier-change CoS — wraps `createModifyOrderForYfOrder` style args. */
+    amendOrder(principal: unknown, yfOrderId: string): Promise<unknown>;
+    /** Pre-install cancel of an in-flight provide order. */
+    cancelOrder(yfOrderId: string, reasonCode: CancellationReasonCode): Promise<unknown>;
+    /** Active-customer cease (post-Active churn / OTS-losing). */
+    ceaseOrder(yfOrderId: string, serviceId: string): Promise<unknown>;
+    /** Inbound supplier KCI / notification handler. */
+    receiveKci(principal: unknown, dto: unknown): Promise<void>;
+    /** Outbound YF→supplier WO sync (cancel propagation, etc.). */
+    syncWorkOrderToSupplier(args: SyncWorkOrderToSupplierArgs): Promise<unknown>;
+    /** Inbound supplier→YF WO change application (post-receiveKci). */
+    syncWorkOrderFromSupplier(order: unknown, dto: unknown): Promise<unknown>;
+    retrieveServiceIdByUprn(uprn: number): Promise<string | null>;
+    updateOrderExternalRef(args: UpdateOrderExternalRefArgs): Promise<void>;
+    /**
+     * Register a typed handler for fanout of supplier order notifications.
+     * The webhook controller invokes `dispatchOrderNotification` on the
+     * provider after envelope-mapping; registered handlers are called in
+     * order with the normalized `VMO2OrderNotification` envelope (the
+     * SDK uses VMO2 envelope types as the cross-supplier normalization
+     * shape — easier to reason about + matches the upcoming VMO2 wire).
+     */
+    onOrderNotification(handler: (n: VMO2OrderNotification) => Promise<void>): void;
+    onSMRNotification(handler: (n: VMO2SMRNotification) => Promise<void>): void;
+}

package/dist/wholesale-provider/interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,110 @@
+/**
+ * NetomniaProvider — concrete `WholesaleProvider` for the Netomnia
+ * wholesale platform (which exposes its tenant API via the FibreCafe
+ * gateway). Same instance handles all three Netomnia-routed `OrderProvider`
+ * values (NETOMNIA / NETOMNIA_LEGACY / BRSK).
+ *
+ * **Architecture (T-20260508-009/010 — Path B):**
+ *
+ * NetomniaProvider is a **strategy-dispatch pass-through**. Its public
+ * methods take YF-context args (matching existing NET module method
+ * signatures) and delegate 1:1 to deps. The deps are wired to the
+ * existing module-level `NetomniaProvider` / `NetomniaService` methods
+ * — zero behaviour change at the call site.
+ *
+ * Why a thin pass-through is enough:
+ *   - The "abstraction value" provided is strategy dispatch — call sites
+ *     do `factory.get(provider).createOrder(...)` instead of
+ *     `if (isNetomnia) netomniaProvider.createNetomniaOrder(...)`.
+ *   - DTO-building / HTTP / PE-log emit semantics already live in the
+ *     existing NET module methods. Lifting them into the SDK (via deps
+ *     that take FibreCafe DTOs and a built-in HTTP transport) was
+ *     considered (Path A/C) but rejected for Phase 0 — that's a follow-up
+ *     standardization step we can take if/when VMO2 alignment requires it.
+ *
+ * Inbound notification handling: provider stores registered handlers
+ * in-memory. The wholesale webhook controller (T-20260508-010 Step 1d)
+ * 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 { VMO2OrderNotification, VMO2SMRNotification } from '../types/vmo2';
+/**
+ * Function-bag of dependencies the NetomniaProvider delegates to.
+ *
+ * **Deps shape mirrors the WholesaleProvider interface 1:1.** Modules wire
+ * each property to their existing NestJS-injected NET service/provider
+ * method that already takes the equivalent YF-context args. The adapter
+ * boundary is intentionally narrow: zero transformation between dep input
+ * and the existing module method's input.
+ *
+ * Example (in a module's WholesaleModule.useFactory):
+ * ```typescript
+ *   {
+ *     createOrder: (p, id, opts) => existingNetomniaProvider.createNetomniaOrder(p, id, opts),
+ *     cancelOrder: (id, reason) => existingNetomniaProvider.cancelProvideOrder(id, reason),
+ *     amendOrder: (p, id) => existingNetomniaService.createModifyOrderForYfOrder(p, id),
+ *     ...
+ *   }
+ * ```
+ */
+export interface NetomniaProviderDeps {
+    searchAddress: (uprn: number) => Promise<unknown>;
+    listAppointments: (args: ListAppointmentsArgs) => Promise<unknown>;
+    reserveAppointment: (args: ReserveAppointmentArgs) => Promise<unknown>;
+    scheduleServiceWorkOrder: (args: ScheduleServiceWorkOrderArgs) => Promise<unknown>;
+    rescheduleServiceWorkOrder: (args: RescheduleServiceWorkOrderArgs) => Promise<unknown>;
+    amendAppointment: (args: AmendAppointmentArgs) => Promise<unknown>;
+    createOrder: (principal: unknown, orderId: string, options?: CreateOrderOptions) => Promise<unknown>;
+    amendOrder: (principal: unknown, yfOrderId: string) => Promise<unknown>;
+    cancelOrder: (yfOrderId: string, reasonCode: CancellationReasonCode) => Promise<unknown>;
+    ceaseOrder: (yfOrderId: string, serviceId: string) => Promise<unknown>;
+    receiveKci: (principal: unknown, dto: unknown) => Promise<void>;
+    syncWorkOrderToSupplier: (args: SyncWorkOrderToSupplierArgs) => Promise<unknown>;
+    syncWorkOrderFromSupplier: (order: unknown, dto: unknown) => Promise<unknown>;
+    retrieveServiceIdByUprn: (uprn: number) => Promise<string | null>;
+    updateOrderExternalRef: (args: UpdateOrderExternalRefArgs) => Promise<void>;
+}
+declare type OrderNotificationHandler = (n: VMO2OrderNotification) => Promise<void>;
+declare type SMRNotificationHandler = (n: VMO2SMRNotification) => Promise<void>;
+export declare class NetomniaProvider implements WholesaleProvider {
+    private readonly deps;
+    private readonly orderHandlers;
+    private readonly smrHandlers;
+    constructor(deps: NetomniaProviderDeps);
+    searchAddress(uprn: number): Promise<unknown>;
+    listAppointments(args: ListAppointmentsArgs): Promise<unknown>;
+    reserveAppointment(args: ReserveAppointmentArgs): Promise<unknown>;
+    scheduleServiceWorkOrder(args: ScheduleServiceWorkOrderArgs): Promise<unknown>;
+    rescheduleServiceWorkOrder(args: RescheduleServiceWorkOrderArgs): Promise<unknown>;
+    amendAppointment(args: AmendAppointmentArgs): Promise<unknown>;
+    createOrder(principal: unknown, orderId: string, options?: CreateOrderOptions): Promise<unknown>;
+    amendOrder(principal: unknown, yfOrderId: string): Promise<unknown>;
+    cancelOrder(yfOrderId: string, reasonCode: CancellationReasonCode): Promise<unknown>;
+    ceaseOrder(yfOrderId: string, serviceId: string): Promise<unknown>;
+    receiveKci(principal: unknown, dto: unknown): Promise<void>;
+    syncWorkOrderToSupplier(args: SyncWorkOrderToSupplierArgs): Promise<unknown>;
+    syncWorkOrderFromSupplier(order: unknown, dto: unknown): Promise<unknown>;
+    retrieveServiceIdByUprn(uprn: number): Promise<string>;
+    updateOrderExternalRef(args: UpdateOrderExternalRefArgs): Promise<void>;
+    onOrderNotification(handler: OrderNotificationHandler): void;
+    onSMRNotification(handler: SMRNotificationHandler): void;
+    /**
+     * Internal dispatch — invoked by the wholesale webhook controller after
+     * mapping a supplier KCI to a normalized `VMO2OrderNotification` envelope.
+     * Fans out to every registered handler in registration order. Handler
+     * errors are aggregated and re-thrown after all handlers complete.
+     */
+    dispatchOrderNotification(n: VMO2OrderNotification): Promise<void>;
+    dispatchSMRNotification(n: VMO2SMRNotification): Promise<void>;
+}
+/**
+ * Aggregates errors thrown by handlers during notification dispatch so the
+ * webhook controller can surface every failure rather than masking later
+ * handlers with the first throw.
+ */
+export declare class AggregateNotificationError extends Error {
+    readonly errors: unknown[];
+    constructor(errors: unknown[]);
+}
+export {};

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

@@ -0,0 +1,124 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AggregateNotificationError = exports.NetomniaProvider = void 0;
+class NetomniaProvider {
+    constructor(deps) {
+        this.deps = deps;
+        this.orderHandlers = [];
+        this.smrHandlers = [];
+    }
+    // ── Pass-through delegation ────────────────────────────────────────
+    searchAddress(uprn) {
+        return this.deps.searchAddress(uprn);
+    }
+    listAppointments(args) {
+        return this.deps.listAppointments(args);
+    }
+    reserveAppointment(args) {
+        return this.deps.reserveAppointment(args);
+    }
+    scheduleServiceWorkOrder(args) {
+        return this.deps.scheduleServiceWorkOrder(args);
+    }
+    rescheduleServiceWorkOrder(args) {
+        return this.deps.rescheduleServiceWorkOrder(args);
+    }
+    amendAppointment(args) {
+        return this.deps.amendAppointment(args);
+    }
+    createOrder(principal, orderId, options) {
+        return this.deps.createOrder(principal, orderId, options);
+    }
+    amendOrder(principal, yfOrderId) {
+        return this.deps.amendOrder(principal, yfOrderId);
+    }
+    cancelOrder(yfOrderId, reasonCode) {
+        return this.deps.cancelOrder(yfOrderId, reasonCode);
+    }
+    ceaseOrder(yfOrderId, serviceId) {
+        return this.deps.ceaseOrder(yfOrderId, serviceId);
+    }
+    receiveKci(principal, dto) {
+        return this.deps.receiveKci(principal, dto);
+    }
+    syncWorkOrderToSupplier(args) {
+        return this.deps.syncWorkOrderToSupplier(args);
+    }
+    syncWorkOrderFromSupplier(order, dto) {
+        return this.deps.syncWorkOrderFromSupplier(order, dto);
+    }
+    retrieveServiceIdByUprn(uprn) {
+        return this.deps.retrieveServiceIdByUprn(uprn);
+    }
+    updateOrderExternalRef(args) {
+        return this.deps.updateOrderExternalRef(args);
+    }
+    // ── Inbound notification subscription ─────────────────────────────
+    onOrderNotification(handler) {
+        this.orderHandlers.push(handler);
+    }
+    onSMRNotification(handler) {
+        this.smrHandlers.push(handler);
+    }
+    /**
+     * Internal dispatch — invoked by the wholesale webhook controller after
+     * mapping a supplier KCI to a normalized `VMO2OrderNotification` envelope.
+     * Fans out to every registered handler in registration order. Handler
+     * errors are aggregated and re-thrown after all handlers complete.
+     */
+    dispatchOrderNotification(n) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const errors = [];
+            for (const h of this.orderHandlers) {
+                try {
+                    yield h(n);
+                }
+                catch (err) {
+                    errors.push(err);
+                }
+            }
+            if (errors.length > 0) {
+                throw new AggregateNotificationError(errors);
+            }
+        });
+    }
+    dispatchSMRNotification(n) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const errors = [];
+            for (const h of this.smrHandlers) {
+                try {
+                    yield h(n);
+                }
+                catch (err) {
+                    errors.push(err);
+                }
+            }
+            if (errors.length > 0) {
+                throw new AggregateNotificationError(errors);
+            }
+        });
+    }
+}
+exports.NetomniaProvider = NetomniaProvider;
+/**
+ * Aggregates errors thrown by handlers during notification dispatch so the
+ * webhook controller can surface every failure rather than masking later
+ * handlers with the first throw.
+ */
+class AggregateNotificationError extends Error {
+    constructor(errors) {
+        super(`${errors.length} handler error(s) during notification dispatch`);
+        this.errors = errors;
+        this.name = 'AggregateNotificationError';
+    }
+}
+exports.AggregateNotificationError = AggregateNotificationError;

package/dist/wholesale-provider/test/netomnia-provider.spec.d.ts

@@ -0,0 +1 @@
+export {};