@useinvio/nfse-sdk 1.0.3 → 2.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 +2 -2
- package/dist/certificateValidation.d.ts +7 -0
- package/dist/certificateValidation.js +27 -0
- package/dist/certificateValidation.js.map +1 -0
- package/dist/dpsJson.js +2 -2
- package/dist/dpsJson.js.map +1 -1
- package/dist/emissaoNota.d.ts +9 -0
- package/dist/emissaoNota.js +34 -24
- package/dist/emissaoNota.js.map +1 -1
- package/dist/fiscalValidation.d.ts +26 -3
- package/dist/fiscalValidation.js +159 -10
- package/dist/fiscalValidation.js.map +1 -1
- package/dist/index.d.ts +7 -4
- package/dist/index.js +5 -3
- package/dist/index.js.map +1 -1
- package/dist/sefinClient.d.ts +8 -4
- package/dist/sefinClient.js +15 -4
- package/dist/sefinClient.js.map +1 -1
- package/dist/xsdValidation.d.ts +6 -0
- package/dist/xsdValidation.js +46 -0
- package/dist/xsdValidation.js.map +1 -0
- package/docs/METRICS.md +49 -5
- package/llms.txt +3 -3
- package/package.json +4 -2
- package/schemas/nfse/v1.01/Schemas/1.00/CNC_v1.00.xsd +13 -0
- package/schemas/nfse/v1.01/Schemas/1.00/DPS_v1.00.xsd +13 -0
- package/schemas/nfse/v1.01/Schemas/1.00/NFSe_v1.00.xsd +14 -0
- package/schemas/nfse/v1.01/Schemas/1.00/evento_v1.00.xsd +15 -0
- package/schemas/nfse/v1.01/Schemas/1.00/pedRegEvento_v1.00.xsd +15 -0
- package/schemas/nfse/v1.01/Schemas/1.00/tiposCnc_v1.00.xsd +181 -0
- package/schemas/nfse/v1.01/Schemas/1.00/tiposComplexos_v1.00.xsd +1828 -0
- package/schemas/nfse/v1.01/Schemas/1.00/tiposEventos_v1.00.xsd +733 -0
- package/schemas/nfse/v1.01/Schemas/1.00/tiposSimples_v1.00.xsd +1658 -0
- package/schemas/nfse/v1.01/Schemas/1.00/xmldsig-core-schema.xsd +92 -0
- package/schemas/nfse/v1.01/Schemas/1.01/CNC_v1.00.xsd +14 -0
- package/schemas/nfse/v1.01/Schemas/1.01/DPS_v1.01.xsd +14 -0
- package/schemas/nfse/v1.01/Schemas/1.01/NFSe_v1.01.xsd +15 -0
- package/schemas/nfse/v1.01/Schemas/1.01/evento_v1.01.xsd +15 -0
- package/schemas/nfse/v1.01/Schemas/1.01/pedRegEvento_v1.01.xsd +15 -0
- package/schemas/nfse/v1.01/Schemas/1.01/tiposCnc_v1.00.xsd +166 -0
- package/schemas/nfse/v1.01/Schemas/1.01/tiposComplexos_v1.01.xsd +2709 -0
- package/schemas/nfse/v1.01/Schemas/1.01/tiposEventos_v1.01.xsd +780 -0
- package/schemas/nfse/v1.01/Schemas/1.01/tiposSimples_v1.01.xsd +1844 -0
- package/schemas/nfse/v1.01/Schemas/1.01/xmldsig-core-schema.xsd +318 -0
package/dist/sefinClient.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { PfxMaterial } from './loadPfx.js';
|
|
2
2
|
import type { Ambiente } from './config.js';
|
|
3
|
+
export declare const SEFIN_LATENCY_METRICS_ENV = "NFSE_SEFIN_LATENCY_METRICS";
|
|
3
4
|
export interface SefinErro {
|
|
4
5
|
Codigo: string;
|
|
5
6
|
Descricao: string;
|
|
@@ -26,9 +27,11 @@ export type SefinRequestObserver = (metric: SefinRequestMetric) => void;
|
|
|
26
27
|
export interface SefinLatencyTrackerOptions {
|
|
27
28
|
/**
|
|
28
29
|
* Maximum number of recent latency samples kept for each operation/environment
|
|
29
|
-
* series.
|
|
30
|
+
* series. Min, max, average, and optional percentiles use this rolling window.
|
|
30
31
|
*/
|
|
31
32
|
maxSamplesPerSeries?: number;
|
|
33
|
+
/** Percentile metrics are intentionally opt-in because they keep extra series in exporters. */
|
|
34
|
+
includePercentiles?: boolean;
|
|
32
35
|
}
|
|
33
36
|
export interface SefinLatencySeriesSnapshot {
|
|
34
37
|
operation: SefinOperation;
|
|
@@ -40,9 +43,9 @@ export interface SefinLatencySeriesSnapshot {
|
|
|
40
43
|
minMs: number;
|
|
41
44
|
maxMs: number;
|
|
42
45
|
avgMs: number;
|
|
43
|
-
p50Ms
|
|
44
|
-
p95Ms
|
|
45
|
-
p99Ms
|
|
46
|
+
p50Ms?: number;
|
|
47
|
+
p95Ms?: number;
|
|
48
|
+
p99Ms?: number;
|
|
46
49
|
}
|
|
47
50
|
export interface SefinLatencySnapshot {
|
|
48
51
|
generatedAt: string;
|
|
@@ -53,6 +56,7 @@ export interface SefinLatencyTracker {
|
|
|
53
56
|
snapshot(): SefinLatencySnapshot;
|
|
54
57
|
reset(): void;
|
|
55
58
|
}
|
|
59
|
+
export declare function isSefinLatencyMetricsEnabled(env?: NodeJS.ProcessEnv): boolean;
|
|
56
60
|
export declare function setSefinRequestObserver(observer: SefinRequestObserver | undefined): void;
|
|
57
61
|
export declare function getSefinRequestObserver(): SefinRequestObserver | undefined;
|
|
58
62
|
export declare function createSefinLatencyTracker(options?: SefinLatencyTrackerOptions): SefinLatencyTracker;
|
package/dist/sefinClient.js
CHANGED
|
@@ -3,7 +3,12 @@ import { performance } from 'node:perf_hooks';
|
|
|
3
3
|
import { resolveSefinBaseUrl } from './config.js';
|
|
4
4
|
/** Evita que uma conexao travada com o SEFIN prenda um worker indefinidamente. */
|
|
5
5
|
const SEFIN_REQUEST_TIMEOUT_MS = 60_000;
|
|
6
|
+
export const SEFIN_LATENCY_METRICS_ENV = 'NFSE_SEFIN_LATENCY_METRICS';
|
|
6
7
|
let sefinRequestObserver;
|
|
8
|
+
export function isSefinLatencyMetricsEnabled(env = process.env) {
|
|
9
|
+
const value = env[SEFIN_LATENCY_METRICS_ENV]?.trim().toLowerCase();
|
|
10
|
+
return value === '1' || value === 'true' || value === 'yes' || value === 'on';
|
|
11
|
+
}
|
|
7
12
|
export function setSefinRequestObserver(observer) {
|
|
8
13
|
sefinRequestObserver = observer;
|
|
9
14
|
}
|
|
@@ -11,6 +16,8 @@ export function getSefinRequestObserver() {
|
|
|
11
16
|
return sefinRequestObserver;
|
|
12
17
|
}
|
|
13
18
|
function notifySefinRequestObserver(metric) {
|
|
19
|
+
if (!isSefinLatencyMetricsEnabled())
|
|
20
|
+
return;
|
|
14
21
|
try {
|
|
15
22
|
sefinRequestObserver?.(metric);
|
|
16
23
|
}
|
|
@@ -29,6 +36,7 @@ function trackerKey(metric) {
|
|
|
29
36
|
}
|
|
30
37
|
export function createSefinLatencyTracker(options = {}) {
|
|
31
38
|
const maxSamplesPerSeries = Math.max(1, Math.floor(options.maxSamplesPerSeries ?? 1_000));
|
|
39
|
+
const includePercentiles = options.includePercentiles === true;
|
|
32
40
|
const series = new Map();
|
|
33
41
|
return {
|
|
34
42
|
observe(metric) {
|
|
@@ -61,7 +69,7 @@ export function createSefinLatencyTracker(options = {}) {
|
|
|
61
69
|
series: Array.from(series.values()).map((bucket) => {
|
|
62
70
|
const sortedDurations = [...bucket.durations].sort((a, b) => a - b);
|
|
63
71
|
const total = sortedDurations.reduce((sum, value) => sum + value, 0);
|
|
64
|
-
|
|
72
|
+
const snapshot = {
|
|
65
73
|
operation: bucket.operation,
|
|
66
74
|
ambiente: bucket.ambiente,
|
|
67
75
|
count: bucket.count,
|
|
@@ -71,10 +79,13 @@ export function createSefinLatencyTracker(options = {}) {
|
|
|
71
79
|
minMs: sortedDurations[0] ?? 0,
|
|
72
80
|
maxMs: sortedDurations.at(-1) ?? 0,
|
|
73
81
|
avgMs: sortedDurations.length ? total / sortedDurations.length : 0,
|
|
74
|
-
p50Ms: percentile(sortedDurations, 0.50),
|
|
75
|
-
p95Ms: percentile(sortedDurations, 0.95),
|
|
76
|
-
p99Ms: percentile(sortedDurations, 0.99),
|
|
77
82
|
};
|
|
83
|
+
if (includePercentiles) {
|
|
84
|
+
snapshot.p50Ms = percentile(sortedDurations, 0.50);
|
|
85
|
+
snapshot.p95Ms = percentile(sortedDurations, 0.95);
|
|
86
|
+
snapshot.p99Ms = percentile(sortedDurations, 0.99);
|
|
87
|
+
}
|
|
88
|
+
return snapshot;
|
|
78
89
|
}).sort((a, b) => (a.operation.localeCompare(b.operation) ||
|
|
79
90
|
(a.ambiente ?? '').localeCompare(b.ambiente ?? ''))),
|
|
80
91
|
};
|
package/dist/sefinClient.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sefinClient.js","sourceRoot":"","sources":["../sefinClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIlD,kFAAkF;AAClF,MAAM,wBAAwB,GAAG,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"sefinClient.js","sourceRoot":"","sources":["../sefinClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIlD,kFAAkF;AAClF,MAAM,wBAAwB,GAAG,MAAM,CAAC;AACxC,MAAM,CAAC,MAAM,yBAAyB,GAAG,4BAA4B,CAAC;AAqFtE,IAAI,oBAAsD,CAAC;AAE3D,MAAM,UAAU,4BAA4B,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC/E,MAAM,KAAK,GAAG,GAAG,CAAC,yBAAyB,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnE,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,IAAI,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,QAA0C;IAChF,oBAAoB,GAAG,QAAQ,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED,SAAS,0BAA0B,CAAC,MAA0B;IAC5D,IAAI,CAAC,4BAA4B,EAAE;QAAE,OAAO;IAE5C,IAAI,CAAC;QACH,oBAAoB,EAAE,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,YAAsB,EAAE,QAAgB;IAC1D,IAAI,CAAC,YAAY,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5G,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,UAAU,CAAC,MAA0D;IAC5E,OAAO,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,QAAQ,IAAI,SAAS,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,UAAsC,EAAE;IAChF,MAAM,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,mBAAmB,IAAI,KAAK,CAAC,CAAC,CAAC;IAC1F,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,KAAK,IAAI,CAAC;IAC/D,MAAM,MAAM,GAAG,IAAI,GAAG,EAOlB,CAAC;IAEL,OAAO;QACL,OAAO,CAAC,MAAM;YACZ,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;YAC/B,IAAI,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,GAAG;oBACP,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,KAAK,EAAE,CAAC;oBACR,YAAY,EAAE,CAAC;oBACf,UAAU,EAAE,CAAC;oBACb,SAAS,EAAE,EAAE;iBACd,CAAC;gBACF,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC1B,CAAC;YAED,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;YAClB,IAAI,MAAM,CAAC,OAAO;gBAAE,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;;gBACxC,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC;YAC5B,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACzC,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,mBAAmB,EAAE,CAAC;gBAClD,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,mBAAmB,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC;QACD,QAAQ;YACN,OAAO;gBACL,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACrC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;oBACjD,MAAM,eAAe,GAAG,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;oBACpE,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;oBAErE,MAAM,QAAQ,GAA+B;wBAC3C,SAAS,EAAE,MAAM,CAAC,SAAS;wBAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;wBACzB,KAAK,EAAE,MAAM,CAAC,KAAK;wBACnB,YAAY,EAAE,MAAM,CAAC,YAAY;wBACjC,UAAU,EAAE,MAAM,CAAC,UAAU;wBAC7B,WAAW,EAAE,eAAe,CAAC,MAAM;wBACnC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC;wBAC9B,KAAK,EAAE,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;wBAClC,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;qBACnE,CAAC;oBAEF,IAAI,kBAAkB,EAAE,CAAC;wBACvB,QAAQ,CAAC,KAAK,GAAG,UAAU,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;wBACnD,QAAQ,CAAC,KAAK,GAAG,UAAU,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;wBACnD,QAAQ,CAAC,KAAK,GAAG,UAAU,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;oBACrD,CAAC;oBAED,OAAO,QAAQ,CAAC;gBAClB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAChB,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;oBACtC,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CACnD,CAAC;aACH,CAAC;QACJ,CAAC;QACD,KAAK;YACH,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CACnB,IAAiB,EACjB,GAAgB,EAChB,UAA6B,EAC7B,YAAqB;IAErB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,YAAY,IAAI,mBAAmB,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAElF,MAAM,OAAO,GAAoC;QAC/C,MAAM,EAAE,kBAAkB;KAC3B,CAAC;IACF,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACpB,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QAC7C,OAAO,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,OAAO,GAAyB;QACpC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,GAAG;QACrB,IAAI,EAAE,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM;QAC/B,OAAO;QACP,GAAG,EAAE,GAAG,CAAC,aAAa;QACtB,IAAI,EAAE,GAAG,CAAC,OAAO;QACjB,kBAAkB,EAAE,IAAI;QACxB,OAAO,EAAE,wBAAwB;KAClC,CAAC;IAEF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACpC,IAAI,UAAU,GAAG,KAAK,CAAC;QACvB,MAAM,UAAU,GAAG,CAAC,MAA8C,EAAE,EAAE;YACpE,IAAI,UAAU;gBAAE,OAAO;YACvB,UAAU,GAAG,IAAI,CAAC;YAClB,0BAA0B,CAAC;gBACzB,GAAG,MAAM;gBACT,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;aAC1C,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACzC,MAAM,MAAM,GAAa,EAAE,CAAC;YAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACtC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;gBACjB,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC;gBACnC,UAAU,CAAC;oBACT,SAAS,EAAE,UAAU,CAAC,SAAS;oBAC/B,QAAQ,EAAE,UAAU,CAAC,QAAQ;oBAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,YAAY,EAAE,UAAU,CAAC,YAAY;oBACrC,MAAM;oBACN,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;iBACvC,CAAC,CAAC;gBACH,OAAO,CAAC;oBACN,MAAM;oBACN,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;oBACtD,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;iBAC9B,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACxB,UAAU,CAAC;gBACT,SAAS,EAAE,UAAU,CAAC,SAAS;gBAC/B,QAAQ,EAAE,UAAU,CAAC,QAAQ;gBAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,YAAY,EAAE,UAAU,CAAC,YAAY;gBACrC,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,YAAY,EAAE,KAAK,CAAC,OAAO;aAC5B,CAAC,CAAC;YACH,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;YACrB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,iCAAiC,wBAAwB,IAAI,CAAC,CAAC,CAAC;QACxF,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,IAAI,IAAI;YAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxC,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,mFAAmF;AACnF,SAAS,SAAS,CAAC,GAAqB;IACtC,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,aAAa,CAAC,KAAU;IAC/B,MAAM,IAAI,GAAc;QACtB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,cAAc,CAAC;QAC5E,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;KAC/F,CAAC;IACF,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAC;IAC3D,IAAI,WAAW,IAAI,IAAI;QAAE,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAyB;IACnD,OAAO,CACL,IAAI,CAAC,OAAO,KAAK,IAAI;QACrB,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ;QACpC,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ;QACvC,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAC/B,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAAC,IAAS;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACxD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,kBAAkB,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAClE,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC/B,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO;QACL,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;KAC5D,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,aAAqB,EACrB,GAAgB,EAChB,QAAmB;IAEnB,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,OAAO,SAAS,CAAC,MAAM,YAAY,CACjC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,aAAa,EAAE,EAAE,EAC9D,GAAG,EACH,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,EAChE,IAAI,CACL,CAAC,CAAC;AACL,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAa,EAAE,GAAgB,EAAE,QAAmB;IACtF,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,OAAO,SAAS,CAAC,MAAM,YAAY,CACjC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,KAAK,EAAE,EAAE,EACzC,GAAG,EACH,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,EACxE,IAAI,CACL,CAAC,CAAC;AACL,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,gBAAwB,EACxB,GAAgB,EAChB,WAAmB,EACnB,QAAmB;IAEnB,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,OAAO,SAAS,CACd,MAAM,YAAY,CAChB;QACE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,SAAS,WAAW,UAAU;QACpC,QAAQ,EAAE,EAAE,gBAAgB,EAAE;KAC/B,EACD,GAAG,EACH,EAAE,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,YAAY,EAAE,uBAAuB,EAAE,EAC/E,IAAI,CACL,CACF,CAAC;AACJ,CAAC"}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export declare class DpsXsdValidationError extends Error {
|
|
2
|
+
readonly details: string[];
|
|
3
|
+
constructor(details: string[]);
|
|
4
|
+
}
|
|
5
|
+
/** Validates a generated DPS against the official v1.01 schema before signing. */
|
|
6
|
+
export declare function validateDpsXmlAgainstXsd(xml: string): void;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { execFileSync } from 'node:child_process';
|
|
2
|
+
import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import { tmpdir } from 'node:os';
|
|
4
|
+
import { join } from 'node:path';
|
|
5
|
+
import { fileURLToPath } from 'node:url';
|
|
6
|
+
export class DpsXsdValidationError extends Error {
|
|
7
|
+
details;
|
|
8
|
+
constructor(details) {
|
|
9
|
+
super(`XML da DPS invalido para o XSD v1.01: ${details.join('; ')}`);
|
|
10
|
+
this.details = details;
|
|
11
|
+
this.name = 'DpsXsdValidationError';
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
function schemaSourceDir() {
|
|
15
|
+
return fileURLToPath(new URL('../schemas/nfse/v1.01/Schemas/1.01/', import.meta.url));
|
|
16
|
+
}
|
|
17
|
+
/** Validates a generated DPS against the official v1.01 schema before signing. */
|
|
18
|
+
export function validateDpsXmlAgainstXsd(xml) {
|
|
19
|
+
const workDir = mkdtempSync(join(tmpdir(), 'nfse-sdk-xsd-'));
|
|
20
|
+
const schemasDir = join(workDir, 'schemas');
|
|
21
|
+
try {
|
|
22
|
+
cpSync(schemaSourceDir(), schemasDir, { recursive: true });
|
|
23
|
+
// libxml2 treats ^/$ literally in XSD regexes. The official package ships
|
|
24
|
+
// one JavaScript-style anchor, so normalize that expression in our copy.
|
|
25
|
+
const simpleTypesPath = join(schemasDir, 'tiposSimples_v1.01.xsd');
|
|
26
|
+
const simpleTypes = readFileSync(simpleTypesPath, 'utf8').replace('<xs:pattern value="^0{0,4}\\d{1,5}$"/>', '<xs:pattern value="0{0,4}\\d{1,5}"/>');
|
|
27
|
+
writeFileSync(simpleTypesPath, simpleTypes);
|
|
28
|
+
const xmlPath = join(workDir, 'dps.xml');
|
|
29
|
+
writeFileSync(xmlPath, xml);
|
|
30
|
+
try {
|
|
31
|
+
execFileSync('xmllint', ['--noout', '--schema', join(schemasDir, 'DPS_v1.01.xsd'), xmlPath], {
|
|
32
|
+
encoding: 'utf8',
|
|
33
|
+
stdio: ['ignore', 'pipe', 'pipe'],
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
catch (error) {
|
|
37
|
+
const stderr = error && typeof error === 'object' && 'stderr' in error ? String(error.stderr) : String(error);
|
|
38
|
+
const details = stderr.split('\n').map((line) => line.trim()).filter(Boolean);
|
|
39
|
+
throw new DpsXsdValidationError(details.length ? details : ['Falha desconhecida ao validar o XSD.']);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
finally {
|
|
43
|
+
rmSync(workDir, { recursive: true, force: true });
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
//# sourceMappingURL=xsdValidation.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"xsdValidation.js","sourceRoot":"","sources":["../xsdValidation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAClB;IAA5B,YAA4B,OAAiB;QAC3C,KAAK,CAAC,yCAAyC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAD3C,YAAO,GAAP,OAAO,CAAU;QAE3C,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,SAAS,eAAe;IACtB,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,qCAAqC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,wBAAwB,CAAC,GAAW;IAClD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,CAAC,eAAe,EAAE,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE3D,0EAA0E;QAC1E,yEAAyE;QACzE,MAAM,eAAe,GAAG,IAAI,CAAC,UAAU,EAAE,wBAAwB,CAAC,CAAC;QACnE,MAAM,WAAW,GAAG,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,OAAO,CAC/D,wCAAwC,EACxC,sCAAsC,CACvC,CAAC;QACF,aAAa,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;QAE5C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QACzC,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC;YACH,YAAY,CAAC,SAAS,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE;gBAC3F,QAAQ,EAAE,MAAM;gBAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;aAClC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9G,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC9E,MAAM,IAAI,qBAAqB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC;QACvG,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;AACH,CAAC"}
|
package/docs/METRICS.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# Metricas da SEFIN
|
|
2
2
|
|
|
3
|
-
O SDK pode medir a latencia das chamadas mTLS feitas contra a SEFIN Nacional. Essas metricas ajudam a responder perguntas como:
|
|
3
|
+
O SDK pode medir a latencia das chamadas mTLS feitas contra a SEFIN Nacional. A coleta fica desligada por padrao e deve ser habilitada com a variavel de ambiente `NFSE_SEFIN_LATENCY_METRICS=1`. Essas metricas ajudam a responder perguntas como:
|
|
4
4
|
|
|
5
5
|
- qual e o P99 de `POST /nfse` no ambiente restrito?
|
|
6
6
|
- as consultas por chave estao ficando lentas?
|
|
7
7
|
- quantas chamadas externas falharam no processo atual?
|
|
8
8
|
- a lentidao vem da SEFIN ou da minha API?
|
|
9
9
|
|
|
10
|
-
As metricas sao emitidas pelo SDK,
|
|
10
|
+
As metricas sao emitidas pelo SDK apenas quando `NFSE_SEFIN_LATENCY_METRICS` esta habilitada, e nao sao enviadas para nenhum servico automaticamente. A aplicacao que usa o SDK decide se quer guardar em memoria, registrar em logs, exportar para Prometheus, enviar para Datadog/New Relic/Grafana, ou expor em um endpoint interno.
|
|
11
11
|
|
|
12
12
|
## O que e medido
|
|
13
13
|
|
|
@@ -49,6 +49,16 @@ latencia SEFIN medida pelo SDK: 4200ms
|
|
|
49
49
|
|
|
50
50
|
Tambem nao ha persistencia automatica. O agregador em memoria zera quando o processo Node reinicia.
|
|
51
51
|
|
|
52
|
+
## Habilitando a coleta
|
|
53
|
+
|
|
54
|
+
Configure a variavel de ambiente no processo que usa o SDK:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
NFSE_SEFIN_LATENCY_METRICS=1
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Valores aceitos para habilitar: `1`, `true`, `yes` e `on`. Sem essa variavel, ou com outro valor, o SDK nao chama o observer de metricas.
|
|
61
|
+
|
|
52
62
|
## Uso basico
|
|
53
63
|
|
|
54
64
|
Registre um observer uma vez na inicializacao da aplicacao, antes de fazer chamadas como `emitirNfse`, `consultarNfse` ou `enviarEvento`.
|
|
@@ -78,6 +88,38 @@ console.log(snapshot.series);
|
|
|
78
88
|
|
|
79
89
|
Exemplo de retorno:
|
|
80
90
|
|
|
91
|
+
```ts
|
|
92
|
+
{
|
|
93
|
+
generatedAt: '2026-07-09T12:00:00.000Z',
|
|
94
|
+
series: [
|
|
95
|
+
{
|
|
96
|
+
operation: 'transmitir_dps',
|
|
97
|
+
ambiente: 'restrita',
|
|
98
|
+
count: 120,
|
|
99
|
+
successCount: 118,
|
|
100
|
+
errorCount: 2,
|
|
101
|
+
sampleCount: 120,
|
|
102
|
+
minMs: 180,
|
|
103
|
+
maxMs: 8100,
|
|
104
|
+
avgMs: 940.2
|
|
105
|
+
}
|
|
106
|
+
]
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Percentis opcionais
|
|
111
|
+
|
|
112
|
+
Metricas de percentil ficam desligadas por padrao. Para incluir `p50Ms`, `p95Ms` e `p99Ms` no snapshot, habilite explicitamente `includePercentiles`:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
export const sefinLatency = createSefinLatencyTracker({
|
|
116
|
+
maxSamplesPerSeries: 1000,
|
|
117
|
+
includePercentiles: true,
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Com percentis habilitados, o snapshot inclui os campos extras:
|
|
122
|
+
|
|
81
123
|
```ts
|
|
82
124
|
{
|
|
83
125
|
generatedAt: '2026-07-09T12:00:00.000Z',
|
|
@@ -132,7 +174,7 @@ const sefinLatency = createSefinLatencyTracker({
|
|
|
132
174
|
});
|
|
133
175
|
```
|
|
134
176
|
|
|
135
|
-
Com `5000`, cada combinacao `operation + ambiente` calcula os percentis usando no maximo as ultimas 5000 amostras daquela serie. O contador `count` continua acumulando o total observado desde o ultimo `reset
|
|
177
|
+
Com `5000`, cada combinacao `operation + ambiente` calcula `minMs`, `maxMs`, `avgMs` e, quando habilitados, os percentis usando no maximo as ultimas 5000 amostras daquela serie. O contador `count` continua acumulando o total observado desde o ultimo `reset`.
|
|
136
178
|
|
|
137
179
|
## Logs estruturados
|
|
138
180
|
|
|
@@ -177,11 +219,13 @@ O SDK nao depende de Prometheus. Para Prometheus, voce pode converter o snapshot
|
|
|
177
219
|
Exemplo conceitual:
|
|
178
220
|
|
|
179
221
|
```txt
|
|
180
|
-
|
|
222
|
+
sefin_request_duration_avg_ms{operation="transmitir_dps",ambiente="restrita"} 940.2
|
|
181
223
|
sefin_request_success_total{operation="transmitir_dps",ambiente="restrita"} 118
|
|
182
224
|
sefin_request_error_total{operation="transmitir_dps",ambiente="restrita"} 2
|
|
183
225
|
```
|
|
184
226
|
|
|
227
|
+
Exporte `sefin_request_duration_p99_ms` apenas quando `includePercentiles: true` estiver habilitado.
|
|
228
|
+
|
|
185
229
|
Se voce ja usa OpenTelemetry, Datadog, New Relic, Grafana Cloud ou outro coletor, use `setSefinRequestObserver` como ponto de saida e envie `durationMs`, `operation`, `ambiente`, `status` e `success`.
|
|
186
230
|
|
|
187
231
|
## Reset
|
|
@@ -199,7 +243,7 @@ Isso remove as series e amostras em memoria. Use com cuidado em producao, porque
|
|
|
199
243
|
- Registre o observer uma unica vez por processo.
|
|
200
244
|
- Nao crie um tracker novo a cada request HTTP.
|
|
201
245
|
- Use `maxSamplesPerSeries` conforme o volume esperado e a memoria disponivel.
|
|
246
|
+
- Habilite `includePercentiles` apenas quando sua operacao realmente precisar de P50/P95/P99.
|
|
202
247
|
- Lembre que processos diferentes tem snapshots diferentes. Em varios containers/replicas, cada processo enxerga apenas as chamadas que ele executou.
|
|
203
248
|
- Para historico entre deploys/restarts, envie as metricas para um sistema externo.
|
|
204
249
|
- Para saber os erros oficiais mais comuns da SEFIN, use a resposta de negocio e `extrairErros(body)` no seu fluxo. As metricas de latencia focam em tempo, status e sucesso/falha da chamada externa.
|
|
205
|
-
|
package/llms.txt
CHANGED
|
@@ -8,7 +8,7 @@ It is not a fiscal decision engine. Do not infer tax codes, accounting rules, te
|
|
|
8
8
|
|
|
9
9
|
- `README.md`: primary Portuguese documentation and examples.
|
|
10
10
|
- `ENGLISH.md`: English documentation with the same conceptual flow.
|
|
11
|
-
- `docs/METRICS.md`: detailed SEFIN latency metrics guide, including observer setup, P99
|
|
11
|
+
- `docs/METRICS.md`: detailed SEFIN latency metrics guide, including the `NFSE_SEFIN_LATENCY_METRICS` env switch, observer setup, optional P99 snapshots, and export guidance.
|
|
12
12
|
- `index.ts`: public exports. Treat this as the supported API surface.
|
|
13
13
|
- `examples/`: runnable usage examples.
|
|
14
14
|
- `JSON_MAPPING.md`: mapping notes for the declarative JSON input.
|
|
@@ -22,7 +22,7 @@ It is not a fiscal decision engine. Do not infer tax codes, accounting rules, te
|
|
|
22
22
|
- `buildDpsId(prestador, nDPS, serie?)`: derive the 45-character DPS Id.
|
|
23
23
|
- `loadPfx(...)` and `loadPfxFromBuffer(...)`: extract key/certificate material from an A1/PFX certificate.
|
|
24
24
|
- `consultarNfse(...)`, `enviarEvento(...)`, `extrairErros(...)`: lower-level SEFIN helpers.
|
|
25
|
-
- `setSefinRequestObserver(...)` and `createSefinLatencyTracker(...)`: observe SEFIN round-trip latency
|
|
25
|
+
- `setSefinRequestObserver(...)` and `createSefinLatencyTracker(...)`: observe SEFIN round-trip latency when `NFSE_SEFIN_LATENCY_METRICS` is enabled; percentiles require `includePercentiles: true`.
|
|
26
26
|
- `gzipBase64(...)`, `gunzipBase64(...)`, `signDps(...)`, `verifyDps(...)`: protocol utilities for custom flows.
|
|
27
27
|
|
|
28
28
|
## File Map
|
|
@@ -59,7 +59,7 @@ Keep values as strings when they represent fiscal codes, identifiers, decimals,
|
|
|
59
59
|
- `buildDpsId` must return a 45-character Id beginning with `DPS`.
|
|
60
60
|
- `emitirNfse` signs the DPS before transport and throws `EmitirNotaError` when SEFIN rejects or no authorized XML is returned.
|
|
61
61
|
- `sefinClient.ts` uses PEM key/cert material for mTLS, not the raw PFX in the Node TLS handshake.
|
|
62
|
-
- SEFIN latency metrics are emitted for the external request only; keep them separate from API route latency when integrating observability.
|
|
62
|
+
- SEFIN latency metrics are off by default, enabled through `NFSE_SEFIN_LATENCY_METRICS`, and emitted for the external request only; keep them separate from API route latency when integrating observability.
|
|
63
63
|
|
|
64
64
|
## Change Guidance for LLMs
|
|
65
65
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@useinvio/nfse-sdk",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.0.0",
|
|
4
4
|
"description": "TypeScript SDK for Brazil's national NFS-e: JSON to DPS/XML, XMLDSIG, GZip/Base64, mTLS and SEFIN errors.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -16,13 +16,15 @@
|
|
|
16
16
|
"dist/*.d.ts",
|
|
17
17
|
"dist/*.js",
|
|
18
18
|
"dist/*.js.map",
|
|
19
|
+
"dist/schemas/**/*.xsd",
|
|
19
20
|
"docs/*.md",
|
|
20
21
|
"examples/*.ts",
|
|
21
22
|
"examples/README.md",
|
|
22
23
|
"README.md",
|
|
23
24
|
"JSON_MAPPING.md",
|
|
24
25
|
"llms.txt",
|
|
25
|
-
"LICENSE"
|
|
26
|
+
"LICENSE",
|
|
27
|
+
"schemas/**/*.xsd"
|
|
26
28
|
],
|
|
27
29
|
"scripts": {
|
|
28
30
|
"build": "tsc -p tsconfig.json",
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
3
|
+
targetNamespace="http://www.sped.fazenda.gov.br/nfse"
|
|
4
|
+
xmlns="http://www.sped.fazenda.gov.br/nfse"
|
|
5
|
+
attributeFormDefault="unqualified"
|
|
6
|
+
elementFormDefault="qualified">
|
|
7
|
+
<xs:include schemaLocation="tiposCnc_v1.00.xsd"/>
|
|
8
|
+
<xs:element name="CNC" type="TCNC">
|
|
9
|
+
<xs:annotation>
|
|
10
|
+
<xs:documentation>Schema XML Leiaute do arquivo para upload - CNC</xs:documentation>
|
|
11
|
+
</xs:annotation>
|
|
12
|
+
</xs:element>
|
|
13
|
+
</xs:schema>
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
3
|
+
targetNamespace="http://www.sped.fazenda.gov.br/nfse"
|
|
4
|
+
xmlns="http://www.sped.fazenda.gov.br/nfse"
|
|
5
|
+
attributeFormDefault="unqualified"
|
|
6
|
+
elementFormDefault="qualified">
|
|
7
|
+
<xs:include schemaLocation="tiposComplexos_v1.00.xsd"/>
|
|
8
|
+
<xs:element name="DPS" type="TCDPS">
|
|
9
|
+
<xs:annotation>
|
|
10
|
+
<xs:documentation>Schema XML da Declaração de Prestação de Serviços - DPS</xs:documentation>
|
|
11
|
+
</xs:annotation>
|
|
12
|
+
</xs:element>
|
|
13
|
+
</xs:schema>
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
3
|
+
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
|
|
4
|
+
targetNamespace="http://www.sped.fazenda.gov.br/nfse"
|
|
5
|
+
xmlns="http://www.sped.fazenda.gov.br/nfse"
|
|
6
|
+
attributeFormDefault="unqualified"
|
|
7
|
+
elementFormDefault="qualified">
|
|
8
|
+
<xs:include schemaLocation="tiposComplexos_v1.00.xsd"/>
|
|
9
|
+
<xs:element name="NFSe" type="TCNFSe">
|
|
10
|
+
<xs:annotation>
|
|
11
|
+
<xs:documentation>Schema XML da Nota Fiscal de Serviços Eletrônica - NFS-e</xs:documentation>
|
|
12
|
+
</xs:annotation>
|
|
13
|
+
</xs:element>
|
|
14
|
+
</xs:schema>
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
3
|
+
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
|
|
4
|
+
targetNamespace="http://www.sped.fazenda.gov.br/nfse"
|
|
5
|
+
xmlns="http://www.sped.fazenda.gov.br/nfse"
|
|
6
|
+
attributeFormDefault="unqualified"
|
|
7
|
+
elementFormDefault="qualified">
|
|
8
|
+
<xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/>
|
|
9
|
+
<xs:include schemaLocation="tiposEventos_v1.00.xsd"/>
|
|
10
|
+
<xs:element name="evento" type="TCEvento">
|
|
11
|
+
<xs:annotation>
|
|
12
|
+
<xs:documentation>Schema XML do Pedido de Registro de Eventos</xs:documentation>
|
|
13
|
+
</xs:annotation>
|
|
14
|
+
</xs:element>
|
|
15
|
+
</xs:schema>
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
3
|
+
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
|
|
4
|
+
targetNamespace="http://www.sped.fazenda.gov.br/nfse"
|
|
5
|
+
xmlns="http://www.sped.fazenda.gov.br/nfse"
|
|
6
|
+
attributeFormDefault="unqualified"
|
|
7
|
+
elementFormDefault="qualified">
|
|
8
|
+
<xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/>
|
|
9
|
+
<xs:include schemaLocation="tiposEventos_v1.00.xsd"/>
|
|
10
|
+
<xs:element name="pedRegEvento" type="TCPedRegEvt">
|
|
11
|
+
<xs:annotation>
|
|
12
|
+
<xs:documentation>Schema XML do Pedido de Registro de Eventos</xs:documentation>
|
|
13
|
+
</xs:annotation>
|
|
14
|
+
</xs:element>
|
|
15
|
+
</xs:schema>
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
3
|
+
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
|
|
4
|
+
targetNamespace="http://www.sped.fazenda.gov.br/nfse"
|
|
5
|
+
xmlns="http://www.sped.fazenda.gov.br/nfse"
|
|
6
|
+
attributeFormDefault="unqualified"
|
|
7
|
+
elementFormDefault="qualified">
|
|
8
|
+
<xs:import namespace="http://www.w3.org/2000/09/xmldsig#" schemaLocation="xmldsig-core-schema.xsd"/>
|
|
9
|
+
<xs:include schemaLocation="tiposComplexos_v1.00.xsd"/>
|
|
10
|
+
<xs:include schemaLocation="tiposSimples_v1.00.xsd"/>
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
<!--TIPO COMPLEXO PARA ENDEREÇO UPLOAD DE CONTRIBUINTES -->
|
|
14
|
+
<xs:complexType name="TCEnderContribuinteCNC">
|
|
15
|
+
<xs:sequence>
|
|
16
|
+
<xs:element name="CEP" type="TSCEP">
|
|
17
|
+
<xs:annotation>
|
|
18
|
+
<xs:documentation>Código de endereçamento postal do estabelecimento do contribuinte</xs:documentation>
|
|
19
|
+
</xs:annotation>
|
|
20
|
+
</xs:element>
|
|
21
|
+
<xs:element name="xLgr" type="TSLogradouro">
|
|
22
|
+
<xs:annotation>
|
|
23
|
+
<xs:documentation>Nome do logradouro</xs:documentation>
|
|
24
|
+
</xs:annotation>
|
|
25
|
+
</xs:element>
|
|
26
|
+
<xs:element name="nro" type="TSNumeroEndereco">
|
|
27
|
+
<xs:annotation>
|
|
28
|
+
<xs:documentation>Número do estabelecimento no logradouro informado</xs:documentation>
|
|
29
|
+
</xs:annotation>
|
|
30
|
+
</xs:element>
|
|
31
|
+
<xs:element name="xCpl" type="TSComplementoEndereco" minOccurs="0">
|
|
32
|
+
<xs:annotation>
|
|
33
|
+
<xs:documentation>Informação complementar para identificação do endereço do contribuinte</xs:documentation>
|
|
34
|
+
</xs:annotation>
|
|
35
|
+
</xs:element>
|
|
36
|
+
<xs:element name="xBairro" type="TSBairro">
|
|
37
|
+
<xs:annotation>
|
|
38
|
+
<xs:documentation>Nome do bairro</xs:documentation>
|
|
39
|
+
</xs:annotation>
|
|
40
|
+
</xs:element>
|
|
41
|
+
</xs:sequence>
|
|
42
|
+
</xs:complexType>
|
|
43
|
+
<!--TIPO COMPLEXO PARA UPLOAD DE CONTRIBUINTES DO CNC -->
|
|
44
|
+
<xs:complexType name="TCNC">
|
|
45
|
+
<xs:sequence>
|
|
46
|
+
<xs:element name="infCNC" type="TCInfCNC"/>
|
|
47
|
+
</xs:sequence>
|
|
48
|
+
<xs:attribute name="versao" type="TVerNFSe" use="required"/>
|
|
49
|
+
</xs:complexType>
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
<!--TIPO COMPLEXO PARA INFORMAÇÕES DO UPLOAD DE CONTRIBUINTES DO CNC -->
|
|
53
|
+
<xs:complexType name="TCInfCNC">
|
|
54
|
+
<xs:sequence>
|
|
55
|
+
<xs:element name="cMun" type="TSCodMunIBGE">
|
|
56
|
+
<xs:annotation>
|
|
57
|
+
<xs:documentation>Código do Municipio</xs:documentation>
|
|
58
|
+
</xs:annotation>
|
|
59
|
+
</xs:element>
|
|
60
|
+
<xs:element name="cnpjMun" type="TSCNPJ">
|
|
61
|
+
<xs:annotation>
|
|
62
|
+
<xs:documentation>CNPJ do Municipio</xs:documentation>
|
|
63
|
+
</xs:annotation>
|
|
64
|
+
</xs:element>
|
|
65
|
+
<xs:element name="CPFAgTrib" type="TSCPF">
|
|
66
|
+
<xs:annotation>
|
|
67
|
+
<xs:documentation>CPF do agente tributário</xs:documentation>
|
|
68
|
+
</xs:annotation>
|
|
69
|
+
</xs:element>
|
|
70
|
+
<xs:element name="tpAmb" type="TSTipoAmbiente">
|
|
71
|
+
<xs:annotation>
|
|
72
|
+
<xs:documentation>Identificação do Ambiente: 1 - Produção; 2 - Homologação</xs:documentation>
|
|
73
|
+
</xs:annotation>
|
|
74
|
+
</xs:element>
|
|
75
|
+
<xs:element name="verAplic" type="TSVerAplic">
|
|
76
|
+
<xs:annotation>
|
|
77
|
+
<xs:documentation>Versão do aplicativo que gerou Informações para cadastramento de novos contribuintes CNC</xs:documentation>
|
|
78
|
+
</xs:annotation>
|
|
79
|
+
</xs:element>
|
|
80
|
+
<xs:element name="infContrib" type="TCInfoContribuinteCNC">
|
|
81
|
+
<xs:annotation>
|
|
82
|
+
<xs:documentation>Grupo de informações cadastramento de novo contribuinte CNC</xs:documentation>
|
|
83
|
+
</xs:annotation>
|
|
84
|
+
</xs:element>
|
|
85
|
+
</xs:sequence>
|
|
86
|
+
<xs:attribute name="Id" type="TSIdCNC" use="required"/>
|
|
87
|
+
</xs:complexType>
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
<!--TIPO COMPLEXO PARA INFORMAÇÕES DE UMA PESSOA MANTIDA PELO CADASTRO DO CNC (CNPJ,CPF)-->
|
|
91
|
+
<xs:complexType name="TCInfoContribuinteCNC">
|
|
92
|
+
<xs:annotation>
|
|
93
|
+
<xs:documentation>Informações para cadastramento de novos contribuintes CNC </xs:documentation>
|
|
94
|
+
</xs:annotation>
|
|
95
|
+
<xs:sequence>
|
|
96
|
+
<xs:choice>
|
|
97
|
+
<xs:element name="CNPJ" type="TSCNPJ">
|
|
98
|
+
<xs:annotation>
|
|
99
|
+
<xs:documentation>Número do CNPJ do contribuinte.</xs:documentation>
|
|
100
|
+
</xs:annotation>
|
|
101
|
+
</xs:element>
|
|
102
|
+
<xs:element name="CPF" type="TSCPF">
|
|
103
|
+
<xs:annotation>
|
|
104
|
+
<xs:documentation>Número do CPF do contribuinte.</xs:documentation>
|
|
105
|
+
</xs:annotation>
|
|
106
|
+
</xs:element>
|
|
107
|
+
</xs:choice>
|
|
108
|
+
<xs:element name="IM" type="TSInscMun">
|
|
109
|
+
<xs:annotation>
|
|
110
|
+
<xs:documentation>Número da inscrição municipal</xs:documentation>
|
|
111
|
+
</xs:annotation>
|
|
112
|
+
</xs:element>
|
|
113
|
+
<xs:element name="dIM" type="TSDataCNC">
|
|
114
|
+
<xs:annotation>
|
|
115
|
+
<xs:documentation> Data da Inscrição Municipal: Dia, mês e ano (AAAAMMDD)</xs:documentation>
|
|
116
|
+
</xs:annotation>
|
|
117
|
+
</xs:element>
|
|
118
|
+
<xs:element name="xFantasia" type="TSNomeFantasia" minOccurs="0">
|
|
119
|
+
<xs:annotation>
|
|
120
|
+
<xs:documentation>Nome fantasia do contribuinte.</xs:documentation>
|
|
121
|
+
</xs:annotation>
|
|
122
|
+
</xs:element>
|
|
123
|
+
<xs:element name="ender" type="TCEnderContribuinteCNC" minOccurs="0">
|
|
124
|
+
<xs:annotation>
|
|
125
|
+
<xs:documentation>Grupo de informações do endereço do contribuinte do CNC</xs:documentation>
|
|
126
|
+
</xs:annotation>
|
|
127
|
+
</xs:element>
|
|
128
|
+
<xs:element name="fone" type="TSTelefone" minOccurs="0">
|
|
129
|
+
<xs:annotation>
|
|
130
|
+
<xs:documentation>
|
|
131
|
+
Número do telefone do prestador:
|
|
132
|
+
Preencher com o Código DDD + número do telefone.
|
|
133
|
+
Nas operações com exterior é permitido informar o código do país + código da localidade + número do telefone)
|
|
134
|
+
</xs:documentation>
|
|
135
|
+
</xs:annotation>
|
|
136
|
+
</xs:element>
|
|
137
|
+
<xs:element name="email" type="TSEmail" minOccurs="0">
|
|
138
|
+
<xs:annotation>
|
|
139
|
+
<xs:documentation>Endereço de e-mail para contato com o contribuinte</xs:documentation>
|
|
140
|
+
</xs:annotation>
|
|
141
|
+
</xs:element>
|
|
142
|
+
<xs:element name="dAutEmiss" type="TSDataCNC">
|
|
143
|
+
<xs:annotation>
|
|
144
|
+
<xs:documentation> Data de autorização de uso dos emissores públicos: Dia, mês e ano (AAAAMMDD)</xs:documentation>
|
|
145
|
+
</xs:annotation>
|
|
146
|
+
</xs:element>
|
|
147
|
+
<xs:element name="cStatEmiss" type="TSSituacaoEmissaoNFSE">
|
|
148
|
+
<xs:annotation>
|
|
149
|
+
<xs:documentation>
|
|
150
|
+
Situação Emissão NFS-e:
|
|
151
|
+
0 - Não Habilitado;
|
|
152
|
+
1 - Habilitado;
|
|
153
|
+
</xs:documentation>
|
|
154
|
+
</xs:annotation>
|
|
155
|
+
</xs:element>
|
|
156
|
+
<xs:element name="cSitCNC" type="TSSituacaoCadastroContribuinteCNC">
|
|
157
|
+
<xs:annotation>
|
|
158
|
+
<xs:documentation>
|
|
159
|
+
Identificação da situação do cadastro do contribuinte
|
|
160
|
+
</xs:documentation>
|
|
161
|
+
</xs:annotation>
|
|
162
|
+
</xs:element>
|
|
163
|
+
<xs:element name="xSitCadMun" type="TSSituacaoCadastroContribuinte" minOccurs="0">
|
|
164
|
+
<xs:annotation>
|
|
165
|
+
<xs:documentation>
|
|
166
|
+
Identificação da situação do cadastro do contribuinte
|
|
167
|
+
</xs:documentation>
|
|
168
|
+
</xs:annotation>
|
|
169
|
+
</xs:element>
|
|
170
|
+
<xs:element name="xMotivoSitCadMun" type="TSMotivoSituacaoCadastroContribuinte" minOccurs="0">
|
|
171
|
+
<xs:annotation>
|
|
172
|
+
<xs:documentation>
|
|
173
|
+
Motivo pelo qual o contribuinte se enquadra na situação informada
|
|
174
|
+
</xs:documentation>
|
|
175
|
+
</xs:annotation>
|
|
176
|
+
</xs:element>
|
|
177
|
+
</xs:sequence>
|
|
178
|
+
</xs:complexType>
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
</xs:schema>
|