《独立开发者的商业指南·收入与财务工程》9.3 跨境预提、转让定价与资金回流

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

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

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

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

export type WithholdingInput = {
  gross: Cents;
  domesticRate: Bps;
  treatyRate: Bps;
  treatyApplied: boolean;
};

export type WithholdingResult = {
  gross: Cents;
  rate: Bps;
  withheld: Cents;
  net: Cents;
  effectiveRateBps: Bps;
};

/**
 * Withholds tax from a cross-border payment. The domestic rate applies when no
 * treaty relief is claimed; the treaty rate applies only when the payer has the
 * supporting documentation. Both rates are inputs, not assumptions.
 */
export function withhold(input: WithholdingInput): Result<WithholdingResult> {
  if (!isCents(input.gross)) {
    return fail("gross payment must be a non-negative integer in cents");
  }
  if (!isValidRate(input.domesticRate) || !isValidRate(input.treatyRate)) {
    return fail("withholding rates must be integers between 0 and 9999 bps");
  }
  const rate = input.treatyApplied ? input.treatyRate : input.domesticRate;
  const withheld = applyRate(input.gross, rate);
  return ok({
    gross: input.gross,
    rate,
    withheld,
    net: sub(input.gross, withheld),
    effectiveRateBps: divide(withheld, input.gross),
  });
}

export type TreatyComparison = {
  withoutTreaty: WithholdingResult;
  withTreaty: WithholdingResult;
  saving: Cents;
  savingBps: Bps;
};

/**
 * Compares the same gross payment with and without treaty relief. A negative
 * saving means the treaty rate is higher than the domestic rate, which is a
 * signal to check the applicable article rather than to force the treaty rate.
 */
export function compareTreaty(
  gross: Cents,
  domesticRate: Bps,
  treatyRate: Bps,
): Result<TreatyComparison> {
  const without = withhold({
    gross,
    domesticRate,
    treatyRate,
    treatyApplied: false,
  });
  if (!without.ok) {
    return without;
  }
  const withTreaty = withhold({
    gross,
    domesticRate,
    treatyRate,
    treatyApplied: true,
  });
  if (!withTreaty.ok) {
    return withTreaty;
  }
  const saving = sub(without.value.withheld, withTreaty.value.withheld);
  return ok({
    withoutTreaty: without.value,
    withTreaty: withTreaty.value,
    saving,
    savingBps: divide(saving, without.value.withheld),
  });
}

/**
 * Works back from a target net receipt to the gross invoice amount. This is
 * what a contractor needs to quote when the client withholds tax at source.
 */
export function grossUp(targetNet: Cents, rate: Bps): Result<Cents> {
  if (!isCents(targetNet)) {
    return fail("target net must be a non-negative integer in cents");
  }
  if (!isValidRate(rate)) {
    return fail("withholding rate must be an integer between 0 and 9999 bps");
  }
  return ok(Math.round((targetNet * 10000) / (10000 - rate)));
}

export type CorridorInput = {
  gross: Cents;
  withholdingRate: Bps;
  intermediaryFeeBps: Bps;
  fxSpreadBps: Bps;
};

export type CorridorResult = {
  gross: Cents;
  withheld: Cents;
  fee: Cents;
  fxCost: Cents;
  received: Cents;
  netRateBps: Bps;
};

/**
 * The full path from a gross invoice to cash in the home account: withholding
 * at source, intermediary fees and the foreign-exchange spread. Each cost is
 * applied to the gross amount so the four deductions stay comparable.
 */
export function crossBorderReceipt(input: CorridorInput): Result<CorridorResult> {
  if (!isCents(input.gross)) {
    return fail("gross payment must be a non-negative integer in cents");
  }
  const rates = [input.withholdingRate, input.intermediaryFeeBps, input.fxSpreadBps];
  if (rates.some((rate) => !Number.isInteger(rate) || rate < 0 || rate > 10000)) {
    return fail("corridor rates must be integers between 0 and 10000 bps");
  }
  const withheld = applyRate(input.gross, input.withholdingRate);
  const fee = applyRate(input.gross, input.intermediaryFeeBps);
  const fxCost = applyRate(input.gross, input.fxSpreadBps);
  const received = sub(sub(sub(input.gross, withheld), fee), fxCost);
  return ok({
    gross: input.gross,
    withheld,
    fee,
    fxCost,
    received,
    netRateBps: divide(received, input.gross),
  });
}