@12-apps/fiscal 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +124 -2
- package/dist/chunk-7QVYU63E.js +7 -0
- package/dist/chunk-7QVYU63E.js.map +1 -0
- package/dist/engine/index.d.ts +361 -0
- package/dist/engine/index.js +591 -0
- package/dist/engine/index.js.map +1 -0
- package/dist/manifest/index.d.ts +83 -0
- package/dist/manifest/index.js +33 -0
- package/dist/manifest/index.js.map +1 -0
- package/package.json +68 -4
- package/src/engine/compare.ts +68 -0
- package/src/engine/compute.ts +40 -0
- package/src/engine/errors.ts +28 -0
- package/src/engine/index.ts +20 -0
- package/src/engine/oracle.ts +81 -0
- package/src/engine/plan.ts +268 -0
- package/src/engine/rounding.ts +81 -0
- package/src/engine/types.ts +270 -0
- package/src/engine/validate.ts +222 -0
- package/src/manifest/index.ts +37 -0
- package/src/manifest/permissions.ts +28 -0
- package/tables/ibs-cbs-2026-11-13.json +156 -0
package/README.md
CHANGED
|
@@ -1,3 +1,125 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @12-apps/fiscal
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Brazilian consumption-tax machinery for any host that sells. The package is
|
|
4
|
+
built module by module; the first is the **IBS/CBS engine**.
|
|
5
|
+
|
|
6
|
+
| subpath | what it is |
|
|
7
|
+
|---|---|
|
|
8
|
+
| `@12-apps/fiscal/engine` | `computeTax(input) → TaxBreakdown`: pure, no I/O, no clock, no defaults. Plus `computeTaxWithOracle` over an injected `OfficialCalculator` port, and `compareBreakdowns`. |
|
|
9
|
+
| `@12-apps/fiscal/tables/<file>.json` | Versioned rate tables — DATA, never code. The engine stamps the table's `version` on every result. |
|
|
10
|
+
| `@12-apps/fiscal/manifest` | The `@12-apps/wiring` manifest. A skeleton today: the four permissions. |
|
|
11
|
+
|
|
12
|
+
## The engine
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
import { computeTax } from "@12-apps/fiscal/engine";
|
|
16
|
+
import tables from "@12-apps/fiscal/tables/ibs-cbs-2026-11-13.json" with { type: "json" };
|
|
17
|
+
|
|
18
|
+
const breakdown = computeTax({
|
|
19
|
+
lines: [
|
|
20
|
+
{
|
|
21
|
+
id: "item-1",
|
|
22
|
+
valueCents: 3990, // what the buyer pays for the line, after its allocated discount
|
|
23
|
+
quantity: 1, // qCom, at most four decimals
|
|
24
|
+
foodAndDrink: true,
|
|
25
|
+
taxClass: { cClassTrib: "200047", cstIbsCbs: "200", regimeEspecifico: "BARES_RESTAURANTES", reductionBp: 0 },
|
|
26
|
+
},
|
|
27
|
+
],
|
|
28
|
+
seller: { regime: "REGIME_REGULAR", regimeEffectiveFrom: "2026-01-01", restaurantRegime: true },
|
|
29
|
+
destinationIbge: "3550308", // the establishment, or for a delivered good the place of delivery
|
|
30
|
+
exclusions: { serviceCharge: null, retainedIntermediation: null },
|
|
31
|
+
tables,
|
|
32
|
+
supplyDate: "2026-11-20", // the local day of the supply, in the seller's clock
|
|
33
|
+
});
|
|
34
|
+
// breakdown.lines[i]: one NF-e item each — valueCents (vProd), taxBaseCents (vBC),
|
|
35
|
+
// cbsRateBp/cbsCents, ibsUfRateBp/ibsUfCents, ibsMunRateBp/ibsMunCents, reductionBp,
|
|
36
|
+
// taxCents, netValueCents (vProdLiq) and netUnitValue (vUnComLiq), the class snapshot
|
|
37
|
+
// breakdown: the sums, netValueCents (vProdLiqTot), gorjetaExcludedCents,
|
|
38
|
+
// intermediationExcludedCents, treatment, informative, provisional, taxInsidePrice,
|
|
39
|
+
// tablesVersion
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Money is integer cents, rates integer basis points, dates `YYYY-MM-DD`. Any
|
|
43
|
+
value the engine cannot read — a missing object, an `undefined` where `null` is
|
|
44
|
+
required, a malformed table — is refused with a `FiscalEngineError` carrying a
|
|
45
|
+
`code`; nothing is defaulted.
|
|
46
|
+
|
|
47
|
+
### What a host passes as a line's value
|
|
48
|
+
|
|
49
|
+
Always **the price the buyer pays for the line** (all units, after the line's
|
|
50
|
+
share of an unconditional discount). The engine decides from the rate table
|
|
51
|
+
whether the tax is inside it:
|
|
52
|
+
|
|
53
|
+
- **A period with `taxInsidePrice: false` (2026).** The value is the base:
|
|
54
|
+
`vBC = value`, each tax is `vBC × rate`, and `netValueCents` /
|
|
55
|
+
`netUnitValue` are `null` — the tax is not part of `vProd` yet.
|
|
56
|
+
- **A period with `taxInsidePrice: true` (2027 on, where the IBS/CBS compose
|
|
57
|
+
`vProd`).** The value is tax-inclusive. The engine takes the taxes out: `vBC`
|
|
58
|
+
is the largest whole-cent base whose rounded taxes, added back, fit inside
|
|
59
|
+
the value; each tax is rounded on that `vBC`; `netValueCents` (`vProdLiq`) is
|
|
60
|
+
the value less the taxes, so `vProdLiq + Σ tax = vProd` to the cent; and
|
|
61
|
+
`netUnitValue` (`vUnComLiq`, reais with ten decimals) times the quantity is
|
|
62
|
+
within the layout's ±0,01 of `vProdLiq` (rule I11c-20). The price never
|
|
63
|
+
changes; the tax is a share of it.
|
|
64
|
+
|
|
65
|
+
### The rules it applies (LC 214/2025)
|
|
66
|
+
|
|
67
|
+
- **Rates by the date of the supply**, from the table's period covering it:
|
|
68
|
+
2026 CBS 0.9% and IBS 0.1% (arts. 343, 346), informative (art. 348 §1);
|
|
69
|
+
2027–2028 IBS 0.05% state + 0.05% municipal (art. 344); later years the
|
|
70
|
+
reference rates the table carries. A period whose figures are not yet law is
|
|
71
|
+
`status: "ESTIMATE"` and stamps its results `provisional: true`.
|
|
72
|
+
- **Destination** (art. 11 I): a state's or municipality's own rate where the
|
|
73
|
+
table lists one (`byUf`, `byMunicipality`), the reference rate elsewhere.
|
|
74
|
+
- **Regimes** (art. 41): regime regular and the Simples híbrido → `FULL`;
|
|
75
|
+
Simples inside the DAS → `INFORMATIVE`, carrying the figures a regime store
|
|
76
|
+
would show and no amount "por fora"; MEI and não contribuinte → `NONE`, zero
|
|
77
|
+
and not informative. In 2026 the test rates are not applied to Simples
|
|
78
|
+
optants (art. 348 III "c"), read from the period's `appliesToSimplesNacional`.
|
|
79
|
+
- **Bares e restaurantes**: in a store with `restaurantRegime`, a line whose
|
|
80
|
+
class is `BARES_RESTAURANTES` (prepared food, non-alcoholic drinks prepared
|
|
81
|
+
on the premises — art. 273; official class 200047) takes the table's 40%
|
|
82
|
+
reduction (art. 275); alcohol and resale carry `regimeEspecifico: null` and
|
|
83
|
+
the full rate (art. 273 §2). Outside the special regime a class's own
|
|
84
|
+
`reductionBp` applies (a cesta-básica zero rate is a 100% reduction).
|
|
85
|
+
- **Exclusions**, restaurant regime only (art. 274 par. único), each
|
|
86
|
+
**segregated as its own item** with no tax (RCBS art. 399 §2; without the
|
|
87
|
+
segregation the base is the full value, §4), under the table's
|
|
88
|
+
`exclusionClasses`:
|
|
89
|
+
- the service charge, when passed in full to the staff AND at most 15% of
|
|
90
|
+
the food and drink (I): one item, class 410019. Above 15%, or kept by the
|
|
91
|
+
store, nothing is excluded — the WHOLE charge is a taxed item under the
|
|
92
|
+
class the host passes. There is no partial exclusion.
|
|
93
|
+
- what a platform retained for delivery and intermediation (II): one item,
|
|
94
|
+
class 410020, passed as `retainedIntermediation` and NOT inside any line's
|
|
95
|
+
value. No goods line's base moves for it. Outside the restaurant regime it
|
|
96
|
+
is refused: there the amount belongs in the lines.
|
|
97
|
+
- **Rounding**: per item, per tax, to whole cents, **half-even** — what the
|
|
98
|
+
official calculator does (R$ 5,00 × 0,9% = 0,045 → 0,04), never a floor; the
|
|
99
|
+
reduction applies to the rate before the product is rounded, and every order
|
|
100
|
+
figure is the sum of its rounded items. The effective rate (`pAliqEfet`) is
|
|
101
|
+
not output: the product is computed exactly from the nominal rate and the
|
|
102
|
+
reduction, which equals `vBC × pAliqEfet` for any whole-percent reduction —
|
|
103
|
+
every reduction in the official table (V0066) is one: 30, 40, 50, 60, 70, 80
|
|
104
|
+
or 100%.
|
|
105
|
+
|
|
106
|
+
### The oracle mode
|
|
107
|
+
|
|
108
|
+
`computeTaxWithOracle(input, calculator)` takes the same input and asks an
|
|
109
|
+
`OfficialCalculator` port for each taxed item's rates, reduction and taxes; the
|
|
110
|
+
regime, the exclusions and the bases stay the engine's (in a tax-inside-price
|
|
111
|
+
period the base is taken out with the table's rates, since the calculator
|
|
112
|
+
takes a base). A host points the port at the official calculator's HTTP API.
|
|
113
|
+
The package's suite replays REAL recorded calculator answers for 2026
|
|
114
|
+
(`src/engine/__tests__/fixtures/calculator/`, version and date in
|
|
115
|
+
`recording.json`) and asserts `compareBreakdowns` finds nothing. The
|
|
116
|
+
calculator has no rates for 2027 and later yet, so those years' goldens are
|
|
117
|
+
the engine's own estimates, marked `provisional`.
|
|
118
|
+
|
|
119
|
+
## The manifest
|
|
120
|
+
|
|
121
|
+
`@12-apps/fiscal/manifest` declares the permissions `fiscal:read`,
|
|
122
|
+
`fiscal:manage`, `fiscal:issue` and `fiscal:cancel`, here and nowhere else. The
|
|
123
|
+
document module adds `db`, `server: ["http", "jobs"]`, `notifications`,
|
|
124
|
+
`web: ["surface"]` and `observability`; until then `.wiring-conformance.json`
|
|
125
|
+
answers each with its reason.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
|
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The engine's vocabulary. Money is integer CENTS, rates are integer BASIS
|
|
3
|
+
* POINTS (1 bp = 0.01%), dates are ISO calendar days (`YYYY-MM-DD`) in the
|
|
4
|
+
* seller's own clock — the fato gerador is the local day of the supply, and the
|
|
5
|
+
* host, which owns the clock, says which day that was.
|
|
6
|
+
*
|
|
7
|
+
* Nothing here has a default. Every field is required, and a value the engine
|
|
8
|
+
* cannot read is refused with a `FiscalEngineError`, never guessed.
|
|
9
|
+
*/
|
|
10
|
+
/** An ISO calendar day, `YYYY-MM-DD`. */
|
|
11
|
+
type IsoDate = string;
|
|
12
|
+
/**
|
|
13
|
+
* The seller's IBS/CBS regime (LC 214/2025 art. 41).
|
|
14
|
+
*
|
|
15
|
+
* - `REGIME_REGULAR` — Lucro Presumido/Real: the full breakdown, "por fora".
|
|
16
|
+
* - `SIMPLES_IBS_CBS_REGULAR` — the Simples híbrido (art. 41 §3): a Simples
|
|
17
|
+
* optant that applies the regime regular to IBS/CBS; full breakdown.
|
|
18
|
+
* - `SIMPLES` — inside the DAS (art. 41 §2): an `INFORMATIVE` breakdown, with
|
|
19
|
+
* the figures a regime store would show and no amount charged "por fora".
|
|
20
|
+
* - `MEI` and `NAO_CONTRIBUINTE` — no IBS/CBS on the document: zero.
|
|
21
|
+
*/
|
|
22
|
+
type TaxRegime = "REGIME_REGULAR" | "SIMPLES_IBS_CBS_REGULAR" | "SIMPLES" | "MEI" | "NAO_CONTRIBUINTE";
|
|
23
|
+
/** The special regimes the engine applies. */
|
|
24
|
+
type RegimeEspecifico = "BARES_RESTAURANTES";
|
|
25
|
+
/** What the treatment of the seller's regime is on the date of the supply. */
|
|
26
|
+
type TaxTreatment = "FULL" | "INFORMATIVE" | "NONE";
|
|
27
|
+
/** The two codes an NF-e item carries for its IBS/CBS classification. */
|
|
28
|
+
interface TaxClassCode {
|
|
29
|
+
readonly cClassTrib: string;
|
|
30
|
+
readonly cstIbsCbs: string;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* A line's tax class, as the host classified the item. `cClassTrib` and
|
|
34
|
+
* `cstIbsCbs` are carried opaque into the snapshot (the classification table
|
|
35
|
+
* is the host's data, Informe Técnico 2025.002).
|
|
36
|
+
*
|
|
37
|
+
* `regimeEspecifico: "BARES_RESTAURANTES"` marks prepared food and
|
|
38
|
+
* non-alcoholic drinks prepared on the premises (art. 273 caput, §1; the
|
|
39
|
+
* official class is 200047). Alcohol, even prepared on the premises, and food
|
|
40
|
+
* or drink bought from third parties and resold as-is are OUT (art. 273 §2)
|
|
41
|
+
* and must carry `null`.
|
|
42
|
+
*/
|
|
43
|
+
interface TaxClass extends TaxClassCode {
|
|
44
|
+
readonly regimeEspecifico: RegimeEspecifico | null;
|
|
45
|
+
/** The class's own rate reduction (a listed-food reduction, say), 0–10000. */
|
|
46
|
+
readonly reductionBp: number;
|
|
47
|
+
}
|
|
48
|
+
/** One priced line of the supply. */
|
|
49
|
+
interface TaxLineInput {
|
|
50
|
+
/** The host's id, echoed on the output line; unique within the input. */
|
|
51
|
+
readonly id: string;
|
|
52
|
+
/**
|
|
53
|
+
* What the line costs the buyer, every unit, AFTER its allocated discount
|
|
54
|
+
* (an unconditional discount is outside the base, art. 12 §2 III). It is
|
|
55
|
+
* the price the shopper sees, so in a period whose table says
|
|
56
|
+
* `taxInsidePrice` the IBS/CBS are INSIDE it and the engine takes them out;
|
|
57
|
+
* otherwise it is the base itself and the tax is computed on top of it.
|
|
58
|
+
*/
|
|
59
|
+
readonly valueCents: number;
|
|
60
|
+
/** Units (`qCom`): positive, at most four decimals (weighed goods). */
|
|
61
|
+
readonly quantity: number;
|
|
62
|
+
/**
|
|
63
|
+
* Whether the line is food or drink — what the gorjeta's 15% ceiling is
|
|
64
|
+
* measured against (art. 274 par. único I). A delivery fee is not.
|
|
65
|
+
*/
|
|
66
|
+
readonly foodAndDrink: boolean;
|
|
67
|
+
readonly taxClass: TaxClass;
|
|
68
|
+
}
|
|
69
|
+
/** Who sells, and under which regime since when. */
|
|
70
|
+
interface SellerProfile {
|
|
71
|
+
readonly regime: TaxRegime;
|
|
72
|
+
/** The first day `regime` applies. A supply before it is refused. */
|
|
73
|
+
readonly regimeEffectiveFrom: IsoDate;
|
|
74
|
+
/** Whether the bares e restaurantes regime (arts. 273–276) applies. */
|
|
75
|
+
readonly restaurantRegime: boolean;
|
|
76
|
+
}
|
|
77
|
+
/** The service charge (taxa de serviço / gorjeta) on the supply. */
|
|
78
|
+
interface ServiceChargeInput {
|
|
79
|
+
/** Echoed as the service-charge line's id; unique within the input. */
|
|
80
|
+
readonly id: string;
|
|
81
|
+
readonly amountCents: number;
|
|
82
|
+
/** Whether the charge is passed in full to the staff. */
|
|
83
|
+
readonly passedToStaff: boolean;
|
|
84
|
+
/** The class the WHOLE charge is taxed at when it is not excluded. */
|
|
85
|
+
readonly taxClass: TaxClass;
|
|
86
|
+
}
|
|
87
|
+
/** What a digital platform retained for delivery and intermediation. */
|
|
88
|
+
interface RetainedIntermediationInput {
|
|
89
|
+
/** Echoed as the excluded line's id; unique within the input. */
|
|
90
|
+
readonly id: string;
|
|
91
|
+
/** Never passed to the restaurant; NOT included in any line's value. */
|
|
92
|
+
readonly amountCents: number;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* The amounts the restaurant regime keeps out of the base (art. 274 par.
|
|
96
|
+
* único), each segregated on the document as its own item (RCBS art. 399 §2:
|
|
97
|
+
* without the segregation the base is the full value, §4).
|
|
98
|
+
*/
|
|
99
|
+
interface TaxExclusions {
|
|
100
|
+
/**
|
|
101
|
+
* Excluded (its own line, the table's gorjeta class) only when the store is
|
|
102
|
+
* in the restaurant regime, the charge is passed in full to the staff AND it
|
|
103
|
+
* is at most 15% of the food and drink. Otherwise the whole charge is a
|
|
104
|
+
* taxed line under its own class — never a partial exclusion.
|
|
105
|
+
*/
|
|
106
|
+
readonly serviceCharge: ServiceChargeInput | null;
|
|
107
|
+
/** Restaurant regime only (art. 274 par. único II); refused elsewhere. */
|
|
108
|
+
readonly retainedIntermediation: RetainedIntermediationInput | null;
|
|
109
|
+
}
|
|
110
|
+
/** The IBS share of one sphere in one period: the reference and the overrides. */
|
|
111
|
+
interface IbsSphereRates {
|
|
112
|
+
/** The reference rate, which applies wherever no own rate is listed. */
|
|
113
|
+
readonly referenceBp: number;
|
|
114
|
+
}
|
|
115
|
+
interface IbsUfRates extends IbsSphereRates {
|
|
116
|
+
/** State rates keyed by the 2-digit IBGE state code. */
|
|
117
|
+
readonly byUf: Readonly<Record<string, number>>;
|
|
118
|
+
}
|
|
119
|
+
interface IbsMunRates extends IbsSphereRates {
|
|
120
|
+
/** Municipal rates keyed by the 7-digit IBGE municipality code. */
|
|
121
|
+
readonly byMunicipality: Readonly<Record<string, number>>;
|
|
122
|
+
}
|
|
123
|
+
/** One stretch of time with one set of rates. */
|
|
124
|
+
interface RatePeriod {
|
|
125
|
+
readonly from: IsoDate;
|
|
126
|
+
/** Inclusive; `null` is open-ended. */
|
|
127
|
+
readonly to: IsoDate | null;
|
|
128
|
+
/** `ESTIMATE` stamps every result computed on it `provisional`. */
|
|
129
|
+
readonly status: "LAW" | "ESTIMATE";
|
|
130
|
+
readonly source: string;
|
|
131
|
+
/** The test year: highlighted, payment waived (art. 348 §1). */
|
|
132
|
+
readonly informative: boolean;
|
|
133
|
+
/** `false` in 2026: the test rates are not applied to Simples optants (art. 348 III "c"). */
|
|
134
|
+
readonly appliesToSimplesNacional: boolean;
|
|
135
|
+
/**
|
|
136
|
+
* Whether the IBS/CBS sit INSIDE the item's value on the document (they
|
|
137
|
+
* compose `vProd` and the price without tax travels in `vProdLiq`) — from
|
|
138
|
+
* 2027 by the NF-e layout. When true, a line's `valueCents` is the
|
|
139
|
+
* tax-inclusive price.
|
|
140
|
+
*/
|
|
141
|
+
readonly taxInsidePrice: boolean;
|
|
142
|
+
readonly cbsBp: number;
|
|
143
|
+
readonly ibsUf: IbsUfRates;
|
|
144
|
+
readonly ibsMun: IbsMunRates;
|
|
145
|
+
}
|
|
146
|
+
/** A versioned rate table: DATA, loaded by the host, stamped on every result. */
|
|
147
|
+
interface RateTables {
|
|
148
|
+
readonly version: string;
|
|
149
|
+
readonly notes?: readonly string[];
|
|
150
|
+
/** The gorjeta's ceiling as a share of food and drink: 1500 (art. 274 par. único I). */
|
|
151
|
+
readonly gorjetaCapBp: number;
|
|
152
|
+
readonly gorjetaCapSource?: string;
|
|
153
|
+
/** The classes the excluded items are segregated under (410019, 410020). */
|
|
154
|
+
readonly exclusionClasses: {
|
|
155
|
+
readonly GORJETA: TaxClassCode;
|
|
156
|
+
readonly INTERMEDIATION: TaxClassCode;
|
|
157
|
+
readonly source?: string;
|
|
158
|
+
};
|
|
159
|
+
readonly specialRegimes: Readonly<Record<RegimeEspecifico, {
|
|
160
|
+
readonly reductionBp: number;
|
|
161
|
+
readonly source: string;
|
|
162
|
+
}>>;
|
|
163
|
+
readonly periods: readonly RatePeriod[];
|
|
164
|
+
}
|
|
165
|
+
/** Everything one computation needs. */
|
|
166
|
+
interface TaxInput {
|
|
167
|
+
readonly lines: readonly TaxLineInput[];
|
|
168
|
+
readonly seller: SellerProfile;
|
|
169
|
+
/**
|
|
170
|
+
* The 7-digit IBGE code of the place the IBS goes to: the establishment,
|
|
171
|
+
* or for a delivered good the place of delivery (art. 11 I).
|
|
172
|
+
*/
|
|
173
|
+
readonly destinationIbge: string;
|
|
174
|
+
readonly exclusions: TaxExclusions;
|
|
175
|
+
readonly tables: RateTables;
|
|
176
|
+
/** The day of the supply; the rate is the rate of that day. */
|
|
177
|
+
readonly supplyDate: IsoDate;
|
|
178
|
+
}
|
|
179
|
+
/** Where an output line came from. */
|
|
180
|
+
type LineSource = "LINE" | "SERVICE_CHARGE" | "GORJETA_EXCLUDED" | "INTERMEDIATION_EXCLUDED";
|
|
181
|
+
/** The per-tax figures of one line. Rates are nominal; `reductionBp` applies to all three. */
|
|
182
|
+
interface LineFigures {
|
|
183
|
+
readonly reductionBp: number;
|
|
184
|
+
readonly cbsRateBp: number;
|
|
185
|
+
readonly cbsCents: number;
|
|
186
|
+
readonly ibsUfRateBp: number;
|
|
187
|
+
readonly ibsUfCents: number;
|
|
188
|
+
readonly ibsMunRateBp: number;
|
|
189
|
+
readonly ibsMunCents: number;
|
|
190
|
+
}
|
|
191
|
+
/** One output line — one NF-e item. */
|
|
192
|
+
interface LineTax extends LineFigures {
|
|
193
|
+
readonly lineId: string;
|
|
194
|
+
readonly source: LineSource;
|
|
195
|
+
readonly quantity: number;
|
|
196
|
+
/** The value as given (`vProd`). */
|
|
197
|
+
readonly valueCents: number;
|
|
198
|
+
/** The base the taxes are computed on (`vBC`): 0 on an excluded line. */
|
|
199
|
+
readonly taxBaseCents: number;
|
|
200
|
+
/** CBS + IBS-UF + IBS-Mun of the line. */
|
|
201
|
+
readonly taxCents: number;
|
|
202
|
+
/**
|
|
203
|
+
* The value without tax (`vProdLiq` = value − tax) in a `taxInsidePrice`
|
|
204
|
+
* period; `null` when the tax is not inside the value.
|
|
205
|
+
*/
|
|
206
|
+
readonly netValueCents: number | null;
|
|
207
|
+
/**
|
|
208
|
+
* The unit value without tax (`vUnComLiq`), in reais with ten decimals as
|
|
209
|
+
* the layout writes it, within ±0,01 of `vProdLiq / qCom` (rule I11c-20);
|
|
210
|
+
* `null` when `netValueCents` is.
|
|
211
|
+
*/
|
|
212
|
+
readonly netUnitValue: string | null;
|
|
213
|
+
/** The class snapshot (the table's exclusion class on an excluded line). */
|
|
214
|
+
readonly taxClass: TaxClass;
|
|
215
|
+
}
|
|
216
|
+
/** The breakdown of one supply. Every order figure is the sum of its rounded lines. */
|
|
217
|
+
interface TaxBreakdown {
|
|
218
|
+
readonly lines: readonly LineTax[];
|
|
219
|
+
readonly valueCents: number;
|
|
220
|
+
readonly taxBaseCents: number;
|
|
221
|
+
readonly cbsCents: number;
|
|
222
|
+
readonly ibsUfCents: number;
|
|
223
|
+
readonly ibsMunCents: number;
|
|
224
|
+
readonly ibsCents: number;
|
|
225
|
+
readonly totalTaxCents: number;
|
|
226
|
+
/** Σ `netValueCents` (`vProdLiqTot`), or `null` when the tax is not inside the values. */
|
|
227
|
+
readonly netValueCents: number | null;
|
|
228
|
+
readonly gorjetaExcludedCents: number;
|
|
229
|
+
readonly intermediationExcludedCents: number;
|
|
230
|
+
readonly regime: TaxRegime;
|
|
231
|
+
readonly treatment: TaxTreatment;
|
|
232
|
+
/**
|
|
233
|
+
* True when the figures are shown but not charged "por fora": the test year
|
|
234
|
+
* (2026), or a Simples store inside the DAS. False for a `NONE` treatment,
|
|
235
|
+
* which shows nothing.
|
|
236
|
+
*/
|
|
237
|
+
readonly informative: boolean;
|
|
238
|
+
/** True when the period's figures are estimates, not law. */
|
|
239
|
+
readonly provisional: boolean;
|
|
240
|
+
/** Whether the line values were taken as tax-inclusive. */
|
|
241
|
+
readonly taxInsidePrice: boolean;
|
|
242
|
+
readonly supplyDate: IsoDate;
|
|
243
|
+
readonly destinationIbge: string;
|
|
244
|
+
readonly tablesVersion: string;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* `computeTax` — the table mode. Pure: no I/O, no clock, no defaults. The
|
|
249
|
+
* same input gives the same breakdown, stamped with the table's version, so a
|
|
250
|
+
* supply settled in March reproduces its own tax in December after the tables
|
|
251
|
+
* moved.
|
|
252
|
+
*/
|
|
253
|
+
|
|
254
|
+
/** The IBS/CBS breakdown of one supply, from the rate tables it is given. */
|
|
255
|
+
declare function computeTax(input: TaxInput): TaxBreakdown;
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* Everything the computation decides BEFORE a per-item figure is produced:
|
|
259
|
+
* the regime's treatment on the date, which items are segregated exclusions,
|
|
260
|
+
* each taxed item's reduction and base (`vBC`). Shared by the table mode and
|
|
261
|
+
* the oracle mode, so the two can only ever disagree on the per-item figures —
|
|
262
|
+
* the thing the oracle is there to check.
|
|
263
|
+
*/
|
|
264
|
+
|
|
265
|
+
/** The three nominal rates at the destination. */
|
|
266
|
+
interface DestinationRates {
|
|
267
|
+
readonly cbsBp: number;
|
|
268
|
+
readonly ibsUfBp: number;
|
|
269
|
+
readonly ibsMunBp: number;
|
|
270
|
+
}
|
|
271
|
+
/** The three nominal rates of the period at the destination (art. 11 I). */
|
|
272
|
+
declare function ratesAt(period: RatePeriod, destinationIbge: string): DestinationRates;
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* The ORACLE mode: the same interface as `computeTax`, with the per-item
|
|
276
|
+
* figures asked of an injected `OfficialCalculator` — the port a host points
|
|
277
|
+
* at the official IBS/CBS calculator (the Receita Federal's Calculadora de
|
|
278
|
+
* Tributos, open source, with an HTTP API and an embeddable component).
|
|
279
|
+
* Everything else — the regime's treatment, the segregated exclusions, each
|
|
280
|
+
* item's base — is the engine's own plan, so running both modes over one
|
|
281
|
+
* fixture set checks exactly the rates, the reductions and the rounding
|
|
282
|
+
* against the official figures.
|
|
283
|
+
*
|
|
284
|
+
* In a tax-inside-price period the base is taken out of the price with the
|
|
285
|
+
* TABLE's rates (the calculator takes a base, not a price), and the
|
|
286
|
+
* calculator's taxes on that base give the net value.
|
|
287
|
+
*/
|
|
288
|
+
|
|
289
|
+
/** One item, as the calculator is asked about it. */
|
|
290
|
+
interface OfficialCalculatorItemRequest {
|
|
291
|
+
readonly supplyDate: string;
|
|
292
|
+
readonly destinationIbge: string;
|
|
293
|
+
readonly cClassTrib: string;
|
|
294
|
+
readonly cstIbsCbs: string;
|
|
295
|
+
/** The base after the engine's exclusions (`vBC`). */
|
|
296
|
+
readonly taxBaseCents: number;
|
|
297
|
+
readonly quantity: number;
|
|
298
|
+
}
|
|
299
|
+
/** The calculator's answer for one item: nominal rates, the reduction, and the rounded taxes. */
|
|
300
|
+
type OfficialCalculatorItemAnswer = LineFigures;
|
|
301
|
+
/** The port. The host's adapter owns the transport, the retries and the unit conversion. */
|
|
302
|
+
interface OfficialCalculator {
|
|
303
|
+
/** Stamped on the result next to the tables' version. */
|
|
304
|
+
readonly version: string;
|
|
305
|
+
calculateItem(request: OfficialCalculatorItemRequest): Promise<OfficialCalculatorItemAnswer>;
|
|
306
|
+
}
|
|
307
|
+
/** `computeTax`, with the per-item figures from the official calculator. */
|
|
308
|
+
declare function computeTaxWithOracle(input: TaxInput, calculator: OfficialCalculator): Promise<TaxBreakdown>;
|
|
309
|
+
|
|
310
|
+
/**
|
|
311
|
+
* Where two breakdowns of the same supply disagree — the table mode against
|
|
312
|
+
* the oracle mode, or a stored snapshot against a recomputation. Versions are
|
|
313
|
+
* not compared: they differ by construction.
|
|
314
|
+
*/
|
|
315
|
+
|
|
316
|
+
interface BreakdownDisagreement {
|
|
317
|
+
/** `null` for an order-level field. */
|
|
318
|
+
readonly lineId: string | null;
|
|
319
|
+
readonly field: string;
|
|
320
|
+
readonly left: unknown;
|
|
321
|
+
readonly right: unknown;
|
|
322
|
+
}
|
|
323
|
+
/** Every per-line field that differs, by line id; then the order fields that the lines do not already explain. */
|
|
324
|
+
declare function compareBreakdowns(left: TaxBreakdown, right: TaxBreakdown): BreakdownDisagreement[];
|
|
325
|
+
|
|
326
|
+
/**
|
|
327
|
+
* Every refusal the engine makes. A refusal is a THROW, on purpose: the
|
|
328
|
+
* engine has no fallback for an input it cannot read, and a figure computed
|
|
329
|
+
* from a guess would be printed on a fiscal document as a confession of the
|
|
330
|
+
* tax due (LC 214/2025 art. 60 §1).
|
|
331
|
+
*/
|
|
332
|
+
type FiscalEngineErrorCode =
|
|
333
|
+
/** A field is missing, out of range or of the wrong shape. */
|
|
334
|
+
"INVALID_INPUT"
|
|
335
|
+
/** The rate table is malformed: a bad rate, a bad date, overlapping periods. */
|
|
336
|
+
| "INVALID_TABLES"
|
|
337
|
+
/** No period of the table covers the date of the supply. */
|
|
338
|
+
| "NO_RATE_PERIOD"
|
|
339
|
+
/** The supply precedes the seller's `regimeEffectiveFrom`. */
|
|
340
|
+
| "REGIME_NOT_IN_EFFECT"
|
|
341
|
+
/** The official calculator answered something that is not integer cents and basis points. */
|
|
342
|
+
| "INVALID_ORACLE_ANSWER";
|
|
343
|
+
declare class FiscalEngineError extends Error {
|
|
344
|
+
readonly code: FiscalEngineErrorCode;
|
|
345
|
+
constructor(code: FiscalEngineErrorCode, message: string);
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/** round_half_even(baseCents × rateBp/10⁴ × (1 − reductionBp/10⁴)), in cents. */
|
|
349
|
+
declare function roundTaxCents(baseCents: number, rateBp: number, reductionBp: number): number;
|
|
350
|
+
|
|
351
|
+
/**
|
|
352
|
+
* Input and table validation. Every check names the field it refused, and
|
|
353
|
+
* every shape is checked before it is read, so a malformed input — a missing
|
|
354
|
+
* object, an `undefined` where `null` is required, a `null` line — is a
|
|
355
|
+
* `FiscalEngineError`, never a TypeError and never a NaN on a document.
|
|
356
|
+
*/
|
|
357
|
+
|
|
358
|
+
/** Refuse a table the engine cannot trust: bad rates, bad dates, overlapping periods. */
|
|
359
|
+
declare function assertRateTables(tables: unknown): asserts tables is RateTables;
|
|
360
|
+
|
|
361
|
+
export { type BreakdownDisagreement, FiscalEngineError, type FiscalEngineErrorCode, type IbsMunRates, type IbsSphereRates, type IbsUfRates, type IsoDate, type LineFigures, type LineSource, type LineTax, type OfficialCalculator, type OfficialCalculatorItemAnswer, type OfficialCalculatorItemRequest, type RatePeriod, type RateTables, type RegimeEspecifico, type RetainedIntermediationInput, type SellerProfile, type ServiceChargeInput, type TaxBreakdown, type TaxClass, type TaxClassCode, type TaxExclusions, type TaxInput, type TaxLineInput, type TaxRegime, type TaxTreatment, assertRateTables, compareBreakdowns, computeTax, computeTaxWithOracle, ratesAt, roundTaxCents };
|