@blob-solutions/vcr-am-sdk 0.16.0 → 0.18.0

package/lib/index.d.cts

@@ -4,6 +4,20 @@ type RequestOptions = {
     signal?: AbortSignal;
     /** Override per-request timeout in ms. `null` disables the timeout. */
     timeoutMs?: number | null;
+    /**
+     * Opt-in replay protection for the document-creating endpoints
+     * (`registerSale`, `registerSaleRefund`, `registerPrepayment`,
+     * `registerPrepaymentRefund`). Retrying a request that carries the same key
+     * returns the original response instead of registering a second document.
+     *
+     * Strongly recommended. Without it, retrying after a 502 produces a
+     * duplicate fiscal receipt, which can only be undone by issuing a refund.
+     *
+     * The SDK deliberately does not generate this for you: the value must stay
+     * **stable across your retries**, so it has to come from something you own —
+     * typically your order id (`order-4821`) — not from a fresh UUID per call.
+     */
+    idempotencyKey?: string;
 };
 
 declare const registerSaleResponseSchema: z.ZodObject<{
@@ -191,9 +205,36 @@ declare const offerListResponseSchema: z.ZodArray<z.ZodObject<{
     archivedAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
 }, z.core.$strip>>;
+/**
+ * Where a document stands with the tax authority, derived from its submission
+ * log. This is the field to poll after a 502 that carried a `pending` handle.
+ *
+ * - `accepted` — SRC registered it. Terminal and final; a fiscal receipt exists.
+ * - `rejected` — SRC refused the document itself. Terminal: resending the same
+ *   payload gets the same refusal, so something has to change.
+ * - `pending` — no answer from SRC yet. VCR owns the retry; do NOT resend.
+ * - `needs_decision` — the automatic retry window (24h) closed without an
+ *   answer. Still not resendable blind — check the document before acting.
+ *
+ * A plain enum rather than a boolean because "not accepted" spans three very
+ * different situations, and the one that matters most (`pending`) is the one
+ * that looks like failure but must not be treated as one.
+ */
+declare const srcStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    accepted: "accepted";
+    rejected: "rejected";
+    needs_decision: "needs_decision";
+}>;
 declare const saleDetailResponseSchema: z.ZodObject<{
     id: z.ZodNumber;
     createdAt: z.ZodString;
+    srcStatus: z.ZodEnum<{
+        pending: "pending";
+        accepted: "accepted";
+        rejected: "rejected";
+        needs_decision: "needs_decision";
+    }>;
     buyerTin: z.ZodNullable<z.ZodString>;
     comment: z.ZodNullable<z.ZodString>;
     cashAmount: z.ZodNumber;
@@ -337,6 +378,12 @@ declare const prepaymentStateSchema: z.ZodEnum<{
 declare const prepaymentDetailResponseSchema: z.ZodObject<{
     id: z.ZodNumber;
     createdAt: z.ZodString;
+    srcStatus: z.ZodEnum<{
+        pending: "pending";
+        accepted: "accepted";
+        rejected: "rejected";
+        needs_decision: "needs_decision";
+    }>;
     buyerTin: z.ZodNullable<z.ZodString>;
     cashAmount: z.ZodNumber;
     nonCashAmount: z.ZodNumber;
@@ -437,6 +484,7 @@ type CashierListItem = z.infer<typeof cashierListItemSchema>;
 type ClassifierSearchItem = z.infer<typeof classifierSearchItemSchema>;
 type Whoami = z.infer<typeof whoamiResponseSchema>;
 type OfferListItem = z.infer<typeof offerListItemSchema>;
+type SrcStatus = z.infer<typeof srcStatusSchema>;
 type SaleDetail = z.infer<typeof saleDetailResponseSchema>;
 type PrepaymentDetail = z.infer<typeof prepaymentDetailResponseSchema>;
 type PrepaymentListItem = z.infer<typeof prepaymentListItemSchema>;
@@ -536,7 +584,24 @@ type NewOffer = {
 type Offer = NewOffer | ExistingOfferByExternalId | ExistingOfferById;
 type SaleItem = {
     offer: Offer;
-    department: DepartmentInput;
+    /**
+     * Department to book this line under. **Omit it** unless you have a reason
+     * not to: the line then inherits the department of the offer it references
+     * (`defaultDepartment`), which for an inline new offer is the one you just
+     * declared on it.
+     *
+     * The department — not the offer — decides the tax regime printed on the
+     * receipt, and every register is created with one department per regime.
+     * So a hard-coded `{ id: 1 }` copied from an example is not a harmless
+     * default: on a register that owes no VAT it books the sale under the VAT
+     * department anyway, and the receipt shows a VAT line the merchant does not
+     * owe. Nothing rejects it, and a fiscal receipt can only be refunded and
+     * reissued, never corrected.
+     *
+     * Set it explicitly only to override the offer — selling the same SKU out
+     * of a second department (a VAT payer booking an exempt transaction, say).
+     */
+    department?: DepartmentInput;
     quantity: string;
     /**
      * Unit price. AMD by default. When {@link SaleItem.currency} is set to a
@@ -865,6 +930,21 @@ type ApiErrorIssue = {
     message: string;
     code: string;
 };
+/**
+ * A document VCR persisted and queued for automatic resubmission to SRC.
+ *
+ * Present on a 502 when SRC was merely unreachable. It means the request was
+ * NOT lost: VCR owns the work and a background sweep usually completes it
+ * within minutes. Poll `statusUrl` to find out; do NOT resend the request,
+ * which would produce a second fiscal receipt.
+ */
+type PendingResource = {
+    /** Which collection `id` belongs to, e.g. `"sale"` or `"prepayment"`. */
+    type: string;
+    id: number;
+    /** Path to poll for the outcome, e.g. `/api/v1/sales/5122`. */
+    statusUrl: string;
+};
 type ApiErrorBody = {
     error: string;
     issues?: Array<ApiErrorIssue>;
@@ -874,6 +954,11 @@ type ApiErrorBody = {
      * and Sentry event can be located.
      */
     requestId?: string;
+    /**
+     * Set when the request was persisted despite the error. Its absence on an
+     * error means nothing was created.
+     */
+    pending?: PendingResource;
 };
 /**
  * Base class for every error thrown by the SDK.
@@ -920,4 +1005,4 @@ declare class VCRNetworkError extends VCRError {
     });
 }
 
-export { AVAILABLE_LANGUAGES, type ApiErrorBody, type ApiErrorIssue, type AutoSettle, type Buyer, type CashierId, type CashierListItem, type ClassifierSearchItem, type ClassifierType, type CreateCashierInput, type CreateCashierResponse, type CreateDepartmentInput, type CreateDepartmentResponse, type CreateOfferInput, type CreateOfferInputProduct, type CreateOfferInputService, type CreateOfferResponse, type CreateOfferTitle, type CustomerPrepaymentBalance, DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, type DepartmentInput, type DepartmentListItem, type Discounts, type ExchangeRate, type Language, type LegacyOfferTitle, type ListOffersFilter, type ListPrepaymentsFilter, type LocalizedName, type NewOffer, type Offer, type OfferListItem, type OfferTitle, type PrepaymentAmount, type PrepaymentDetail, type PrepaymentListItem, type PrepaymentState, REFUND_REASONS, type RefundAmount, type RefundItemInput, type RefundReason, type RegisterPrepaymentInput, type RegisterPrepaymentRefundInput, type RegisterPrepaymentRefundResponse, type RegisterPrepaymentResponse, type RegisterSaleInput, type RegisterSaleRefundInput, type RegisterSaleRefundResponse, type RegisterSaleResponse, type RequestOptions, type SaleAmount, type SaleData, type SaleDetail, type SaleItem, type SalePayment, type SearchClassifierInput, type SendReceiptToBuyer, TAX_REGIMES, type TaxRegime, type Unit, type UpdateOfferInput, VCRApiError, VCRClient, type VCRClientOptions, VCRError, VCRNetworkError, VCRValidationError, type Whoami, cashierListItemSchema, cashierListResponseSchema, classifierSearchItemSchema, classifierSearchResponseSchema, createCashierResponseSchema, createDepartmentResponseSchema, createOfferResponseSchema, customerPrepaymentBalanceResponseSchema, departmentListItemSchema, departmentListResponseSchema, exchangeRateResponseSchema, offerListItemSchema, offerListResponseSchema, prepaymentDetailResponseSchema, prepaymentListItemSchema, prepaymentListResponseSchema, prepaymentStateSchema, registerPrepaymentRefundResponseSchema, registerPrepaymentResponseSchema, registerSaleRefundResponseSchema, registerSaleResponseSchema, saleDetailResponseSchema, unitsKeys, whoamiResponseSchema };
+export { AVAILABLE_LANGUAGES, type ApiErrorBody, type ApiErrorIssue, type AutoSettle, type Buyer, type CashierId, type CashierListItem, type ClassifierSearchItem, type ClassifierType, type CreateCashierInput, type CreateCashierResponse, type CreateDepartmentInput, type CreateDepartmentResponse, type CreateOfferInput, type CreateOfferInputProduct, type CreateOfferInputService, type CreateOfferResponse, type CreateOfferTitle, type CustomerPrepaymentBalance, DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, type DepartmentInput, type DepartmentListItem, type Discounts, type ExchangeRate, type Language, type LegacyOfferTitle, type ListOffersFilter, type ListPrepaymentsFilter, type LocalizedName, type NewOffer, type Offer, type OfferListItem, type OfferTitle, type PendingResource, type PrepaymentAmount, type PrepaymentDetail, type PrepaymentListItem, type PrepaymentState, REFUND_REASONS, type RefundAmount, type RefundItemInput, type RefundReason, type RegisterPrepaymentInput, type RegisterPrepaymentRefundInput, type RegisterPrepaymentRefundResponse, type RegisterPrepaymentResponse, type RegisterSaleInput, type RegisterSaleRefundInput, type RegisterSaleRefundResponse, type RegisterSaleResponse, type RequestOptions, type SaleAmount, type SaleData, type SaleDetail, type SaleItem, type SalePayment, type SearchClassifierInput, type SendReceiptToBuyer, type SrcStatus, TAX_REGIMES, type TaxRegime, type Unit, type UpdateOfferInput, VCRApiError, VCRClient, type VCRClientOptions, VCRError, VCRNetworkError, VCRValidationError, type Whoami, cashierListItemSchema, cashierListResponseSchema, classifierSearchItemSchema, classifierSearchResponseSchema, createCashierResponseSchema, createDepartmentResponseSchema, createOfferResponseSchema, customerPrepaymentBalanceResponseSchema, departmentListItemSchema, departmentListResponseSchema, exchangeRateResponseSchema, offerListItemSchema, offerListResponseSchema, prepaymentDetailResponseSchema, prepaymentListItemSchema, prepaymentListResponseSchema, prepaymentStateSchema, registerPrepaymentRefundResponseSchema, registerPrepaymentResponseSchema, registerSaleRefundResponseSchema, registerSaleResponseSchema, saleDetailResponseSchema, srcStatusSchema, unitsKeys, whoamiResponseSchema };

package/lib/index.d.ts

@@ -4,6 +4,20 @@ type RequestOptions = {
     signal?: AbortSignal;
     /** Override per-request timeout in ms. `null` disables the timeout. */
     timeoutMs?: number | null;
+    /**
+     * Opt-in replay protection for the document-creating endpoints
+     * (`registerSale`, `registerSaleRefund`, `registerPrepayment`,
+     * `registerPrepaymentRefund`). Retrying a request that carries the same key
+     * returns the original response instead of registering a second document.
+     *
+     * Strongly recommended. Without it, retrying after a 502 produces a
+     * duplicate fiscal receipt, which can only be undone by issuing a refund.
+     *
+     * The SDK deliberately does not generate this for you: the value must stay
+     * **stable across your retries**, so it has to come from something you own —
+     * typically your order id (`order-4821`) — not from a fresh UUID per call.
+     */
+    idempotencyKey?: string;
 };
 
 declare const registerSaleResponseSchema: z.ZodObject<{
@@ -191,9 +205,36 @@ declare const offerListResponseSchema: z.ZodArray<z.ZodObject<{
     archivedAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
 }, z.core.$strip>>;
+/**
+ * Where a document stands with the tax authority, derived from its submission
+ * log. This is the field to poll after a 502 that carried a `pending` handle.
+ *
+ * - `accepted` — SRC registered it. Terminal and final; a fiscal receipt exists.
+ * - `rejected` — SRC refused the document itself. Terminal: resending the same
+ *   payload gets the same refusal, so something has to change.
+ * - `pending` — no answer from SRC yet. VCR owns the retry; do NOT resend.
+ * - `needs_decision` — the automatic retry window (24h) closed without an
+ *   answer. Still not resendable blind — check the document before acting.
+ *
+ * A plain enum rather than a boolean because "not accepted" spans three very
+ * different situations, and the one that matters most (`pending`) is the one
+ * that looks like failure but must not be treated as one.
+ */
+declare const srcStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    accepted: "accepted";
+    rejected: "rejected";
+    needs_decision: "needs_decision";
+}>;
 declare const saleDetailResponseSchema: z.ZodObject<{
     id: z.ZodNumber;
     createdAt: z.ZodString;
+    srcStatus: z.ZodEnum<{
+        pending: "pending";
+        accepted: "accepted";
+        rejected: "rejected";
+        needs_decision: "needs_decision";
+    }>;
     buyerTin: z.ZodNullable<z.ZodString>;
     comment: z.ZodNullable<z.ZodString>;
     cashAmount: z.ZodNumber;
@@ -337,6 +378,12 @@ declare const prepaymentStateSchema: z.ZodEnum<{
 declare const prepaymentDetailResponseSchema: z.ZodObject<{
     id: z.ZodNumber;
     createdAt: z.ZodString;
+    srcStatus: z.ZodEnum<{
+        pending: "pending";
+        accepted: "accepted";
+        rejected: "rejected";
+        needs_decision: "needs_decision";
+    }>;
     buyerTin: z.ZodNullable<z.ZodString>;
     cashAmount: z.ZodNumber;
     nonCashAmount: z.ZodNumber;
@@ -437,6 +484,7 @@ type CashierListItem = z.infer<typeof cashierListItemSchema>;
 type ClassifierSearchItem = z.infer<typeof classifierSearchItemSchema>;
 type Whoami = z.infer<typeof whoamiResponseSchema>;
 type OfferListItem = z.infer<typeof offerListItemSchema>;
+type SrcStatus = z.infer<typeof srcStatusSchema>;
 type SaleDetail = z.infer<typeof saleDetailResponseSchema>;
 type PrepaymentDetail = z.infer<typeof prepaymentDetailResponseSchema>;
 type PrepaymentListItem = z.infer<typeof prepaymentListItemSchema>;
@@ -536,7 +584,24 @@ type NewOffer = {
 type Offer = NewOffer | ExistingOfferByExternalId | ExistingOfferById;
 type SaleItem = {
     offer: Offer;
-    department: DepartmentInput;
+    /**
+     * Department to book this line under. **Omit it** unless you have a reason
+     * not to: the line then inherits the department of the offer it references
+     * (`defaultDepartment`), which for an inline new offer is the one you just
+     * declared on it.
+     *
+     * The department — not the offer — decides the tax regime printed on the
+     * receipt, and every register is created with one department per regime.
+     * So a hard-coded `{ id: 1 }` copied from an example is not a harmless
+     * default: on a register that owes no VAT it books the sale under the VAT
+     * department anyway, and the receipt shows a VAT line the merchant does not
+     * owe. Nothing rejects it, and a fiscal receipt can only be refunded and
+     * reissued, never corrected.
+     *
+     * Set it explicitly only to override the offer — selling the same SKU out
+     * of a second department (a VAT payer booking an exempt transaction, say).
+     */
+    department?: DepartmentInput;
     quantity: string;
     /**
      * Unit price. AMD by default. When {@link SaleItem.currency} is set to a
@@ -865,6 +930,21 @@ type ApiErrorIssue = {
     message: string;
     code: string;
 };
+/**
+ * A document VCR persisted and queued for automatic resubmission to SRC.
+ *
+ * Present on a 502 when SRC was merely unreachable. It means the request was
+ * NOT lost: VCR owns the work and a background sweep usually completes it
+ * within minutes. Poll `statusUrl` to find out; do NOT resend the request,
+ * which would produce a second fiscal receipt.
+ */
+type PendingResource = {
+    /** Which collection `id` belongs to, e.g. `"sale"` or `"prepayment"`. */
+    type: string;
+    id: number;
+    /** Path to poll for the outcome, e.g. `/api/v1/sales/5122`. */
+    statusUrl: string;
+};
 type ApiErrorBody = {
     error: string;
     issues?: Array<ApiErrorIssue>;
@@ -874,6 +954,11 @@ type ApiErrorBody = {
      * and Sentry event can be located.
      */
     requestId?: string;
+    /**
+     * Set when the request was persisted despite the error. Its absence on an
+     * error means nothing was created.
+     */
+    pending?: PendingResource;
 };
 /**
  * Base class for every error thrown by the SDK.
@@ -920,4 +1005,4 @@ declare class VCRNetworkError extends VCRError {
     });
 }
 
-export { AVAILABLE_LANGUAGES, type ApiErrorBody, type ApiErrorIssue, type AutoSettle, type Buyer, type CashierId, type CashierListItem, type ClassifierSearchItem, type ClassifierType, type CreateCashierInput, type CreateCashierResponse, type CreateDepartmentInput, type CreateDepartmentResponse, type CreateOfferInput, type CreateOfferInputProduct, type CreateOfferInputService, type CreateOfferResponse, type CreateOfferTitle, type CustomerPrepaymentBalance, DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, type DepartmentInput, type DepartmentListItem, type Discounts, type ExchangeRate, type Language, type LegacyOfferTitle, type ListOffersFilter, type ListPrepaymentsFilter, type LocalizedName, type NewOffer, type Offer, type OfferListItem, type OfferTitle, type PrepaymentAmount, type PrepaymentDetail, type PrepaymentListItem, type PrepaymentState, REFUND_REASONS, type RefundAmount, type RefundItemInput, type RefundReason, type RegisterPrepaymentInput, type RegisterPrepaymentRefundInput, type RegisterPrepaymentRefundResponse, type RegisterPrepaymentResponse, type RegisterSaleInput, type RegisterSaleRefundInput, type RegisterSaleRefundResponse, type RegisterSaleResponse, type RequestOptions, type SaleAmount, type SaleData, type SaleDetail, type SaleItem, type SalePayment, type SearchClassifierInput, type SendReceiptToBuyer, TAX_REGIMES, type TaxRegime, type Unit, type UpdateOfferInput, VCRApiError, VCRClient, type VCRClientOptions, VCRError, VCRNetworkError, VCRValidationError, type Whoami, cashierListItemSchema, cashierListResponseSchema, classifierSearchItemSchema, classifierSearchResponseSchema, createCashierResponseSchema, createDepartmentResponseSchema, createOfferResponseSchema, customerPrepaymentBalanceResponseSchema, departmentListItemSchema, departmentListResponseSchema, exchangeRateResponseSchema, offerListItemSchema, offerListResponseSchema, prepaymentDetailResponseSchema, prepaymentListItemSchema, prepaymentListResponseSchema, prepaymentStateSchema, registerPrepaymentRefundResponseSchema, registerPrepaymentResponseSchema, registerSaleRefundResponseSchema, registerSaleResponseSchema, saleDetailResponseSchema, unitsKeys, whoamiResponseSchema };
+export { AVAILABLE_LANGUAGES, type ApiErrorBody, type ApiErrorIssue, type AutoSettle, type Buyer, type CashierId, type CashierListItem, type ClassifierSearchItem, type ClassifierType, type CreateCashierInput, type CreateCashierResponse, type CreateDepartmentInput, type CreateDepartmentResponse, type CreateOfferInput, type CreateOfferInputProduct, type CreateOfferInputService, type CreateOfferResponse, type CreateOfferTitle, type CustomerPrepaymentBalance, DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, type DepartmentInput, type DepartmentListItem, type Discounts, type ExchangeRate, type Language, type LegacyOfferTitle, type ListOffersFilter, type ListPrepaymentsFilter, type LocalizedName, type NewOffer, type Offer, type OfferListItem, type OfferTitle, type PendingResource, type PrepaymentAmount, type PrepaymentDetail, type PrepaymentListItem, type PrepaymentState, REFUND_REASONS, type RefundAmount, type RefundItemInput, type RefundReason, type RegisterPrepaymentInput, type RegisterPrepaymentRefundInput, type RegisterPrepaymentRefundResponse, type RegisterPrepaymentResponse, type RegisterSaleInput, type RegisterSaleRefundInput, type RegisterSaleRefundResponse, type RegisterSaleResponse, type RequestOptions, type SaleAmount, type SaleData, type SaleDetail, type SaleItem, type SalePayment, type SearchClassifierInput, type SendReceiptToBuyer, type SrcStatus, TAX_REGIMES, type TaxRegime, type Unit, type UpdateOfferInput, VCRApiError, VCRClient, type VCRClientOptions, VCRError, VCRNetworkError, VCRValidationError, type Whoami, cashierListItemSchema, cashierListResponseSchema, classifierSearchItemSchema, classifierSearchResponseSchema, createCashierResponseSchema, createDepartmentResponseSchema, createOfferResponseSchema, customerPrepaymentBalanceResponseSchema, departmentListItemSchema, departmentListResponseSchema, exchangeRateResponseSchema, offerListItemSchema, offerListResponseSchema, prepaymentDetailResponseSchema, prepaymentListItemSchema, prepaymentListResponseSchema, prepaymentStateSchema, registerPrepaymentRefundResponseSchema, registerPrepaymentResponseSchema, registerSaleRefundResponseSchema, registerSaleResponseSchema, saleDetailResponseSchema, srcStatusSchema, unitsKeys, whoamiResponseSchema };