@go-avro/avro-js 0.0.49 → 0.0.50

package/dist/billing/fees.d.ts

@@ -0,0 +1,40 @@
+import { PaymentType } from '../types/api/PaymentType';
+export interface PassOnFeeBreakdown {
+    /** Stripe processing fee on the grossed-up amount, in cents. */
+    stripeFee: number;
+    /** Avro application fee on the net (gross - stripeFee), in cents. */
+    avroFee: number;
+    /** Total fee added on top of the subtotal: stripeFee + avroFee. */
+    totalFee: number;
+    /** Gross amount the customer is charged: subtotal + totalFee. */
+    gross: number;
+}
+/**
+ * Compute Stripe's processing fee on a gross amount, in cents.
+ * Ceiling matches Stripe's worst-case rounding so the merchant is never short.
+ */
+export declare function computeStripeFee(grossCents: number, method: PaymentType): number;
+/**
+ * Compute Avro's application fee on a net amount (gross - stripeFee), in cents.
+ */
+export declare function computeAvroFee(netCents: number): number;
+/**
+ * Compute the pass-on fee (in cents) such that, after Stripe and Avro deduct
+ * their fees from the gross amount the customer is charged, the merchant
+ * receives at least `subtotalCents`.
+ *
+ * Returns `ZERO_FEE` when `subtotalCents <= 0`.
+ *
+ * Closed form: a finite set of candidate grosses is derived from each fee
+ * regime (avro at the 5¢ floor vs. percentage; ACH stripe at the $5 cap vs.
+ * percentage). The smallest candidate that satisfies the invariant
+ * `gross - stripeFee(gross) - avroFee(gross - stripeFee(gross)) >= subtotal`
+ * is selected. No iteration.
+ */
+export declare function computePassOnFee(subtotalCents: number, method: PaymentType): PassOnFeeBreakdown;
+/**
+ * Pick the payment method to use when computing the persisted ("default")
+ * fee line item amount on a bill. Card if enabled (worst case for the
+ * customer), otherwise ACH, otherwise null (no fee should be persisted).
+ */
+export declare function defaultPassOnFeeMethod(enabledPaymentMethods: PaymentType[] | null | undefined): PaymentType | null;

package/dist/billing/fees.js

@@ -0,0 +1,155 @@
+import { PaymentType } from '../types/api/PaymentType';
+/**
+ * Pass-on (surcharge) fee calculations.
+ *
+ * When `pass_on_fees` is enabled on a bill, the customer is charged a gross
+ * amount that, after Stripe's processing fees and Avro's application fee, leaves
+ * the merchant with the bill's subtotal. The fee added on top of the subtotal
+ * is exposed as a single read-only line item on the bill.
+ *
+ * Stripe US standard pricing (online):
+ *   - Card:          2.9% of gross + 30¢
+ *   - ACH (us_bank): 0.8% of gross, capped at $5.00
+ * Avro application fee:
+ *   - 0.4% of net (gross - stripe), minimum 5¢
+ *
+ * All amounts are integer cents. All math is closed-form (no iteration).
+ *
+ * The integer-ceiling on the gross-up guarantees the merchant nets at
+ * least the requested subtotal. In rare regime-boundary cases the merchant
+ * may net a sub-cent more than requested — never less.
+ */
+// --- Rate constants (per 1000 for integer math where applicable) ---
+const CARD_PCT_PER_1000 = 29; // 2.9%
+const CARD_FIXED_CENTS = 30; // 30¢
+const ACH_PCT_PER_1000 = 8; // 0.8%
+const ACH_CAP_CENTS = 500; // $5.00
+const AVRO_PCT_PER_1000 = 4; // 0.4%
+const AVRO_MIN_CENTS = 5; // 5¢
+const ZERO_FEE = {
+    stripeFee: 0,
+    avroFee: 0,
+    totalFee: 0,
+    gross: 0,
+};
+/**
+ * Compute Stripe's processing fee on a gross amount, in cents.
+ * Ceiling matches Stripe's worst-case rounding so the merchant is never short.
+ */
+export function computeStripeFee(grossCents, method) {
+    if (grossCents <= 0)
+        return 0;
+    if (method === PaymentType.CARD) {
+        return Math.ceil((CARD_PCT_PER_1000 * grossCents) / 1000) + CARD_FIXED_CENTS;
+    }
+    // us_bank_account: percentage capped at $5.00
+    return Math.min(Math.ceil((ACH_PCT_PER_1000 * grossCents) / 1000), ACH_CAP_CENTS);
+}
+/**
+ * Compute Avro's application fee on a net amount (gross - stripeFee), in cents.
+ */
+export function computeAvroFee(netCents) {
+    if (netCents <= 0)
+        return AVRO_MIN_CENTS;
+    return Math.max(Math.ceil((AVRO_PCT_PER_1000 * netCents) / 1000), AVRO_MIN_CENTS);
+}
+/**
+ * Compute the pass-on fee (in cents) such that, after Stripe and Avro deduct
+ * their fees from the gross amount the customer is charged, the merchant
+ * receives at least `subtotalCents`.
+ *
+ * Returns `ZERO_FEE` when `subtotalCents <= 0`.
+ *
+ * Closed form: a finite set of candidate grosses is derived from each fee
+ * regime (avro at the 5¢ floor vs. percentage; ACH stripe at the $5 cap vs.
+ * percentage). The smallest candidate that satisfies the invariant
+ * `gross - stripeFee(gross) - avroFee(gross - stripeFee(gross)) >= subtotal`
+ * is selected. No iteration.
+ */
+export function computePassOnFee(subtotalCents, method) {
+    if (subtotalCents <= 0)
+        return { ...ZERO_FEE };
+    const B = subtotalCents;
+    const candidates = method === PaymentType.CARD ? cardCandidates(B) : achCandidates(B);
+    let best = Number.POSITIVE_INFINITY;
+    for (const g of candidates) {
+        const stripe = computeStripeFee(g, method);
+        const avro = computeAvroFee(g - stripe);
+        if (g - stripe - avro >= B && g < best) {
+            best = g;
+        }
+    }
+    if (!Number.isFinite(best)) {
+        // Should never happen — the candidate set covers every regime — but
+        // fall back to a safe overshoot rather than throwing.
+        best = B + Math.ceil(B * 0.05) + CARD_FIXED_CENTS + AVRO_MIN_CENTS;
+    }
+    const stripeFee = computeStripeFee(best, method);
+    const avroFee = computeAvroFee(best - stripeFee);
+    return {
+        stripeFee,
+        avroFee,
+        totalFee: best - B,
+        gross: best,
+    };
+}
+/**
+ * Card regime candidates.
+ *
+ * Stripe = ceil(0.029 * G) + 30; avro = max(ceil(0.004 * (G - stripe)), 5).
+ *
+ * The two `ceil`s can each add up to 1¢ relative to the exact rational form,
+ * so each candidate carries a baked-in 2¢ (percentage regime) or 1¢ (floor
+ * regime) safety margin to guarantee the invariant holds for every B in
+ * integer cents — no post-hoc iteration required.
+ *
+ * 1) Percentage avro:  G * 0.967116 ≥ B + 29.88 + 2
+ *      => G = ceil((1_000_000 * B + 31_880_000) / 967_116)
+ * 2) Floor avro (5¢):  G * 0.971    ≥ B + 35 + 1
+ *      => G = ceil((1000 * B + 36_000) / 971)
+ */
+function cardCandidates(B) {
+    return [
+        Math.ceil((1000000 * B + 31880000) / 967116),
+        Math.ceil((1000 * B + 36000) / 971),
+    ];
+}
+/**
+ * ACH regime candidates.
+ *
+ * Stripe = min(ceil(0.008 * G), 500); avro = max(ceil(0.004 * (G - stripe)), 5).
+ *
+ * Same ceiling-safety logic as card. Stripe at the $5 cap is a fixed integer
+ * so its ceiling-slack disappears in the capped regimes.
+ *
+ * 1) No-cap percentage avro: G * 0.988032 ≥ B + 2
+ *      => G = ceil((1_000_000 * (B + 2)) / 988_032)
+ * 2) No-cap floor avro:      G * 0.992    ≥ B + 5 + 1
+ *      => G = ceil((1000 * (B + 6)) / 992)
+ * 3) Capped percentage avro: G * 0.996    ≥ B + 498 + 1
+ *      => G = ceil((1000 * (B + 499)) / 996)
+ * 4) Capped floor avro:      G = B + 505
+ */
+function achCandidates(B) {
+    return [
+        Math.ceil((1000000 * (B + 2)) / 988032),
+        Math.ceil((1000 * (B + 6)) / 992),
+        Math.ceil((1000 * (B + 499)) / 996),
+        B + 505,
+    ];
+}
+/**
+ * Pick the payment method to use when computing the persisted ("default")
+ * fee line item amount on a bill. Card if enabled (worst case for the
+ * customer), otherwise ACH, otherwise null (no fee should be persisted).
+ */
+export function defaultPassOnFeeMethod(enabledPaymentMethods) {
+    if (!enabledPaymentMethods || enabledPaymentMethods.length === 0)
+        return null;
+    if (enabledPaymentMethods.includes(PaymentType.CARD))
+        return PaymentType.CARD;
+    if (enabledPaymentMethods.includes(PaymentType.US_BANK_ACCOUNT)) {
+        return PaymentType.US_BANK_ACCOUNT;
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -32,6 +32,8 @@ import './client/hooks/proposal';
 import './client/hooks/timecards';
 import './client/hooks/waivers';
 import './client/hooks/email';
+export { computePassOnFee, computeStripeFee, computeAvroFee, defaultPassOnFeeMethod, } from './billing/fees';
+export type { PassOnFeeBreakdown } from './billing/fees';
 export * from './types/api';
 export * from './types/auth';
 export * from './types/cache';

package/dist/index.js

@@ -30,6 +30,7 @@ import './client/hooks/proposal';
 import './client/hooks/timecards';
 import './client/hooks/waivers';
 import './client/hooks/email';
+export { computePassOnFee, computeStripeFee, computeAvroFee, defaultPassOnFeeMethod, } from './billing/fees';
 export * from './types/api';
 export * from './types/auth';
 export * from './types/cache';

package/dist/types/api/Bill.d.ts

@@ -2,6 +2,8 @@ import { BillPayment } from '../../types/api/BillPayment';
 import { BillUser } from '../../types/api/BillUser';
 import { CustomLineItem } from '../../types/api/CustomLineItem';
 import { PaymentType } from '../../types/api/PaymentType';
+import { ProcessingFeeLineItem } from '../../types/api/ProcessingFeeLineItem';
+export type BillLineItem = CustomLineItem | ProcessingFeeLineItem;
 export declare const BillStatus: {
     readonly SENT: "SENT";
     readonly PAID: "PAID";
@@ -27,8 +29,9 @@ export interface Bill {
     intent_created_at: number;
     intent_last_created_at: number;
     payments: BillPayment[];
-    line_items: CustomLineItem[];
+    line_items: BillLineItem[];
     prepayments: string[];
     months: string[];
     due_date: number;
+    pass_on_fees: boolean;
 }

package/dist/types/api/Company.d.ts

@@ -58,4 +58,5 @@ export interface Company {
     next_payment_due: number | null;
     timecard_base: number;
     timecard_length: number;
+    default_pass_on_fees: boolean;
 }

package/dist/types/api/LineItem.d.ts

@@ -14,6 +14,7 @@ export declare const LineItemType: {
     readonly EVENT: "EVENT";
     readonly SERVICE_MONTH: "SERVICE_MONTH";
     readonly PREPAYMENT: "PREPAYMENT";
+    readonly PROCESSING_FEE: "PROCESSING_FEE";
 };
 export type LineItemType = (typeof LineItemType)[keyof typeof LineItemType];
 declare module '../../types/api/LineItem' {

package/dist/types/api/LineItem.js

@@ -13,6 +13,7 @@ export const LineItemType = {
     EVENT: 'EVENT',
     SERVICE_MONTH: 'SERVICE_MONTH',
     PREPAYMENT: 'PREPAYMENT',
+    PROCESSING_FEE: 'PROCESSING_FEE',
 };
 export class LineItem {
     constructor(init) {

package/dist/types/api/ProcessingFeeLineItem.d.ts

@@ -0,0 +1,21 @@
+import { LineItem } from '../../types/api/LineItem';
+import { PaymentType } from '../../types/api/PaymentType';
+/**
+ * A read-only line item populated by the backend when the bill has
+ * `pass_on_fees` enabled. Represents the Stripe + Avro processing fees being
+ * passed on to the end customer.
+ *
+ * Merchants cannot edit, add, or delete these rows directly; they are managed
+ * by the server (created on bill save, recomputed when the payment method
+ * changes at checkout, and reconciled to the actual collected fees on
+ * `payment_intent.succeeded`).
+ *
+ * `payment_method_assumption` records which method was used to compute the
+ * current `cost`. UI surfaces (invoice details, email PDF, QB sync) display
+ * this value so the merchant knows whether the persisted figure is the card
+ * estimate, the ACH estimate, or the actual reconciled amount.
+ */
+export interface ProcessingFeeLineItem extends LineItem {
+    line_item_type: 'PROCESSING_FEE';
+    payment_method_assumption: PaymentType | null;
+}

package/dist/types/api/ProcessingFeeLineItem.js

@@ -0,0 +1 @@
+export {};

package/dist/types/api.d.ts

@@ -25,6 +25,7 @@ export * from '../types/api/PaymentType';
 export * from '../types/api/Plan';
 export * from '../types/api/PlanPayment';
 export * from '../types/api/Prepayment';
+export * from '../types/api/ProcessingFeeLineItem';
 export * from '../types/api/Reaction';
 export * from '../types/api/Route';
 export * from '../types/api/RouteJob';

package/dist/types/api.js

@@ -24,6 +24,7 @@ export * from '../types/api/PaymentType';
 export * from '../types/api/Plan';
 export * from '../types/api/PlanPayment';
 export * from '../types/api/Prepayment';
+export * from '../types/api/ProcessingFeeLineItem';
 export * from '../types/api/Reaction';
 export * from '../types/api/Route';
 export * from '../types/api/RouteJob';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-avro/avro-js",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "description": "JS client for Avro backend integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",