@go-avro/avro-js 0.0.48 → 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/client/QueryClient.d.ts

@@ -9,17 +9,9 @@ import { CacheData } from '../types/cache';
 import { Waiver } from '../types/api/Waiver';
 import type { EmailSucceededPayload, EmailFailedPayload, EmailType } from '../types/api/EmailNotification';
 import type { BulkDeleteBillsResponse, BulkEmailBillsResponse } from '../client/hooks/bills';
-/** Callbacks for a tracked email request. */
 export interface TrackEmailOptions {
     emailType?: EmailType;
-    /**
-     * Pre-existing request_id to register. When omitted, a fresh uuid is
-     * generated. Pass this when the request_id was produced elsewhere
-     * (e.g. a bulk endpoint returns one in its synchronous response, or
-     * the caller wants to pre-generate it and ship it in the POST body).
-     */
     requestId?: string;
-    /** How long to wait before firing onTimeout (ms). Default 30 000. */
     timeout?: number;
     onSuccess?: (data: EmailSucceededPayload) => void;
     onFailure?: (data: EmailFailedPayload) => void;
@@ -757,20 +749,7 @@ export declare class AvroQueryClient {
         query?: string;
         offset?: number;
     }, cancelToken?: CancelToken, headers?: Record<string, string>): Promise<any>;
-    /**
-     * Lazily register socket listeners for email_succeeded / email_failed.
-     * Listeners live on the socket (not in a React effect) so they survive
-     * component unmounts.
-     */
     private _initEmailListeners;
-    /**
-     * Track an outbound email request.
-     *
-     * Generates a `request_id`, registers socket listeners (once), and returns
-     * the ID so callers can pass it in the HTTP body. The backend emits
-     * `email_succeeded` / `email_failed` to the user's GUID room; this method
-     * correlates the event by `request_id` and fires the appropriate callback.
-     */
     trackEmail(options?: TrackEmailOptions): string;
     sendEmail(emailId: string, formData: FormData, progressUpdateCallback?: (loaded: number, total: number) => void): Promise<void>;
     sendBillEmail(billId: string, body?: {

package/dist/client/QueryClient.js

@@ -1100,12 +1100,6 @@ export class AvroQueryClient {
             throw new StandardError(500, 'Failed to fetch sessions');
         });
     }
-    /* ── Email delivery tracking ──────────────────────────────────────── */
-    /**
-     * Lazily register socket listeners for email_succeeded / email_failed.
-     * Listeners live on the socket (not in a React effect) so they survive
-     * component unmounts.
-     */
     _initEmailListeners() {
         if (this._emailListenersInit)
             return;
@@ -1114,7 +1108,6 @@ export class AvroQueryClient {
             const entry = this._emailTracking.get(data.request_id);
             if (!entry)
                 return;
-            // Reset timeout — more recipients may follow for the same request_id
             clearTimeout(entry.timerId);
             entry.timerId = setTimeout(() => {
                 this._emailTracking.delete(data.request_id);
@@ -1132,21 +1125,10 @@ export class AvroQueryClient {
             entry.onFailure?.(data);
         });
     }
-    /**
-     * Track an outbound email request.
-     *
-     * Generates a `request_id`, registers socket listeners (once), and returns
-     * the ID so callers can pass it in the HTTP body. The backend emits
-     * `email_succeeded` / `email_failed` to the user's GUID room; this method
-     * correlates the event by `request_id` and fires the appropriate callback.
-     */
     trackEmail(options = {}) {
         this._initEmailListeners();
         const requestId = options.requestId ?? uuidv4();
         const { timeout = 30000 } = options;
-        // If this request_id is already being tracked, replace the existing
-        // entry so the latest caller's handlers win. (Callers that reuse a
-        // request_id are explicitly opting in to this behaviour.)
         const existing = this._emailTracking.get(requestId);
         if (existing) {
             clearTimeout(existing.timerId);

package/dist/client/hooks/email.d.ts

@@ -5,43 +5,15 @@ export interface EmailResult {
     status: EmailResultStatus;
     emailType?: EmailType;
     recipient?: string;
-    /**
-     * Bill GUID when the event came from a bill email — single or bulk.
-     * Use this to correlate per-bill outcomes when one `requestId`
-     * covers many bills (`POST /company/<id>/bills/bulk`).
-     */
     billGuid?: string;
     error?: EmailFailedPayload['error'];
 }
 export interface UseEmailStatusOptions {
-    /** How long to wait for a socket event before firing `onTimeout` (ms). Default 30 000. */
     timeout?: number;
-    /** Called when the backend reports success. */
     onSuccess?: (result: EmailResult) => void;
-    /** Called when the backend reports failure. */
     onFailure?: (result: EmailResult) => void;
-    /** Called when neither success nor failure arrives within the timeout window. */
     onTimeout?: (requestId: string) => void;
 }
-/**
- * Subscribe to backend email delivery notifications via Socket.IO.
- *
- * Delegates to `AvroQueryClient.trackEmail()` which registers socket
- * listeners on the client itself (not in a React effect), so
- * notifications survive component unmounts.
- *
- * Usage:
- * ```ts
- * const { trackEmail, pending, results } = useEmailStatus({
- *   onSuccess: (r) => toast.success(`Email sent to ${r.recipient}`),
- *   onFailure: (r) => toast.error(`Email failed: ${r.error?.message}`),
- *   onTimeout: (id) => toast.warn("Email status unknown"),
- * });
- *
- * const requestId = trackEmail("bill");
- * await avroQueryClient.sendBillingEmail({ billId, request_id: requestId });
- * ```
- */
 export declare function useEmailStatus(options?: UseEmailStatusOptions): {
     readonly trackEmail: (emailType?: EmailType, opts?: {
         requestId?: string;

package/dist/client/hooks/email.js

@@ -1,41 +1,16 @@
 import { useCallback, useRef, useState } from 'react';
 import { useAvroQueryClient } from '../../client/AvroQueryClientProvider';
-/* ──────────────────────────────────────────────────────────────────────── */
-/*  Hook                                                                                                                                                                                                        */
-/* ──────────────────────────────────────────────────────────────────────── */
-/**
- * Subscribe to backend email delivery notifications via Socket.IO.
- *
- * Delegates to `AvroQueryClient.trackEmail()` which registers socket
- * listeners on the client itself (not in a React effect), so
- * notifications survive component unmounts.
- *
- * Usage:
- * ```ts
- * const { trackEmail, pending, results } = useEmailStatus({
- *   onSuccess: (r) => toast.success(`Email sent to ${r.recipient}`),
- *   onFailure: (r) => toast.error(`Email failed: ${r.error?.message}`),
- *   onTimeout: (id) => toast.warn("Email status unknown"),
- * });
- *
- * const requestId = trackEmail("bill");
- * await avroQueryClient.sendBillingEmail({ billId, request_id: requestId });
- * ```
- */
 export function useEmailStatus(options = {}) {
     const { timeout = 30000 } = options;
     const client = useAvroQueryClient();
-    // Use refs for callbacks so the client-level handlers always see the latest
     const onSuccessRef = useRef(options.onSuccess);
     const onFailureRef = useRef(options.onFailure);
     const onTimeoutRef = useRef(options.onTimeout);
     onSuccessRef.current = options.onSuccess;
     onFailureRef.current = options.onFailure;
     onTimeoutRef.current = options.onTimeout;
-    // Expose reactive state so the UI can render pending / completed
     const [pending, setPending] = useState(new Map());
     const [results, setResults] = useState(new Map());
-    /* ── trackEmail — delegates to client.trackEmail() ──────────────── */
     const trackEmail = useCallback((emailType, opts = {}) => {
         const requestId = client.trackEmail({
             emailType,

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.48",
+  "version": "0.0.50",
   "description": "JS client for Avro backend integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",