@bisondesk/core-sdk 1.0.644 → 1.0.646

package/src/types/transports.ts

@@ -1,9 +1,15 @@
-import { LocationValue, NextList, PaginatedList } from '@bisondesk/commons-sdk/types';
+import { GPSCoord, NextList, PaginatedList } from '@bisondesk/commons-sdk/types';
 import { Organization } from './crm.js';
-import { Opportunity } from './opportunities.js';
-import { DeliveryTypes } from './quotes.js';
+import { BaseEvent } from './internal-events.js';
+import { Opportunity, OpportunityPaymentStatus } from './opportunities.js';
+import {
+  AddressDeliveryType,
+  DeliveryTypes,
+  PickUpDeliveryType,
+  PortDeliverytype,
+} from './quotes.js';
 import { BaseSearchRequest, SortOrder } from './search.js';
-import { ReferenceData } from './utils.js';
+import { DataRecord, ReferenceData } from './utils.js';
 import { Vehicle, VehiclePurchase } from './vehicles.js';
 
 export enum TransportType {
@@ -42,49 +48,66 @@ export enum TransportPriority {
   Urgent = 'URGENT',
 }
 
-export const TransportDeliveryType = {
+export const TransportSalesDeliveryType = {
   Address: DeliveryTypes.ADDRESS,
   Port: DeliveryTypes.PORT,
   PortAndShip: DeliveryTypes.PORT_AND_SHIP,
+  PickUp: DeliveryTypes.PICK_UP,
 } as const;
 
-export type TransportDeliveryType =
-  (typeof TransportDeliveryType)[keyof typeof TransportDeliveryType];
+/**
+ * The customer collects the vehicle. Nothing is driven anywhere, but the papers still have to be
+ * arranged and paid for — transit plates, technical control, insurance — which is why it is a
+ * delivery type administration reviews rather than the absence of one.
+ *
+ * `dateOfPickUpByCustomer` is dropped from the quote's shape: the transport's own `date` is the
+ * collection day, and two fields for one date only ever disagree.
+ */
+export type TransportPickUpDeliveryType = Omit<PickUpDeliveryType, 'dateOfPickUpByCustomer'>;
+
+export type TransportSalesDeliveryType = (
+  | PortDeliverytype
+  | AddressDeliveryType
+  | TransportPickUpDeliveryType
+) & {
+  cleaningNeeded?: boolean;
+  driver?: string;
+  transportCompany?: string;
+  date?: string; // Pick-up (purchase) | Delivery (OPP) (leaves parking)
+  adminCost?: string; // user-entered administrative cost summed into totalCostExclVat
+  stackingVehicleCostPrice?: string; // overrides the stacking rate from the delivery settings
+};
+
+export type TransportPurchaseDeliveryType = AddressDeliveryType & {
+  cleaningNeeded?: boolean;
+  driver?: string;
+  transportCompany?: string;
+  date?: string; // Pick-up (purchase) | Delivery (OPP) (leaves parking)
+  adminCost?: string; // user-entered administrative cost summed into totalCostExclVat
+  stackingVehicleCostPrice?: string; // overrides the stacking rate from the delivery settings
+};
 
 export type Transport = {
   id: string;
   vehicleId: string;
   opportunityId?: string;
 
-  type: TransportType;
-  deliveryType: TransportDeliveryType;
   status: TransportStatus;
-
   priority: TransportPriority;
 
   // administrative fields
   adminApproved: boolean;
-
+  adminApprovedAt?: string;
+  adminApprovedBy?: string;
+  transportWithoutPayment?: boolean;
   notes?: string;
 
-  // semi-trailer specific fields
-  cleaningNeeded?: boolean;
-  stacking?: boolean;
-  stackingDetails?: string;
-
-  port?: {
-    sourcePort?: string;
-    destinationPort?: string;
-
-    deliveryLocation?: string;
-    bookingRef?: string;
-    shippingCompany?: string;
-    ets?: string;
-    eta?: string;
+  totals: {
+    totalRetailAmountExclVat: string;
+    totalCostExclVat: string;
+    estimatedTotalCostExclVat?: string;
   };
 
-  address?: LocationValue;
-
   log: Array<{
     status: TransportStatus;
     completedAt: string;
@@ -100,7 +123,16 @@ export type Transport = {
   createdBy: string;
   updatedAt: string;
   updatedBy: string;
-};
+} & (
+  | {
+      type: TransportType.PurchasePickUp;
+      delivery: TransportPurchaseDeliveryType;
+    }
+  | {
+      type: TransportType.SaleDelivery;
+      delivery: TransportSalesDeliveryType;
+    }
+);
 
 export enum TransportWarningCode {
   PurchaseLogisticsNotReady = 'purchase_logistics_not_ready',
@@ -111,15 +143,108 @@ export type TransportWarning = {
   details?: Record<string, string | number | boolean>;
 };
 
+export type TransportCost = Pick<Transport, 'totals'>;
+
+export type TransportRecord = DataRecord<Transport>;
+
+/**
+ * What a requester may change on a transport, field group by field group. The server filters an
+ * update through these and returns the ones granted on the record, so the drawer disables what the
+ * user cannot touch instead of deciding for itself from the user's roles.
+ */
+export enum TransportActions {
+  /** The route: addresses, ports, dates, costs. */
+  SetDelivery = 'set_delivery',
+  SetNotes = 'set_notes',
+  /** The administrative sign-off, and the clearance to move before the payment. */
+  SetApproval = 'set_approval',
+  /** The board column. */
+  SetStatus = 'set_status',
+  SetPriority = 'set_priority',
+  SetBookingRef = 'set_booking_ref',
+}
+
+/**
+ * Every field a write may set, in one shape. `delivery` is replaced whole when it is sent — there is
+ * no partial merge into the stored one — which is why `bookingRef` rides alongside as a scalar the
+ * server writes into the delivery it ends up with.
+ */
+export type TransportUpdate = {
+  delivery?: TransportSalesDeliveryType | TransportPurchaseDeliveryType;
+  notes?: string | null;
+  adminApproved?: boolean;
+  transportWithoutPayment?: boolean;
+  status?: TransportStatus;
+  priority?: TransportPriority;
+  bookingRef?: string | null;
+};
+
+type BaseTransportEvent = {
+  actionAt: string;
+  userId: string;
+  tenantId: string;
+  transportId: string;
+};
+
+export type TransportCreateEvent = BaseTransportEvent & {
+  action: 'create';
+  data: Transport;
+  previousData?: undefined;
+};
+
+export type TransportUpdateEvent = BaseTransportEvent & {
+  action: 'update';
+  data: Transport;
+  previousData: Transport;
+};
+
+/** Published whenever a transport is written. Carries both sides so subscribers judge relevance. */
+export type TransportEvent = BaseEvent & (TransportCreateEvent | TransportUpdateEvent);
+
+/**
+ * Where the money stands on the record the transport serves: the customer's payments on the
+ * opportunity for a sale delivery, ours to the supplier for a purchase pick-up. Denormalised at
+ * indexing time so the board can show it without joining.
+ */
+export type TransportPayment = {
+  status: OpportunityPaymentStatus;
+  /** Only a sale delivery knows the ratio — a pick-up has milestones, not a running total. */
+  percentagePaid?: string;
+};
+
+/** Which address the map pin came from, so the UI can tell an exact pin from an approximate one. */
+export enum TransportLocationSource {
+  DeliveryAddress = 'delivery_address',
+  OriginPort = 'origin_port',
+  OrgAddress = 'org_address',
+}
+
 export type SearchTransport = {
   transport: Transport;
   vehicle: Vehicle;
   org: Organization;
   opportunity?: Opportunity;
   purchase: VehiclePurchase;
+  tasks: {
+    totalTasks: number;
+    openTasks: number;
+    nextDueAt?: string;
+  };
   custom: {
     commercialUserIds: string[];
     warnings: TransportWarning[];
+    priorityOrdinal: number;
+    payment: TransportPayment;
+    /**
+     * Where the transport happens: the delivery address, or the origin port for a shipped delivery.
+     * Denormalised into one field because the map clusters over a single geo_point, and a port
+     * delivery carries no address of its own.
+     *
+     * Deliberately narrower than `GPSCoord`: a geo_point field rejects any key beyond lat/lon, so
+     * the map zoom the coordinates picker stores must not reach the index.
+     */
+    location?: Pick<GPSCoord, 'lat' | 'lon'>;
+    locationSource?: TransportLocationSource;
   };
 };
 

package/src/types/vehicles.ts

@@ -142,6 +142,7 @@ export type NewVehicleRequest = {
     deliveryType?: VehiclePurchaseDeliveryType;
     pickupAddress?: LocationValue;
     status: VehiclePurchaseLogisticsStatus;
+    transportWithoutPayment?: boolean;
   };
   prices: {
     minimum?: string;
@@ -855,6 +856,7 @@ export type VehiclePurchase = {
     deliveryType?: VehiclePurchaseDeliveryType;
     pickupAddress?: LocationValue;
     availableWeek?: string; // ISOWEEK, e.g. 2016-W02
+    transportWithoutPayment?: boolean;
   };
 };
 

package/src/utils/search.ts

@@ -5,6 +5,7 @@ import { LeasingContract } from '../types/leasing.js';
 import { DebtorsDossier, SearchDebtorsDossier } from '../types/leasing-debtors.js';
 import { SearchLeasingContract } from '../types/leasing-search.js';
 import { Opportunity, SearchOpportunity } from '../types/opportunities.js';
+import { SearchTransport, Transport } from '../types/transports.js';
 import { SearchVehicle, Vehicle } from '../types/vehicles.js';
 
 export type GlobalBusinessEntity =
@@ -12,13 +13,15 @@ export type GlobalBusinessEntity =
   | Vehicle
   | Organization
   | LeasingContract
-  | DebtorsDossier;
+  | DebtorsDossier
+  | Transport;
 export type GlobalSearchEntity =
   | SearchOpportunity
   | SearchVehicle
   | SearchOrganization
   | SearchLeasingContract
-  | SearchDebtorsDossier;
+  | SearchDebtorsDossier
+  | SearchTransport;
 
 export const getCustomerInformation = (org?: Organization, contact?: Contact) => {
   if (org != null) {
@@ -41,6 +44,7 @@ export const mappings: {
   [key in BusinessEntityIds]?: {
     getMainEntity: (entity: any) => GlobalBusinessEntity;
     getTitle: (entity: any) => string;
+    getTitleForSearchEntity?: (entity: any) => string;
     getTags: (entity: any) => string[];
     getTagsForSearchEntity?: (entity: any) => string[];
     getDescription?: (entity: any) => string;
@@ -123,6 +127,30 @@ export const mappings: {
     getTitle: (dossier: DebtorsDossier) => dossier.id,
     getTags: (dossier: DebtorsDossier) => [dossier.id].filter(Boolean) as string[],
   },
+  // A transport on its own knows only ids, so the readable title and description come from the
+  // search entity (vehicle + customer). The bare-record variants stay on the id as a fallback.
+  [BusinessEntityIds.Transports]: {
+    getMainEntity: (entity: SearchTransport) => entity.transport,
+    getTitle: (transport: Transport) => transport.id,
+    getTitleForSearchEntity: (entity: SearchTransport) =>
+      entity.vehicle?.external.identification?.stockNumber ?? entity.transport.id,
+    getDescription: (entity: SearchTransport) => {
+      const customer = getCustomerInformation(entity.org);
+      const parts = [customer?.code, customer?.title].filter(Boolean) as string[];
+      // The API rejects an empty association description, so never return one.
+      return parts.length > 0 ? joinWithSeparator(parts) : entity.transport.id;
+    },
+    getTags: (transport: Transport) => [transport.id],
+    getTagsForSearchEntity: (entity: SearchTransport) => {
+      const vehicleTags =
+        entity.vehicle != null
+          ? getTagsForBusinessEntity(BusinessEntityIds.Vehicles, entity.vehicle)
+          : [];
+      return [...vehicleTags, entity.transport.id, entity.transport.opportunityId].filter(
+        Boolean,
+      ) as string[];
+    },
+  },
 };
 
 const getMapping = (businessEntityId: BusinessEntityIds) => {
@@ -186,6 +214,7 @@ export const getTitleForSearchBusinessEntity = (
   businessEntityId: BusinessEntityIds,
   searchEntity: GlobalSearchEntity,
 ) =>
+  getMapping(businessEntityId).getTitleForSearchEntity?.(searchEntity) ??
   getTitleForBusinessEntity(
     businessEntityId,
     getMainEntityFromSearchEntity(businessEntityId, searchEntity),

package/src/utils/transports.ts

@@ -0,0 +1,37 @@
+import { Opportunity } from '../types/opportunities.js';
+import { SearchTransport, Transport, TransportType } from '../types/transports.js';
+import { VehiclePurchase, VehiclePurchaseLogisticsStatus } from '../types/vehicles.js';
+
+/**
+ * A transport is finished when the journey it describes has demonstrably happened: the customer has
+ * the vehicle for a sale delivery, the vehicle is on our park for a purchase pick-up. From then on
+ * the record is history and the server refuses edits to it.
+ *
+ * Not the same thing as the transport's own `doneAt`. Delivery can be declared on the opportunity
+ * (a CMR, a delivery confirmation) and arrival on the purchase, without the transport ever being
+ * moved — and reversing either of those is what unlocks the transport again, which a status stamped
+ * on the transport itself could not express.
+ *
+ * Shared so the board, the drawer and the server all answer the question the same way.
+ */
+export const isTransportCompleted = (
+  transport: Transport,
+  context: { opportunity?: Opportunity; purchase?: VehiclePurchase },
+): boolean => {
+  if (transport.type === TransportType.SaleDelivery) {
+    return context.opportunity?.deliveredAt != null;
+  }
+
+  const status = context.purchase?.logistics.status;
+  return (
+    status === VehiclePurchaseLogisticsStatus.Arrived ||
+    status === VehiclePurchaseLogisticsStatus.CheckedIn
+  );
+};
+
+/** The same question asked of a search document, which already carries both sides. */
+export const isSearchTransportCompleted = (record: SearchTransport): boolean =>
+  isTransportCompleted(record.transport, {
+    opportunity: record.opportunity,
+    purchase: record.purchase,
+  });