@bisondesk/core-sdk 1.0.675 → 1.0.677

package/src/types/offers.ts

@@ -9,6 +9,7 @@ import {
   SearchVehicle,
   VehicleExternalInfo,
   VehicleInternalInfo,
+  VehiclePurchaseDealForeign,
   VehiclePurchaseDealStatus,
   VehiclePurchaseDeliveryType,
 } from './vehicles.js';
@@ -330,6 +331,7 @@ export type OfferPurchase = {
       | VehiclePurchaseDealStatus.Marketing;
     costs: {
       purchase: string;
+      foreign?: VehiclePurchaseDealForeign;
       purchaseVatPercentage: string;
       internalGarage?: string;
       externalGarage?: string;

package/src/types/opportunities.ts

@@ -251,8 +251,23 @@ export type OpportunityUpdate = {
 };
 
 export type OpportunityPaymentSummary = {
+  /** Branch currency. */
   total: string;
+  /** Sum of `amount` over the payments, in branch currency. */
   paid: string;
+  /**
+   * The same pair in the quote's alternative currency, present when the branch can be paid in it.
+   * `paid` sums the payments that arrived in that currency.
+   */
+  foreign?: {
+    total: string;
+    paid: string;
+    currencyCode: string;
+    exchangeRate: string;
+  };
+  /** Fully paid when either currency reaches its total. */
+  status: OpportunityPaymentStatus;
+  percentagePaid: string;
   entries: DataRecord<OpportunityPayment>[];
 };
 
@@ -604,6 +619,7 @@ export type HpLeasingContractRequest = {
     vanCourier: boolean;
     startDate: number;
     opportunityContractId: string;
+    maxKmPerYear?: number;
     data: {
       leasingParameter: {
         allRisksPercentage: number;

package/src/types/opportunity-payments.ts

@@ -7,8 +7,27 @@ export enum OpportunityPaymentActions {
 
 export const OPPORTUNITY_PAYMENT_NOTIFICATION_ORIGIN = 'opportunity-payment-notification';
 
+/**
+ * The money as it arrived, when it arrived in the quote's alternative currency. `amount` then
+ * holds its value in branch currency: `foreign.amount × foreign.exchangeRate`.
+ */
+export type OpportunityPaymentForeign = {
+  amount: string;
+  currencyCode: string;
+  /** Branch currency units per 1 unit of `currencyCode`, the quote's rate. */
+  exchangeRate: string;
+};
+
+/** What a user sends for a payment in another currency. The backend takes the rate from the quote
+ * and derives `amount`. */
+export type OpportunityPaymentForeignRequest = Pick<
+  OpportunityPaymentForeign,
+  'amount' | 'currencyCode'
+>;
+
 type BaseOpportunityPayment = {
   opportunityId: string;
+  /** Branch currency. */
   amount: string;
   description?: string;
   vehicleId: string;
@@ -24,6 +43,7 @@ export type NewOpportunityPayment = BaseOpportunityPayment & {
   deletedAt?: undefined;
   deletedBy?: undefined;
   paidAt: string;
+  foreign?: OpportunityPaymentForeignRequest;
 };
 
 export type OpportunityPayment = BaseOpportunityPayment & {
@@ -35,11 +55,14 @@ export type OpportunityPayment = BaseOpportunityPayment & {
   deletedAt?: string;
   deletedBy?: string;
   paidAt?: string;
+  foreign?: OpportunityPaymentForeign;
 };
 
 export type OpportunityPaymentUpdate = {
   description?: string;
   amount?: string;
+  /** `null` turns the payment back into a branch currency payment. */
+  foreign?: OpportunityPaymentForeignRequest | null;
   paidAt?: string;
 };
 

package/src/types/quote-settings.ts

@@ -91,6 +91,8 @@ export type LeasingQuoteParams<P extends CountrySpecificQuoteParams = CountrySpe
       leasingDuration: number;
       leasingDepositPercentage: string;
       leasingResidualValuePercentage: string;
+      /** Seeds `leasing.maxKmPerYear` on new quotes. */
+      maxKmPerYear?: number;
     };
     costs: {
       bankDepositPercentage: string;

package/src/types/quotes.ts

@@ -91,6 +91,8 @@ export type LeasingCalculatorInput = BaseQuoteCalculatorInput & {
     interestRate: string;
     duration: number;
     contractStartDate: string;
+    /** Mileage cap the contract allows per year, in km. Printed on the quote and the contract. */
+    maxKmPerYear?: number;
   };
   bank: {
     interestRate: string;

package/src/types/tenants.ts

@@ -148,6 +148,12 @@ export type Branch = {
   exactAccounting?: boolean;
   accounting?: AccountingProvider;
   currency: string;
+  /**
+   * The currencies money moves in at this branch, its own `currency` included. Customer payments,
+   * purchase prices, supplier invoice drafts and Exact bookings are supported in these currencies
+   * only. Absent = the branch's own `currency` only. Set by script.
+   */
+  paymentCurrencies?: [string, ...string[]];
   adminNumberPrefix: string;
   stockNumberPrefix: string;
   vatNumber: string;
@@ -156,6 +162,12 @@ export type Branch = {
     standard: string; //percentage value (e.g. 21)
   };
   location: LocationValue;
+  /**
+   * The parking (a `location` picklist value) this branch's vehicles go to when their purchase
+   * names none. Vehicle entry offers it as the stock destination, and the transport ITR prints
+   * it as the park. Absent = the ITR prints the branch's own address.
+   */
+  defaultParking?: string;
 
   storecoveExternalId?: number;
   // true if the branch is for a company where VAT is due when the invoice

package/src/types/vehicle-purchase-payments.ts

@@ -4,18 +4,33 @@ import { SearchVehicle } from './vehicles.js';
 export const VEHICLE_PURCHASE_PAYMENT_ALLOWED_NOTIFICATION_ORIGIN =
   'vehicle-purchase-payment-allowed-notification';
 
+/**
+ * A payment on a purchase priced in another currency is authorized and paid in that currency.
+ * `amount` then holds its value in branch currency: `foreign.amount × foreign.exchangeRate`.
+ */
+export type VehiclePurchasePaymentForeign = {
+  amount: string;
+  currencyCode: string;
+  /** Branch currency units per 1 unit of `currencyCode`, the purchase's rate. */
+  exchangeRate: string;
+};
+
 export type NewVehiclePurchasePayment = {
   vehicleId: string;
+  /** Branch currency. Derived from `foreign` when the purchase is priced in another currency. */
   amount: string;
+  /** The backend takes the rate from the purchase. */
+  foreign?: Pick<VehiclePurchasePaymentForeign, 'amount' | 'currencyCode'>;
   description?: string;
   paidAt?: string;
   paidBy?: string;
 };
 
-export type VehiclePurchasePayment = NewVehiclePurchasePayment & {
+export type VehiclePurchasePayment = Omit<NewVehiclePurchasePayment, 'foreign'> & {
   id: string;
   createdBy: string;
   createdAt: string;
+  foreign?: VehiclePurchasePaymentForeign;
 };
 
 export type VehiclePurchasePaymentBff = {

package/src/types/vehicles.ts

@@ -170,6 +170,7 @@ export type NewVehicleRequest = {
     dealStatus: VehiclePurchaseDealStatus;
     costs: {
       purchase: string;
+      foreign?: VehiclePurchaseDealForeign;
       purchaseVatPercentage: string;
       commission?: string;
       externalTransport?: string;
@@ -811,6 +812,18 @@ export type VehiclePriceUpdateResponse =
       errors: VehiclePriceUpdateError[];
     };
 
+/**
+ * The price the supplier asked, in the supplier's currency: one of the payment currencies of the
+ * vehicle's branch. The purchase's `deal.purchase` is then `purchase × exchangeRate`, and payments
+ * are authorized in `currencyCode`.
+ */
+export type VehiclePurchaseDealForeign = {
+  purchase: string; // exclusive VAT
+  currencyCode: string;
+  /** Branch currency units per 1 unit of `currencyCode`. */
+  exchangeRate: string;
+};
+
 export type VehiclePurchase = {
   organizationId: string;
   contactId: string;
@@ -851,7 +864,8 @@ export type VehiclePurchase = {
     readyToDeliver?: boolean;
 
     purchaseVatRate?: string;
-    purchase?: string; // exclusive VAT
+    purchase?: string; // exclusive VAT; derived from `foreign` when present
+    foreign?: VehiclePurchaseDealForeign;
 
     bonus?: string; // sometimes manufacturers pay us a bonus when we reach a target
 

package/src/utils/opportunity-payments.test.ts

@@ -0,0 +1,31 @@
+import { OpportunityPayment } from '../types/opportunity-payments.js';
+import { isPaidInAlternativeCurrency } from './opportunity-payments.js';
+
+const dollarPayment: Pick<OpportunityPayment, 'foreign' | 'deletedAt'> = {
+  foreign: { amount: '30000', currencyCode: 'USD', exchangeRate: '0.861804' },
+};
+const euroPayment: Pick<OpportunityPayment, 'foreign' | 'deletedAt'> = {};
+
+describe('isPaidInAlternativeCurrency', () => {
+  it('shows the alternative currency before any payment arrived', () => {
+    expect(isPaidInAlternativeCurrency('USD', [])).toBe(true);
+  });
+
+  it('shows the alternative currency while every payment arrived in it', () => {
+    expect(isPaidInAlternativeCurrency('USD', [dollarPayment, dollarPayment])).toBe(true);
+  });
+
+  it('switches to branch currency once one payment arrived in branch currency', () => {
+    expect(isPaidInAlternativeCurrency('USD', [dollarPayment, euroPayment])).toBe(false);
+  });
+
+  it('leaves deleted payments out', () => {
+    expect(
+      isPaidInAlternativeCurrency('USD', [dollarPayment, { deletedAt: '2026-09-30T10:00:00Z' }]),
+    ).toBe(true);
+  });
+
+  it('shows branch currency when the quote has no alternative currency', () => {
+    expect(isPaidInAlternativeCurrency(undefined, [dollarPayment])).toBe(false);
+  });
+});

package/src/utils/opportunity-payments.ts

@@ -0,0 +1,15 @@
+import { OpportunityPayment } from '../types/opportunity-payments.js';
+
+/**
+ * Whether a deal's payments are shown in the quote's alternative currency: every payment so far
+ * arrived in it. One payment in branch currency switches the deal to branch currency, because
+ * only the branch currency amounts then add up to the whole.
+ */
+export const isPaidInAlternativeCurrency = (
+  alternativeCurrency: string | undefined,
+  payments: Pick<OpportunityPayment, 'foreign' | 'deletedAt'>[],
+): boolean =>
+  alternativeCurrency != null &&
+  payments
+    .filter((payment) => payment.deletedAt == null)
+    .every((payment) => payment.foreign?.currencyCode === alternativeCurrency);

package/src/utils/tenants.test.ts

@@ -1,5 +1,11 @@
-import { Branch } from '../types/tenants.js';
-import { areBranchesQuoteCompatible } from './tenants.js';
+import { Branch, Tenant } from '../types/tenants.js';
+import {
+  areBranchesQuoteCompatible,
+  getBranchAskingVies,
+  getBranchPaymentCurrencies,
+  hasForeignPaymentCurrency,
+  isForeignPaymentCurrency,
+} from './tenants.js';
 
 const createBranch = (override?: Partial<Branch>): Branch => ({
   id: 'TTC',
@@ -45,3 +51,55 @@ describe('areBranchesQuoteCompatible', () => {
     expect(areBranchesQuoteCompatible(implicit, explicit)).toBe(true);
   });
 });
+
+describe('getBranchAskingVies', () => {
+  const bolivia = createBranch({ id: 'BO', country: 'bo', vatNumber: '387032026' });
+  const belgium = createBranch({ id: 'BE', country: 'be', vatNumber: 'BE0405567886' });
+  const france = createBranch({ id: 'FR', country: 'fr', vatNumber: 'FR10821739638' });
+  const tenantOf = (branches: Branch[]) => ({ branches }) as Tenant;
+
+  test.each([
+    ['the European branch the check is made for', 'FR', 'FR'],
+    ['the first European branch when no branch is given', undefined, 'BE'],
+    ['the first European branch when the given branch is outside the EU', 'BO', 'BE'],
+    ['the first European branch when the given branch is unknown', 'GONE', 'BE'],
+  ])('picks %s', (_label, branchId, expected) => {
+    expect(getBranchAskingVies(tenantOf([bolivia, belgium, france]), branchId)?.id).toBe(expected);
+  });
+
+  test('asks anonymously for a tenant without a European branch', () => {
+    expect(getBranchAskingVies(tenantOf([bolivia]), 'BO')).toBeUndefined();
+  });
+});
+
+describe('payment currencies of a branch', () => {
+  const southAmerica = createBranch({
+    id: 'HPA South America',
+    paymentCurrencies: ['EUR', 'USD'],
+  });
+
+  test('a branch without a list is paid in its own currency only', () => {
+    expect(getBranchPaymentCurrencies(createBranch())).toEqual(['EUR']);
+  });
+
+  test('a branch with a list is paid in the currencies it lists', () => {
+    expect(getBranchPaymentCurrencies(southAmerica)).toEqual(['EUR', 'USD']);
+  });
+
+  test.each([
+    ['a listed currency other than its own', 'USD', true],
+    ['its own currency', 'EUR', false],
+    ['a currency it does not list', 'BOB', false],
+  ])('%s is a foreign payment currency: %s', (_label, currencyCode, expected) => {
+    expect(isForeignPaymentCurrency(southAmerica, currencyCode)).toBe(expected);
+  });
+
+  test('a branch without a list has no foreign payment currency', () => {
+    expect(isForeignPaymentCurrency(createBranch(), 'USD')).toBe(false);
+    expect(hasForeignPaymentCurrency(createBranch())).toBe(false);
+  });
+
+  test('a branch listing another currency has a foreign payment currency', () => {
+    expect(hasForeignPaymentCurrency(southAmerica)).toBe(true);
+  });
+});

package/src/utils/tenants.ts

@@ -1,4 +1,5 @@
 import { XError } from '@bisondesk/commons-sdk/errors';
+import { isEUCountry } from '@bisondesk/commons-sdk/locations';
 import { first } from 'lodash-es';
 import { Branch, Tenant } from '../types/tenants.js';
 
@@ -13,6 +14,33 @@ export const getBranch = (tenant: Tenant, branchId: string): Branch => {
 
 export const getDefaultBranch = (tenant: Tenant): Branch => first(tenant.branches)!;
 
+/**
+ * The branch whose VAT number VIES records as the requester of a VAT check, which earns a
+ * consultation number: the branch the check is made for when it is European, else the tenant's
+ * first European branch. A tenant without a European branch asks VIES anonymously.
+ */
+export const getBranchAskingVies = (tenant: Tenant, branchId?: string): Branch | undefined => {
+  const europeanBranches = tenant.branches.filter((branch) => isEUCountry(branch.country));
+  return europeanBranches.find((branch) => branch.id === branchId) ?? europeanBranches.at(0);
+};
+
+/** The currencies money moves in at the branch, its own currency included. */
+export const getBranchPaymentCurrencies = (branch: Branch): string[] =>
+  branch.paymentCurrencies ?? [branch.currency];
+
+/**
+ * Whether the branch can be paid, price a purchase or receive a supplier invoice in a currency
+ * other than its own. Its own currency is never a foreign one.
+ */
+export const isForeignPaymentCurrency = (branch: Branch, currencyCode: string): boolean =>
+  currencyCode !== branch.currency && getBranchPaymentCurrencies(branch).includes(currencyCode);
+
+/** Whether the branch lists any payment currency other than its own. */
+export const hasForeignPaymentCurrency = (branch: Branch): boolean =>
+  getBranchPaymentCurrencies(branch).some((currencyCode) =>
+    isForeignPaymentCurrency(branch, currencyCode),
+  );
+
 /** The source invoices the end customer directly; this branch collects payment and earns
  * commission (see {@link Branch.dropshipping}). */
 export const isDropshippingBranch = (branch: Branch): boolean => branch.dropshipping === true;