@beliq/sdk 0.4.5 → 0.5.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/CHANGELOG.md CHANGED
@@ -4,6 +4,60 @@
4
4
  resolves 0.4.x and never reaches 0.5.0. Additive spec syncs ship as patches for
5
5
  that reason, and a minor is reserved for a change that needs consumers to opt in.
6
6
 
7
+ ## 0.5.0 - 2026-10-08
8
+
9
+ A minor, because code that reads a `parse()` result can stop compiling, and a
10
+ `^0.4.0` range does not reach a minor. Only the types of `parse()` change. No
11
+ method does.
12
+
13
+ - `ParseResult['invoice']` is the invoice `POST /v1/parse` declares for its
14
+ answer, where it was the invoice `generate()` takes. It lists the 13 fields
15
+ the parser returns, and only `lines` is always present:
16
+ `result.invoice.number` was a `string` and is a `string | undefined`. Below
17
+ the invoice nothing is required but the `id` of a `delivery.locationId`,
18
+ which is optional itself. The 35 fields of the generate invoice that parse
19
+ does not return, such as `allowances`, `paymentMeans` and `taxSummary`, are
20
+ gone from the type. A line lists 7 fields where it listed 20, a party 4
21
+ where it listed 9, and a party's address 5 where it listed 9.
22
+ - What stops compiling: a read of a field parse does not return, and
23
+ `result.invoice` passed where an `Invoice` is expected, or a party, a line,
24
+ an address or the delivery of it passed where that part of an `Invoice` is.
25
+ With `strictNullChecks` on, which `strict` includes, so does a field used
26
+ as always present, such as `result.invoice.seller.name` or a `string` taken
27
+ from `result.invoice.number`. Check for a field before reading it.
28
+ - The types follow the API, which changed first. Since 2026-10-07
29
+ `POST /v1/parse` returns a field only when the parser has a value for it,
30
+ and puts nothing in the place of an absent one. `parse()` hands the answer
31
+ on as it is, so an installed 0.4.6 gets the same answer, and its types still
32
+ say that nine fields of the invoice are always there, and more inside a
33
+ party, an address and a line.
34
+ https://beliq.eu/changelog/ has the API change under that date.
35
+ https://docs.beliq.eu/api-reference/parse/ says what an absent field means,
36
+ and when a `PARSE_VALUE_NOT_FOUND` warning in `result.warnings` names it.
37
+ - The vendored `openapi.json` is document `0.12.0` of the API, up from
38
+ `0.9.0`. Besides the parsed invoice one thing differs: the 14 nullable
39
+ fields of `GET /v1/me` and `GET /v1/rulesets` are spelled with
40
+ `nullable: true`, which is what OpenAPI 3.0 has for a nullable field, where
41
+ each had an `anyOf` with a `"type": "null"` arm. The type generated for each
42
+ of the 14 is the same, and two gain an `@enum` doc tag.
43
+
44
+ ## 0.4.6 - 2026-10-06
45
+
46
+ - The vendored `openapi.json` carries the four fields `POST /v1/parse` answers
47
+ with and the previous copy did not. `warnings` is always present, and empty
48
+ when the parser read every element that holds something: `PARSE_NOT_RETURNED`
49
+ lists what the document carries beyond the parsed `invoice`, by path and
50
+ count, and `PARSE_VALUE_NOT_FOUND` names a field no value could be read for.
51
+ `profileUrn` (BT-24) and `businessProcessId` (BT-23) carry what the document
52
+ states, and the latter is not the `businessProcessId` a `generate()` invoice
53
+ takes, which is an input limited to the three French Flux 2 codes.
54
+ `franceCtcDetected` is true when BT-23 is one of the French cadre de
55
+ facturation codes or BT-24 is the EXTENDED-CTC-FR URN, and absent otherwise.
56
+ - `ParseResult` picks all four up from the regenerated schema, and
57
+ `ParseWarning` and `ParseWarningCode` are exported beside it, the way
58
+ `ValidationIssue` is exported beside `ValidationResult`, so a caller can
59
+ annotate a warning without indexing into the result type.
60
+
7
61
  ## 0.4.5 - 2026-10-03
8
62
 
9
63
  - `LIVE_GENERATE_STANDARDS` carries all eight standards `POST /v1/generate`
package/dist/index.d.cts CHANGED
@@ -1087,173 +1087,48 @@ interface operations {
1087
1087
  data?: {
1088
1088
  format: "cii" | "ubl";
1089
1089
  profileDetected?: string;
1090
+ profileUrn?: string;
1091
+ businessProcessId?: string;
1092
+ franceCtcDetected?: boolean;
1090
1093
  invoice: {
1091
- number: string;
1092
- issueDate: string;
1093
- dueDate?: string;
1094
- vatPointDate?: string;
1095
- vatPointDateCode?: "3" | "35" | "432";
1096
- invoicingPeriod?: {
1097
- startDate?: string;
1098
- endDate?: string;
1099
- };
1100
- currencyCode: string;
1101
- taxCurrencyCode?: string;
1102
- taxTotalInAccountingCurrency?: number;
1094
+ number?: string;
1095
+ issueDate?: string;
1096
+ currencyCode?: string;
1103
1097
  documentType?: "invoice" | "creditnote";
1104
1098
  typeCode?: string;
1105
- precedingInvoiceReference?: {
1106
- id: string;
1107
- issueDate?: string;
1108
- };
1109
1099
  buyerReference?: string;
1110
- orderReference?: string;
1111
- salesOrderReference?: string;
1112
- contractReference?: string;
1113
- projectReference?: string;
1114
- receivingAdviceReference?: string;
1115
- despatchAdviceReference?: string;
1116
- tenderReference?: string;
1117
- invoicedObjectIdentifier?: {
1118
- id: string;
1119
- schemeId?: string;
1120
- };
1121
- buyerAccountingReference?: string;
1122
- supportingDocuments?: {
1123
- id: string;
1124
- description?: string;
1125
- externalLocation?: string;
1126
- attachment?: {
1127
- content: string;
1128
- mimeCode: string;
1129
- filename: string;
1130
- };
1131
- }[];
1132
- note?: string;
1133
- seller: {
1134
- name: string;
1100
+ seller?: {
1101
+ name?: string;
1135
1102
  vatId?: string;
1136
1103
  taxId?: string;
1137
- registrationId?: string;
1138
- /** Format: email */
1139
- email?: string;
1140
- phone?: string;
1141
- address: {
1104
+ address?: {
1142
1105
  street?: string;
1143
1106
  additionalStreet?: string;
1144
- city: string;
1145
- postalCode: string;
1146
- countryCode: string;
1147
- state?: string;
1148
- region?: string;
1149
- province?: string;
1150
- countrySubentity?: string;
1151
- };
1152
- contactName?: string;
1153
- peppol?: {
1154
- schemeId: string;
1155
- id: string;
1107
+ city?: string;
1108
+ postalCode?: string;
1109
+ countryCode?: string;
1156
1110
  };
1157
1111
  };
1158
- buyer: {
1159
- name: string;
1112
+ buyer?: {
1113
+ name?: string;
1160
1114
  vatId?: string;
1161
1115
  taxId?: string;
1162
- registrationId?: string;
1163
- /** Format: email */
1164
- email?: string;
1165
- phone?: string;
1166
- address: {
1167
- street?: string;
1168
- additionalStreet?: string;
1169
- city: string;
1170
- postalCode: string;
1171
- countryCode: string;
1172
- state?: string;
1173
- region?: string;
1174
- province?: string;
1175
- countrySubentity?: string;
1176
- };
1177
- contactName?: string;
1178
- peppol?: {
1179
- schemeId: string;
1180
- id: string;
1181
- };
1182
- };
1183
- payee?: {
1184
- name: string;
1185
- identifier?: {
1186
- id: string;
1187
- schemeId?: string;
1188
- };
1189
- registrationId?: string;
1190
- };
1191
- taxRepresentative?: {
1192
- name: string;
1193
- vatId: string;
1194
- address: {
1116
+ address?: {
1195
1117
  street?: string;
1196
1118
  additionalStreet?: string;
1197
1119
  city?: string;
1198
1120
  postalCode?: string;
1199
- countryCode: string;
1200
- countrySubentity?: string;
1121
+ countryCode?: string;
1201
1122
  };
1202
1123
  };
1203
1124
  lines: {
1204
- description: string;
1205
- quantity: number;
1206
- unitCode: string;
1207
- unitPrice: number;
1208
- lineTotal: number;
1209
- vatRate: number;
1210
- vatCategoryCode: string;
1211
- itemId?: string;
1212
- buyerItemId?: string;
1213
- grossPrice?: number;
1214
- priceDiscount?: number;
1215
- priceBaseQuantity?: number;
1216
- standardItemId?: {
1217
- id: string;
1218
- schemeId: string;
1219
- };
1220
- classifications?: {
1221
- code: string;
1222
- listId: string;
1223
- listVersionId?: string;
1224
- }[];
1225
- originCountryCode?: string;
1226
- attributes?: {
1227
- name: string;
1228
- value: string;
1229
- }[];
1230
- allowances?: {
1231
- amount: number;
1232
- baseAmount?: number;
1233
- percentage?: number;
1234
- reason?: string;
1235
- reasonCode?: string;
1236
- }[];
1237
- charges?: {
1238
- amount: number;
1239
- baseAmount?: number;
1240
- percentage?: number;
1241
- reason?: string;
1242
- reasonCode?: string;
1243
- }[];
1244
- invoicingPeriod?: {
1245
- startDate?: string;
1246
- endDate?: string;
1247
- };
1248
- subLines?: components["schemas"]["InvoiceLine"][];
1249
- }[];
1250
- taxSummary?: {
1251
- vatCategoryCode: string;
1252
- vatRate: number;
1253
- taxableAmount: number;
1254
- taxAmount: number;
1255
- exemptionReasonText?: string;
1256
- exemptionReasonCode?: string;
1125
+ description?: string;
1126
+ quantity?: number;
1127
+ unitCode?: string;
1128
+ unitPrice?: number;
1129
+ lineTotal?: number;
1130
+ vatRate?: number;
1131
+ vatCategoryCode?: string;
1257
1132
  }[];
1258
1133
  delivery?: {
1259
1134
  name?: string;
@@ -1267,95 +1142,24 @@ interface operations {
1267
1142
  additionalStreet?: string;
1268
1143
  city?: string;
1269
1144
  postalCode?: string;
1270
- countryCode: string;
1271
1145
  countrySubentity?: string;
1146
+ countryCode?: string;
1272
1147
  };
1273
1148
  };
1274
- paymentMeans?: {
1275
- typeCode: string;
1276
- iban?: string;
1277
- bic?: string;
1278
- bankName?: string;
1279
- paymentReference?: string;
1280
- information?: string;
1281
- mandateReference?: string;
1282
- creditorId?: string;
1283
- debitedAccountId?: string;
1284
- };
1285
- paymentTerms?: string;
1286
- allowances?: {
1287
- amount: number;
1288
- baseAmount?: number;
1289
- percentage?: number;
1290
- reason?: string;
1291
- reasonCode?: string;
1292
- vatCategoryCode: string;
1293
- vatRate?: number;
1294
- }[];
1295
- charges?: {
1296
- amount: number;
1297
- baseAmount?: number;
1298
- percentage?: number;
1299
- reason?: string;
1300
- reasonCode?: string;
1301
- vatCategoryCode: string;
1302
- vatRate?: number;
1303
- }[];
1304
- totalNetAmount: number;
1305
- totalTaxAmount: number;
1306
- totalGrossAmount: number;
1307
- paidAmount?: number;
1308
- roundingAmount?: number;
1309
- franceCtc?: boolean;
1310
- businessProcessId?: "S8" | "B8" | "M8";
1311
- italy?: {
1312
- codiceDestinatario?: string;
1313
- regimeFiscale?: string;
1314
- progressivoInvio?: string;
1315
- idTrasmittente?: {
1316
- country: string;
1317
- id: string;
1318
- };
1319
- tipoDocumento?: string;
1320
- condizioniPagamento?: string;
1321
- modalitaPagamento?: string;
1322
- esigibilitaIVA?: string;
1323
- causale?: string[];
1324
- };
1325
- romania?: Record<string, never>;
1326
- netherlands?: Record<string, never>;
1327
- spain?: {
1328
- modality?: "I" | "L";
1329
- invoiceIssuerType?: "EM" | "RE" | "TE";
1330
- invoiceDocumentType?: string;
1331
- invoiceClass?: string;
1332
- taxTypeCode?: string;
1333
- languageName?: string;
1334
- batchIdentifier?: string;
1335
- seller?: {
1336
- personTypeCode?: "J" | "F";
1337
- residenceTypeCode?: "R" | "U" | "E";
1338
- };
1339
- buyer?: {
1340
- personTypeCode?: "J" | "F";
1341
- residenceTypeCode?: "R" | "U" | "E";
1342
- };
1343
- };
1344
- slovenia?: Record<string, never>;
1345
- poland?: {
1346
- adnotacje?: {
1347
- P_16?: "1" | "2";
1348
- P_17?: "1" | "2";
1349
- P_18?: "1" | "2";
1350
- P_18A?: "1" | "2";
1351
- P_23?: "1" | "2";
1352
- };
1353
- dataWytworzenia?: string;
1354
- placeOfIssue?: string;
1355
- jst?: "1" | "2";
1356
- gv?: "1" | "2";
1357
- };
1149
+ totalNetAmount?: number;
1150
+ totalTaxAmount?: number;
1151
+ totalGrossAmount?: number;
1358
1152
  };
1153
+ warnings: {
1154
+ code: "PARSE_NOT_RETURNED" | "PARSE_VALUE_NOT_FOUND";
1155
+ message: string;
1156
+ field?: string;
1157
+ terms?: string[];
1158
+ elements?: {
1159
+ path: string;
1160
+ count: number;
1161
+ }[];
1162
+ }[];
1359
1163
  };
1360
1164
  error?: {
1361
1165
  code: "VALIDATION_ERROR" | "INVALID_INVOICE" | "PROFILE_STANDARD_MISMATCH" | "DOCUMENT_TYPE_STANDARD_MISMATCH" | "PARSE_FAILED" | "AUTHENTICATION_REQUIRED" | "INVALID_API_KEY" | "INSUFFICIENT_ROLE" | "QUOTA_EXCEEDED" | "RATE_LIMITED" | "ACCOUNT_THROTTLED" | "ENGINE_UNAVAILABLE" | "INTERNAL_ERROR" | "NOT_FOUND" | "CONVERSION_UNSUPPORTED_PAIR" | "CONVERSION_LOSSY_FAILCLOSED" | "CONVERSION_TOOL_UNAVAILABLE" | "CONVERSION_TOOL_ERROR" | "PDF_TEMPLATE_AUTH_REQUIRED" | "PDF_TEMPLATE_NOT_FOUND" | "PDF_TEMPLATE_INVALID" | "TRANSMISSION_DISABLED" | "TRANSMISSION_NO_PROVIDER" | "IDEMPOTENCY_KEY_REUSED" | "INVALID_IDEMPOTENCY_KEY" | "SENDER_NOT_REGISTERED" | "CONTENT_ALREADY_SENT" | "INBOX_UNKNOWN_PROVIDER" | "INBOX_VERIFICATION_FAILED" | "INBOX_SIGNATURE_EXPIRED" | "ENROLLMENT_MODE_UNSUPPORTED" | "ENROLLMENT_REFUSED" | "RECIPIENT_NOT_ROUTABLE" | "SENDER_COUNTRY_MISSING" | "DOCUMENT_PARTY_MISMATCH" | "FRENCH_DOMESTIC_FLOW" | "FRANCE_CTC_BLOCKING_FINDINGS" | "FRANCE_CTC_NOT_JUDGED" | "FRANCE_INVOICE_NUMBER_BURNED" | "UNSUPPORTED_SYNTAX" | "MALFORMED_DOCUMENT" | "EMPTY_DOCUMENT" | "MISSING_CUSTOMIZATION_ID" | "MISSING_PROCESS_ID";
@@ -1811,6 +1615,7 @@ interface operations {
1811
1615
  rulesetVersion: string;
1812
1616
  rulesetArtefact: string;
1813
1617
  versionKey: string;
1618
+ /** @enum {string|null} */
1814
1619
  verificationTier: "conformance-verified" | "builder-round-trip" | "reconstructed-rules" | "xsd-structural" | null;
1815
1620
  rulesProvenance: "authority-conformance" | "authority-artifact" | "community" | "beliq-authored" | "none";
1816
1621
  verificationBadge: "authority-verified" | "independently-rule-checked" | "structure-checked";
@@ -1837,7 +1642,10 @@ interface operations {
1837
1642
  servingVersion: string;
1838
1643
  /** @description The version `Beliq-Ruleset: previous` resolves to for this artefact today, or null when the channel falls back to `latest` for it. Pin it exactly as `Beliq-Ruleset: <versionKey>:<previousVersion>` to reach it regardless. */
1839
1644
  previousVersion: string | null;
1840
- /** @description Why `previous` reaches nothing for this artefact; null exactly when `previousVersion` is set. `sunset` = every retained version is past its `retainedUntil`, so not even an exact pin resolves. `notice-period` = the only retained version is the one standing in for `latest` until a scheduled bump takes effect, so there is nothing behind it yet. `superseded` = the authority made the successor mandatory, so Beliq will not choose the older ruleset on your behalf; an exact pin still reaches it until `retainedUntil`. */
1645
+ /**
1646
+ * @description Why `previous` reaches nothing for this artefact; null exactly when `previousVersion` is set. `sunset` = every retained version is past its `retainedUntil`, so not even an exact pin resolves. `notice-period` = the only retained version is the one standing in for `latest` until a scheduled bump takes effect, so there is nothing behind it yet. `superseded` = the authority made the successor mandatory, so Beliq will not choose the older ruleset on your behalf; an exact pin still reaches it until `retainedUntil`.
1647
+ * @enum {string|null}
1648
+ */
1841
1649
  fallbackReason: "sunset" | "notice-period" | "superseded" | null;
1842
1650
  }[];
1843
1651
  }[];
@@ -1939,8 +1747,16 @@ type ValidationResult = Json200Data<'validateInvoice'>;
1939
1747
  type ValidationIssue = ValidationResult['errors'][number];
1940
1748
  type Severity = ValidationIssue['severity'];
1941
1749
  type ValidationFormat = ValidationResult['format'];
1942
- /** Structured invoice extracted from a document (POST /v1/parse). */
1750
+ /**
1751
+ * What POST /v1/parse read from a document. Of `invoice`, only `lines` is
1752
+ * always present. Every other field is left out when the answer holds no value
1753
+ * for it, so check for a field before reading it.
1754
+ * https://docs.beliq.eu/api-reference/parse/ says what an absent field means.
1755
+ */
1943
1756
  type ParseResult = Json200Data<'parseInvoice'>;
1757
+ /** One warning about what the document holds and the parsed invoice does not. */
1758
+ type ParseWarning = ParseResult['warnings'][number];
1759
+ type ParseWarningCode = ParseWarning['code'];
1944
1760
  /** The JSON-mode generate envelope (Accept: application/json): the seal. */
1945
1761
  type GenerateResponse = Json200Data<'generateInvoice'>;
1946
1762
  /** One row of the ruleset fingerprint (key, version, file hash). */
@@ -2104,4 +1920,4 @@ declare class BeliqApiError extends Error {
2104
1920
  });
2105
1921
  }
2106
1922
 
2107
- export { type AccountInfo, type ApiError, type ApiErrorCode, Beliq, BeliqApiError, type BeliqOptions, type ConvertMeta, type ConvertOptions, type ConvertResult, type ConvertSourceFormat, type ConvertTargetFormat, DocumentInput, type DocumentOptions, type FacturxProfile, type GenerateBody, type GenerateInput, type GenerateMeta, type GenerateProfile, type GenerateResponse, type GenerateResult, type Invoice, type ParseFormat, type ParseOptions, type ParseResult, type RulesetArtifact, type Severity, type Standard, type ValidateFormat, type ValidateOptions, type ValidationFormat, type ValidationIssue, type ValidationResult };
1923
+ export { type AccountInfo, type ApiError, type ApiErrorCode, Beliq, BeliqApiError, type BeliqOptions, type ConvertMeta, type ConvertOptions, type ConvertResult, type ConvertSourceFormat, type ConvertTargetFormat, DocumentInput, type DocumentOptions, type FacturxProfile, type GenerateBody, type GenerateInput, type GenerateMeta, type GenerateProfile, type GenerateResponse, type GenerateResult, type Invoice, type ParseFormat, type ParseOptions, type ParseResult, type ParseWarning, type ParseWarningCode, type RulesetArtifact, type Severity, type Standard, type ValidateFormat, type ValidateOptions, type ValidationFormat, type ValidationIssue, type ValidationResult };
package/dist/index.d.ts CHANGED
@@ -1087,173 +1087,48 @@ interface operations {
1087
1087
  data?: {
1088
1088
  format: "cii" | "ubl";
1089
1089
  profileDetected?: string;
1090
+ profileUrn?: string;
1091
+ businessProcessId?: string;
1092
+ franceCtcDetected?: boolean;
1090
1093
  invoice: {
1091
- number: string;
1092
- issueDate: string;
1093
- dueDate?: string;
1094
- vatPointDate?: string;
1095
- vatPointDateCode?: "3" | "35" | "432";
1096
- invoicingPeriod?: {
1097
- startDate?: string;
1098
- endDate?: string;
1099
- };
1100
- currencyCode: string;
1101
- taxCurrencyCode?: string;
1102
- taxTotalInAccountingCurrency?: number;
1094
+ number?: string;
1095
+ issueDate?: string;
1096
+ currencyCode?: string;
1103
1097
  documentType?: "invoice" | "creditnote";
1104
1098
  typeCode?: string;
1105
- precedingInvoiceReference?: {
1106
- id: string;
1107
- issueDate?: string;
1108
- };
1109
1099
  buyerReference?: string;
1110
- orderReference?: string;
1111
- salesOrderReference?: string;
1112
- contractReference?: string;
1113
- projectReference?: string;
1114
- receivingAdviceReference?: string;
1115
- despatchAdviceReference?: string;
1116
- tenderReference?: string;
1117
- invoicedObjectIdentifier?: {
1118
- id: string;
1119
- schemeId?: string;
1120
- };
1121
- buyerAccountingReference?: string;
1122
- supportingDocuments?: {
1123
- id: string;
1124
- description?: string;
1125
- externalLocation?: string;
1126
- attachment?: {
1127
- content: string;
1128
- mimeCode: string;
1129
- filename: string;
1130
- };
1131
- }[];
1132
- note?: string;
1133
- seller: {
1134
- name: string;
1100
+ seller?: {
1101
+ name?: string;
1135
1102
  vatId?: string;
1136
1103
  taxId?: string;
1137
- registrationId?: string;
1138
- /** Format: email */
1139
- email?: string;
1140
- phone?: string;
1141
- address: {
1104
+ address?: {
1142
1105
  street?: string;
1143
1106
  additionalStreet?: string;
1144
- city: string;
1145
- postalCode: string;
1146
- countryCode: string;
1147
- state?: string;
1148
- region?: string;
1149
- province?: string;
1150
- countrySubentity?: string;
1151
- };
1152
- contactName?: string;
1153
- peppol?: {
1154
- schemeId: string;
1155
- id: string;
1107
+ city?: string;
1108
+ postalCode?: string;
1109
+ countryCode?: string;
1156
1110
  };
1157
1111
  };
1158
- buyer: {
1159
- name: string;
1112
+ buyer?: {
1113
+ name?: string;
1160
1114
  vatId?: string;
1161
1115
  taxId?: string;
1162
- registrationId?: string;
1163
- /** Format: email */
1164
- email?: string;
1165
- phone?: string;
1166
- address: {
1167
- street?: string;
1168
- additionalStreet?: string;
1169
- city: string;
1170
- postalCode: string;
1171
- countryCode: string;
1172
- state?: string;
1173
- region?: string;
1174
- province?: string;
1175
- countrySubentity?: string;
1176
- };
1177
- contactName?: string;
1178
- peppol?: {
1179
- schemeId: string;
1180
- id: string;
1181
- };
1182
- };
1183
- payee?: {
1184
- name: string;
1185
- identifier?: {
1186
- id: string;
1187
- schemeId?: string;
1188
- };
1189
- registrationId?: string;
1190
- };
1191
- taxRepresentative?: {
1192
- name: string;
1193
- vatId: string;
1194
- address: {
1116
+ address?: {
1195
1117
  street?: string;
1196
1118
  additionalStreet?: string;
1197
1119
  city?: string;
1198
1120
  postalCode?: string;
1199
- countryCode: string;
1200
- countrySubentity?: string;
1121
+ countryCode?: string;
1201
1122
  };
1202
1123
  };
1203
1124
  lines: {
1204
- description: string;
1205
- quantity: number;
1206
- unitCode: string;
1207
- unitPrice: number;
1208
- lineTotal: number;
1209
- vatRate: number;
1210
- vatCategoryCode: string;
1211
- itemId?: string;
1212
- buyerItemId?: string;
1213
- grossPrice?: number;
1214
- priceDiscount?: number;
1215
- priceBaseQuantity?: number;
1216
- standardItemId?: {
1217
- id: string;
1218
- schemeId: string;
1219
- };
1220
- classifications?: {
1221
- code: string;
1222
- listId: string;
1223
- listVersionId?: string;
1224
- }[];
1225
- originCountryCode?: string;
1226
- attributes?: {
1227
- name: string;
1228
- value: string;
1229
- }[];
1230
- allowances?: {
1231
- amount: number;
1232
- baseAmount?: number;
1233
- percentage?: number;
1234
- reason?: string;
1235
- reasonCode?: string;
1236
- }[];
1237
- charges?: {
1238
- amount: number;
1239
- baseAmount?: number;
1240
- percentage?: number;
1241
- reason?: string;
1242
- reasonCode?: string;
1243
- }[];
1244
- invoicingPeriod?: {
1245
- startDate?: string;
1246
- endDate?: string;
1247
- };
1248
- subLines?: components["schemas"]["InvoiceLine"][];
1249
- }[];
1250
- taxSummary?: {
1251
- vatCategoryCode: string;
1252
- vatRate: number;
1253
- taxableAmount: number;
1254
- taxAmount: number;
1255
- exemptionReasonText?: string;
1256
- exemptionReasonCode?: string;
1125
+ description?: string;
1126
+ quantity?: number;
1127
+ unitCode?: string;
1128
+ unitPrice?: number;
1129
+ lineTotal?: number;
1130
+ vatRate?: number;
1131
+ vatCategoryCode?: string;
1257
1132
  }[];
1258
1133
  delivery?: {
1259
1134
  name?: string;
@@ -1267,95 +1142,24 @@ interface operations {
1267
1142
  additionalStreet?: string;
1268
1143
  city?: string;
1269
1144
  postalCode?: string;
1270
- countryCode: string;
1271
1145
  countrySubentity?: string;
1146
+ countryCode?: string;
1272
1147
  };
1273
1148
  };
1274
- paymentMeans?: {
1275
- typeCode: string;
1276
- iban?: string;
1277
- bic?: string;
1278
- bankName?: string;
1279
- paymentReference?: string;
1280
- information?: string;
1281
- mandateReference?: string;
1282
- creditorId?: string;
1283
- debitedAccountId?: string;
1284
- };
1285
- paymentTerms?: string;
1286
- allowances?: {
1287
- amount: number;
1288
- baseAmount?: number;
1289
- percentage?: number;
1290
- reason?: string;
1291
- reasonCode?: string;
1292
- vatCategoryCode: string;
1293
- vatRate?: number;
1294
- }[];
1295
- charges?: {
1296
- amount: number;
1297
- baseAmount?: number;
1298
- percentage?: number;
1299
- reason?: string;
1300
- reasonCode?: string;
1301
- vatCategoryCode: string;
1302
- vatRate?: number;
1303
- }[];
1304
- totalNetAmount: number;
1305
- totalTaxAmount: number;
1306
- totalGrossAmount: number;
1307
- paidAmount?: number;
1308
- roundingAmount?: number;
1309
- franceCtc?: boolean;
1310
- businessProcessId?: "S8" | "B8" | "M8";
1311
- italy?: {
1312
- codiceDestinatario?: string;
1313
- regimeFiscale?: string;
1314
- progressivoInvio?: string;
1315
- idTrasmittente?: {
1316
- country: string;
1317
- id: string;
1318
- };
1319
- tipoDocumento?: string;
1320
- condizioniPagamento?: string;
1321
- modalitaPagamento?: string;
1322
- esigibilitaIVA?: string;
1323
- causale?: string[];
1324
- };
1325
- romania?: Record<string, never>;
1326
- netherlands?: Record<string, never>;
1327
- spain?: {
1328
- modality?: "I" | "L";
1329
- invoiceIssuerType?: "EM" | "RE" | "TE";
1330
- invoiceDocumentType?: string;
1331
- invoiceClass?: string;
1332
- taxTypeCode?: string;
1333
- languageName?: string;
1334
- batchIdentifier?: string;
1335
- seller?: {
1336
- personTypeCode?: "J" | "F";
1337
- residenceTypeCode?: "R" | "U" | "E";
1338
- };
1339
- buyer?: {
1340
- personTypeCode?: "J" | "F";
1341
- residenceTypeCode?: "R" | "U" | "E";
1342
- };
1343
- };
1344
- slovenia?: Record<string, never>;
1345
- poland?: {
1346
- adnotacje?: {
1347
- P_16?: "1" | "2";
1348
- P_17?: "1" | "2";
1349
- P_18?: "1" | "2";
1350
- P_18A?: "1" | "2";
1351
- P_23?: "1" | "2";
1352
- };
1353
- dataWytworzenia?: string;
1354
- placeOfIssue?: string;
1355
- jst?: "1" | "2";
1356
- gv?: "1" | "2";
1357
- };
1149
+ totalNetAmount?: number;
1150
+ totalTaxAmount?: number;
1151
+ totalGrossAmount?: number;
1358
1152
  };
1153
+ warnings: {
1154
+ code: "PARSE_NOT_RETURNED" | "PARSE_VALUE_NOT_FOUND";
1155
+ message: string;
1156
+ field?: string;
1157
+ terms?: string[];
1158
+ elements?: {
1159
+ path: string;
1160
+ count: number;
1161
+ }[];
1162
+ }[];
1359
1163
  };
1360
1164
  error?: {
1361
1165
  code: "VALIDATION_ERROR" | "INVALID_INVOICE" | "PROFILE_STANDARD_MISMATCH" | "DOCUMENT_TYPE_STANDARD_MISMATCH" | "PARSE_FAILED" | "AUTHENTICATION_REQUIRED" | "INVALID_API_KEY" | "INSUFFICIENT_ROLE" | "QUOTA_EXCEEDED" | "RATE_LIMITED" | "ACCOUNT_THROTTLED" | "ENGINE_UNAVAILABLE" | "INTERNAL_ERROR" | "NOT_FOUND" | "CONVERSION_UNSUPPORTED_PAIR" | "CONVERSION_LOSSY_FAILCLOSED" | "CONVERSION_TOOL_UNAVAILABLE" | "CONVERSION_TOOL_ERROR" | "PDF_TEMPLATE_AUTH_REQUIRED" | "PDF_TEMPLATE_NOT_FOUND" | "PDF_TEMPLATE_INVALID" | "TRANSMISSION_DISABLED" | "TRANSMISSION_NO_PROVIDER" | "IDEMPOTENCY_KEY_REUSED" | "INVALID_IDEMPOTENCY_KEY" | "SENDER_NOT_REGISTERED" | "CONTENT_ALREADY_SENT" | "INBOX_UNKNOWN_PROVIDER" | "INBOX_VERIFICATION_FAILED" | "INBOX_SIGNATURE_EXPIRED" | "ENROLLMENT_MODE_UNSUPPORTED" | "ENROLLMENT_REFUSED" | "RECIPIENT_NOT_ROUTABLE" | "SENDER_COUNTRY_MISSING" | "DOCUMENT_PARTY_MISMATCH" | "FRENCH_DOMESTIC_FLOW" | "FRANCE_CTC_BLOCKING_FINDINGS" | "FRANCE_CTC_NOT_JUDGED" | "FRANCE_INVOICE_NUMBER_BURNED" | "UNSUPPORTED_SYNTAX" | "MALFORMED_DOCUMENT" | "EMPTY_DOCUMENT" | "MISSING_CUSTOMIZATION_ID" | "MISSING_PROCESS_ID";
@@ -1811,6 +1615,7 @@ interface operations {
1811
1615
  rulesetVersion: string;
1812
1616
  rulesetArtefact: string;
1813
1617
  versionKey: string;
1618
+ /** @enum {string|null} */
1814
1619
  verificationTier: "conformance-verified" | "builder-round-trip" | "reconstructed-rules" | "xsd-structural" | null;
1815
1620
  rulesProvenance: "authority-conformance" | "authority-artifact" | "community" | "beliq-authored" | "none";
1816
1621
  verificationBadge: "authority-verified" | "independently-rule-checked" | "structure-checked";
@@ -1837,7 +1642,10 @@ interface operations {
1837
1642
  servingVersion: string;
1838
1643
  /** @description The version `Beliq-Ruleset: previous` resolves to for this artefact today, or null when the channel falls back to `latest` for it. Pin it exactly as `Beliq-Ruleset: <versionKey>:<previousVersion>` to reach it regardless. */
1839
1644
  previousVersion: string | null;
1840
- /** @description Why `previous` reaches nothing for this artefact; null exactly when `previousVersion` is set. `sunset` = every retained version is past its `retainedUntil`, so not even an exact pin resolves. `notice-period` = the only retained version is the one standing in for `latest` until a scheduled bump takes effect, so there is nothing behind it yet. `superseded` = the authority made the successor mandatory, so Beliq will not choose the older ruleset on your behalf; an exact pin still reaches it until `retainedUntil`. */
1645
+ /**
1646
+ * @description Why `previous` reaches nothing for this artefact; null exactly when `previousVersion` is set. `sunset` = every retained version is past its `retainedUntil`, so not even an exact pin resolves. `notice-period` = the only retained version is the one standing in for `latest` until a scheduled bump takes effect, so there is nothing behind it yet. `superseded` = the authority made the successor mandatory, so Beliq will not choose the older ruleset on your behalf; an exact pin still reaches it until `retainedUntil`.
1647
+ * @enum {string|null}
1648
+ */
1841
1649
  fallbackReason: "sunset" | "notice-period" | "superseded" | null;
1842
1650
  }[];
1843
1651
  }[];
@@ -1939,8 +1747,16 @@ type ValidationResult = Json200Data<'validateInvoice'>;
1939
1747
  type ValidationIssue = ValidationResult['errors'][number];
1940
1748
  type Severity = ValidationIssue['severity'];
1941
1749
  type ValidationFormat = ValidationResult['format'];
1942
- /** Structured invoice extracted from a document (POST /v1/parse). */
1750
+ /**
1751
+ * What POST /v1/parse read from a document. Of `invoice`, only `lines` is
1752
+ * always present. Every other field is left out when the answer holds no value
1753
+ * for it, so check for a field before reading it.
1754
+ * https://docs.beliq.eu/api-reference/parse/ says what an absent field means.
1755
+ */
1943
1756
  type ParseResult = Json200Data<'parseInvoice'>;
1757
+ /** One warning about what the document holds and the parsed invoice does not. */
1758
+ type ParseWarning = ParseResult['warnings'][number];
1759
+ type ParseWarningCode = ParseWarning['code'];
1944
1760
  /** The JSON-mode generate envelope (Accept: application/json): the seal. */
1945
1761
  type GenerateResponse = Json200Data<'generateInvoice'>;
1946
1762
  /** One row of the ruleset fingerprint (key, version, file hash). */
@@ -2104,4 +1920,4 @@ declare class BeliqApiError extends Error {
2104
1920
  });
2105
1921
  }
2106
1922
 
2107
- export { type AccountInfo, type ApiError, type ApiErrorCode, Beliq, BeliqApiError, type BeliqOptions, type ConvertMeta, type ConvertOptions, type ConvertResult, type ConvertSourceFormat, type ConvertTargetFormat, DocumentInput, type DocumentOptions, type FacturxProfile, type GenerateBody, type GenerateInput, type GenerateMeta, type GenerateProfile, type GenerateResponse, type GenerateResult, type Invoice, type ParseFormat, type ParseOptions, type ParseResult, type RulesetArtifact, type Severity, type Standard, type ValidateFormat, type ValidateOptions, type ValidationFormat, type ValidationIssue, type ValidationResult };
1923
+ export { type AccountInfo, type ApiError, type ApiErrorCode, Beliq, BeliqApiError, type BeliqOptions, type ConvertMeta, type ConvertOptions, type ConvertResult, type ConvertSourceFormat, type ConvertTargetFormat, DocumentInput, type DocumentOptions, type FacturxProfile, type GenerateBody, type GenerateInput, type GenerateMeta, type GenerateProfile, type GenerateResponse, type GenerateResult, type Invoice, type ParseFormat, type ParseOptions, type ParseResult, type ParseWarning, type ParseWarningCode, type RulesetArtifact, type Severity, type Standard, type ValidateFormat, type ValidateOptions, type ValidationFormat, type ValidationIssue, type ValidationResult };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@beliq/sdk",
3
- "version": "0.4.5",
3
+ "version": "0.5.0",
4
4
  "description": "Official beliq SDK: generate, validate, parse, and convert EU-compliant e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) against authority-pinned, drift-checked rules.",
5
5
  "keywords": [
6
6
  "beliq",
@@ -69,8 +69,8 @@
69
69
  "clean": "rm -rf dist",
70
70
  "build": "npm run clean && tsup",
71
71
  "typecheck": "tsc --noEmit",
72
- "lint": "eslint src test",
73
- "lint:fix": "eslint src test --fix",
72
+ "lint": "eslint src test scripts",
73
+ "lint:fix": "eslint src test scripts --fix",
74
74
  "scrub:check": "bash scripts/scrub-check.sh",
75
75
  "sync:spec": "node scripts/sync-spec.mjs",
76
76
  "gen:types": "node scripts/gen-types.mjs",