@12-apps/fiscal 0.0.0-stage → 1.1.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.
Files changed (155) hide show
  1. package/README.md +269 -2
  2. package/dist/chunk-27B4HNO6.js +574 -0
  3. package/dist/chunk-27B4HNO6.js.map +1 -0
  4. package/dist/chunk-3SDXLSG4.js +24 -0
  5. package/dist/chunk-3SDXLSG4.js.map +1 -0
  6. package/dist/chunk-7QVYU63E.js +7 -0
  7. package/dist/chunk-7QVYU63E.js.map +1 -0
  8. package/dist/chunk-ALABGVPO.js +247 -0
  9. package/dist/chunk-ALABGVPO.js.map +1 -0
  10. package/dist/chunk-FOFIN5M7.js +14 -0
  11. package/dist/chunk-FOFIN5M7.js.map +1 -0
  12. package/dist/chunk-HQ2NXSTX.js +85 -0
  13. package/dist/chunk-HQ2NXSTX.js.map +1 -0
  14. package/dist/chunk-PNTKG3DZ.js +47 -0
  15. package/dist/chunk-PNTKG3DZ.js.map +1 -0
  16. package/dist/chunk-RRFKYVLZ.js +192 -0
  17. package/dist/chunk-RRFKYVLZ.js.map +1 -0
  18. package/dist/chunk-V5ZQAAJT.js +210 -0
  19. package/dist/chunk-V5ZQAAJT.js.map +1 -0
  20. package/dist/chunk-X6MRDUYH.js +21 -0
  21. package/dist/chunk-X6MRDUYH.js.map +1 -0
  22. package/dist/chunk-XQGW5HUG.js +30 -0
  23. package/dist/chunk-XQGW5HUG.js.map +1 -0
  24. package/dist/context-ChnWR4Kb.d.ts +455 -0
  25. package/dist/danfe/en-US.d.ts +12 -0
  26. package/dist/danfe/en-US.js +51 -0
  27. package/dist/danfe/en-US.js.map +1 -0
  28. package/dist/danfe/index.d.ts +50 -0
  29. package/dist/danfe/index.js +18 -0
  30. package/dist/danfe/index.js.map +1 -0
  31. package/dist/danfe/pt-BR.d.ts +11 -0
  32. package/dist/danfe/pt-BR.js +51 -0
  33. package/dist/danfe/pt-BR.js.map +1 -0
  34. package/dist/documents/index.d.ts +169 -0
  35. package/dist/documents/index.js +1228 -0
  36. package/dist/documents/index.js.map +1 -0
  37. package/dist/engine/index.d.ts +118 -0
  38. package/dist/engine/index.js +591 -0
  39. package/dist/engine/index.js.map +1 -0
  40. package/dist/http.d.ts +73 -0
  41. package/dist/http.js +16 -0
  42. package/dist/http.js.map +1 -0
  43. package/dist/issuer/index.d.ts +43 -0
  44. package/dist/issuer/index.js +131 -0
  45. package/dist/issuer/index.js.map +1 -0
  46. package/dist/jobs.d.ts +74 -0
  47. package/dist/jobs.js +22 -0
  48. package/dist/jobs.js.map +1 -0
  49. package/dist/labels-BNvflT0h.d.ts +44 -0
  50. package/dist/manifest/index.d.ts +97 -0
  51. package/dist/manifest/index.js +27 -0
  52. package/dist/manifest/index.js.map +1 -0
  53. package/dist/manifest/server.d.ts +57 -0
  54. package/dist/manifest/server.js +25 -0
  55. package/dist/manifest/server.js.map +1 -0
  56. package/dist/notifications.d.ts +93 -0
  57. package/dist/notifications.js +41 -0
  58. package/dist/notifications.js.map +1 -0
  59. package/dist/port-DpRFK56U.d.ts +238 -0
  60. package/dist/sale/index.d.ts +243 -0
  61. package/dist/sale/index.js +1 -0
  62. package/dist/sale/index.js.map +1 -0
  63. package/dist/service-KTjH7AxW.d.ts +139 -0
  64. package/dist/sidecar/index.d.ts +216 -0
  65. package/dist/sidecar/index.js +8 -0
  66. package/dist/sidecar/index.js.map +1 -0
  67. package/dist/types-B1b8LIWX.d.ts +247 -0
  68. package/package.json +126 -4
  69. package/prisma/fiscal.prisma +158 -0
  70. package/prisma/migrations/20261113220000_fiscal_documents/migration.sql +201 -0
  71. package/sidecar/.dockerignore +5 -0
  72. package/sidecar/Dockerfile +68 -0
  73. package/sidecar/README.md +149 -0
  74. package/sidecar/composer.json +30 -0
  75. package/sidecar/composer.lock +2224 -0
  76. package/sidecar/docker/apache.conf +14 -0
  77. package/sidecar/docker/icp-brasil.pem +8031 -0
  78. package/sidecar/docker/mpm.conf +17 -0
  79. package/sidecar/docker/openssl.cnf +16 -0
  80. package/sidecar/docker/php.ini +19 -0
  81. package/sidecar/public/index.php +15 -0
  82. package/sidecar/schema/sale-for-document.schema.json +401 -0
  83. package/sidecar/src/ErrorClass.php +31 -0
  84. package/sidecar/src/Http/Request.php +48 -0
  85. package/sidecar/src/Http/Response.php +32 -0
  86. package/sidecar/src/Http/Router.php +59 -0
  87. package/sidecar/src/Kernel.php +99 -0
  88. package/sidecar/src/Module.php +31 -0
  89. package/sidecar/src/Nfe/Classifier.php +89 -0
  90. package/sidecar/src/Nfe/Credentials.php +52 -0
  91. package/sidecar/src/Nfe/DocumentMapper.php +383 -0
  92. package/sidecar/src/Nfe/DocumentSchema.php +39 -0
  93. package/sidecar/src/Nfe/Input.php +125 -0
  94. package/sidecar/src/Nfe/Model.php +17 -0
  95. package/sidecar/src/Nfe/NfeModule.php +62 -0
  96. package/sidecar/src/Nfe/NfeService.php +504 -0
  97. package/sidecar/src/Nfe/Sefaz.php +49 -0
  98. package/sidecar/src/Nfe/SefazReply.php +81 -0
  99. package/sidecar/src/Nfe/Transport/CurlTransport.php +198 -0
  100. package/sidecar/src/Nfe/Transport/SoapAdapter.php +57 -0
  101. package/sidecar/src/Nfe/Transport/Transport.php +20 -0
  102. package/sidecar/src/Nfe/Transport/TransportFailure.php +42 -0
  103. package/sidecar/src/RequestLog.php +54 -0
  104. package/sidecar/src/ServiceError.php +69 -0
  105. package/src/danfe/en-US.ts +53 -0
  106. package/src/danfe/index.ts +11 -0
  107. package/src/danfe/labels.ts +49 -0
  108. package/src/danfe/pt-BR.ts +52 -0
  109. package/src/danfe/render.ts +265 -0
  110. package/src/danfe/xml.ts +45 -0
  111. package/src/documents/context.ts +260 -0
  112. package/src/documents/errors.ts +41 -0
  113. package/src/documents/helpers.ts +128 -0
  114. package/src/documents/index.ts +39 -0
  115. package/src/documents/lines.ts +63 -0
  116. package/src/documents/machine-steps.ts +260 -0
  117. package/src/documents/machine.ts +128 -0
  118. package/src/documents/memory.ts +138 -0
  119. package/src/documents/nfe-proc.ts +51 -0
  120. package/src/documents/ports.ts +130 -0
  121. package/src/documents/profile-input.ts +168 -0
  122. package/src/documents/profile.ts +98 -0
  123. package/src/documents/service-profile.ts +104 -0
  124. package/src/documents/service.ts +296 -0
  125. package/src/documents/settle.ts +121 -0
  126. package/src/documents/signing.ts +61 -0
  127. package/src/documents/sql-rows.ts +180 -0
  128. package/src/documents/sql-store.ts +242 -0
  129. package/src/documents/sql.ts +18 -0
  130. package/src/documents/steps.ts +173 -0
  131. package/src/documents/tests/integration/pglite.ts +73 -0
  132. package/src/documents/types.ts +193 -0
  133. package/src/engine/compare.ts +68 -0
  134. package/src/engine/compute.ts +40 -0
  135. package/src/engine/errors.ts +28 -0
  136. package/src/engine/index.ts +20 -0
  137. package/src/engine/oracle.ts +81 -0
  138. package/src/engine/plan.ts +268 -0
  139. package/src/engine/rounding.ts +81 -0
  140. package/src/engine/types.ts +270 -0
  141. package/src/engine/validate.ts +222 -0
  142. package/src/http.ts +264 -0
  143. package/src/issuer/index.ts +9 -0
  144. package/src/issuer/port.ts +109 -0
  145. package/src/issuer/sidecar.ts +171 -0
  146. package/src/jobs.ts +115 -0
  147. package/src/manifest/index.ts +46 -0
  148. package/src/manifest/permissions.ts +28 -0
  149. package/src/manifest/server.ts +20 -0
  150. package/src/notifications.ts +120 -0
  151. package/src/sale/index.ts +8 -0
  152. package/src/sale/types.ts +292 -0
  153. package/src/sidecar/index.ts +9 -0
  154. package/src/sidecar/types.ts +243 -0
  155. package/tables/ibs-cbs-2026-11-13.json +156 -0
@@ -0,0 +1,243 @@
1
+ /**
2
+ * The neutral document shape: one sale, host-agnostic, as the fiscal service
3
+ * (`sidecar/`) accepts it and as the issuer port maps a host's sale into it.
4
+ *
5
+ * Money is integer CENTS, rates integer BASIS POINTS (1 bp = 0.01%) — the
6
+ * engine's conventions (`@12-apps/fiscal/engine`) — and quantities carry at
7
+ * most four decimals. Every field is required; an absent value is `null`,
8
+ * never a missing key, so a host cannot forget one silently.
9
+ *
10
+ * The JSON schema the service validates against is
11
+ * `@12-apps/fiscal/sidecar/schema/sale-for-document.schema.json`; a test keeps
12
+ * it and these types in step. Whether the sale becomes an NF-e (model 55) or
13
+ * an NFC-e (model 65) is the request path's choice, never this document's.
14
+ */
15
+ /** The 27 federative units. */
16
+ type Uf = "AC" | "AL" | "AM" | "AP" | "BA" | "CE" | "DF" | "ES" | "GO" | "MA" | "MG" | "MS" | "MT" | "PA" | "PB" | "PE" | "PI" | "PR" | "RJ" | "RN" | "RO" | "RR" | "RS" | "SC" | "SE" | "SP" | "TO";
17
+ /** A postal address. `postalCode` is required on the issuer's. */
18
+ interface Address {
19
+ readonly street: string;
20
+ readonly number: string;
21
+ readonly complement: string | null;
22
+ readonly district: string;
23
+ /** The 7-digit IBGE municipality code. */
24
+ readonly municipalityIbge: string;
25
+ readonly municipalityName: string;
26
+ readonly uf: Uf;
27
+ /** CEP, 8 digits. */
28
+ readonly postalCode: string | null;
29
+ readonly phone: string | null;
30
+ }
31
+ /** The issuer's tax regime on the document (`CRT` 1, 2, 3, 4). */
32
+ type IssuerTaxRegime = "SIMPLES" | "SIMPLES_EXCESS" | "NORMAL" | "MEI";
33
+ interface DocumentIssuer {
34
+ /** 14 characters; the 2026 alphanumeric CNPJ is accepted. */
35
+ readonly cnpj: string;
36
+ /** IE digits, or `ISENTO`. */
37
+ readonly stateRegistration: string;
38
+ readonly legalName: string;
39
+ readonly tradeName: string | null;
40
+ readonly taxRegime: IssuerTaxRegime;
41
+ readonly address: Address & {
42
+ readonly postalCode: string;
43
+ };
44
+ }
45
+ type BuyerDocument = {
46
+ readonly kind: "CPF";
47
+ readonly number: string;
48
+ } | {
49
+ readonly kind: "CNPJ";
50
+ readonly number: string;
51
+ } | {
52
+ readonly kind: "FOREIGN";
53
+ readonly number: string;
54
+ };
55
+ /** `indIEDest` 1, 2, 9. */
56
+ type StateRegistrationStatus = "CONTRIBUTOR" | "EXEMPT" | "NON_CONTRIBUTOR";
57
+ interface DocumentBuyer {
58
+ readonly document: BuyerDocument;
59
+ readonly name: string | null;
60
+ readonly stateRegistrationStatus: StateRegistrationStatus;
61
+ readonly stateRegistration: string | null;
62
+ readonly email: string | null;
63
+ readonly address: Address | null;
64
+ }
65
+ /** The goods' origin (`orig`), 0–8. */
66
+ type GoodsOrigin = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
67
+ /** ICMS of a Simples Nacional issuer, without a credit. */
68
+ interface IcmsSimples {
69
+ readonly regime: "SIMPLES";
70
+ readonly origin: GoodsOrigin;
71
+ readonly csosn: "102" | "103" | "300" | "400" | "500";
72
+ }
73
+ /** ICMS of a Simples Nacional issuer that grants the buyer a credit (CSOSN 101). */
74
+ interface IcmsSimplesWithCredit {
75
+ readonly regime: "SIMPLES";
76
+ readonly origin: GoodsOrigin;
77
+ readonly csosn: "101";
78
+ readonly creditRateBp: number;
79
+ readonly creditCents: number;
80
+ }
81
+ /** ICMS fully taxed (CST 00). */
82
+ interface IcmsTaxed {
83
+ readonly regime: "NORMAL";
84
+ readonly origin: GoodsOrigin;
85
+ readonly cst: "00";
86
+ readonly baseCents: number;
87
+ readonly rateBp: number;
88
+ readonly amountCents: number;
89
+ }
90
+ /** ICMS exempt, not taxed, suspended (40, 41, 50) or collected before by substitution (60). */
91
+ interface IcmsUntaxed {
92
+ readonly regime: "NORMAL";
93
+ readonly origin: GoodsOrigin;
94
+ readonly cst: "40" | "41" | "50" | "60";
95
+ }
96
+ type LineIcms = IcmsSimples | IcmsSimplesWithCredit | IcmsTaxed | IcmsUntaxed;
97
+ /** The PIS and COFINS situation codes the layout accepts on an outgoing document. */
98
+ type ContributionCst = "01" | "02" | "04" | "05" | "06" | "07" | "08" | "09" | "49" | "50" | "51" | "52" | "53" | "54" | "55" | "56" | "60" | "61" | "62" | "63" | "64" | "65" | "66" | "67" | "70" | "71" | "72" | "73" | "74" | "75" | "98" | "99";
99
+ /**
100
+ * PIS or COFINS. CST 01/02 write the base, the rate and the amount; 04–09
101
+ * write none (send zeros); 49–99 write all three.
102
+ */
103
+ interface LineContribution {
104
+ readonly cst: ContributionCst;
105
+ readonly baseCents: number;
106
+ readonly rateBp: number;
107
+ readonly amountCents: number;
108
+ }
109
+ /**
110
+ * The IBS/CBS figures of one line — what the engine's `LineTax` carries:
111
+ * `vBC` and, per tax, the NOMINAL rate and the amount. `reductionBp` applies
112
+ * to all three rates (`pRedAliq`; the effective rate is written beside it).
113
+ */
114
+ interface IbsCbsFigures {
115
+ readonly baseCents: number;
116
+ readonly reductionBp: number;
117
+ readonly cbsRateBp: number;
118
+ readonly cbsCents: number;
119
+ readonly ibsUfRateBp: number;
120
+ readonly ibsUfCents: number;
121
+ readonly ibsMunRateBp: number;
122
+ readonly ibsMunCents: number;
123
+ }
124
+ /** The IBS/CBS group of a line. `figures: null` writes the CST and class only (immunity, say). */
125
+ interface LineIbsCbs {
126
+ /** `CST` of the IBS/CBS, 3 digits. */
127
+ readonly cst: string;
128
+ /** `cClassTrib`, 6 digits. */
129
+ readonly classCode: string;
130
+ readonly figures: IbsCbsFigures | null;
131
+ }
132
+ /** One item of the document. */
133
+ interface SaleLine {
134
+ /** The host's id; quoted back in a mapping error. */
135
+ readonly id: string;
136
+ /** `cProd`. */
137
+ readonly code: string;
138
+ /** GTIN/EAN, or `null` for "SEM GTIN". */
139
+ readonly gtin: string | null;
140
+ readonly description: string;
141
+ readonly ncm: string;
142
+ readonly cest: string | null;
143
+ readonly cfop: string;
144
+ /** `uCom` and `uTrib`. */
145
+ readonly unit: string;
146
+ /** `qCom` and `qTrib`: positive, at most four decimals. */
147
+ readonly quantity: number;
148
+ /** `vProd`: every unit, BEFORE the line's discount. The unit value is derived. */
149
+ readonly valueCents: number;
150
+ /** `vDesc`. */
151
+ readonly discountCents: number;
152
+ /** `vTotTrib` (the approximate tax of the transparency law), or `null`. */
153
+ readonly approximateTaxCents: number | null;
154
+ /** `infAdProd`. */
155
+ readonly additionalInfo: string | null;
156
+ readonly icms: LineIcms;
157
+ readonly pis: LineContribution;
158
+ readonly cofins: LineContribution;
159
+ /** `null` writes no IBS/CBS group — a regime the engine answered `NONE` for. */
160
+ readonly ibsCbs: LineIbsCbs | null;
161
+ }
162
+ /** `tPag`. */
163
+ type PaymentMethod = "CASH" | "CHECK" | "CREDIT_CARD" | "DEBIT_CARD" | "STORE_CREDIT" | "FOOD_VOUCHER" | "MEAL_VOUCHER" | "GIFT_VOUCHER" | "FUEL_VOUCHER" | "BANK_SLIP" | "BANK_DEPOSIT" | "PIX_DYNAMIC" | "TRANSFER" | "LOYALTY" | "PIX_STATIC" | "NO_PAYMENT" | "OTHER";
164
+ interface CardDetails {
165
+ /** `tpIntegra`: whether the payment went through an integrated terminal. */
166
+ readonly integrated: boolean;
167
+ readonly acquirerCnpj: string | null;
168
+ /** `tBand`, 2 digits. */
169
+ readonly brand: string | null;
170
+ /** `cAut`. */
171
+ readonly authorizationCode: string | null;
172
+ }
173
+ interface SalePayment {
174
+ readonly method: PaymentMethod;
175
+ readonly amountCents: number;
176
+ /** Required by the layout for a card and for a Pix; `null` otherwise. */
177
+ readonly card: CardDetails | null;
178
+ /** `xPag`: required when `method` is `OTHER`. */
179
+ readonly description: string | null;
180
+ }
181
+ /** `finNFe` 1–4. */
182
+ type DocumentPurpose = "NORMAL" | "COMPLEMENTARY" | "ADJUSTMENT" | "RETURN";
183
+ /** `idDest` 1–3. */
184
+ type OperationDestination = "INTERNAL" | "INTERSTATE" | "FOREIGN";
185
+ /** `indPres` 1, 2, 3, 4, 5, 9. */
186
+ type BuyerPresence = "IN_PERSON" | "INTERNET" | "TELEPHONE" | "HOME_DELIVERY" | "IN_PERSON_OFF_PREMISES" | "OTHER";
187
+ /** `modFrete` 0, 1, 2, 3, 4, 9. */
188
+ type FreightMode = "BY_ISSUER" | "BY_RECIPIENT" | "BY_THIRD_PARTY" | "OWN_BY_ISSUER" | "OWN_BY_RECIPIENT" | "NONE";
189
+ /** `infIntermed`: the third-party platform the sale went through. */
190
+ interface SaleIntermediary {
191
+ readonly cnpj: string;
192
+ /** `idCadIntTran`: the seller's id on that platform. */
193
+ readonly userId: string;
194
+ }
195
+ /** `infRespTec`: the software house responsible for the issuing system. */
196
+ interface TechnicalResponsible {
197
+ readonly cnpj: string;
198
+ readonly contactName: string;
199
+ readonly email: string;
200
+ readonly phone: string;
201
+ }
202
+ /** One sale, ready to become an NF-e or an NFC-e. */
203
+ interface SaleForDocument {
204
+ readonly version: 1;
205
+ /** `serie`, 0–999. */
206
+ readonly series: number;
207
+ /** `nNF`, 1–999999999. The package's counter owns it. */
208
+ readonly number: number;
209
+ /**
210
+ * `cNF`: the 8-digit code inside the access key. The caller draws it ONCE and
211
+ * keeps it with the document, so a retried call yields the same key.
212
+ */
213
+ readonly keyCode: string;
214
+ /** `dhEmi`: ISO 8601 with the UTC offset, `2026-11-20T12:30:00-03:00`. */
215
+ readonly issuedAt: string;
216
+ /** `natOp`. */
217
+ readonly operationNature: string;
218
+ readonly purpose: DocumentPurpose;
219
+ readonly destination: OperationDestination;
220
+ readonly presence: BuyerPresence;
221
+ /** `indFinal`. */
222
+ readonly finalConsumer: boolean;
223
+ readonly intermediary: SaleIntermediary | null;
224
+ readonly issuer: DocumentIssuer;
225
+ /** `null` on an NFC-e with no identified buyer. */
226
+ readonly buyer: DocumentBuyer | null;
227
+ /** 1–990 items. */
228
+ readonly lines: readonly SaleLine[];
229
+ readonly freight: FreightMode;
230
+ /** 1–100 payments. */
231
+ readonly payments: readonly SalePayment[];
232
+ /** `vTroco`. */
233
+ readonly changeCents: number;
234
+ readonly additionalInfo: {
235
+ /** `infCpl`. */
236
+ readonly forTaxpayer: string | null;
237
+ /** `infAdFisco`. */
238
+ readonly forTaxAuthority: string | null;
239
+ };
240
+ readonly technicalResponsible: TechnicalResponsible | null;
241
+ }
242
+
243
+ export type { Address, BuyerDocument, BuyerPresence, CardDetails, ContributionCst, DocumentBuyer, DocumentIssuer, DocumentPurpose, FreightMode, GoodsOrigin, IbsCbsFigures, IcmsSimples, IcmsSimplesWithCredit, IcmsTaxed, IcmsUntaxed, IssuerTaxRegime, LineContribution, LineIbsCbs, LineIcms, OperationDestination, PaymentMethod, SaleForDocument, SaleIntermediary, SaleLine, SalePayment, StateRegistrationStatus, TechnicalResponsible, Uf };
@@ -0,0 +1 @@
1
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
@@ -0,0 +1,139 @@
1
+ import { F as FiscalDocumentModel, h as FiscalDocument, d as IssuerFailure, i as FiscalDocumentEvent } from './port-DpRFK56U.js';
2
+ import { T as TaxRegime } from './types-B1b8LIWX.js';
3
+ import { IssuerTaxRegime, Address } from './sale/index.js';
4
+ import { SefazEnvironment, LookedUpDocument } from './sidecar/index.js';
5
+ import { f as DocumentPolicy, S as SigningIdentityKind, g as FiscalDocumentsConfig, C as Cipher, E as EmitterProfile, I as IssuingPoint } from './context-ChnWR4Kb.js';
6
+
7
+ /**
8
+ * Reading the emitter profile and the certificate upload off a request body:
9
+ * every field required (an absent value is `null`), unknown keys refused, and
10
+ * every refusal a {@link FiscalDocumentError} `INVALID_INPUT` naming the
11
+ * field — never its value, since the certificate upload carries secrets.
12
+ */
13
+
14
+ /** The profile fields a host writes; the secrets arrive through their own calls. */
15
+ interface EmitterProfileInput {
16
+ readonly cnpj: string;
17
+ readonly stateRegistration: string;
18
+ readonly municipalRegistration: string | null;
19
+ readonly cnae: string | null;
20
+ readonly legalName: string;
21
+ readonly tradeName: string | null;
22
+ readonly taxRegime: IssuerTaxRegime;
23
+ readonly regime: TaxRegime;
24
+ readonly regimeEffectiveFrom: string;
25
+ readonly restaurantRegime: boolean;
26
+ readonly address: Address & {
27
+ readonly postalCode: string;
28
+ };
29
+ readonly environment: SefazEnvironment;
30
+ readonly documentPolicy: DocumentPolicy;
31
+ readonly signingIdentity: SigningIdentityKind;
32
+ readonly cscId: string | null;
33
+ /** The CSC token in clear, encrypted on arrival; `null` keeps the stored one. */
34
+ readonly cscToken: string | null;
35
+ readonly consentRecordedAt: string | null;
36
+ }
37
+ interface CertificateUpload {
38
+ readonly pfxBase64: string;
39
+ readonly password: string;
40
+ }
41
+ interface IssuingPointInput {
42
+ readonly id: string;
43
+ readonly model: FiscalDocumentModel;
44
+ readonly onlineSeries: number;
45
+ readonly contingencySeries: number | null;
46
+ readonly firstOnlineNumber: number;
47
+ readonly firstContingencyNumber: number;
48
+ }
49
+ declare function parseProfileInput(value: unknown): EmitterProfileInput;
50
+ declare function parseCertificateUpload(value: unknown): CertificateUpload;
51
+ declare function parseIssuingPointInput(value: unknown): IssuingPointInput;
52
+
53
+ /**
54
+ * The profile half of the document service: the emitter profile, the
55
+ * certificate upload and the issuing points. A secret is encrypted through the
56
+ * host's cipher the moment it arrives, and only its ciphertext is stored.
57
+ */
58
+
59
+ /** What the host learns from an A1 without this package parsing PKCS#12. */
60
+ interface CertificateFacts {
61
+ /** `notAfter`, ISO 8601. */
62
+ readonly expiresAt: string;
63
+ }
64
+ interface FiscalDocumentsServiceConfig extends FiscalDocumentsConfig {
65
+ /** Encrypts the certificate, its password and the CSC on arrival. */
66
+ readonly cipher: Cipher;
67
+ /**
68
+ * Reads the expiry out of an uploaded A1; throws when the file does not
69
+ * open with the password. The host's: Node's crypto cannot open every A1
70
+ * (most issued before 2023 use RC2-40), and this package adds no parser.
71
+ */
72
+ readonly readCertificate: (certificate: CertificateUpload) => Promise<CertificateFacts>;
73
+ }
74
+
75
+ interface SweepReport {
76
+ readonly advanced: Array<{
77
+ readonly documentId: string;
78
+ readonly status: FiscalDocument["status"];
79
+ }>;
80
+ readonly failures: Array<{
81
+ readonly documentId: string;
82
+ readonly message: string;
83
+ }>;
84
+ }
85
+ interface IssueInput {
86
+ readonly ownerId: string;
87
+ readonly subjectId: string;
88
+ readonly issuingPointId: string;
89
+ readonly model: FiscalDocumentModel;
90
+ }
91
+ /** How long an NFC-e may wait in contingency before it must be transmitted (24 h); the warning goes out at 20 h. */
92
+ declare const CONTINGENCY_WARNING_AFTER_MS: number;
93
+ declare function createFiscalDocuments(config: FiscalDocumentsServiceConfig): {
94
+ getProfile: (ownerId: string) => Promise<EmitterProfile | null>;
95
+ saveProfile: (ownerId: string, input: EmitterProfileInput) => Promise<EmitterProfile>;
96
+ uploadCertificate: (ownerId: string, certificate: CertificateUpload) => Promise<EmitterProfile>;
97
+ listIssuingPoints: (ownerId: string) => Promise<IssuingPoint[]>;
98
+ createIssuingPoint: (ownerId: string, input: IssuingPointInput) => Promise<IssuingPoint>;
99
+ /** Issue the subject's document, or answer the live one it has. A rejection is final; anything SEFAZ may still answer is the sweep's. */
100
+ issue: (input: IssueInput) => Promise<FiscalDocument>;
101
+ issueOffline: (input: Omit<IssueInput, "model">) => Promise<FiscalDocument>;
102
+ resendContingency: (input: {
103
+ ownerId: string;
104
+ documentId: string;
105
+ }) => Promise<FiscalDocument>;
106
+ /** Cancel an authorised document. A refusal (late, say) answers the issuer's failure and changes nothing. */
107
+ cancel: (input: {
108
+ ownerId: string;
109
+ documentId: string;
110
+ reason: string;
111
+ }) => Promise<{
112
+ document: FiscalDocument;
113
+ failure: IssuerFailure | null;
114
+ }>;
115
+ /** Ask SEFAZ what it knows of the key; a state the answer moves is recorded. */
116
+ lookup: (input: {
117
+ ownerId: string;
118
+ documentId: string;
119
+ }) => Promise<{
120
+ document: FiscalDocument;
121
+ answer: LookedUpDocument | null;
122
+ failure: IssuerFailure | null;
123
+ }>;
124
+ /** A person takes a document back from `attention`; the sweep tries it again. */
125
+ release(input: {
126
+ ownerId: string;
127
+ documentId: string;
128
+ }): Promise<FiscalDocument>;
129
+ getDocument: (ownerId: string, documentId: string) => Promise<FiscalDocument>;
130
+ listBySubject: (ownerId: string, subjectId: string, model: FiscalDocumentModel) => Promise<FiscalDocument[]>;
131
+ listEvents(ownerId: string, documentId: string): Promise<FiscalDocumentEvent[]>;
132
+ /** One pass of the retry sweep: PENDING/SUBMITTED documents and owed numbers whose next attempt has come. */
133
+ sweep: (limit: number) => Promise<SweepReport>;
134
+ /** One pass of the contingency transmission, then the 20-hour deadline warnings. */
135
+ transmitContingency(limit: number): Promise<SweepReport>;
136
+ };
137
+ type FiscalDocuments = ReturnType<typeof createFiscalDocuments>;
138
+
139
+ export { CONTINGENCY_WARNING_AFTER_MS as C, type EmitterProfileInput as E, type FiscalDocuments as F, type IssueInput as I, type SweepReport as S, type CertificateFacts as a, type CertificateUpload as b, type FiscalDocumentsServiceConfig as c, type IssuingPointInput as d, createFiscalDocuments as e, parseIssuingPointInput as f, parseProfileInput as g, parseCertificateUpload as p };
@@ -0,0 +1,216 @@
1
+ import { SaleForDocument } from '../sale/index.js';
2
+
3
+ /**
4
+ * The wire contract of the fiscal service (`sidecar/` in this package): a
5
+ * stateless HTTP door in front of sped-nfe. JSON in, JSON out.
6
+ *
7
+ * Stateless means every call carries what it needs: the signing certificate
8
+ * (an A1 `.pfx` as base64 and its password) and, for an NFC-e, the CSC. The
9
+ * service keeps nothing between calls, writes nothing to disk and never logs
10
+ * any of the three.
11
+ */
12
+
13
+ /** The path segment of a document model: `nfe` is model 55, `nfce` model 65. */
14
+ type DocumentModelPath = "nfe" | "nfce";
15
+ /** The SEFAZ environment (`tpAmb` 2 and 1). */
16
+ type SefazEnvironment = "homologacao" | "producao";
17
+ /** The A1 certificate, per call. */
18
+ interface SigningCertificate {
19
+ /** The `.pfx` (PKCS#12) bytes, base64. */
20
+ readonly pfxBase64: string;
21
+ readonly password: string;
22
+ }
23
+ /** The NFC-e's Código de Segurança do Contribuinte and its id. */
24
+ interface Csc {
25
+ readonly id: string;
26
+ readonly token: string;
27
+ }
28
+ interface Authenticated {
29
+ readonly environment: SefazEnvironment;
30
+ readonly certificate: SigningCertificate;
31
+ }
32
+ /**
33
+ * `POST /<model>/issue`: builds, signs and transmits. `csc` is required for
34
+ * `nfce` and refused for `nfe`.
35
+ */
36
+ interface IssueRequest extends Authenticated {
37
+ readonly csc: Csc | null;
38
+ readonly document: SaleForDocument;
39
+ }
40
+ /** Why and since when the caixa issues offline (`dhCont`, `xJust`). */
41
+ interface ContingencyEntry {
42
+ /** ISO 8601 with the UTC offset. */
43
+ readonly since: string;
44
+ /** 15–256 characters. */
45
+ readonly reason: string;
46
+ }
47
+ /** `POST /nfce/sign-contingency`: builds and signs with `tpEmis = 9`; does NOT transmit. */
48
+ interface SignContingencyRequest extends IssueRequest {
49
+ readonly contingency: ContingencyEntry;
50
+ }
51
+ /** `POST /<model>/transmit`: an already signed XML (from `/nfce/sign-contingency`, say). */
52
+ interface TransmitRequest extends Authenticated {
53
+ readonly signedXml: string;
54
+ }
55
+ /** `POST /<model>/cancel`: the UF and the issuer come from the access key. */
56
+ interface CancelRequest extends Authenticated {
57
+ readonly accessKey: string;
58
+ /** The authorisation protocol (`nProt`). */
59
+ readonly protocol: string;
60
+ /** 15–255 characters. */
61
+ readonly reason: string;
62
+ }
63
+ /**
64
+ * `POST /nfce/cancel-substitution`: the NFC-e "cancelamento por substituição"
65
+ * (event 110112) — an online NFC-e found authorised after its sale was issued
66
+ * again in contingency, cancelled naming the substitute. Answers as `/cancel`.
67
+ */
68
+ interface CancelBySubstitutionRequest extends CancelRequest {
69
+ /** The contingency document that replaced it (`chNFeRef`). */
70
+ readonly substituteAccessKey: string;
71
+ }
72
+ /** `POST /<model>/lookup`. */
73
+ interface LookupRequest extends Authenticated {
74
+ readonly accessKey: string;
75
+ }
76
+ /** `POST /inutilize`: voids a range of unused numbers. */
77
+ interface InutilizeRequest extends Authenticated {
78
+ readonly model: DocumentModelPath;
79
+ readonly uf: string;
80
+ readonly cnpj: string;
81
+ /** The year of the numbers, four digits. */
82
+ readonly year: number;
83
+ readonly series: number;
84
+ readonly from: number;
85
+ readonly to: number;
86
+ /** 15–255 characters. */
87
+ readonly reason: string;
88
+ }
89
+ /** What SEFAZ answered, as the service read it. */
90
+ interface SefazAnswer {
91
+ /** `cStat`. */
92
+ readonly statusCode: string;
93
+ /** `xMotivo`. */
94
+ readonly statusReason: string;
95
+ /** The SOAP body SEFAZ returned, verbatim. */
96
+ readonly sefazReply: string;
97
+ }
98
+ /**
99
+ * `/issue` and `/transmit`: SEFAZ's final answer on the document.
100
+ *
101
+ * - `AUTHORIZED` (100, 120, 150).
102
+ * - `DENIED` (110, 301, 302, 303): a denial of use. The number is SPENT and
103
+ * the denial is kept like an authorisation (its `authorizedXml` carries the
104
+ * denial protocol); it is not a rejection, which leaves the number free.
105
+ *
106
+ * A retried call answers the same: SEFAZ's "already authorised" (204) and
107
+ * "already denied" (205), and a request sent with no answer, are settled by
108
+ * looking the key up, so a retry never turns an authorised document into an error.
109
+ */
110
+ interface IssuedDocument extends SefazAnswer {
111
+ readonly status: "AUTHORIZED" | "DENIED";
112
+ readonly accessKey: string;
113
+ readonly protocol: string;
114
+ /** `dhRecbto` of the protocol. */
115
+ readonly authorizedAt: string;
116
+ readonly signedXml: string;
117
+ /** The `nfeProc`: the signed XML with its protocol (of authorisation or of denial), what is stored. */
118
+ readonly authorizedXml: string;
119
+ }
120
+ /** `/nfce/sign-contingency`. */
121
+ interface ContingencySignedDocument {
122
+ readonly status: "SIGNED";
123
+ readonly accessKey: string;
124
+ /** Carries `tpEmis = 9` and the QR code; transmit it later through `/nfce/transmit`. */
125
+ readonly signedXml: string;
126
+ }
127
+ /**
128
+ * `/cancel`. A retried cancel (SEFAZ's 218 "already cancelled" or 573
129
+ * "duplicate event", or a cancel sent with no answer) is settled by looking
130
+ * the key up, and answers CANCELLED with what the lookup carries: the event's
131
+ * protocol and XML when SEFAZ returns them, `null` when it does not.
132
+ */
133
+ interface CancelledDocument extends SefazAnswer {
134
+ readonly status: "CANCELLED";
135
+ readonly accessKey: string;
136
+ /** The event's protocol. */
137
+ readonly protocol: string | null;
138
+ readonly registeredAt: string | null;
139
+ /** The `procEventoNFe`. */
140
+ readonly eventXml: string | null;
141
+ }
142
+ /** `/lookup`: what SEFAZ knows of the key. `NOT_FOUND` is an answer, not an error. */
143
+ interface LookedUpDocument extends SefazAnswer {
144
+ readonly status: "AUTHORIZED" | "CANCELLED" | "DENIED" | "NOT_FOUND";
145
+ readonly accessKey: string;
146
+ readonly protocol: string | null;
147
+ }
148
+ /**
149
+ * `/inutilize`. A retried inutilização (563, "a request for the same range
150
+ * already exists") answers INUTILIZED too, with `protocol` and
151
+ * `inutilizationXml` `null`: the range is void at SEFAZ, and SEFAZ offers no
152
+ * query that would return the first protocol.
153
+ */
154
+ interface InutilizedRange extends SefazAnswer {
155
+ readonly status: "INUTILIZED";
156
+ readonly protocol: string | null;
157
+ readonly registeredAt: string | null;
158
+ /** The signed request with its reply (`procInutNFe`). */
159
+ readonly inutilizationXml: string | null;
160
+ }
161
+ /**
162
+ * How a failed call is classified — the issuer port's own classes:
163
+ *
164
+ * - `REJECTED`: SEFAZ refused the document or the event; `code` is its `cStat`.
165
+ * The number is NOT spent (a denial is not an error: it answers `DENIED`).
166
+ * - `RETRYABLE`: try the same call again later. When `outcomeUnknown` is true
167
+ * the request went out and neither it nor the lookup that would settle it
168
+ * was answered: look the key up before sending it again.
169
+ * - `CONTINGENCY`: SEFAZ is unavailable. For an NFC-e being issued, nothing
170
+ * reached SEFAZ (or the lookup after an unanswered request could not reach
171
+ * it): go offline through `/nfce/sign-contingency`. For an NF-e (model 55)
172
+ * the service has no offline path (no SVC, no EPEC): treat it as RETRYABLE.
173
+ * - `AUTH`: the certificate is unreadable, the password wrong, the certificate
174
+ * expired, or SEFAZ refused it.
175
+ * - `INVALID`: the request itself is malformed (the schema, a missing CSC, an
176
+ * XML the layout refuses, a document the layout version cannot express).
177
+ * Fix the input; never retry it as is.
178
+ * - `INTERNAL`: a defect of the service, or a 4xx other than 403/408/429 from
179
+ * the verified SEFAZ host (a wrong web-service address). A retry would only repeat it.
180
+ */
181
+ type SidecarErrorClass = "REJECTED" | "RETRYABLE" | "CONTINGENCY" | "AUTH" | "INVALID" | "INTERNAL";
182
+ declare const SIDECAR_ERROR_CLASSES: readonly SidecarErrorClass[];
183
+ /** The body of every non-2xx answer. */
184
+ interface SidecarErrorBody {
185
+ readonly error: {
186
+ readonly class: SidecarErrorClass;
187
+ /**
188
+ * The SEFAZ `cStat` when SEFAZ answered (always for `REJECTED`); for
189
+ * `INVALID`, a named code where one applies (`NT_2026_008_NOT_SUPPORTED`:
190
+ * a document issued on or after 2027-01-01, which needs NT 2026.008's
191
+ * `vProdLiq`); `null` otherwise.
192
+ */
193
+ readonly code: string | null;
194
+ readonly message: string;
195
+ /** Per-field problems of an `INVALID` request. */
196
+ readonly details: readonly string[];
197
+ /** When the call got as far as building and signing: keep it, the key is now spoken for. */
198
+ readonly accessKey: string | null;
199
+ readonly signedXml: string | null;
200
+ readonly sefazReply: string | null;
201
+ /** The request went out and its outcome is still unknown: look the key up before sending it again. */
202
+ readonly outcomeUnknown: boolean;
203
+ };
204
+ }
205
+ /** `GET /health`. */
206
+ interface SidecarHealth {
207
+ readonly status: "ok";
208
+ /** The libraries the service runs, by name, with the version installed. */
209
+ readonly libraries: Readonly<Record<string, string>>;
210
+ /** The schema package the NF-e layout is validated against. */
211
+ readonly nfeSchemas: string;
212
+ /** Whether SEFAZ's server certificate is verified; `false` only with `FISCAL_SEFAZ_TLS_VERIFY=off`. */
213
+ readonly sefazTlsVerify: boolean;
214
+ }
215
+
216
+ export { type CancelBySubstitutionRequest, type CancelRequest, type CancelledDocument, type ContingencyEntry, type ContingencySignedDocument, type Csc, type DocumentModelPath, type InutilizeRequest, type InutilizedRange, type IssueRequest, type IssuedDocument, type LookedUpDocument, type LookupRequest, SIDECAR_ERROR_CLASSES, type SefazAnswer, type SefazEnvironment, type SidecarErrorBody, type SidecarErrorClass, type SidecarHealth, type SignContingencyRequest, type SigningCertificate, type TransmitRequest };
@@ -0,0 +1,8 @@
1
+ import {
2
+ SIDECAR_ERROR_CLASSES
3
+ } from "../chunk-FOFIN5M7.js";
4
+ import "../chunk-7QVYU63E.js";
5
+ export {
6
+ SIDECAR_ERROR_CLASSES
7
+ };
8
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}