《独立开发者的商业指南·收入与财务工程》9.1 销售税/VAT/GST 的注册与代收

// file: src/tax/sales-tax.ts
// tier: L1
// verify: node --test test/tax/sales-tax.test.ts

import { type Cents, add, sub } from "../core/money.ts";
import { type Bps, applyRate } from "../core/rate.ts";
import { type Result, fail, ok } from "../core/result.ts";

export type TaxedPrice = {
  net: Cents;
  tax: Cents;
  gross: Cents;
};

function isCents(value: number): boolean {
  return Number.isInteger(value) && value >= 0;
}

function isValidRate(rate: Bps): boolean {
  return Number.isInteger(rate) && rate >= 0 && rate < 10000;
}

/**
 * Adds tax to a net (tax-exclusive) price. The tax is rounded once, at the
 * invoice level, so the gross amount is always net plus the booked tax.
 */
export function addTax(net: Cents, rate: Bps): Result<TaxedPrice> {
  if (!isCents(net)) {
    return fail("net price must be a non-negative integer in cents");
  }
  if (!isValidRate(rate)) {
    return fail("tax rate must be an integer between 0 and 9999 bps");
  }
  const tax = applyRate(net, rate);
  return ok({ net, tax, gross: add(net, tax) });
}

/**
 * Extracts tax from a gross (tax-inclusive) price. The net amount is derived
 * first and the tax is the remainder, so net plus tax equals gross exactly.
 */
export function extractTax(gross: Cents, rate: Bps): Result<TaxedPrice> {
  if (!isCents(gross)) {
    return fail("gross price must be a non-negative integer in cents");
  }
  if (!isValidRate(rate)) {
    return fail("tax rate must be an integer between 0 and 9999 bps");
  }
  const net = Math.round((gross * 10000) / (10000 + rate));
  return ok({ net, tax: sub(gross, net), gross });
}

export type RegistrationCheck = {
  required: boolean;
  taxableSales: Cents;
  threshold: Cents;
  headroom: Cents;
};

/**
 * Compares cumulative taxable sales with a registration threshold. The
 * threshold is an input because it depends on jurisdiction, period and the
 * nature of the supply. A negative headroom means the threshold is exceeded.
 */
export function checkRegistration(
  taxableSales: Cents,
  threshold: Cents,
): Result<RegistrationCheck> {
  if (!isCents(taxableSales)) {
    return fail("taxable sales must be a non-negative integer in cents");
  }
  if (!Number.isInteger(threshold) || threshold <= 0) {
    return fail("threshold must be a positive integer in cents");
  }
  return ok({
    required: taxableSales >= threshold,
    taxableSales,
    threshold,
    headroom: sub(threshold, taxableSales),
  });
}

export type CollectionMode = "platform" | "direct";

export type CollectionInput = {
  gross: Cents;
  rate: Bps;
  commissionBps: Bps;
  feeBps: Bps;
  mode: CollectionMode;
};

export type CollectionResult = {
  mode: CollectionMode;
  gross: Cents;
  net: Cents;
  tax: Cents;
  commission: Cents;
  fee: Cents;
  received: Cents;
  taxRemittedBySeller: Cents;
};

function isValidCostRate(rate: Bps): boolean {
  return Number.isInteger(rate) && rate >= 0 && rate <= 10000;
}

/**
 * Compares two ways of collecting consumption tax. Under platform collection
 * the marketplace extracts the tax, remits it and pays the seller net minus
 * commission; the seller never holds the tax. Under direct collection the
 * seller receives the gross price, pays a payment fee and still owes the tax
 * to the authority until it is remitted.
 */
export function settleCollection(input: CollectionInput): Result<CollectionResult> {
  if (!isCents(input.gross)) {
    return fail("gross price must be a non-negative integer in cents");
  }
  if (input.mode !== "platform" && input.mode !== "direct") {
    return fail(`unknown collection mode: ${input.mode}`);
  }
  if (!isValidCostRate(input.commissionBps) || !isValidCostRate(input.feeBps)) {
    return fail("commission and fee rates must be integers between 0 and 10000 bps");
  }
  const priced = extractTax(input.gross, input.rate);
  if (!priced.ok) {
    return priced;
  }
  const commission =
    input.mode === "platform" ? applyRate(priced.value.net, input.commissionBps) : 0;
  const fee = input.mode === "direct" ? applyRate(input.gross, input.feeBps) : 0;
  const received = sub(sub(sub(input.gross, priced.value.tax), commission), fee);
  return ok({
    mode: input.mode,
    gross: input.gross,
    net: priced.value.net,
    tax: priced.value.tax,
    commission,
    fee,
    received,
    taxRemittedBySeller: input.mode === "direct" ? priced.value.tax : 0,
  });
}