@classytic/ledger-bd 0.6.0 → 0.7.0

package/dist/posting-recipes/index.d.mts

@@ -0,0 +1,457 @@
+import { PostingRecipe } from "@classytic/ledger/posting-rules";
+
+//#region src/posting-recipes/resolvers.d.ts
+/**
+ * BD posting-recipe resolver context — the jurisdiction ports the recipes
+ * close over. Injected by the host (be-prod wires its existing
+ * `posting/tax.accounts.ts` + `withholding-amount.ts` + tax-resolver
+ * implementations); recipes NEVER import a host.
+ *
+ * Design: packages/ledger/docs/posting-rules-design.md §3.4 item 9 — tax
+ * resolvers COMPUTE, recipes PLACE.
+ */
+type BdAccountingRegime = 'standard' | 'tot' | 'exempt' | 'importer' | (string & {});
+interface BdImportStackResult {
+  /**
+   * Assessable value + CD + SD. The recipe capitalizes only the DUTIES portion
+   * (`landedCost − assessableValue`) — the AV itself is owed to the supplier
+   * and booked by the follow-up vendor bill (+ non-claimable VAT folds in).
+   */
+  landedCost: number;
+  /** RAW VAT computed by the stack — claimability is the RECIPE's decision via inputVatAccount. */
+  recoverableTax: number;
+  /** AT + AIT prepaid at the customs gate. */
+  prepaidTax: number;
+  /** Total paid at customs (bank credit) — duties + taxes ONLY, never the AV. */
+  totalPayable: number;
+}
+interface BdPostingResolvers {
+  /**
+   * Rate/regime-gated input-VAT account code. `null` = VAT not claimable
+   * (TOT/exempt regimes) — the recipe folds the amount into inventory.
+   * Mirrors be-prod `posting/tax.accounts.ts#inputVatAccount`.
+   */
+  inputVatAccount(rateCode: string, regime: BdAccountingRegime): string | null;
+  /** Rate → rate-code inference (be-prod `rateCodeForRate`). */
+  rateCodeForRate(rate: number): string;
+  /**
+   * VDS (VAT-deducted-at-source) withheld amount. Mirrors be-prod
+   * `posting/withholding-amount.ts#resolveVatWithheldAtSource`.
+   */
+  resolveVatWithheldAtSource(claimableVat: number, opts: {
+    applicable?: boolean | undefined;
+    rate?: number | undefined;
+  }): number;
+  /**
+   * Customs clearance stack (CD → SD → VAT → AT → AIT). Mirrors the active
+   * tax resolver's `computeImportStack` port.
+   *
+   * INVARIANT the implementation must satisfy (the import-clearance recipe
+   * balances on it): `(landedCost − assessableValue) + recoverableTax +
+   * prepaidTax` MUST equal `totalPayable` — i.e. `totalPayable` is what's paid
+   * at the customs gate (CD + SD + VAT + AT + AIT), never including the AV
+   * (recoverableTax is the raw VAT regardless of claimability). bd-tax's
+   * `calculateImportTaxStack.totalCustomsPayment` satisfies this natively.
+   */
+  computeImportStack(input: {
+    assessableValue: number;
+    cdRate: number;
+    date?: Date | undefined;
+    sdRate?: number | undefined;
+    atRate?: number | undefined;
+    vatRate?: number | undefined;
+    aitRate?: number | undefined;
+    regime?: BdAccountingRegime | undefined;
+  }): BdImportStackResult;
+}
+/** Inventory-type → slot name (mirrors be-prod INVENTORY_ACCOUNTS keys). */
+declare const INVENTORY_SLOT: Record<string, string>;
+declare function inventorySlotFor(inventoryType: string | undefined): string;
+/** `displayRef` parity: human ref when present, else the id. */
+declare function displayRef(referenceNumber: string | undefined, id: string): string;
+//#endregion
+//#region src/posting-recipes/pack.d.ts
+/**
+ * Every chart slot any BD recipe references — statically (slot mode) or at
+ * evaluation time (route mode). The registry validates the host chart
+ * provides ALL of them at boot (fail-loud; anti-silent-default).
+ */
+declare const BD_REQUIRED_POSTING_SLOTS: ReadonlyArray<string>;
+declare function buildBdPostingRecipes(resolvers: BdPostingResolvers): ReadonlyArray<PostingRecipe<any>>;
+//#endregion
+//#region src/posting-recipes/purchases.recipes.d.ts
+interface PurchaseRecipeInput {
+  purchaseId: string;
+  purchaseReferenceNumber?: string | undefined;
+  supplierId: string;
+  totalAmount: number;
+  tax: number;
+  vatRateCode?: string | undefined;
+  vatRate?: number | undefined;
+  regime?: BdAccountingRegime | undefined;
+  date: Date;
+  inventoryType?: string | undefined;
+  isPaid?: boolean | undefined;
+  description?: string | undefined;
+  currency?: string | undefined;
+  exchangeRate?: number | undefined;
+  foreignTotal?: number | undefined;
+}
+interface GoodsReceiptRecipeInput {
+  orderId: string;
+  orderNumber?: string | undefined;
+  receiptKey: string | number;
+  /** Net-of-VAT goods value in paisa (handler computes from lines or passes explicit). */
+  goodsValuePaisa: number;
+  date: Date;
+}
+interface VendorBillRecipeInput {
+  purchaseId: string;
+  supplierId: string;
+  totalAmount: number;
+  tax?: number | undefined;
+  vatRateCode?: string | undefined;
+  vatRate?: number | undefined;
+  regime?: BdAccountingRegime | undefined;
+  receivedAt: Date;
+  dueDate?: Date | undefined;
+  inventoryType?: string | undefined;
+  billNumber?: string | undefined;
+  withholdVds?: boolean | undefined;
+  vdsRate?: number | undefined;
+  /** Document-currency audit snapshot. GL amounts remain base minor units. */
+  currency?: string | undefined;
+  exchangeRate?: number | undefined;
+  foreignTotal?: number | undefined;
+}
+interface VendorPaymentRecipeInput {
+  purchaseId: string;
+  supplierId: string;
+  supplierName?: string | undefined;
+  amount: number;
+  /** Cash/bank amount at the settlement-date rate; defaults to `amount`. */
+  settlementAmount?: number | undefined;
+  currency?: string | undefined;
+  exchangeRate?: number | undefined;
+  foreignAmount?: number | undefined;
+  date: Date;
+  /** GL code — handler defaults via the 'cash' slot (Cash at Bank). */
+  fromAccountCode: string;
+  reference?: string | undefined;
+  realizedGainAccountCode?: string | undefined;
+  realizedLossAccountCode?: string | undefined;
+}
+interface VendorBillReversalRecipeInput extends Omit<VendorBillRecipeInput, 'receivedAt' | 'dueDate'> {
+  reason?: string | undefined;
+  /** Handler pre-defaults (original: `data.date ?? new Date()` — impure, so the seam owns it). */
+  date: Date;
+}
+interface SupplierReturnRecipeInput {
+  purchaseId: string;
+  supplierId: string;
+  moveGroupId: string;
+  /** Σ(qty × unitCost) in paisa — handler converts from major-unit lines. */
+  totalPaisa: number;
+  /** Handler pre-defaults (original: `data.date ?? new Date()`). */
+  date: Date;
+  reason?: string | undefined;
+  inventoryType?: string | undefined;
+}
+interface ImportClearanceRecipeInput {
+  clearanceId: string;
+  supplierId: string;
+  assessableValue: number;
+  cdRate: number;
+  sdRate?: number | undefined;
+  atRate?: number | undefined;
+  vatRate?: number | undefined;
+  aitRate?: number | undefined;
+  regime?: BdAccountingRegime | undefined;
+  date: Date;
+  inventoryType?: string | undefined;
+  billOfEntry?: string | undefined;
+  description?: string | undefined;
+}
+declare function buildPurchaseRecipes(resolvers: BdPostingResolvers): {
+  purchase: PostingRecipe<PurchaseRecipeInput>;
+  goodsReceipt: PostingRecipe<GoodsReceiptRecipeInput>;
+  vendorBill: PostingRecipe<VendorBillRecipeInput>;
+  vendorPayment: PostingRecipe<VendorPaymentRecipeInput>;
+  vendorBillReversal: PostingRecipe<VendorBillReversalRecipeInput>;
+  supplierReturn: PostingRecipe<SupplierReturnRecipeInput>;
+  importClearance: PostingRecipe<ImportClearanceRecipeInput>;
+};
+//#endregion
+//#region src/posting-recipes/sales-cod.recipes.d.ts
+/** sales.contract.ts:48-61 — method → activeCodes slot name. */
+declare const PAYMENT_METHOD_SLOT: Record<string, string>;
+/** restocking-fee.contract.ts:32-40 adds the 'cod' key (fee retained as cash). */
+declare const RESTOCKING_METHOD_SLOT: Record<string, string>;
+declare function paymentMethodSlot(method: string | undefined): string;
+interface SalesTransactionRecipeInput {
+  transactionId: string;
+  amount: number;
+  tax: number;
+  method: string;
+  date: Date;
+  orderId?: string | undefined;
+  orderReferenceNumber?: string | undefined;
+  source?: string | undefined;
+  branchCode?: string | undefined;
+  description?: string | undefined;
+  promoDiscount?: number | undefined;
+  gatewayTransactionId?: string | undefined;
+  gatewayProvider?: string | undefined;
+}
+interface DailyPosSummaryRecipeInput {
+  branchId: string;
+  branchCode: string;
+  date: string;
+  byMethod: Array<{
+    method: string;
+    amount: number;
+  }>;
+  totalAmount: number;
+  totalTax: number;
+  transactionCount: number;
+}
+interface RefundRecipeInput {
+  transactionId: string;
+  refundAmount: number;
+  tax: number;
+  method: string;
+  date: Date;
+  orderId?: string | undefined;
+  reason?: string | undefined;
+}
+interface CodPlacementRecipeInput {
+  transactionId: string;
+  orderId: string;
+  orderReferenceNumber?: string | undefined;
+  customerId?: string | null | undefined;
+  amount: number;
+  tax: number;
+  date: Date;
+  branchCode?: string | undefined;
+  description?: string | undefined;
+  promoDiscount?: number | undefined;
+  /** Handler computes: addDays(date, expectedRemittanceDays ?? 14). Pure recipes take the Date. */
+  maturityDate: Date;
+}
+interface CodSettlementRecipeInput {
+  settlementId: string;
+  orderId: string;
+  orderReferenceNumber?: string | undefined;
+  grossAmount: number;
+  actualReceived: number;
+  courierCommission: number;
+  writeoff: number;
+  /** GL code — handler defaults via the 'cash' slot (Cash at Bank). */
+  cashAccountCode: string;
+  customerId?: string | null | undefined;
+  date: Date;
+  notes?: string | undefined;
+}
+interface CodCancellationRecipeInput {
+  orderId: string;
+  orderReferenceNumber?: string | undefined;
+  customerId?: string | null | undefined;
+  grossAmount: number;
+  tax: number;
+  promoDiscount?: number | undefined;
+  date: Date;
+  reason?: string | undefined;
+}
+interface RestockingFeeRecipeInput {
+  changeNumber: string;
+  orderId: string;
+  amount: number;
+  paymentMethod?: string | undefined;
+  date: Date;
+  reason?: string | undefined;
+}
+/**
+ * cod-settlement.contract.ts:121-134 — result-style pre-condition (ported
+ * verbatim, messages included). Handlers call BEFORE evaluate.
+ */
+declare function validateCodSettlementInputs(data: Pick<CodSettlementRecipeInput, 'grossAmount' | 'actualReceived' | 'courierCommission' | 'writeoff'>): {
+  ok: true;
+} | {
+  ok: false;
+  reason: string;
+};
+/** Throw-style form of the same pre-condition (for guard-clause call sites). */
+declare function validateCodSettlement(i: CodSettlementRecipeInput): void;
+declare function buildSalesCodRecipes(): {
+  salesTransaction: PostingRecipe<SalesTransactionRecipeInput>;
+  dailyPosSummary: PostingRecipe<DailyPosSummaryRecipeInput>;
+  refund: PostingRecipe<RefundRecipeInput>;
+  codPlacement: PostingRecipe<CodPlacementRecipeInput>;
+  codSettlement: PostingRecipe<CodSettlementRecipeInput>;
+  codCancellation: PostingRecipe<CodCancellationRecipeInput>;
+  restockingFee: PostingRecipe<RestockingFeeRecipeInput>;
+};
+//#endregion
+//#region src/posting-recipes/inventory-transfer.recipes.d.ts
+type StockAdjustmentType = 'loss' | 'gain' | 'correction' | 'opening';
+interface StockAdjustmentRecipeInput {
+  adjustmentId: string;
+  referenceNumber?: string | undefined;
+  type: StockAdjustmentType;
+  amount: number;
+  date: Date;
+  reason?: string | undefined;
+  description?: string | undefined;
+  sourceModel?: string | undefined;
+  sourceId?: string | undefined;
+}
+interface CogsRecipeInput {
+  orderId: string;
+  orderReferenceNumber?: string | undefined;
+  costAmount: number;
+  date: Date;
+  metadata?: Record<string, unknown> | undefined;
+}
+interface CogsReversalRecipeInput {
+  returnId: string;
+  orderId: string;
+  returnReferenceNumber?: string | undefined;
+  costAmount: number;
+  date: Date;
+  description?: string | undefined;
+  metadata?: Record<string, unknown> | undefined;
+}
+interface TransferDispatchRecipeInput {
+  transferId: string;
+  documentNumber: string;
+  goodsCost: number;
+  date: Date;
+  /** Sender branch — stamped as the JE's organizationId. */
+  organizationId: string;
+  metadata?: Record<string, unknown> | undefined;
+  reason?: string | undefined;
+}
+interface TransferReceiveRecipeInput {
+  transferId: string;
+  documentNumber: string;
+  goodsCost: number;
+  transitCost?: number | undefined;
+  date: Date;
+  /** Receiver branch — stamped as the JE's organizationId. */
+  organizationId: string;
+  metadata?: Record<string, unknown> | undefined;
+  reason?: string | undefined;
+}
+interface LandedCostAllocationInput {
+  skuRef: string;
+  costLineCode: string;
+  /** Paisa — the handler converts from Flow's major-unit allocations. */
+  allocatedPaisa: number;
+}
+interface LandedCostRecipeInput {
+  landedCostId: string;
+  allocations: ReadonlyArray<LandedCostAllocationInput>;
+  date: Date;
+  reference?: string | undefined;
+}
+declare function landedCostClearingSlot(costLineCode: string): string;
+declare function buildInventoryTransferRecipes(): {
+  stockAdjustment: PostingRecipe<StockAdjustmentRecipeInput>;
+  cogs: PostingRecipe<CogsRecipeInput>;
+  cogsReversal: PostingRecipe<CogsReversalRecipeInput>;
+  transferDispatch: PostingRecipe<TransferDispatchRecipeInput>;
+  transferReceive: PostingRecipe<TransferReceiveRecipeInput>;
+  transferDispatchReversal: PostingRecipe<TransferDispatchRecipeInput>;
+  transferReceiveReversal: PostingRecipe<TransferReceiveRecipeInput>;
+  landedCost: PostingRecipe<LandedCostRecipeInput>;
+  landedCostReversal: PostingRecipe<LandedCostRecipeInput>;
+};
+//#endregion
+//#region src/posting-recipes/misc.recipes.d.ts
+interface SettlementRecipeInput {
+  importId: string;
+  provider: string;
+  externalRef: string;
+  /** GL codes — the original passes explicit codes (host clearing config). */
+  clearingAccountCode: string;
+  bankAccountCode: string;
+  feeAccountCode: string;
+  writeoffAccountCode: string;
+  totalGross: number;
+  totalFee: number;
+  totalWriteoff: number;
+  totalNet: number;
+  date: Date;
+  notes?: string | undefined;
+}
+interface CustomerInvoiceRecipeInput {
+  orderId: string;
+  customerId: string;
+  totalAmount: number;
+  issuedAt: Date;
+  /** Handler computes dueDate ?? addDays(issuedAt, creditDays ?? 0). */
+  dueDate: Date;
+  invoiceNumber?: string | undefined;
+  vatAmount?: number | undefined;
+  withholdVds?: boolean | undefined;
+  vdsRate?: number | undefined;
+}
+interface CustomerReceiptRecipeInput {
+  orderId: string;
+  customerId: string;
+  customerName?: string | undefined;
+  amount: number;
+  date: Date;
+  /** GL code — handler defaults via the 'cash' slot. */
+  toAccountCode: string;
+  reference?: string | undefined;
+}
+interface VendorCreditNoteRecipeInput {
+  sourceId: string;
+  supplierId: string;
+  amount: number;
+  reason: string;
+  reference: string;
+  date: Date;
+  /** GL code override — handler defaults via the 'purchaseReturns' slot. */
+  contraAccountCode: string;
+  currency?: string | undefined;
+  exchangeRate?: number | undefined;
+  foreignAmount?: number | undefined;
+}
+interface CustomerDebitNoteRecipeInput {
+  sourceId: string;
+  customerId: string;
+  amount: number;
+  reason: string;
+  reference: string;
+  date: Date;
+  /** GL code override — handler defaults via the 'salesReturns' slot. */
+  contraAccountCode: string;
+}
+interface OpeningBalanceRecipeInput {
+  side: 'supplier' | 'customer';
+  partnerId: string;
+  partnerName?: string | undefined;
+  amount: number;
+  asOf: Date;
+  reason?: string | undefined;
+}
+/** settlement.contract.ts balance invariant. */
+declare function validateSettlement(i: SettlementRecipeInput): void;
+/** credit-debit-note.contract.ts fintech rules (positive int, reason, reference). */
+declare function validateNoteInput(i: {
+  amount: number;
+  reason: string;
+  reference: string;
+}): void;
+declare function buildMiscRecipes(resolvers: BdPostingResolvers): {
+  settlement: PostingRecipe<SettlementRecipeInput>;
+  customerInvoice: PostingRecipe<CustomerInvoiceRecipeInput>;
+  customerReceipt: PostingRecipe<CustomerReceiptRecipeInput>;
+  vendorCreditNote: PostingRecipe<VendorCreditNoteRecipeInput>;
+  customerDebitNote: PostingRecipe<CustomerDebitNoteRecipeInput>;
+  openingBalance: PostingRecipe<OpeningBalanceRecipeInput>;
+};
+//#endregion
+export { BD_REQUIRED_POSTING_SLOTS, type BdAccountingRegime, type BdImportStackResult, type BdPostingResolvers, type CodCancellationRecipeInput, type CodPlacementRecipeInput, type CodSettlementRecipeInput, type CogsRecipeInput, type CogsReversalRecipeInput, type CustomerDebitNoteRecipeInput, type CustomerInvoiceRecipeInput, type CustomerReceiptRecipeInput, type DailyPosSummaryRecipeInput, type GoodsReceiptRecipeInput, INVENTORY_SLOT, type ImportClearanceRecipeInput, type LandedCostAllocationInput, type LandedCostRecipeInput, type OpeningBalanceRecipeInput, PAYMENT_METHOD_SLOT, type PurchaseRecipeInput, RESTOCKING_METHOD_SLOT, type RefundRecipeInput, type RestockingFeeRecipeInput, type SalesTransactionRecipeInput, type SettlementRecipeInput, type StockAdjustmentRecipeInput, type StockAdjustmentType, type SupplierReturnRecipeInput, type TransferDispatchRecipeInput, type TransferReceiveRecipeInput, type VendorBillRecipeInput, type VendorBillReversalRecipeInput, type VendorCreditNoteRecipeInput, type VendorPaymentRecipeInput, buildBdPostingRecipes, buildInventoryTransferRecipes, buildMiscRecipes, buildPurchaseRecipes, buildSalesCodRecipes, displayRef, inventorySlotFor, landedCostClearingSlot, paymentMethodSlot, validateCodSettlement, validateCodSettlementInputs, validateNoteInput, validateSettlement };