@stackflow-lab/tef-elgin 1.0.3

package/dist/index.d.cts

@@ -0,0 +1,232 @@
+import { EventEmitter } from 'node:events';
+import koffi from 'koffi';
+
+declare function loadElginDll(dllPath?: string): {
+    GetProdutoTef: koffi.KoffiFunction;
+    GetClientTCP: koffi.KoffiFunction;
+    SetClientTCP: koffi.KoffiFunction;
+    ConfigurarDadosPDV: koffi.KoffiFunction;
+    IniciarOperacaoTEF: koffi.KoffiFunction;
+    RecuperarOperacaoTEF: koffi.KoffiFunction;
+    RealizarPagamentoTEF: koffi.KoffiFunction;
+    RealizarPixTEF: koffi.KoffiFunction;
+    RealizarAdmTEF: koffi.KoffiFunction;
+    ConfirmarOperacaoTEF: koffi.KoffiFunction;
+    FinalizarOperacaoTEF: koffi.KoffiFunction;
+    unload: () => void;
+};
+type ElginDll = ReturnType<typeof loadElginDll>;
+
+/**
+ * Payment operations API — provides dedicated methods for each payment type
+ */
+declare class PaymentApi {
+    private client;
+    constructor(client: Client);
+    /**
+     * PIX payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    pix(amount: string): Promise<void>;
+    /**
+     * Credit card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    credit(amount: string): Promise<void>;
+    /**
+     * Debit card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    debit(amount: string): Promise<void>;
+    /**
+     * Voucher card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    voucher(amount: string): Promise<void>;
+    /**
+     * Fleet card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    fleet(amount: string): Promise<void>;
+    /**
+     * Private label card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    privateLabel(amount: string): Promise<void>;
+    /**
+     * Ask user which card type to use
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    ask(amount: string): Promise<void>;
+}
+
+/**
+ * Administrative operations API
+ */
+declare class AdminApi {
+    private client;
+    constructor(client: Client);
+    /**
+     * Ask user which administrative operation to perform
+     */
+    ask(): Promise<void>;
+    /**
+     * Cancel a previous transaction
+     */
+    cancel(): Promise<void>;
+    /**
+     * Check for pending transactions
+     */
+    pending(): Promise<void>;
+    /**
+     * Reprint last receipt
+     */
+    reprint(): Promise<void>;
+}
+
+interface PdvConfig {
+    pinpadText: string;
+    version: string;
+    storeName: string;
+    storeCode: string;
+    terminalId: string;
+}
+/** Raw JSON returned by the DLL — field names are dictated by Elgin's protocol */
+interface TefResponse {
+    codigo?: number;
+    mensagem?: string;
+    tef?: {
+        retorno?: string;
+        sequencial?: string;
+        automacao_coleta_retorno?: string;
+        automacao_coleta_sequencial?: string;
+        automacao_coleta_tipo?: string;
+        automacao_coleta_opcao?: string;
+        automacao_coleta_mascara?: string;
+        mensagemResultado?: string;
+        comprovanteDiferenciadoLoja?: string;
+        comprovanteDiferenciadoPortador?: string;
+        [key: string]: unknown;
+    };
+}
+/** Card type for payment transactions */
+type CardType = 'ask' | 'credit' | 'debit' | 'voucher' | 'fleet' | 'private-label';
+/** Administrative operation */
+type AdminOp = 'ask' | 'cancel' | 'pending' | 'reprint';
+interface CollectTextEvent {
+    message: string;
+    type: string;
+    mask?: string;
+}
+interface CollectOptionsEvent {
+    message: string;
+    options: string[];
+}
+interface ApprovedEvent {
+    sequenceId: string;
+    needsConfirmation: boolean;
+    acquirerDocument?: string;
+    authorizationCode?: string;
+    transactionDateTime?: string;
+    paymentMethod?: string;
+    merchantId?: string;
+    terminalId?: string;
+    message?: string;
+    cardBrand?: string;
+    merchantName?: string;
+    provider?: string;
+    nsu?: string;
+    maskedPan?: string;
+    result?: string;
+    service?: string;
+    cardType?: string;
+    transaction?: string;
+    uniqueId?: string;
+    totalAmount?: string;
+}
+interface PrintEvent {
+    store: string;
+    customer: string;
+}
+interface QrCodeEvent {
+    data: string;
+}
+interface TefClientEvents {
+    /** Status/display message from the device */
+    display: [message: string];
+    /** Informational message — no user input needed, client continues automatically */
+    waiting: [message: string];
+    /** Requests free-text input from the user */
+    'collect:text': [data: CollectTextEvent];
+    /** Requests option selection from the user */
+    'collect:options': [data: CollectOptionsEvent];
+    /** PIX QR Code available for display */
+    qrcode: [data: QrCodeEvent];
+    /** Receipt ready for printing */
+    print: [data: PrintEvent];
+    /** Transaction approved */
+    approved: [data: ApprovedEvent];
+    /** Transaction declined by the network/bank */
+    declined: [code: string, message: string];
+    /** Confirmation recorded */
+    confirmed: [];
+    /** Session finished */
+    finished: [];
+    /** Technical error (connection, DLL, etc.) */
+    error: [code: string, message: string];
+}
+
+declare class Client extends EventEmitter<TefClientEvents> {
+    private worker;
+    private mockDll;
+    private operationType;
+    private cardType;
+    private adminOp;
+    private collectResolver;
+    private _debugEnabled;
+    private workerPromiseResolve;
+    private workerPromiseReject;
+    /** Payment operations - use methods like payment.pix(), payment.credit(), etc. */
+    readonly payment: PaymentApi;
+    /** Administrative operations - use methods like admin.cancel(), admin.pending(), etc. */
+    readonly admin: AdminApi;
+    constructor(dllPathOrInstance?: string | ElginDll);
+    /**
+     * Creates a new Client instance
+     * @param dllPath - Optional path to the DLL (defaults to C:\Elgin\TEF\E1_Tef01.dll)
+     */
+    static instance(dllPath?: string): Client;
+    /**
+     * Enables debug logging to see all DLL calls, responses, and events
+     */
+    enableDebug(): void;
+    /**
+     * Disables debug logging
+     */
+    disableDebug(): void;
+    private _log;
+    private _sendToWorker;
+    configure(ip: string, port: number, pdv: PdvConfig): Promise<void>;
+    /** @internal */
+    _executePayment(card: CardType, amount: string): Promise<void>;
+    /** @internal */
+    _executePix(amount: string): Promise<void>;
+    /** @internal */
+    _executeAdmin(op: AdminOp): Promise<void>;
+    /** Sends the user's answer to the pending collect request */
+    respond(info: string): void;
+    /** Cancels the pending collect request */
+    cancel(): void;
+    unload(): void;
+    private _run;
+    private _collectLoop;
+    private _callTransaction;
+    private _confirm;
+    private _finalize;
+    private _waitCollect;
+    private _parse;
+    private _nextSeq;
+    private _extractQrCode;
+}
+
+export { AdminApi, type ApprovedEvent, Client, type CollectOptionsEvent, type CollectTextEvent, PaymentApi, type PdvConfig, type PrintEvent, type QrCodeEvent, type TefClientEvents, type TefResponse };

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { EventEmitter } from 'node:events';
+import koffi from 'koffi';
+
+declare function loadElginDll(dllPath?: string): {
+    GetProdutoTef: koffi.KoffiFunction;
+    GetClientTCP: koffi.KoffiFunction;
+    SetClientTCP: koffi.KoffiFunction;
+    ConfigurarDadosPDV: koffi.KoffiFunction;
+    IniciarOperacaoTEF: koffi.KoffiFunction;
+    RecuperarOperacaoTEF: koffi.KoffiFunction;
+    RealizarPagamentoTEF: koffi.KoffiFunction;
+    RealizarPixTEF: koffi.KoffiFunction;
+    RealizarAdmTEF: koffi.KoffiFunction;
+    ConfirmarOperacaoTEF: koffi.KoffiFunction;
+    FinalizarOperacaoTEF: koffi.KoffiFunction;
+    unload: () => void;
+};
+type ElginDll = ReturnType<typeof loadElginDll>;
+
+/**
+ * Payment operations API — provides dedicated methods for each payment type
+ */
+declare class PaymentApi {
+    private client;
+    constructor(client: Client);
+    /**
+     * PIX payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    pix(amount: string): Promise<void>;
+    /**
+     * Credit card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    credit(amount: string): Promise<void>;
+    /**
+     * Debit card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    debit(amount: string): Promise<void>;
+    /**
+     * Voucher card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    voucher(amount: string): Promise<void>;
+    /**
+     * Fleet card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    fleet(amount: string): Promise<void>;
+    /**
+     * Private label card payment
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    privateLabel(amount: string): Promise<void>;
+    /**
+     * Ask user which card type to use
+     * @param amount - Amount in format "10.00" or "1000" (cents)
+     */
+    ask(amount: string): Promise<void>;
+}
+
+/**
+ * Administrative operations API
+ */
+declare class AdminApi {
+    private client;
+    constructor(client: Client);
+    /**
+     * Ask user which administrative operation to perform
+     */
+    ask(): Promise<void>;
+    /**
+     * Cancel a previous transaction
+     */
+    cancel(): Promise<void>;
+    /**
+     * Check for pending transactions
+     */
+    pending(): Promise<void>;
+    /**
+     * Reprint last receipt
+     */
+    reprint(): Promise<void>;
+}
+
+interface PdvConfig {
+    pinpadText: string;
+    version: string;
+    storeName: string;
+    storeCode: string;
+    terminalId: string;
+}
+/** Raw JSON returned by the DLL — field names are dictated by Elgin's protocol */
+interface TefResponse {
+    codigo?: number;
+    mensagem?: string;
+    tef?: {
+        retorno?: string;
+        sequencial?: string;
+        automacao_coleta_retorno?: string;
+        automacao_coleta_sequencial?: string;
+        automacao_coleta_tipo?: string;
+        automacao_coleta_opcao?: string;
+        automacao_coleta_mascara?: string;
+        mensagemResultado?: string;
+        comprovanteDiferenciadoLoja?: string;
+        comprovanteDiferenciadoPortador?: string;
+        [key: string]: unknown;
+    };
+}
+/** Card type for payment transactions */
+type CardType = 'ask' | 'credit' | 'debit' | 'voucher' | 'fleet' | 'private-label';
+/** Administrative operation */
+type AdminOp = 'ask' | 'cancel' | 'pending' | 'reprint';
+interface CollectTextEvent {
+    message: string;
+    type: string;
+    mask?: string;
+}
+interface CollectOptionsEvent {
+    message: string;
+    options: string[];
+}
+interface ApprovedEvent {
+    sequenceId: string;
+    needsConfirmation: boolean;
+    acquirerDocument?: string;
+    authorizationCode?: string;
+    transactionDateTime?: string;
+    paymentMethod?: string;
+    merchantId?: string;
+    terminalId?: string;
+    message?: string;
+    cardBrand?: string;
+    merchantName?: string;
+    provider?: string;
+    nsu?: string;
+    maskedPan?: string;
+    result?: string;
+    service?: string;
+    cardType?: string;
+    transaction?: string;
+    uniqueId?: string;
+    totalAmount?: string;
+}
+interface PrintEvent {
+    store: string;
+    customer: string;
+}
+interface QrCodeEvent {
+    data: string;
+}
+interface TefClientEvents {
+    /** Status/display message from the device */
+    display: [message: string];
+    /** Informational message — no user input needed, client continues automatically */
+    waiting: [message: string];
+    /** Requests free-text input from the user */
+    'collect:text': [data: CollectTextEvent];
+    /** Requests option selection from the user */
+    'collect:options': [data: CollectOptionsEvent];
+    /** PIX QR Code available for display */
+    qrcode: [data: QrCodeEvent];
+    /** Receipt ready for printing */
+    print: [data: PrintEvent];
+    /** Transaction approved */
+    approved: [data: ApprovedEvent];
+    /** Transaction declined by the network/bank */
+    declined: [code: string, message: string];
+    /** Confirmation recorded */
+    confirmed: [];
+    /** Session finished */
+    finished: [];
+    /** Technical error (connection, DLL, etc.) */
+    error: [code: string, message: string];
+}
+
+declare class Client extends EventEmitter<TefClientEvents> {
+    private worker;
+    private mockDll;
+    private operationType;
+    private cardType;
+    private adminOp;
+    private collectResolver;
+    private _debugEnabled;
+    private workerPromiseResolve;
+    private workerPromiseReject;
+    /** Payment operations - use methods like payment.pix(), payment.credit(), etc. */
+    readonly payment: PaymentApi;
+    /** Administrative operations - use methods like admin.cancel(), admin.pending(), etc. */
+    readonly admin: AdminApi;
+    constructor(dllPathOrInstance?: string | ElginDll);
+    /**
+     * Creates a new Client instance
+     * @param dllPath - Optional path to the DLL (defaults to C:\Elgin\TEF\E1_Tef01.dll)
+     */
+    static instance(dllPath?: string): Client;
+    /**
+     * Enables debug logging to see all DLL calls, responses, and events
+     */
+    enableDebug(): void;
+    /**
+     * Disables debug logging
+     */
+    disableDebug(): void;
+    private _log;
+    private _sendToWorker;
+    configure(ip: string, port: number, pdv: PdvConfig): Promise<void>;
+    /** @internal */
+    _executePayment(card: CardType, amount: string): Promise<void>;
+    /** @internal */
+    _executePix(amount: string): Promise<void>;
+    /** @internal */
+    _executeAdmin(op: AdminOp): Promise<void>;
+    /** Sends the user's answer to the pending collect request */
+    respond(info: string): void;
+    /** Cancels the pending collect request */
+    cancel(): void;
+    unload(): void;
+    private _run;
+    private _collectLoop;
+    private _callTransaction;
+    private _confirm;
+    private _finalize;
+    private _waitCollect;
+    private _parse;
+    private _nextSeq;
+    private _extractQrCode;
+}
+
+export { AdminApi, type ApprovedEvent, Client, type CollectOptionsEvent, type CollectTextEvent, PaymentApi, type PdvConfig, type PrintEvent, type QrCodeEvent, type TefClientEvents, type TefResponse };