flexpay-engine 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,52 @@
+# flexpay-engine
+
+FlexPay loan servicing engine — pricing, schedules, allocation, delinquency.
+
+## Installation
+
+```bash
+bun add flexpay-engine
+```
+
+## Usage
+
+```typescript
+import { recordPayment, toCents, seedContract } from 'flexpay-engine';
+import { engineContracts, enginePayments } from 'flexpay-engine/schema';
+```
+
+## Publishing to npm
+
+1. Bump version in `package.json`
+2. Commit: `git commit -am "chore: bump to vX.Y.Z"`
+3. Publish: `npm publish --access public --otp=YOUR_CODE`
+4. Update consumers:
+   ```bash
+   # In flexpay-client-worker
+   bun add flexpay-engine@X.Y.Z
+   
+   # In flexpay-backend
+   bun add flexpay-engine@X.Y.Z
+   ```
+5. Commit lockfile changes in each consumer repo
+
+## Versioning
+
+- **Patch** (0.1.x): Bug fixes, no API changes
+- **Minor** (0.x.0): New features, backwards compatible
+- **Major** (x.0.0): Breaking changes
+
+## Consumers
+
+- `flexpay-client-worker` — portal payments (PORTAL source)
+- `flexpay-backend` — ChinChin payments (CHINCHIN source)
+
+Both write to shared D1 database `ENGINE_DB`.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+```

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "flexpay-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "FlexPay loan servicing engine — pricing, schedules, allocation, delinquency",
   "license": "MIT",
   "main": "src/index.ts",
   "types": "src/index.ts",
-  "files": ["src"],
+  "files": [
+    "src"
+  ],
   "exports": {
     ".": {
       "types": "./src/index.ts",

package/src/calc/pricing.ts

@@ -5,7 +5,7 @@ import type { PricingInput, PricingResult } from "../types";
  * Uses Number.EPSILON to handle floating-point edge cases (e.g., 1.005).
  */
 export function round2(n: number): number {
-  return Math.round((n + Number.EPSILON) * 100) / 100;
+  return Math.round((n + Number.EPSILON * Math.sign(n)) * 100) / 100;
 }
 
 /**

package/src/operations/originate.ts

@@ -30,6 +30,13 @@ export async function originateContract(
   db: EngineDb,
   input: OriginateContractInput,
 ): Promise<OriginateContractResult> {
+  if (!Number.isFinite(input.basePrice) || input.basePrice <= 0) {
+    throw new Error(`Invalid basePrice: ${input.basePrice}`);
+  }
+  if (input.numInstallments < 0) {
+    throw new Error(`Invalid numInstallments: ${input.numInstallments}`);
+  }
+
   // 1. Pure calc: pricing
   const pricing = calculatePricing({
     basePrice: input.basePrice,

package/src/operations/recordPayment.ts

@@ -2,7 +2,7 @@
 // recordPayment — Allocate a payment against an engine contract
 // ============================================================
 
-import { eq, sql } from "drizzle-orm";
+import { eq } from "drizzle-orm";
 import { allocatePayment } from "../calc/allocation";
 import {
   engineContracts,
@@ -12,13 +12,15 @@ import {
   type NewEnginePayment,
   type NewEnginePaymentLine,
 } from "../schema";
-import type {
-  InstallmentState,
-  InstallmentStatus,
+import {
+  ContractAlreadyPaidOffError,
+  type InstallmentState,
+  type InstallmentStatus,
 } from "../types";
 import { fromCents, toCents } from "../utils/cents";
 import {
   ContractNotFoundError,
+  EngineOperationError,
   type EngineDb,
   type RecordPaymentInput,
   type RecordPaymentResult,
@@ -54,6 +56,17 @@ export async function recordPayment(
     throw new ContractNotFoundError(input.contractNumber);
   }
 
+  if (contract.status === "COMPLETED") {
+    throw new ContractAlreadyPaidOffError();
+  }
+
+  if (!Number.isInteger(input.amountCents) || input.amountCents <= 0) {
+    throw new EngineOperationError(
+      `Invalid amountCents: ${input.amountCents}`,
+      "INVALID_AMOUNT",
+    );
+  }
+
   // 2. Idempotency check — duplicate transactionId is a no-op success
   const existing = await db
     .select({ id: enginePayments.id })
@@ -112,11 +125,6 @@ export async function recordPayment(
     createdAt: now,
   };
 
-  // Index allocations by installment id for update statements
-  const allocationByInstallmentId = new Map(
-    allocation.allocations.map((a) => [a.installmentId, a]),
-  );
-
   // New totals for contract (in cents)
   const newTotalPaidCents = toCents(allocation.newTotalPaid);
   const newRemainingCents = toCents(allocation.newRemainingDebt);

package/src/schema/index.ts

@@ -10,7 +10,7 @@
 // See docs/plans/2026-04-09-native-engine-design.md §3
 // ============================================================
 
-import { sqliteTable, text, integer, index } from "drizzle-orm/sqlite-core";
+import { sqliteTable, text, integer, index, uniqueIndex } from "drizzle-orm/sqlite-core";
 
 // --- Contracts -----------------------------------------------
 
@@ -61,6 +61,7 @@ export const engineInstallments = sqliteTable(
   },
   (t) => ({
     contractIdx: index("idx_installments_contract").on(t.contractNumber),
+    uniqueSeq: uniqueIndex("idx_installments_unique").on(t.contractNumber, t.sequenceNumber),
   }),
 );