@blob-solutions/vcr-am-sdk 0.17.0 → 0.20.0

package/lib/index.d.cts

@@ -10,8 +10,9 @@ type RequestOptions = {
      * `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.
+     * Strongly recommended. Without it, retrying after a 502 or a 409 that
+     * carried a `pending` handle 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 —
@@ -20,12 +21,25 @@ type RequestOptions = {
     idempotencyKey?: string;
 };
 
+/**
+ * Public receipt page for the buyer — safe to email, print as a QR, or put on
+ * an order-confirmation page: it carries no account access. The page picks the
+ * reader's own language.
+ *
+ * Optional, and deliberately so: the field was added to the API after this
+ * schema shipped, and a client that required it would fail to parse a
+ * perfectly good receipt from a server that predates it. A convenience field
+ * must never be the reason a fiscal call errors. It is always present from
+ * vcr.am today; build it yourself from `crn` and `urlId` if you need a
+ * fallback.
+ */
 declare const registerSaleResponseSchema: z.ZodObject<{
     urlId: z.ZodString;
     saleId: z.ZodNumber;
     crn: z.ZodString;
     srcReceiptId: z.ZodNumber;
     fiscal: z.ZodString;
+    receiptUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const registerSaleRefundResponseSchema: z.ZodObject<{
     urlId: z.ZodString;
@@ -33,6 +47,7 @@ declare const registerSaleRefundResponseSchema: z.ZodObject<{
     crn: z.ZodNullable<z.ZodString>;
     receiptId: z.ZodNumber;
     fiscal: z.ZodNullable<z.ZodString>;
+    receiptUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const registerPrepaymentResponseSchema: z.ZodObject<{
     urlId: z.ZodString;
@@ -40,6 +55,7 @@ declare const registerPrepaymentResponseSchema: z.ZodObject<{
     crn: z.ZodNullable<z.ZodString>;
     receiptId: z.ZodNumber;
     fiscal: z.ZodNullable<z.ZodString>;
+    receiptUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const registerPrepaymentRefundResponseSchema: z.ZodObject<{
     urlId: z.ZodString;
@@ -47,6 +63,7 @@ declare const registerPrepaymentRefundResponseSchema: z.ZodObject<{
     crn: z.ZodNullable<z.ZodString>;
     receiptId: z.ZodNumber;
     fiscal: z.ZodNullable<z.ZodString>;
+    receiptUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const createOfferResponseSchema: z.ZodObject<{
     offerId: z.ZodNumber;
@@ -207,14 +224,21 @@ declare const offerListResponseSchema: z.ZodArray<z.ZodObject<{
 }, 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.
+ * log. This is the field to poll after any response that carried a `pending`
+ * handle (502 or 409).
  *
  * - `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.
+ * - `pending` — no answer from SRC yet, and VCR still owns the document: it
+ *   may already be registered there, or VCR is going to send it again. Do NOT
+ *   resend.
+ * - `needs_decision` — nothing is going to submit this document on its own.
+ *   Either the merchant has late fiscalization off (the default), in which
+ *   case SRC registered nothing and it is yours to send again, or the 24h
+ *   automatic window closed. The `502` that created it told you which via
+ *   `pending.mayResubmit`; if you no longer have that response, check the
+ *   document before acting rather than resending blind.
  *
  * 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
@@ -584,7 +608,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
@@ -666,11 +707,19 @@ type AutoSettle = {
 type PayByAmount = {
     amount: SaleAmount;
     autoSettle?: never;
+    /**
+     * The prepayment `amount.prepayment` is spent from. Without it the sale
+     * consumes the oldest open prepayments, which for a buyer with no TIN means
+     * anyone's. A prepayment that cannot cover the amount refuses the sale with
+     * a `400` and nothing saved.
+     */
+    prepaymentId?: number;
 };
 /** VCR derives the AMD total onto one tender. Mutually exclusive with `amount`. */
 type PayByAutoSettle = {
     autoSettle: AutoSettle;
     amount?: never;
+    prepaymentId?: never;
 };
 /**
  * A sale settles EITHER by explicit `amount` OR by `autoSettle` — exactly one,
@@ -728,6 +777,11 @@ type RegisterPrepaymentInput = {
 type RegisterPrepaymentRefundInput = {
     cashier: CashierId;
     prepaymentId: number;
+    /**
+     * Return all that sales left of the prepayment. Without it, a prepayment a
+     * sale has used is refused. There is no amount: the rest cannot stay behind.
+     */
+    returnRemainder?: true;
     receipt?: SendReceiptToBuyer;
     reason?: RefundReason;
     reasonNote?: string;
@@ -914,19 +968,47 @@ type ApiErrorIssue = {
     code: string;
 };
 /**
- * A document VCR persisted and queued for automatic resubmission to SRC.
+ * A document VCR persisted despite the error. Its presence means the request
+ * was NOT lost, so never resend blindly — read `mayResubmit` first.
  *
- * 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.
+ * Present on two statuses:
+ *
+ * - **502** — SRC was unreachable. What to do next is `mayResubmit`.
+ * - **409** — SRC answered and refused the document on business grounds (for
+ *   example 196, the cash register is not activated at SRC). `mayResubmit` is
+ *   always false here: the same payload earns the same refusal. Read the SRC
+ *   code in `error`, fix the cause, then send the corrected document.
  */
 type PendingResource = {
-    /** Which collection `id` belongs to, e.g. `"sale"` or `"prepayment"`. */
+    /**
+     * Which collection `id` belongs to: `"sale"`, `"prepayment"`, or
+     * `"sale_refund"`. Deliberately a plain string — a server that adds a type
+     * must not break parsing in an older SDK.
+     */
     type: string;
     id: number;
-    /** Path to poll for the outcome, e.g. `/api/v1/sales/5122`. */
+    /**
+     * Path to poll for the outcome, e.g. `/api/v1/sales/5122`. For
+     * `"sale_refund"` this is the PARENT SALE: find your refund by `id` in the
+     * response's `refunds` array.
+     */
     statusUrl: string;
+    /**
+     * Whether sending this exact request again is safe.
+     *
+     * `false` — the document is still VCR's to settle: SRC may have registered
+     * it already, or VCR will submit it again for you. Resending risks a second
+     * fiscal receipt for one sale. Poll `statusUrl` instead.
+     *
+     * `true` — SRC registered nothing and VCR will not send it again (the
+     * merchant has late fiscalization off, which is the default). Nothing
+     * further happens server-side; resubmitting is how the document gets
+     * fiscalized.
+     *
+     * Absent when the server predates the field. Treat that as `false` — the
+     * conservative reading, and what those servers did.
+     */
+    mayResubmit?: boolean;
 };
 type ApiErrorBody = {
     error: string;

package/lib/index.d.ts

@@ -10,8 +10,9 @@ type RequestOptions = {
      * `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.
+     * Strongly recommended. Without it, retrying after a 502 or a 409 that
+     * carried a `pending` handle 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 —
@@ -20,12 +21,25 @@ type RequestOptions = {
     idempotencyKey?: string;
 };
 
+/**
+ * Public receipt page for the buyer — safe to email, print as a QR, or put on
+ * an order-confirmation page: it carries no account access. The page picks the
+ * reader's own language.
+ *
+ * Optional, and deliberately so: the field was added to the API after this
+ * schema shipped, and a client that required it would fail to parse a
+ * perfectly good receipt from a server that predates it. A convenience field
+ * must never be the reason a fiscal call errors. It is always present from
+ * vcr.am today; build it yourself from `crn` and `urlId` if you need a
+ * fallback.
+ */
 declare const registerSaleResponseSchema: z.ZodObject<{
     urlId: z.ZodString;
     saleId: z.ZodNumber;
     crn: z.ZodString;
     srcReceiptId: z.ZodNumber;
     fiscal: z.ZodString;
+    receiptUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const registerSaleRefundResponseSchema: z.ZodObject<{
     urlId: z.ZodString;
@@ -33,6 +47,7 @@ declare const registerSaleRefundResponseSchema: z.ZodObject<{
     crn: z.ZodNullable<z.ZodString>;
     receiptId: z.ZodNumber;
     fiscal: z.ZodNullable<z.ZodString>;
+    receiptUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const registerPrepaymentResponseSchema: z.ZodObject<{
     urlId: z.ZodString;
@@ -40,6 +55,7 @@ declare const registerPrepaymentResponseSchema: z.ZodObject<{
     crn: z.ZodNullable<z.ZodString>;
     receiptId: z.ZodNumber;
     fiscal: z.ZodNullable<z.ZodString>;
+    receiptUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const registerPrepaymentRefundResponseSchema: z.ZodObject<{
     urlId: z.ZodString;
@@ -47,6 +63,7 @@ declare const registerPrepaymentRefundResponseSchema: z.ZodObject<{
     crn: z.ZodNullable<z.ZodString>;
     receiptId: z.ZodNumber;
     fiscal: z.ZodNullable<z.ZodString>;
+    receiptUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const createOfferResponseSchema: z.ZodObject<{
     offerId: z.ZodNumber;
@@ -207,14 +224,21 @@ declare const offerListResponseSchema: z.ZodArray<z.ZodObject<{
 }, 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.
+ * log. This is the field to poll after any response that carried a `pending`
+ * handle (502 or 409).
  *
  * - `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.
+ * - `pending` — no answer from SRC yet, and VCR still owns the document: it
+ *   may already be registered there, or VCR is going to send it again. Do NOT
+ *   resend.
+ * - `needs_decision` — nothing is going to submit this document on its own.
+ *   Either the merchant has late fiscalization off (the default), in which
+ *   case SRC registered nothing and it is yours to send again, or the 24h
+ *   automatic window closed. The `502` that created it told you which via
+ *   `pending.mayResubmit`; if you no longer have that response, check the
+ *   document before acting rather than resending blind.
  *
  * 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
@@ -584,7 +608,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
@@ -666,11 +707,19 @@ type AutoSettle = {
 type PayByAmount = {
     amount: SaleAmount;
     autoSettle?: never;
+    /**
+     * The prepayment `amount.prepayment` is spent from. Without it the sale
+     * consumes the oldest open prepayments, which for a buyer with no TIN means
+     * anyone's. A prepayment that cannot cover the amount refuses the sale with
+     * a `400` and nothing saved.
+     */
+    prepaymentId?: number;
 };
 /** VCR derives the AMD total onto one tender. Mutually exclusive with `amount`. */
 type PayByAutoSettle = {
     autoSettle: AutoSettle;
     amount?: never;
+    prepaymentId?: never;
 };
 /**
  * A sale settles EITHER by explicit `amount` OR by `autoSettle` — exactly one,
@@ -728,6 +777,11 @@ type RegisterPrepaymentInput = {
 type RegisterPrepaymentRefundInput = {
     cashier: CashierId;
     prepaymentId: number;
+    /**
+     * Return all that sales left of the prepayment. Without it, a prepayment a
+     * sale has used is refused. There is no amount: the rest cannot stay behind.
+     */
+    returnRemainder?: true;
     receipt?: SendReceiptToBuyer;
     reason?: RefundReason;
     reasonNote?: string;
@@ -914,19 +968,47 @@ type ApiErrorIssue = {
     code: string;
 };
 /**
- * A document VCR persisted and queued for automatic resubmission to SRC.
+ * A document VCR persisted despite the error. Its presence means the request
+ * was NOT lost, so never resend blindly — read `mayResubmit` first.
  *
- * 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.
+ * Present on two statuses:
+ *
+ * - **502** — SRC was unreachable. What to do next is `mayResubmit`.
+ * - **409** — SRC answered and refused the document on business grounds (for
+ *   example 196, the cash register is not activated at SRC). `mayResubmit` is
+ *   always false here: the same payload earns the same refusal. Read the SRC
+ *   code in `error`, fix the cause, then send the corrected document.
  */
 type PendingResource = {
-    /** Which collection `id` belongs to, e.g. `"sale"` or `"prepayment"`. */
+    /**
+     * Which collection `id` belongs to: `"sale"`, `"prepayment"`, or
+     * `"sale_refund"`. Deliberately a plain string — a server that adds a type
+     * must not break parsing in an older SDK.
+     */
     type: string;
     id: number;
-    /** Path to poll for the outcome, e.g. `/api/v1/sales/5122`. */
+    /**
+     * Path to poll for the outcome, e.g. `/api/v1/sales/5122`. For
+     * `"sale_refund"` this is the PARENT SALE: find your refund by `id` in the
+     * response's `refunds` array.
+     */
     statusUrl: string;
+    /**
+     * Whether sending this exact request again is safe.
+     *
+     * `false` — the document is still VCR's to settle: SRC may have registered
+     * it already, or VCR will submit it again for you. Resending risks a second
+     * fiscal receipt for one sale. Poll `statusUrl` instead.
+     *
+     * `true` — SRC registered nothing and VCR will not send it again (the
+     * merchant has late fiscalization off, which is the default). Nothing
+     * further happens server-side; resubmitting is how the document gets
+     * fiscalized.
+     *
+     * Absent when the server predates the field. Treat that as `false` — the
+     * conservative reading, and what those servers did.
+     */
+    mayResubmit?: boolean;
 };
 type ApiErrorBody = {
     error: string;