@blob-solutions/vcr-am-sdk 0.8.0 → 0.11.0

package/lib/index.d.ts

@@ -1,8 +1,298 @@
-import { RequireAtLeastOne } from 'type-fest';
+import { z } from 'zod';
+
+type RequestOptions = {
+    signal?: AbortSignal;
+    /** Override per-request timeout in ms. `null` disables the timeout. */
+    timeoutMs?: number | null;
+};
+
+declare const registerSaleResponseSchema: z.ZodObject<{
+    urlId: z.ZodString;
+    saleId: z.ZodNumber;
+    crn: z.ZodString;
+    srcReceiptId: z.ZodNumber;
+    fiscal: z.ZodString;
+}, z.core.$strip>;
+declare const registerSaleRefundResponseSchema: z.ZodObject<{
+    urlId: z.ZodString;
+    saleRefundId: z.ZodNumber;
+    crn: z.ZodNullable<z.ZodString>;
+    receiptId: z.ZodNumber;
+    fiscal: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const registerPrepaymentResponseSchema: z.ZodObject<{
+    urlId: z.ZodString;
+    prepaymentId: z.ZodNumber;
+    crn: z.ZodNullable<z.ZodString>;
+    receiptId: z.ZodNumber;
+    fiscal: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const registerPrepaymentRefundResponseSchema: z.ZodObject<{
+    urlId: z.ZodString;
+    prepaymentRefundId: z.ZodNumber;
+    crn: z.ZodNullable<z.ZodString>;
+    receiptId: z.ZodNumber;
+    fiscal: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const createOfferResponseSchema: z.ZodObject<{
+    offerId: z.ZodNumber;
+}, z.core.$strip>;
+declare const createCashierResponseSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    deskId: z.ZodString;
+}, z.core.$strip>;
+declare const createDepartmentResponseSchema: z.ZodObject<{
+    message: z.ZodString;
+    department: z.ZodNumber;
+}, z.core.$strip>;
+declare const cashierListItemSchema: z.ZodObject<{
+    deskId: z.ZodString;
+    internalId: z.ZodNumber;
+    name: z.ZodRecord<z.ZodString, z.ZodObject<{
+        language: z.ZodEnum<{
+            hy: "hy";
+            ru: "ru";
+            en: "en";
+            multi: "multi";
+        }>;
+        content: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const cashierListResponseSchema: z.ZodArray<z.ZodObject<{
+    deskId: z.ZodString;
+    internalId: z.ZodNumber;
+    name: z.ZodRecord<z.ZodString, z.ZodObject<{
+        language: z.ZodEnum<{
+            hy: "hy";
+            ru: "ru";
+            en: "en";
+            multi: "multi";
+        }>;
+        content: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+declare const classifierSearchItemSchema: z.ZodObject<{
+    code: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const classifierSearchResponseSchema: z.ZodArray<z.ZodObject<{
+    code: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const saleDetailResponseSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    createdAt: z.ZodString;
+    buyerTin: z.ZodNullable<z.ZodString>;
+    cashAmount: z.ZodNumber;
+    nonCashAmount: z.ZodNumber;
+    prepaymentAmount: z.ZodNumber;
+    compensationAmount: z.ZodNumber;
+    receipt: z.ZodNullable<z.ZodObject<{
+        srcId: z.ZodNumber;
+        time: z.ZodString;
+        tin: z.ZodString;
+        fiscal: z.ZodNullable<z.ZodString>;
+        sn: z.ZodString;
+        address: z.ZodNullable<z.ZodString>;
+        total: z.ZodNumber;
+        taxpayer: z.ZodString;
+        change: z.ZodNumber;
+    }, z.core.$strip>>;
+    refunds: z.ZodArray<z.ZodObject<{
+        nonCashAmount: z.ZodNumber;
+        cashAmount: z.ZodNumber;
+        receipt: z.ZodNullable<z.ZodObject<{
+            srcId: z.ZodNumber;
+            time: z.ZodString;
+            tin: z.ZodString;
+            fiscal: z.ZodNullable<z.ZodString>;
+            sn: z.ZodString;
+            address: z.ZodNullable<z.ZodString>;
+            total: z.ZodNumber;
+            taxpayer: z.ZodString;
+            change: z.ZodNumber;
+        }, z.core.$strip>>;
+        items: z.ZodArray<z.ZodObject<{
+            quantity: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    cashier: z.ZodObject<{
+        internalId: z.ZodNumber;
+        deskId: z.ZodString;
+        name: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            language: z.ZodEnum<{
+                hy: "hy";
+                ru: "ru";
+                en: "en";
+                multi: "multi";
+            }>;
+            content: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    items: z.ZodArray<z.ZodObject<{
+        srcId: z.ZodNumber;
+        quantity: z.ZodNumber;
+        price: z.ZodNumber;
+        unit: z.ZodEnum<{
+            pc: "pc";
+            unit: "unit";
+            set: "set";
+            box: "box";
+            pack: "pack";
+            case: "case";
+            hr: "hr";
+            sess: "sess";
+            proj: "proj";
+            sub: "sub";
+            kg: "kg";
+            l: "l";
+            m: "m";
+            g: "g";
+            ml: "ml";
+            cm: "cm";
+            bottle: "bottle";
+            can: "can";
+            jar: "jar";
+            bag: "bag";
+            m2: "m2";
+            dozen: "dozen";
+            pair: "pair";
+            mm: "mm";
+            roll: "roll";
+            tube: "tube";
+            km: "km";
+            ton: "ton";
+            m3: "m3";
+            pallet: "pallet";
+            other: "other";
+        }>;
+        discount: z.ZodNullable<z.ZodNumber>;
+        discountType: z.ZodNullable<z.ZodEnum<{
+            percent: "percent";
+            price: "price";
+            total: "total";
+        }>>;
+        additionalDiscount: z.ZodNullable<z.ZodNumber>;
+        additionalDiscountType: z.ZodNullable<z.ZodEnum<{
+            percent: "percent";
+            total: "total";
+        }>>;
+        department: z.ZodObject<{
+            internalId: z.ZodNumber;
+            taxRegime: z.ZodEnum<{
+                vat: "vat";
+                vat_exempt: "vat_exempt";
+                turnover_tax: "turnover_tax";
+                micro_enterprise: "micro_enterprise";
+            }>;
+            title: z.ZodArray<z.ZodObject<{
+                id: z.ZodNumber;
+                language: z.ZodEnum<{
+                    hy: "hy";
+                    ru: "ru";
+                    en: "en";
+                    multi: "multi";
+                }>;
+                content: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        offer: z.ZodObject<{
+            type: z.ZodEnum<{
+                product: "product";
+                service: "service";
+            }>;
+            classifierCode: z.ZodString;
+            title: z.ZodArray<z.ZodObject<{
+                id: z.ZodNumber;
+                language: z.ZodEnum<{
+                    hy: "hy";
+                    ru: "ru";
+                    en: "en";
+                    multi: "multi";
+                }>;
+                content: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const prepaymentDetailResponseSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    createdAt: z.ZodString;
+    buyerTin: z.ZodNullable<z.ZodString>;
+    cashAmount: z.ZodNumber;
+    nonCashAmount: z.ZodNumber;
+    receipt: z.ZodNullable<z.ZodObject<{
+        srcId: z.ZodNumber;
+        time: z.ZodString;
+        tin: z.ZodString;
+        fiscal: z.ZodNullable<z.ZodString>;
+        sn: z.ZodString;
+        address: z.ZodNullable<z.ZodString>;
+        total: z.ZodNumber;
+        taxpayer: z.ZodString;
+        change: z.ZodNumber;
+    }, z.core.$strip>>;
+    refund: z.ZodNullable<z.ZodObject<{
+        nonCashAmount: z.ZodNumber;
+        cashAmount: z.ZodNumber;
+        receipt: z.ZodNullable<z.ZodObject<{
+            srcId: z.ZodNumber;
+            time: z.ZodString;
+            tin: z.ZodString;
+            fiscal: z.ZodNullable<z.ZodString>;
+            sn: z.ZodString;
+            address: z.ZodNullable<z.ZodString>;
+            total: z.ZodNumber;
+            taxpayer: z.ZodString;
+            change: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    cashier: z.ZodObject<{
+        internalId: z.ZodNumber;
+        deskId: z.ZodString;
+        name: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            language: z.ZodEnum<{
+                hy: "hy";
+                ru: "ru";
+                en: "en";
+                multi: "multi";
+            }>;
+            content: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type RegisterSaleResponse = z.infer<typeof registerSaleResponseSchema>;
+type RegisterSaleRefundResponse = z.infer<typeof registerSaleRefundResponseSchema>;
+type RegisterPrepaymentResponse = z.infer<typeof registerPrepaymentResponseSchema>;
+type RegisterPrepaymentRefundResponse = z.infer<typeof registerPrepaymentRefundResponseSchema>;
+type CreateOfferResponse = z.infer<typeof createOfferResponseSchema>;
+type CreateCashierResponse = z.infer<typeof createCashierResponseSchema>;
+type CreateDepartmentResponse = z.infer<typeof createDepartmentResponseSchema>;
+type CashierListItem = z.infer<typeof cashierListItemSchema>;
+type ClassifierSearchItem = z.infer<typeof classifierSearchItemSchema>;
+type SaleDetail = z.infer<typeof saleDetailResponseSchema>;
+type PrepaymentDetail = z.infer<typeof prepaymentDetailResponseSchema>;
 
 declare const unitsKeys: readonly ["pc", "unit", "set", "box", "pack", "case", "hr", "sess", "proj", "sub", "kg", "l", "m", "g", "ml", "cm", "bottle", "can", "jar", "bag", "m2", "dozen", "pair", "mm", "roll", "tube", "km", "ton", "m3", "pallet", "other"];
 declare const AVAILABLE_LANGUAGES: readonly ["hy", "ru", "en"];
+declare const REFUND_REASONS: readonly ["customer_request", "defective_goods", "wrong_goods", "cashier_error", "duplicate_receipt", "other"];
+declare const TAX_REGIMES: readonly ["vat", "vat_exempt", "turnover_tax", "micro_enterprise"];
+declare const DEFAULT_API_URL = "https://vcr.am/api/v1";
+declare const DEFAULT_TIMEOUT_MS = 30000;
 
+/**
+ * Object where at least one of the listed keys must be present.
+ * Inlined here to avoid pulling type-fest into runtime dependents.
+ */
+type RequireAtLeastOne<T, K extends keyof T = keyof T> = Omit<T, K> & {
+    [P in K]-?: Required<Pick<T, P>> & Partial<Pick<T, Exclude<K, P>>>;
+}[K];
+type Unit = (typeof unitsKeys)[number];
+type Language = (typeof AVAILABLE_LANGUAGES)[number];
+type RefundReason = (typeof REFUND_REASONS)[number];
+type TaxRegime = (typeof TAX_REGIMES)[number];
 type CashierInternalId = {
     id: number;
 };
@@ -10,8 +300,6 @@ type CashierDeskId = {
     deskId: string;
 };
 type CashierId = CashierInternalId | CashierDeskId;
-type Unit = (typeof unitsKeys)[number];
-type Language = (typeof AVAILABLE_LANGUAGES)[number];
 type PercentDiscount = {
     type: "percent";
     value: string;
@@ -26,30 +314,25 @@ type AbsoluteAdditionalDiscount = {
 };
 type BaseDiscount = PercentDiscount | AbsoluteDiscount;
 type AdditionalDiscount = PercentDiscount | AbsoluteAdditionalDiscount;
-type NoDiscounts = {
+type Discounts = {
     base?: BaseDiscount;
     additional?: AdditionalDiscount;
 };
-type BaseDiscounts = {
-    base: BaseDiscount;
-};
-type BaseAndAdditionalDiscounts = {
-    base: BaseDiscount;
-    additional: AdditionalDiscount;
-};
 type ExistingOffer = {
     externalId: string;
 };
-type OfferTitle = {
+type LocalizedOfferTitle = {
     type: "localized";
     content: Partial<Record<Language, string>> & {
         hy: string;
     };
     localizationStrategy: "translation" | "transliteration";
-} | {
+};
+type UniversalOfferTitle = {
     type: "universal";
     content: string;
 };
+type OfferTitle = LocalizedOfferTitle | UniversalOfferTitle;
 type DepartmentInput = {
     id: number;
 };
@@ -68,11 +351,11 @@ type SaleItem = {
     quantity: string;
     price: string;
     unit: Unit;
-    discounts?: NoDiscounts | BaseDiscounts | BaseAndAdditionalDiscounts;
+    discounts?: Discounts;
     totalAmountTolerance?: string;
 };
 type SaleAmount = RequireAtLeastOne<{
-    prePayment?: string;
+    prepayment?: string;
     compensation?: string;
     nonCash?: string;
     cash?: string;
@@ -91,27 +374,177 @@ type LegalEntityBuyer = {
     receipt?: SendReceiptToBuyer;
 };
 type Buyer = IndividualBuyer | LegalEntityBuyer;
-type SaleData = {
+type RegisterSaleInput = {
     cashier: CashierId;
     items: SaleItem[];
     amount: SaleAmount;
     buyer: Buyer;
 };
+/** @deprecated Use {@link RegisterSaleInput} instead. Will be removed in 1.0. */
+type SaleData = RegisterSaleInput;
+type ClassifierType = "product" | "service";
+type SearchClassifierInput = {
+    query: string;
+    type: ClassifierType;
+    language: Language;
+};
+type RefundItemInput = {
+    srcId: number;
+    quantity: string;
+    emarks?: string[];
+};
+type RefundAmount = RequireAtLeastOne<{
+    cash?: string;
+    nonCash?: string;
+}>;
+type RegisterSaleRefundInput = {
+    cashier: CashierId;
+    saleId: number;
+    receipt?: SendReceiptToBuyer;
+    reason?: RefundReason;
+    reasonNote?: string;
+    refundAmounts?: RefundAmount;
+    items?: RefundItemInput[];
+};
+type PrepaymentAmount = RequireAtLeastOne<{
+    cash?: string;
+    nonCash?: string;
+}>;
+type RegisterPrepaymentInput = {
+    cashier: CashierId;
+    amount: PrepaymentAmount;
+    buyer: Buyer;
+};
+type RegisterPrepaymentRefundInput = {
+    cashier: CashierId;
+    prepaymentId: number;
+    receipt?: SendReceiptToBuyer;
+    reason?: RefundReason;
+    reasonNote?: string;
+};
+type LocalizedName = Partial<Record<Language, string>> & {
+    hy: string;
+};
+type CreateCashierInput = {
+    name: {
+        value: LocalizedName;
+        localizationStrategy: "translation" | "transliteration";
+    };
+    /** 4–8 digit numeric PIN. */
+    password: string;
+};
+type CreateDepartmentInput = {
+    externalId?: string;
+    taxRegime: TaxRegime;
+    /**
+     * Department title shown on reports and receipts. `value.hy` is required;
+     * `value.ru` and `value.en` are optional and auto-transliterated from
+     * `hy` at render time when missing. `localizationStrategy` follows the
+     * same shape used by `CreateCashierInput.name` and `CreateOfferInput.title`.
+     */
+    title: {
+        value: LocalizedName;
+        localizationStrategy: "translation" | "transliteration";
+    };
+};
+type CreateOfferInputProduct = {
+    type: "product";
+    classifierCode: string;
+    title: {
+        value: LocalizedName;
+        localizationStrategy: "translation" | "transliteration";
+    };
+    defaultMeasureUnit: Unit;
+    defaultDepartment: DepartmentInput;
+    externalId?: string;
+};
+type CreateOfferInputService = Omit<CreateOfferInputProduct, "type"> & {
+    type: "service";
+};
+type CreateOfferInput = CreateOfferInputProduct | CreateOfferInputService;
 
+type VCRClientOptions = {
+    /** Base URL for the VCR API. Defaults to https://vcr.am/api/v1. */
+    baseUrl?: string;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Default request timeout in ms. Pass `null` to disable. Default 30s. */
+    timeoutMs?: number | null;
+};
 declare class VCRClient {
-    private readonly apiKey;
-    constructor(apiKey: string);
-    registerSale(data: SaleData): Promise<{
-        urlId: string;
-        saleId: number;
-        crn: string;
-        srcReceiptId: number;
-        fiscal: string;
-    }>;
-    searchClassifierCategory(query: string, type: "product" | "service", language: Language): Promise<{
-        code: string;
-        title: string;
-    }[]>;
+    #private;
+    constructor(apiKey: string, options?: VCRClientOptions);
+    registerSale(data: RegisterSaleInput, options?: RequestOptions): Promise<RegisterSaleResponse>;
+    getSale(saleId: number, options?: RequestOptions): Promise<SaleDetail>;
+    registerSaleRefund(data: RegisterSaleRefundInput, options?: RequestOptions): Promise<RegisterSaleRefundResponse>;
+    registerPrepayment(data: RegisterPrepaymentInput, options?: RequestOptions): Promise<RegisterPrepaymentResponse>;
+    getPrepayment(prepaymentId: number, options?: RequestOptions): Promise<PrepaymentDetail>;
+    registerPrepaymentRefund(data: RegisterPrepaymentRefundInput, options?: RequestOptions): Promise<RegisterPrepaymentRefundResponse>;
+    listCashiers(options?: RequestOptions): Promise<CashierListItem[]>;
+    createCashier(data: CreateCashierInput, options?: RequestOptions): Promise<CreateCashierResponse>;
+    createOffer(data: CreateOfferInput, options?: RequestOptions): Promise<CreateOfferResponse>;
+    createDepartment(data: CreateDepartmentInput, options?: RequestOptions): Promise<CreateDepartmentResponse>;
+    searchClassifier(input: SearchClassifierInput, options?: RequestOptions): Promise<ClassifierSearchItem[]>;
+    /**
+     * @deprecated Use {@link searchClassifier} with an options object. Will be
+     *   removed in 1.0. The new signature accepts `{ query, type, language }` so
+     *   future params can be added without breaking the call site.
+     */
+    searchClassifierCategory(query: string, type: ClassifierType, language: Language, options?: RequestOptions): Promise<ClassifierSearchItem[]>;
+}
+
+type ApiErrorIssue = {
+    path: Array<string | number>;
+    message: string;
+    code: string;
+};
+type ApiErrorBody = {
+    error: string;
+    issues?: Array<ApiErrorIssue>;
+};
+/**
+ * Base class for every error thrown by the SDK.
+ * Catch this if you want a single catch-all.
+ */
+declare abstract class VCRError extends Error {
+    abstract readonly kind: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Server returned a non-2xx response with a parseable JSON error body.
+ * Mirrors the unified `{ error, issues? }` envelope from /api/v1.
+ */
+declare class VCRApiError extends VCRError {
+    readonly status: number;
+    readonly body: ApiErrorBody;
+    readonly url: string;
+    readonly kind: "api";
+    constructor(status: number, body: ApiErrorBody, url: string);
+}
+/**
+ * Server returned a non-2xx response that did not match the error envelope,
+ * or a 2xx response whose body did not match the expected schema.
+ */
+declare class VCRValidationError extends VCRError {
+    readonly status: number;
+    readonly url: string;
+    readonly issues: z.ZodIssue[];
+    readonly raw: unknown;
+    readonly kind: "validation";
+    constructor(message: string, status: number, url: string, issues: z.ZodIssue[], raw: unknown);
+}
+/**
+ * Network-level failure: DNS, connection refused, timeout, abort.
+ * The request never produced a parseable HTTP response.
+ */
+declare class VCRNetworkError extends VCRError {
+    readonly url: string;
+    readonly kind: "network";
+    constructor(message: string, url: string, options: {
+        cause: unknown;
+    });
 }
 
-export { AVAILABLE_LANGUAGES, type Language, type SaleData, type SaleItem, type Unit, VCRClient, unitsKeys };
+export { AVAILABLE_LANGUAGES, type ApiErrorBody, type ApiErrorIssue, 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, DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, type DepartmentInput, type Discounts, type Language, type LocalizedName, type NewOffer, type Offer, type OfferTitle, type PrepaymentAmount, type PrepaymentDetail, 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 SearchClassifierInput, type SendReceiptToBuyer, TAX_REGIMES, type TaxRegime, type Unit, VCRApiError, VCRClient, type VCRClientOptions, VCRError, VCRNetworkError, VCRValidationError, cashierListItemSchema, cashierListResponseSchema, classifierSearchItemSchema, classifierSearchResponseSchema, createCashierResponseSchema, createDepartmentResponseSchema, createOfferResponseSchema, prepaymentDetailResponseSchema, registerPrepaymentRefundResponseSchema, registerPrepaymentResponseSchema, registerSaleRefundResponseSchema, registerSaleResponseSchema, saleDetailResponseSchema, unitsKeys };