@classytic/ledger-bd 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2]
+
+### Added
+
+**`BD_ACCOUNT_CODES` map** — canonical export of domain-meaningful keys
+to 4-digit chart codes (e.g. `BD_ACCOUNT_CODES.AR === '1141'`). Hosts
+build their posting contracts against this map instead of hand-coding
+chart-code literals. The map covers the codes most posting layers
+reference (cash/AR/AP/inventory/COGS/revenue/tax/clearings) and is
+typed with `BDAccountCode` and `BDAccountKey` helpers.
+
+Hosts that need different default mappings (e.g. a manufacturer
+defaulting `MERCHANDISE → FINISHED_GOODS`) layer their own thin alias
+module on top — the chart is the same; the host's "default inventory
+account" is policy. See `BDAccountCode` for the typed key list.
+
+**Two clearing-account codes** in the liability section (2125 / 2126),
+matching SAP / Oracle / ERPNext placement (clearings have credit-natural
+balances, so they belong in 2xxx, not 1xxx):
+
+- **`2125` — Goods Received / Invoice Received (GR/IR)** — accrued
+  liability for physical goods receipt pending vendor invoice. Decouples
+  physical receipt from financial posting:
+  - Receipt: `Dr Inventory / Cr 2125`
+  - Vendor bill: `Dr 2125 / Cr AP`
+  - Period-end balance = receipts pending invoice (accrual reportable
+    on the balance sheet). Cleared on 3-way match (PO ↔ receipt ↔
+    invoice).
+
+- **`2126` — Transfer Cost Clearing (Inter-Branch)** — accrued liability
+  for inter-branch transit costs capitalized into receiver inventory per
+  IAS 2:
+  - Receive leg: `Dr 1164 (goods + transit) / Cr 1179 (goods) / Cr 2126 (transit)`
+  - Host clears against actual freight invoice: `Dr 2126 / Cr AP`
+
+Both codes slot into the previously-empty 2125–2126 gap in the chart
+(between 2124 Freight & Shipping Payable and 2131 Income Tax Payable),
+so no existing seeded codes shift.
+
+### Migration
+
+Pure additive change. Run `seedAccounts()` once after upgrade to pick up
+the two new codes — `accountRepository.seedAccounts()` is idempotent and
+will not modify pre-existing accounts.
+
 ## [0.2.1]
 
 ### Added

package/dist/index.d.mts

@@ -49,6 +49,106 @@ declare const TDS_LIABILITY_ACCOUNTS: AccountType[];
 declare const VDS_LIABILITY_ACCOUNTS: AccountType[];
 declare const ALL_TAX_ACCOUNTS: AccountType[];
 //#endregion
+//#region src/accounts/codes.d.ts
+/**
+ * Canonical BD chart account codes — domain-meaningful keys to the
+ * 4-digit chart codes that posting layers reference.
+ *
+ * This is the **fact** layer (chart of accounts is what it is). Hosts
+ * import these to write posting contracts:
+ *
+ * ```typescript
+ * import { BD_ACCOUNT_CODES as BD } from '@classytic/ledger-bd';
+ *
+ * { accountCode: BD.AR, debit: 1000, credit: 0 }   // 1141 Accounts Receivable
+ * ```
+ *
+ * Hosts that want different default mappings (e.g. a manufacturer
+ * defaulting to `FINISHED_GOODS` instead of `MERCHANDISE` for "the
+ * inventory account") layer their own thin alias module on top —
+ * never edit this file. It's the chart, not policy.
+ *
+ * Pinned to the codes seeded by `BD_ACCOUNT_TYPES` in this same package.
+ * Adding a code here without seeding it via the chart will cause
+ * `accountRepository.resolveAccountId(code)` to fail at runtime.
+ */
+declare const BD_ACCOUNT_CODES: {
+  /**
+   * 1113 — Cash at Bank (Current Account). The normal default for
+   * "where receipts land". NOT 1112 — that's "Cash in Hand (Foreign
+   * Currency)" in this chart, a common mis-mapping in BD ERP setups.
+   */
+  readonly CASH: "1113"; /** 1111 — Cash in Hand (Petty Cash). Use for petty-cash accounts only. */
+  readonly PETTY_CASH: "1111"; /** 1123 — Per-register POS till float (cash drawer). */
+  readonly POS_DRAWER: "1123"; /** 1124 — POS reconciliation variance (over/short clearing). */
+  readonly POS_OVER_SHORT: "1124"; /** 1125 — Payment gateway proceeds awaiting bank settlement. */
+  readonly GATEWAY_CLEARING: "1125"; /** 1126 — Mobile money merchant balance (bKash/Nagad/Rocket merchant). */
+  readonly MOBILE_MONEY_MERCHANT: "1126"; /** 1127 — COD cash held by courier awaiting remittance. */
+  readonly COD_CLEARING: "1127";
+  readonly AR: "1141"; /** 1158 — Net amount due from marketplaces (Daraz/Chaldal/Pickaboo). */
+  readonly MARKETPLACE_RECEIVABLE: "1158";
+  /**
+   * 1145 — Receivable from Related Parties.
+   * Used as inter-branch receivable when consolidated reporting needs
+   * explicit settlement balances. For standard inter-branch transfers
+   * the `1179` clearing path is sufficient.
+   */
+  readonly INTER_BRANCH_RECEIVABLE: "1145";
+  readonly VAT_RECEIVABLE: "1150";
+  readonly ADVANCE_INCOME_TAX: "1151";
+  readonly VAT_CASH_BASIS_TRANSITION: "1157";
+  readonly RAW_MATERIALS: "1161";
+  readonly WIP: "1162";
+  readonly FINISHED_GOODS: "1163";
+  /**
+   * 1164 — Merchandise / Trading Goods. The retail default for stock
+   * movements (procurement, sales COGS, transfers, adjustments). NOTE:
+   * earlier (pre-0.2.2) BFRS audits sometimes confused this with 1165;
+   * `1165` is Packing Materials in this chart.
+   */
+  readonly MERCHANDISE: "1164";
+  readonly PACKING_MATERIALS: "1165";
+  readonly INVENTORY_IN_TRANSIT: "1179";
+  readonly AP: "2111";
+  readonly BILLS_PAYABLE: "2112";
+  /**
+   * 2113 — Payable to Related Parties.
+   * Mirror of 1145 for intra-company settlements.
+   */
+  readonly INTER_BRANCH_PAYABLE: "2113";
+  readonly ACCRUED_EXPENSES: "2114";
+  readonly FREIGHT_PAYABLE: "2124";
+  /**
+   * 2125 — Goods Received / Invoice Received (GR/IR).
+   * Accrued liability for goods physically received but not yet
+   * billed. Receipt: `Dr Inventory / Cr 2125`. Bill: `Dr 2125 / Cr AP`.
+   * Cleared on 3-way match. SAP/Oracle/ERPNext-aligned placement.
+   */
+  readonly GR_IR_CLEARING: "2125";
+  /**
+   * 2126 — Transfer Cost Clearing (Inter-Branch).
+   * Capitalization clearing for inter-branch transit costs into
+   * receiver inventory per IAS 2. Receive: `Dr 1164 (goods + transit)
+   * / Cr 1179 (goods) / Cr 2126 (transit)`. Cleared by host against
+   * actual freight invoices.
+   */
+  readonly TRANSFER_COST_CLEARING: "2126"; /** 2127 — Goods returned in transit, awaiting RMA receipt + inspection. */
+  readonly SALES_RETURN_CLEARING: "2127"; /** 2128 — Approved customer refund authorized but not yet remitted. */
+  readonly REFUND_PAYABLE: "2128"; /** 2129 — Customer pre-paid balance (gift cards, vouchers). */
+  readonly GIFT_CARD_LIABILITY: "2129"; /** 2130 — Customer in-store credit balance. */
+  readonly STORE_CREDIT_LIABILITY: "2130"; /** 2160 — Outstanding loyalty points valued per IFRS 15. */
+  readonly LOYALTY_POINT_LIABILITY: "2160";
+  readonly INCOME_TAX_PAYABLE: "2131";
+  readonly VAT_OUTPUT_PAYABLE: "2132";
+  readonly TDS_PAYABLE: "2135";
+  readonly SALES_REVENUE: "4111"; /** 5111 — Cost of Goods Sold — Raw Materials */
+  readonly COGS_MATERIALS: "5111"; /** 6703 — Inventory Write-down / Obsolescence (slow-moving / expired). */
+  readonly OBSOLESCENCE: "6703"; /** 6711 — Inventory Shrinkage / Theft / Loss (audit shortfall). */
+  readonly SHRINKAGE: "6711";
+};
+type BDAccountCode = (typeof BD_ACCOUNT_CODES)[keyof typeof BD_ACCOUNT_CODES];
+type BDAccountKey = keyof typeof BD_ACCOUNT_CODES;
+//#endregion
 //#region src/accounts/index.d.ts
 /** Complete flat array of all BD account types + tax sub-accounts + group labels */
 declare const BD_ACCOUNT_TYPES: readonly AccountType[];
@@ -176,4 +276,4 @@ declare const ALL_DIVISIONS: ("Dhaka" | "Chittagong" | "Rajshahi" | "Khulna" | "
  */
 declare const bangladeshPack: _$_classytic_ledger0.CountryPack;
 //#endregion
-export { ADMIN_EXPENSES, ALL_DIVISIONS, ALL_TAX_ACCOUNTS, ASSETS, BANKING_REVENUE, BD_ACCOUNT_TYPES, BD_DIVISIONS, COGS, COST_OF_SERVICES, CURRENT_ASSETS, CURRENT_LIABILITIES, DEPRECIATION, DIRECT_LABOR, DIRECT_MATERIALS, DIVISIONS, EMPLOYEE_COSTS, EQUITY, EXPENSES, FINANCIAL_EXPENSES, INDUSTRY_REVENUE, LIABILITIES, MANUFACTURING_OVERHEAD, NGO_REVENUE, NON_CURRENT_ASSETS, NON_CURRENT_LIABILITIES, OTHER_INCOME, OTHER_OPERATING, PREMISES_COSTS, PROVISIONS, PURCHASES, REVENUE, SALES_REVENUE, SELLING_DISTRIBUTION, ALL_TAX_CODES as TAX_CODES, TAX_CODES_BY_DIVISION, TAX_EXPENSE, TDS_LIABILITY_ACCOUNTS, VAT_ASSET_ACCOUNTS, VAT_LIABILITY_ACCOUNTS, VDS_LIABILITY_ACCOUNTS, bangladeshPack, getTaxCodeDetails, mushakReturnTemplate };
+export { ADMIN_EXPENSES, ALL_DIVISIONS, ALL_TAX_ACCOUNTS, ASSETS, BANKING_REVENUE, type BDAccountCode, type BDAccountKey, BD_ACCOUNT_CODES, BD_ACCOUNT_TYPES, BD_DIVISIONS, COGS, COST_OF_SERVICES, CURRENT_ASSETS, CURRENT_LIABILITIES, DEPRECIATION, DIRECT_LABOR, DIRECT_MATERIALS, DIVISIONS, EMPLOYEE_COSTS, EQUITY, EXPENSES, FINANCIAL_EXPENSES, INDUSTRY_REVENUE, LIABILITIES, MANUFACTURING_OVERHEAD, NGO_REVENUE, NON_CURRENT_ASSETS, NON_CURRENT_LIABILITIES, OTHER_INCOME, OTHER_OPERATING, PREMISES_COSTS, PROVISIONS, PURCHASES, REVENUE, SALES_REVENUE, SELLING_DISTRIBUTION, ALL_TAX_CODES as TAX_CODES, TAX_CODES_BY_DIVISION, TAX_EXPENSE, TDS_LIABILITY_ACCOUNTS, VAT_ASSET_ACCOUNTS, VAT_LIABILITY_ACCOUNTS, VDS_LIABILITY_ACCOUNTS, bangladeshPack, getTaxCodeDetails, mushakReturnTemplate };