@qrcommunication/viva-local-terminal-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,593 @@
+import { Dispatcher } from 'undici';
+
+/**
+ * Configuration for the Viva.com Local Terminal API.
+ *
+ * Unlike the Viva cloud APIs (api.vivapayments.com, OAuth2), the Local Terminal
+ * API is a PEER-TO-PEER (P2P) protocol: the client talks DIRECTLY to the EFT POS
+ * terminal over the local network. There is therefore:
+ *
+ *   - NO cloud "environment" (demo/production) — the base URL is the terminal's
+ *     own IP address and port, e.g. `https://192.168.1.50:8080`.
+ *   - NO authentication. The official spec states verbatim:
+ *       "In a closed network environment, authentication is not required for
+ *        peer-to-peer communication. [...] eliminating the need to include an
+ *        Authorization tag in the header."
+ *
+ * The terminal serves HTTPS, usually with a self-signed certificate. By default
+ * this SDK VERIFIES TLS. On a closed LAN with a self-signed terminal cert you
+ * typically pass `verifyTls: false` (accepting the LAN-only trust model).
+ */
+
+interface VivaLocalTerminalConfigOptions {
+    /**
+     * The terminal's base URL: scheme + IP + port, e.g.
+     * `https://192.168.1.50:8080`. A trailing slash, if present, is stripped.
+     */
+    terminalBaseUrl: string;
+    /**
+     * TLS certificate verification.
+     *
+     * `true` (default) verifies the terminal's certificate against the system CA
+     * bundle. `false` disables verification, which is the common case for a
+     * self-signed terminal certificate on a trusted closed LAN.
+     */
+    verifyTls?: boolean;
+    /**
+     * Target the ISV (trailing-slash) endpoint variants, e.g. `/pos/v1/sale/`.
+     * The merchant (default) variants use no trailing slash.
+     */
+    useIsvEndpoints?: boolean;
+    /**
+     * Per-request timeout in milliseconds. Terminal interactions are async (they
+     * return PROCESSING immediately), so a short timeout is fine for the
+     * initiating call. Defaults to 30000 (30s).
+     */
+    timeout?: number;
+    /**
+     * Optional `fetch` implementation override (mainly for testing). Defaults to
+     * the platform global `fetch` (Node 18+, browsers, Deno).
+     */
+    fetch?: typeof fetch;
+    /**
+     * Optional undici `Dispatcher` override. When omitted and `verifyTls` is
+     * `false` on Node, an undici `Agent` with `connect.rejectUnauthorized = false`
+     * is created automatically so the self-signed terminal cert is accepted.
+     */
+    dispatcher?: Dispatcher;
+}
+/**
+ * Immutable runtime configuration for the Local Terminal client.
+ */
+declare class VivaLocalTerminalConfig {
+    /** The normalized terminal base URL (no trailing slash). */
+    readonly baseUrl: string;
+    readonly verifyTls: boolean;
+    readonly useIsvEndpoints: boolean;
+    readonly timeout: number;
+    readonly fetch: typeof fetch;
+    readonly dispatcher: Dispatcher | undefined;
+    constructor(options: VivaLocalTerminalConfigOptions);
+    /**
+     * Build the absolute URL for a `/pos/v1/...` endpoint.
+     *
+     * The ISV variants of the endpoints differ only by a trailing slash. When
+     * {@link useIsvEndpoints} is true, a trailing slash is appended to the path
+     * (unless one is already present), matching the spec's `(ISV)` paths.
+     */
+    url(path: string): string;
+}
+
+interface HttpRequestOptions {
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+    signal?: AbortSignal;
+}
+/**
+ * Low-level HTTP client for the Local Terminal (P2P) API.
+ *
+ * Transport model:
+ *   - Requests go DIRECTLY to the terminal on the LAN (base URL = terminal
+ *     IP:port). There is NO cloud endpoint.
+ *   - NO authentication: no Authorization header, no token exchange. The
+ *     terminal trusts any caller on the closed network (per the official spec).
+ *   - HTTPS is served by the terminal, often with a self-signed certificate. On
+ *     Node, when `verifyTls` is `false`, an undici `Agent` with
+ *     `connect.rejectUnauthorized = false` is used so the self-signed cert is
+ *     accepted (the standard `fetch` API has no per-call TLS toggle).
+ *
+ * Error model:
+ *   The API returns JSON on 2xx but a PLAIN STRING body on 400 (e.g.
+ *   "ZeroconfException error message Amount cannot be null"). This client
+ *   decodes JSON when possible and preserves the raw string under `raw`
+ *   otherwise. The thrown {@link ApiError}'s message is that raw text.
+ */
+declare class HttpClient {
+    private readonly config;
+    private readonly dispatcher;
+    constructor(config: VivaLocalTerminalConfig);
+    get<T = unknown>(path: string, options?: Omit<HttpRequestOptions, "body">): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, options?: Omit<HttpRequestOptions, "body">): Promise<T>;
+    private request;
+    private buildUrl;
+    private decodeBody;
+    private buildException;
+    private mergeSignals;
+}
+
+/**
+ * Enumerations for the Viva.com Local Terminal API.
+ *
+ * These mirror the string/numeric values the terminal returns and accepts.
+ */
+/**
+ * The `paymentMethod` accepted by the sale request — the payment method
+ * displayed to the user first by default. The user may still choose an
+ * alternative method on the terminal.
+ *
+ * @see /pos/v1/sale
+ */
+declare enum PaymentMethod {
+    CARD_PRESENT = "CardPresent",
+    IRIS = "Iris"
+}
+/**
+ * The `state` value returned by the Local Terminal API.
+ *
+ * Returned immediately by sale/refund/abort/etc. (PROCESSING, BUSY_ERROR, ...)
+ * and as the terminal/session outcome by GET /pos/v1/sessions/{sessionId}
+ * (SUCCESS, FAILURE).
+ *
+ * @see /pos/v1/sale, /pos/v1/sessions/{sessionId}
+ */
+declare enum SessionState {
+    /** The operation is in progress on the terminal. */
+    PROCESSING = "PROCESSING",
+    /** Another transaction is already in progress on the terminal. */
+    BUSY_ERROR = "BUSY_ERROR",
+    /** The terminal reported a server-side error. */
+    SERVER_ERROR = "SERVER_ERROR",
+    /** The given session id could not be found (abort). */
+    SESSION_NOT_FOUND_ERROR = "SESSION_NOT_FOUND_ERROR",
+    /** The transaction completed successfully (sessions outcome). */
+    SUCCESS = "SUCCESS",
+    /** The transaction completed with an error (sessions outcome). */
+    FAILURE = "FAILURE"
+}
+/**
+ * The `sessionType` returned by the Local Terminal API, indicating which kind
+ * of operation a session represents.
+ *
+ * @see /pos/v1/sale, /pos/v1/refund, /pos/v1/abort, /pos/v1/sessions/{sessionId}
+ */
+declare enum SessionType {
+    /** A sale transaction. */
+    SALE = "SALE",
+    /** A capture (completion) of a pre-authorized sale. */
+    CAPTURE_PREAUTH = "CAPTURE_PREAUTH",
+    /** A refund / cancellation referencing an original transaction. */
+    CANCEL = "CANCEL",
+    /** An unreferenced refund (not linked to an original transaction). */
+    UNREFERENCED_REFUND = "UNREFERENCED_REFUND",
+    /** An abort of an in-progress SALE session. */
+    ABORT = "ABORT"
+}
+/**
+ * Transaction type identifiers returned in transaction / session payloads
+ * (`transactionTypeId`) and accepted as the `transactionTypes` query filter on
+ * GET /pos/v1/transactions.
+ *
+ * @see /pos/v1/transactions, /pos/v1/sessions/{sessionId}
+ */
+declare enum TransactionTypeId {
+    SALE = 5,
+    REFUND = 4,
+    REVERSAL = 7,
+    IRIS_SALE = 60,
+    IRIS_REFUND = 61,
+    IRIS_VOID = 85
+}
+
+/**
+ * Immediate response returned by sale / capture / refund / abort operations.
+ *
+ * The terminal returns this synchronously with `state` typically `PROCESSING`.
+ * Poll {@link SessionResponse} via `sessions.get(sessionId)` for the outcome.
+ */
+interface TransactionResponse {
+    /** Operation state, e.g. PROCESSING, BUSY_ERROR. */
+    state?: SessionState | string;
+    /** The kind of session created, e.g. SALE, CANCEL. */
+    sessionType?: SessionType | string;
+    /** The session id echoed back (the one you passed in). */
+    sessionId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Full session details returned by GET /pos/v1/sessions/{sessionId}.
+ *
+ * `payloadData` is populated only once the transaction has completed (state
+ * SUCCESS or FAILURE).
+ */
+interface SessionResponse {
+    state?: SessionState | string;
+    sessionType?: SessionType | string;
+    sessionId?: string;
+    /** Final transaction payload, present once the session has completed. */
+    payloadData?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Response to AADE FIM control creation (Greek fiscalisation).
+ *
+ * @see /pos/v1/aade-fim-control
+ */
+interface AadeFimControlResponse {
+    status?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * Response to historical transaction retrieval.
+ *
+ * @see /pos/v1/transactions
+ */
+interface TransactionsListResponse {
+    isSuccess?: boolean;
+    transactions?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+/**
+ * Generic device-operation response (`screenControl`, `brightness`).
+ *
+ * @see /pos/v1/awake-lock, /pos/v1/brightness
+ */
+interface DeviceResponse {
+    isSuccess?: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * Device configuration operations on the Local Terminal (P2P) API.
+ *
+ * These control the physical terminal device directly: screen wake/sleep and
+ * display brightness.
+ *
+ * @see /pos/v1/awake-lock, /pos/v1/brightness
+ */
+declare class Device {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Control the device screen / sleep mode — POST /pos/v1/awake-lock.
+     *
+     * @param wakeUpLock When `true`, the device wakes from sleep and the screen
+     *   stays active until the user unlocks it. When `false`, the device reverts
+     *   to its normal sleep behavior.
+     */
+    screenControl(wakeUpLock: boolean): Promise<DeviceResponse>;
+    /**
+     * Adjust the terminal app brightness — POST /pos/v1/brightness.
+     *
+     * @param brightness Value in the range (0, 1], where 1.00 is maximum
+     *   brightness. A value of 0 is NOT allowed.
+     * @throws {RangeError} If `brightness` is not within (0, 1].
+     */
+    brightness(brightness: number): Promise<DeviceResponse>;
+}
+
+/**
+ * Session retrieval on the Local Terminal (P2P) API.
+ *
+ * After a sale/refund/preauth-completion returns `PROCESSING`, poll the session
+ * to obtain the final outcome. The `payloadData` field is populated only once
+ * the transaction has completed (with `state` SUCCESS or FAILURE).
+ *
+ * The ISV variant uses a trailing slash (`/pos/v1/sessions/{id}/`), handled
+ * automatically when `useIsvEndpoints` is enabled.
+ *
+ * @see /pos/v1/sessions/{sessionId}
+ */
+declare class Sessions {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Retrieve a session's full details by its id —
+     * GET /pos/v1/sessions/{sessionId}.
+     */
+    get(sessionId: string): Promise<SessionResponse>;
+}
+
+/**
+ * Parameters for {@link Transactions.sale} — POST /pos/v1/sale.
+ *
+ * Amounts are ALWAYS integers in the currency's minor unit (cents).
+ */
+interface SaleParams {
+    /** Caller-generated transaction session UUID. */
+    sessionId: string;
+    /** Amount to authorize, in cents. */
+    amount: number;
+    /** Free-text merchant reference. */
+    merchantReference?: string;
+    /** Free-text customer reference. */
+    customerTrns?: string;
+    /** Whether the payment is a pre-authorization. */
+    preauth?: boolean;
+    /** Tip amount in cents (not compatible with `preauth`). */
+    tipAmount?: number;
+    /** Default payment method shown first (e.g. "CardPresent"). */
+    paymentMethod?: PaymentMethod | string;
+    /** Whether to show the transaction result on screen. */
+    showTransactionResult?: boolean;
+    /** Whether to show the receipt and result on screen. */
+    showReceipt?: boolean;
+    /** ISO 4217 numeric currency code (merchant currency), e.g. 978 for EUR. */
+    currencyCode?: number;
+    /** Disable surcharge even on eligible cards. */
+    skipSurcharge?: boolean;
+    /** Base64-encoded JSON of extra acquirer metadata. */
+    saleToAcquirerData?: string;
+    /** Max instalments allowed (Greek merchants only). */
+    maxInstalments?: number;
+    /** AADE provider id (Greece). */
+    aadeProviderId?: string;
+    /** AADE provider signature data (Greece). */
+    aadeProviderSignatureData?: string;
+    /** AADE provider signature (Greece). */
+    aadeProviderSignature?: string;
+    /** AADE preloaded flag (Greece). */
+    aadePreloaded?: boolean;
+    /** AADE preloaded expiry duration (Greece). */
+    aadePreloadedDuration?: number;
+    /** Viva Fiscalisation object. */
+    fiscalisationData?: Record<string, unknown>;
+    /** ISV partner / fee / multi-merchant object (ISV endpoints only). */
+    isvDetails?: Record<string, unknown>;
+}
+/**
+ * Parameters for {@link Transactions.capturePreauth} —
+ * POST /pos/v1/preauth-completion.
+ */
+interface CapturePreauthParams {
+    /** Caller-generated transaction session UUID. */
+    sessionId: string;
+    /** Amount to capture, in cents. */
+    amount: number;
+    /** Transaction id of the original pre-authorized sale. */
+    transactionId: string;
+    merchantReference?: string;
+    customerTrns?: string;
+    /** ISO 4217 numeric currency code. */
+    currencyCode?: number;
+    saleToAcquirerData?: string;
+    aadeProviderId?: string;
+    aadeProviderSignatureData?: string;
+    aadeProviderSignature?: string;
+    aadePreloaded?: boolean;
+    aadePreloadedDuration?: number;
+}
+/**
+ * Parameters for {@link Transactions.refund} — POST /pos/v1/refund.
+ *
+ * A referenced refund / cancellation linked to an original transaction.
+ */
+interface RefundParams {
+    /** Caller-generated transaction session UUID. */
+    sessionId: string;
+    /** Amount to refund, in cents. */
+    amount: number;
+    /** Transaction id of the original sale to refund. */
+    transactionId: string;
+    /** Order code of the original sale. */
+    orderCode?: number;
+    /** Short order code (filter helper). */
+    shortOrderCode?: number;
+    merchantReference?: string;
+    customerTrns?: string;
+    currencyCode?: number;
+    showTransactionResult?: boolean;
+    showReceipt?: boolean;
+    /** ISO 8601 lower bound for locating the transaction. */
+    txnDateFrom?: string;
+    /** ISO 8601 upper bound for locating the transaction. */
+    txnDateTo?: string;
+    aadeProviderId?: string;
+    aadeProviderSignatureData?: string;
+    aadeProviderSignature?: string;
+}
+/**
+ * Parameters for {@link Transactions.unreferencedRefund} —
+ * POST /pos/v1/unreferenced-refund.
+ */
+interface UnreferencedRefundParams {
+    /** Caller-generated transaction session UUID. */
+    sessionId: string;
+    /** Amount to refund, in cents. */
+    amount: number;
+    merchantReference?: string;
+    customerTrns?: string;
+    showTransactionResult?: boolean;
+    showReceipt?: boolean;
+    aadeProviderId?: string;
+    aadeProviderSignatureData?: string;
+    aadeProviderSignature?: string;
+    fiscalisationData?: Record<string, unknown>;
+}
+/**
+ * Filters for {@link Transactions.retrieve} — GET /pos/v1/transactions.
+ *
+ * All filters are optional. `transactionTypes` may be a single id or a list.
+ */
+interface RetrieveTransactionsParams {
+    cardNumber?: string;
+    orderCode?: string;
+    transactionTypes?: TransactionTypeId | number | Array<TransactionTypeId | number>;
+    transactionStatus?: string;
+    /** ISO 8601 lower bound. */
+    startDate?: string;
+    /** ISO 8601 upper bound. */
+    endDate?: string;
+    isAadeAutonomouslyOnly?: boolean;
+}
+
+/**
+ * Transaction operations on the Local Terminal (P2P) API.
+ *
+ * Every operation that starts a transaction returns IMMEDIATELY with a `state`
+ * (typically `PROCESSING`) and a `sessionId`. The actual outcome is then polled
+ * via `sessions.get()` once the cardholder has interacted with the terminal.
+ *
+ * Amounts are ALWAYS integers in the currency's minor unit (cents).
+ *
+ * Merchant vs ISV variants: the same methods serve both. Whether a request hits
+ * the ISV trailing-slash path (e.g. `/pos/v1/sale/`) is controlled globally by
+ * `useIsvEndpoints`. ISV sale/refund additionally accept `isvDetails`.
+ *
+ * @see /pos/v1/sale, /pos/v1/preauth-completion, /pos/v1/refund,
+ *      /pos/v1/unreferenced-refund, /pos/v1/abort, /pos/v1/aade-fim-control,
+ *      /pos/v1/transactions
+ */
+declare class Transactions {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Initiate a sale request — POST /pos/v1/sale.
+     *
+     * The terminal displays the amount and waits for the card. Use
+     * `sessions.get()` with the returned `sessionId` to retrieve the final result.
+     */
+    sale(params: SaleParams): Promise<TransactionResponse>;
+    /**
+     * Capture (complete) a previously pre-authorized sale —
+     * POST /pos/v1/preauth-completion.
+     */
+    capturePreauth(params: CapturePreauthParams): Promise<TransactionResponse>;
+    /**
+     * Refund / cancel a transaction by its original transaction id —
+     * POST /pos/v1/refund.
+     */
+    refund(params: RefundParams): Promise<TransactionResponse>;
+    /**
+     * Issue an unreferenced refund (not linked to an original transaction) —
+     * POST /pos/v1/unreferenced-refund.
+     */
+    unreferencedRefund(params: UnreferencedRefundParams): Promise<TransactionResponse>;
+    /**
+     * Abort an in-progress SALE session — POST /pos/v1/abort.
+     */
+    abort(sessionId: string): Promise<TransactionResponse>;
+    /**
+     * Create an AADE FIM control action — POST /pos/v1/aade-fim-control.
+     *
+     * Creates the Echo Message (to fetch the Master Key) and the Control Message
+     * (to create the Session Key), validating the Master Key, KCV and encrypted
+     * Session Key (Greek AADE fiscalisation).
+     *
+     * @param token The FIMAS control token including the AADE token.
+     */
+    aadeFimControl(token: string): Promise<AadeFimControlResponse>;
+    /**
+     * Retrieve historical transactions with optional filters —
+     * GET /pos/v1/transactions.
+     *
+     * `transactionTypes` may be a single id or a list. When an array is passed it
+     * is sent as a comma-separated value.
+     */
+    retrieve(params?: RetrieveTransactionsParams): Promise<TransactionsListResponse>;
+}
+
+type VivaLocalTerminalClientOptions = VivaLocalTerminalConfigOptions;
+/**
+ * Viva.com Local Terminal SDK — main entry point.
+ *
+ * The Local Terminal API is a PEER-TO-PEER (P2P) protocol: this client talks
+ * DIRECTLY to an EFT POS terminal over the local network. There is no Viva cloud
+ * endpoint and no authentication — you address the terminal's own IP and port.
+ *
+ * @example
+ * ```ts
+ * import { VivaLocalTerminalClient } from "@qrcommunication/viva-local-terminal-sdk";
+ * import { randomUUID } from "node:crypto";
+ *
+ * const terminal = new VivaLocalTerminalClient({
+ *   terminalBaseUrl: "https://192.168.1.50:8080",
+ *   // self-signed terminal cert on a closed LAN:
+ *   verifyTls: false,
+ * });
+ *
+ * // Start a sale (amount in cents)
+ * const sessionId = randomUUID();
+ * const res = await terminal.transactions.sale({
+ *   sessionId,
+ *   amount: 1170,        // 11.70 EUR
+ *   currencyCode: 978,   // EUR
+ *   merchantReference: "order-123",
+ * });
+ * // res.state === "PROCESSING"
+ *
+ * // Poll for the result
+ * const session = await terminal.sessions.get(sessionId);
+ * // session.state === "SUCCESS" once the cardholder has paid
+ *
+ * // Control the device
+ * await terminal.device.screenControl(true);
+ * await terminal.device.brightness(0.5);
+ * ```
+ */
+declare class VivaLocalTerminalClient {
+    readonly transactions: Transactions;
+    readonly sessions: Sessions;
+    readonly device: Device;
+    private readonly config;
+    private readonly http;
+    constructor(options: VivaLocalTerminalClientOptions);
+    /** The resolved, immutable configuration in use by this client. */
+    getConfig(): VivaLocalTerminalConfig;
+}
+
+/**
+ * Error model for the Viva.com Local Terminal (P2P) API.
+ *
+ * The Local Terminal API does NOT return structured error codes. On a 400 it
+ * returns a PLAIN STRING body (e.g. "ZeroconfException error message Amount
+ * cannot be null"). The raw body is always preserved so callers can inspect the
+ * exact text the terminal sent back.
+ */
+/**
+ * Shape used to carry whatever the terminal returned on an error. When the body
+ * was JSON it is spread here; when it was a plain string it is preserved under
+ * `raw`.
+ */
+interface VivaErrorBody {
+    message?: string;
+    error?: string;
+    /** The raw, undecoded response body (set when the terminal returns a string). */
+    raw?: string;
+    [key: string]: unknown;
+}
+/**
+ * Base error for every Viva Local Terminal SDK failure.
+ */
+declare class VivaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the terminal returns an HTTP error (4xx/5xx) or when the request
+ * could not reach the terminal at all (httpStatus === 0).
+ *
+ * The Local Terminal API returns a plain string body on 400, so the human
+ * message is that raw string verbatim. Use {@link getErrorText} to retrieve it.
+ */
+declare class ApiError extends VivaError {
+    readonly httpStatus: number;
+    readonly responseBody: VivaErrorBody | null;
+    constructor(message: string, httpStatus: number, responseBody?: VivaErrorBody | null);
+    /**
+     * The error text reported by the terminal, preferring a structured field and
+     * falling back to the raw string body. Returns `null` if nothing was sent.
+     */
+    getErrorText(): string | null;
+}
+
+export { type AadeFimControlResponse, ApiError, type CapturePreauthParams, Device, type DeviceResponse, HttpClient, type HttpRequestOptions, PaymentMethod, type RefundParams, type RetrieveTransactionsParams, type SaleParams, type SessionResponse, SessionState, SessionType, Sessions, type TransactionResponse, TransactionTypeId, Transactions, type TransactionsListResponse, type UnreferencedRefundParams, VivaError, type VivaErrorBody, VivaLocalTerminalClient, type VivaLocalTerminalClientOptions, VivaLocalTerminalConfig, type VivaLocalTerminalConfigOptions };