@bisondesk/core-sdk 1.0.677 → 1.0.678

package/src/types/organization-bank-accounts.ts

@@ -0,0 +1,56 @@
+import { BankAccountDetails } from '@bisondesk/commons-sdk/bank-accounts';
+
+/**
+ * An accountant's confirmation of one account number. It only counts while the account still
+ * holds that number, so trust never carries over to a new number however the account was edited.
+ */
+export type OrganizationBankAccountVerification = {
+  accountNumber: string;
+  verifiedBy: string;
+  verifiedAt: string;
+};
+
+export enum OrganizationBankAccountActions {
+  VERIFY = 'verify',
+}
+
+export enum OrganizationBankAccountActionBlockerCode {
+  CHANGED_NEEDS_VERIFICATION = 'changed_needs_verification',
+}
+
+export type OrganizationBankAccountActionBlocker = {
+  code: OrganizationBankAccountActionBlockerCode;
+};
+
+/**
+ * Why an action the user would otherwise see is refused right now. A missing permission hides the
+ * action instead.
+ */
+export type OrganizationBankAccountBlockedAction = {
+  action: OrganizationBankAccountActions;
+  reasons: OrganizationBankAccountActionBlocker[];
+};
+
+export type OrganizationBankAccountMeta = {
+  blockedActions: OrganizationBankAccountBlockedAction[];
+};
+
+export type NewOrganizationBankAccount = BankAccountDetails & {
+  organizationId: string;
+};
+
+/**
+ * An organisation's bank account for outgoing SEPA transfers, never shared across companies. An
+ * organisation can hold several; at most one is its `default`, the one payment exports pay to.
+ * Editing the account number or holder name clears the manual verification, so a valid checksum is
+ * never mistaken for a confirmed account holder.
+ */
+export type OrganizationBankAccount = NewOrganizationBankAccount & {
+  id: string;
+  default?: boolean;
+  createdAt: string;
+  createdBy: string;
+  modifiedAt: string;
+  modifiedBy: string;
+  verification?: OrganizationBankAccountVerification;
+};

package/src/types/payment-exports.ts

@@ -0,0 +1,40 @@
+import { BankAccountDetails } from '@bisondesk/commons-sdk/bank-accounts';
+import { AttachmentValue } from '@bisondesk/commons-sdk/types';
+
+/**
+ * The transfer details of one payment, frozen at export time. A later edit to the payment or the
+ * supplier bank account must not rewrite what the sent file said, so the export keeps its own copy
+ * of every value that went into the XML. It also records the payment batch the payment was sent to
+ * processing in, so the export is a self-contained audit record even though one file can span
+ * several batches.
+ */
+export type PaymentExportLine = {
+  paymentId: string;
+  vehicleId: string;
+  amount: string;
+  creditor: BankAccountDetails;
+  paymentBatchId: string;
+  transferReference?: string;
+};
+
+export type NewPaymentExport = {
+  /** Single execution date (`yyyy-MM-dd`) written to the file's `ReqdExctnDt`. */
+  executionDate: string;
+  /** Σ of the exported line amounts (string; computed with decimal arithmetic). */
+  totalAmount: string;
+  paymentIds: string[];
+  lines: PaymentExportLine[];
+  /** The generated SEPA file, stored in S3 and re-downloadable from Processing. */
+  xmlFile: AttachmentValue;
+};
+
+/**
+ * A generated SEPA file for a selection of Processing payments, plus the frozen record of exactly what
+ * was sent. Re-downloading serves the same file and never re-exports; a payment cancelled out of the
+ * file returns to Allowed and leaves this record intact.
+ */
+export type PaymentExport = NewPaymentExport & {
+  id: string;
+  exportedAt: string;
+  exportedBy: string;
+};

package/src/types/tenants.ts

@@ -55,6 +55,13 @@ export enum TenantModule {
   Intercompany = 'intercompany',
   Opportunities = 'opportunities',
   Offers = 'offers',
+  /**
+   * The tenant pays suppliers through Isabel file exports (SEPA transfer files). It grants the
+   * export itself and the verification of the supplier bank accounts it pays to, and requires those
+   * account numbers to be valid IBANs. Without it, Processing payments are simply marked paid, and
+   * a bank account can hold any account number.
+   */
+  PaymentExports = 'payment_exports',
   Vehicles = 'vehicles',
   Tasks = 'tasks',
   TrackAndTrace = 'track_and_trace',
@@ -148,12 +155,6 @@ 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;

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

@@ -1,41 +1,142 @@
 import { BaseEvent } from './internal-events.js';
+import { OrganizationBankAccountActions } from './organization-bank-accounts.js';
 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`.
+ * The stage a supplier payment sits at, driving the Unpaid/Allowed/Processing/Executed tabs.
+ * A payment only ever moves forward: an authorised payment is `allowed`; sending it to processing
+ * groups it into a payment batch and hands it to accounting (`processing`), which exports it
+ * to the Isabel bank file; marking it paid moves it to `executed`.
+ * (`unpaid` is not a stage — it is an agreed purchase with an amount still to authorise.)
  */
-export type VehiclePurchasePaymentForeign = {
-  amount: string;
-  currencyCode: string;
-  /** Branch currency units per 1 unit of `currencyCode`, the purchase's rate. */
-  exchangeRate: string;
-};
+export enum PaymentStage {
+  Allowed = 'allowed',
+  Processing = 'processing',
+  Executed = 'executed',
+}
 
 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 = Omit<NewVehiclePurchasePayment, 'foreign'> & {
+export type VehiclePurchasePayment = NewVehiclePurchasePayment & {
   id: string;
   createdBy: string;
   createdAt: string;
-  foreign?: VehiclePurchasePaymentForeign;
+  stage: PaymentStage;
+  /** Manual settlement priority within the Allowed tab; lower is paid first. */
+  priority: number;
+  /** Set once the payment has been exported; links it to its payment export. */
+  exportId?: string;
+  /** The payment batch this payment was sent to processing in; unset while Allowed, and on payments
+   * marked paid straight from Allowed. */
+  paymentBatchId?: string;
+  /**
+   * Supplier-facing communication that becomes the SEPA transfer's remittance information (`RmtInf`),
+   * so the supplier can reconcile the payment to an invoice. Editable while Processing and not yet
+   * exported; prefilled from the latest purchase invoice. This is not the file's per-line
+   * `EndToEndId`.
+   */
+  transferReference?: string;
+  /** Who sent the payment to processing, and when — set at the Allowed → Processing step. */
+  sentToProcessingBy?: string;
+  sentToProcessingAt?: string;
+};
+
+/**
+ * One send to processing: the Allowed payments an accountant moved to Processing together, and who
+ * sent them. The Processing tab groups its rows by batch. A batch holds no amount of its own; its
+ * total is the sum of the payments still in it.
+ */
+export type PaymentBatch = {
+  id: string;
+  createdAt: string;
+  createdBy: string;
+};
+
+/**
+ * Whether a payment's supplier can be paid in an export. Mirrors the export gate: a transfer needs a
+ * supplier bank account that carries an IBAN and holder name and has been verified. Shown as an
+ * export-blocked marker on the Processing rows, where the accountant clears it before exporting.
+ * (The invoice / pro-forma document half of the gate is not reflected here — its source is a Q3
+ * residual the backend export gate also defers.)
+ *
+ * The bank account is the supplier's default one, `bankAccountId`, which is the account an export
+ * pays. `bankAccountActions` lists what the current user may do on it, so a row can point out the
+ * accounts they can verify themselves. Once the account number or holder name changed, verify is
+ * left out for accountants, and for whichever Senior Accountant made the change (four-eyes).
+ */
+export type PaymentExportChecks = {
+  bankAccountId?: string;
+  hasBankAccount: boolean;
+  bankAccountVerified: boolean;
+  bankAccountActions: OrganizationBankAccountActions[];
 };
 
 export type VehiclePurchasePaymentBff = {
   payment: VehiclePurchasePayment;
   vehicle: SearchVehicle;
+  /** Name of the supplier organisation (`vehicle.purchase.organizationId`), resolved for display. */
+  supplierName?: string;
+  /** Export checks on the supplier bank account; filled for the Processing list only. */
+  exportChecks?: PaymentExportChecks;
+};
+
+/**
+ * A row on the Unpaid tab: an agreed purchase that still has an amount to authorise for payment.
+ * Derived from the purchase deal and the payments already authorised, not a payment record.
+ */
+export type UnpaidPurchase = {
+  vehicle: SearchVehicle;
+  /** The agreed purchase price including VAT (`deal.purchase` grossed up by `deal.purchaseVatRate`),
+   * so it matches the VAT-inclusive cost the vehicle purchase tab authorises against. */
+  purchaseAmount: string;
+  /** Sum of amounts already authorised (payments in any stage) for this vehicle. */
+  allowedAmount: string;
+  /** Sum of the authorised amounts already settled (payments in Executed) for this vehicle. */
+  paidAmount: string;
+  /** `purchaseAmount − allowedAmount`; always greater than zero for rows shown here. */
+  remainingAmount: string;
+  /** Due date of the purchase invoice. */
+  invoiceDueDate?: string;
+  /** Name of the supplier organisation (`vehicle.purchase.organizationId`), resolved for display. */
+  supplierName?: string;
+};
+
+/** Body of the export request: the Processing payments to put in one file, the paying account, and the execution date. */
+export type ExportPaymentsRequest = {
+  paymentIds: string[];
+  /** The bank account (from documents settings) to pay the file from — the file's debtor. */
+  debtorBankAccountId: string;
+  /** Single execution date (`yyyy-MM-dd`) written to `ReqdExctnDt`; defaults to today. */
+  executionDate?: string;
+};
+
+/** Body of the mark-paid request: the payments (Allowed or Processing) to settle in one call. */
+export type MarkPaymentsPaidRequest = {
+  paymentIds: string[];
+};
+
+/** Body of the send-to-processing request: the Allowed payments to send together as one batch. */
+export type SendPaymentsToProcessingRequest = {
+  paymentIds: string[];
+};
+
+/**
+ * How many rows sit behind each payment tab, for the tab counters. Executed is unbounded and has no
+ * counter, so it is left out.
+ */
+export type PurchasePaymentCounts = {
+  unpaid: number;
+  allowed: number;
+  processing: number;
 };
 
 export type VehiclePurchasePaymentCreateEvent = {

package/src/types/vehicles.ts

@@ -170,7 +170,6 @@ export type NewVehicleRequest = {
     dealStatus: VehiclePurchaseDealStatus;
     costs: {
       purchase: string;
-      foreign?: VehiclePurchaseDealForeign;
       purchaseVatPercentage: string;
       commission?: string;
       externalTransport?: string;
@@ -812,18 +811,6 @@ 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;
@@ -859,13 +846,15 @@ export type VehiclePurchase = {
     checkedInBy?: string;
   };
 
+  /** Due date of the supplier purchase invoice; editable from the payments page. */
+  invoiceDueDate?: string;
+
   deal: {
     status: VehiclePurchaseDealStatus; // partially set by the user, if there are payments then it is set automatically by the backend
     readyToDeliver?: boolean;
 
     purchaseVatRate?: string;
-    purchase?: string; // exclusive VAT; derived from `foreign` when present
-    foreign?: VehiclePurchaseDealForeign;
+    purchase?: string; // exclusive VAT
 
     bonus?: string; // sometimes manufacturers pay us a bonus when we reach a target
 

package/src/utils/organization-bank-accounts.ts

@@ -0,0 +1,19 @@
+import { normalizeIban } from '@bisondesk/commons-sdk/iban';
+import { OrganizationBankAccount } from '../types/organization-bank-accounts.js';
+
+/**
+ * Whether an organisation's bank account can be paid: it carries a verification, and that
+ * verification was given for the account number the account holds now. A verification recorded
+ * without an account number, or for a different one, does not count.
+ *
+ * Shared so the export gate and the Processing rows read one rule.
+ */
+export const isOrganizationBankAccountVerified = (
+  account: OrganizationBankAccount | undefined,
+): boolean => {
+  const verifiedAccountNumber = account?.verification?.accountNumber;
+  if (account == null || verifiedAccountNumber == null) {
+    return false;
+  }
+  return normalizeIban(verifiedAccountNumber) === normalizeIban(account.accountNumber);
+};

package/src/utils/tenants.test.ts

@@ -1,11 +1,5 @@
 import { Branch, Tenant } from '../types/tenants.js';
-import {
-  areBranchesQuoteCompatible,
-  getBranchAskingVies,
-  getBranchPaymentCurrencies,
-  hasForeignPaymentCurrency,
-  isForeignPaymentCurrency,
-} from './tenants.js';
+import { areBranchesQuoteCompatible, getBranchAskingVies } from './tenants.js';
 
 const createBranch = (override?: Partial<Branch>): Branch => ({
   id: 'TTC',
@@ -71,35 +65,3 @@ describe('getBranchAskingVies', () => {
     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

@@ -24,23 +24,6 @@ export const getBranchAskingVies = (tenant: Tenant, branchId?: string): Branch |
   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;