《独立开发者的商业指南·合同、应收与风险》8.2 版税结构与保底

// file: src/contract/royalty.ts
// tier: L1
// verify: node --test test/contract/royalty.test.ts

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

export type RoyaltyTier = {
  upToCents: Cents | null;
  rateBps: Bps;
};

export type GuaranteeSettlement = {
  royaltyCents: Cents;
  guaranteeCents: Cents;
  payableCents: Cents;
  shortfallCents: Cents;
  effectiveRateBps: Bps;
};

export type UnitThreshold = {
  royaltyPerUnitCents: Cents;
  minimumUnits: number;
  minimumNetRevenueCents: Cents;
};

function checkBps(value: Bps, label: string): string | null {
  if (!Number.isInteger(value) || value < 0 || value > 10000) {
    return `${label} must be between 0 and 10000 bps`;
  }
  return null;
}

function checkAmount(value: Cents, label: string): string | null {
  if (!Number.isInteger(value) || value < 0) {
    return `${label} must be a non-negative integer amount in cents`;
  }
  return null;
}

export function royaltyOnNet(
  netRevenueCents: Cents,
  rateBps: Bps,
): Result<Cents> {
  const amountError = checkAmount(netRevenueCents, "net revenue");
  if (amountError) {
    return fail(amountError);
  }
  const rateError = checkBps(rateBps, "royalty rate");
  if (rateError) {
    return fail(rateError);
  }
  return ok(applyRate(netRevenueCents, rateBps));
}

export function royaltyPerUnit(
  units: number,
  ratePerUnitCents: Cents,
): Result<Cents> {
  if (!Number.isInteger(units) || units < 0) {
    return fail("units must be a non-negative integer");
  }
  const amountError = checkAmount(ratePerUnitCents, "per-unit royalty");
  if (amountError) {
    return fail(amountError);
  }
  return ok(units * ratePerUnitCents);
}

export function tieredRoyalty(
  netRevenueCents: Cents,
  tiers: RoyaltyTier[],
): Result<Cents> {
  const amountError = checkAmount(netRevenueCents, "net revenue");
  if (amountError) {
    return fail(amountError);
  }
  if (tiers.length === 0) {
    return fail("at least one tier is required");
  }
  let previous = 0;
  let total = 0;
  for (let index = 0; index < tiers.length; index += 1) {
    const tier = tiers[index];
    const rateError = checkBps(tier.rateBps, `tier ${index + 1} rate`);
    if (rateError) {
      return fail(rateError);
    }
    if (index < tiers.length - 1 && tier.upToCents === null) {
      return fail("only the last tier may be open-ended");
    }
    const cap = tier.upToCents === null ? netRevenueCents : tier.upToCents;
    if (!Number.isInteger(cap) || cap < previous) {
      return fail(`tier ${index + 1} cap must not decrease`);
    }
    const band = Math.min(netRevenueCents, cap) - previous;
    if (band > 0) {
      total += applyRate(band, tier.rateBps);
    }
    previous = cap;
    if (netRevenueCents <= cap) {
      break;
    }
  }
  return ok(total);
}

/**
 * A minimum guarantee is a floor, not an advance: the licensee pays the
 * larger of the guarantee and the earned royalty. The effective rate is
 * measured against net revenue, so a guarantee can look like a very high
 * royalty rate when sales are far below the guarantee.
 */
export function settleGuarantee(
  netRevenueCents: Cents,
  rateBps: Bps,
  guaranteeCents: Cents,
): Result<GuaranteeSettlement> {
  const royalty = royaltyOnNet(netRevenueCents, rateBps);
  if (!royalty.ok) {
    return royalty;
  }
  const amountError = checkAmount(guaranteeCents, "guarantee");
  if (amountError) {
    return fail(amountError);
  }
  const payableCents = Math.max(royalty.value, guaranteeCents);
  const shortfallCents = Math.max(0, guaranteeCents - royalty.value);
  return ok({
    royaltyCents: royalty.value,
    guaranteeCents,
    payableCents,
    shortfallCents,
    effectiveRateBps:
      netRevenueCents === 0 ? 0 : divide(payableCents, netRevenueCents),
  });
}

/**
 * Converts a guarantee into the sales volume that would make the earned
 * royalty equal the guarantee. The per-unit rate is rounded to cents first,
 * so the unit threshold is the number the licensee can actually count.
 */
export function minimumUnits(
  guaranteeCents: Cents,
  netPerUnitCents: Cents,
  rateBps: Bps,
): Result<UnitThreshold> {
  const guaranteeError = checkAmount(guaranteeCents, "guarantee");
  if (guaranteeError) {
    return fail(guaranteeError);
  }
  const unitError = checkAmount(netPerUnitCents, "net per unit");
  if (unitError) {
    return fail(unitError);
  }
  const rateError = checkBps(rateBps, "royalty rate");
  if (rateError) {
    return fail(rateError);
  }
  if (rateBps === 0) {
    return fail("royalty rate must be positive to compute a threshold");
  }
  const royaltyPerUnitCents = applyRate(netPerUnitCents, rateBps);
  if (royaltyPerUnitCents === 0) {
    return fail("per-unit royalty rounds to zero");
  }
  return ok({
    royaltyPerUnitCents,
    minimumUnits: Math.ceil(guaranteeCents / royaltyPerUnitCents),
    minimumNetRevenueCents: Math.ceil((guaranteeCents * 10000) / rateBps),
  });
}