@reservation-studio/electron-types

TypeScript type definitions for the Reservation.Studio Electron application.

Installation

npm install @reservation-studio/electron-types

Overview

This package provides TypeScript type definitions for the Reservation.Studio Electron application. It includes interfaces and enums for working with:

• Certificate management
• XML signing
• HTTP requests
• Fiscal device operations
• Application environment and version information

API Reference

ReservationStudioElectron

The main API object exposed by the Electron application. It's available in the renderer process as window.ReservationStudioElectron.

import { ReservationStudioElectron } from '@reservation-studio/electron-types';

// Example usage
const version = await ReservationStudioElectron.version();

Certificates

Methods for working with certificates:

// List all available certificates
const certificates = await ReservationStudioElectron.certificates.list();

// Validate a certificate PIN
const isValid = await ReservationStudioElectron.certificates.isValidPin(
  slot,
  pin
);

XML Signing

Methods for signing XML documents:

// Sign an XML document
const signedXml = await ReservationStudioElectron.xml.sign(xml, slot, pin);

HTTP Requests

Methods for making HTTP requests:

// Make a GET request
const response = await ReservationStudioElectron.http.get(url, {
  headers: { 'Content-Type': 'application/json' },
  timeout: 5000,
  params: { key: 'value' }
});

// Make a POST request
const response = await ReservationStudioElectron.http.post(url, data, {
  headers: { 'Content-Type': 'application/json' }
});

Application Information

Methods for getting application information:

// Get application version
const version = await ReservationStudioElectron.version();

// Get application environment
const environment = await ReservationStudioElectron.environment();

// Reload the application window
await ReservationStudioElectron.reload();

Fiscal Devices

Methods for working with fiscal devices:

// List all available fiscal devices
const devices = await ReservationStudioElectron.fiscalDevices.list();

// Select a deviceId for each call
const deviceId = devices[0].deviceId;

// Print a fiscal receipt
const response = await ReservationStudioElectron.fiscalDevices.printReceipt(
  {
    operator: {
      number: 1,
      password: '1'
    },
    uniqueSaleNumber: '1',
    items: [
      {
        name: 'Product 1',
        unitPrice: 10.0,
        quantity: 1,
        vatGroup: FiscalVATGroup.A
      }
    ],
    payments: [
      {
        type: FiscalPaymentType.CASH,
        amount: 10.0
      }
    ]
  },
  deviceId
);

// Print non-fiscal receipt
await ReservationStudioElectron.fiscalDevices.printNonFiscalReceipt(
  {
    operator: {
      number: 1,
      password: '1'
    },
    items: [
      {
        name: 'Service',
        unitPrice: 5.0,
        quantity: 1,
        vatGroup: FiscalVATGroup.A
      }
    ]
  },
  deviceId
);

// Get the last fiscal memory record
const lastRecord =
  await ReservationStudioElectron.fiscalDevices.getLastFiscalRecord(deviceId);

// Get the fiscal device status
const status =
  await ReservationStudioElectron.fiscalDevices.getStatus(deviceId);

// Print X report (daily report without reset)
await ReservationStudioElectron.fiscalDevices.printXReport(deviceId);

// Print Z report (daily report with reset)
await ReservationStudioElectron.fiscalDevices.printZReport(deviceId);

// Print duplicate of last receipt
await ReservationStudioElectron.fiscalDevices.printDuplicate(deviceId);

// Deposit money to cash register
await ReservationStudioElectron.fiscalDevices.depositMoney(100, deviceId);

// Withdraw money from cash register
await ReservationStudioElectron.fiscalDevices.withdrawMoney(50, deviceId);

// Get current cash amount in register
const cashAmount =
  await ReservationStudioElectron.fiscalDevices.getCashAmount(deviceId);

// Set date and time on fiscal device
await ReservationStudioElectron.fiscalDevices.setDateTime(new Date(), deviceId);

// Get date and time from fiscal device
const deviceDateTime =
  await ReservationStudioElectron.fiscalDevices.getDateTime(deviceId);

// Run diagnostics test
const diagnosticsResult =
  await ReservationStudioElectron.fiscalDevices.runDiagnostics(deviceId, {
    operator: {
      number: 1,
      password: '0000',
      code: 'OP01' // optional
    },
    amount: 1,
    vatGroup: FiscalVATGroup.A,
    itemName: 'Diagnostic item'
  });

// Print reversal receipt
const reversalResponse =
  await ReservationStudioElectron.fiscalDevices.printReversalReceipt(
    {
      operator: {
        number: 1,
        password: '0000'
      },
      uniqueSaleNumber: '1',
      reason: 'refund', // or 'void', 'tax-base-reduction'
      originalReceiptNumber: '12345',
      originalReceiptDateTime: new Date('2023-01-01T10:00:00'),
      originalFiscalMemorySerialNumber: 'FM12345678',
      items: [
        {
          name: 'Returned Item',
          unitPrice: 10.0,
          quantity: 1,
          vatGroup: FiscalVATGroup.A
        }
      ],
      payments: [
        {
          type: FiscalPaymentType.CASH,
          amount: 10.0
        }
      ]
    },
    deviceId
  );

Interfaces

ApiInterface

The main interface that defines the structure of the ReservationStudioElectron object.

CertificateInfo

interface CertificateInfo {
  slot: number;
  name: string;
  serialNumber: string;
}

HttpResponse

interface HttpResponse {
  status: number;
  headers: Record<string, string>;
  data: any;
  error: boolean;
}

HttpOptions

interface HttpOptions {
  headers?: Record<string, string>;
  timeout?: number;
  params?: Record<string, string>;
}

OperatorInfo

interface OperatorInfo {
  number: number;
  password: string;
  code?: string;
}

FiscalReceipt

interface FiscalReceipt {
  operator: OperatorInfo;
  uniqueSaleNumber: string; // numeric string up to 7 digits
  items: FiscalReceiptItem[];
  payments: FiscalPayment[];
  client?: FiscalClient;
}

NonFiscalReceipt

interface NonFiscalReceipt {
  operator: OperatorInfo;
  items: FiscalReceiptItem[];
  payments?: FiscalPayment[];
  client?: FiscalClient;
}

FiscalReceiptItem

interface FiscalReceiptItem {
  name: string;
  unitPrice: number;
  quantity: number;
  vatGroup: FiscalVATGroup;
  discount?: number;
}

FiscalPayment

interface FiscalPayment {
  type: FiscalPaymentType;
  amount: number;
}

FiscalPaymentType

enum FiscalPaymentType {
  CASH = 'cash',
  CARD = 'card',
  CHECK = 'check',
  TRANSFER = 'transfer'
}

FiscalVATGroup

enum FiscalVATGroup {
  A = '1', // 20%
  B = '2', // 9%
  C = '3', // 0%
  D = '4', // Exempt
  E = '5', // Special rate 1
  F = '6', // Special rate 2
  G = '7', // Special rate 3
  H = '8' // Special rate 4
}

FiscalClient

interface FiscalClient {
  name: string;
  address?: string;
  taxNumber?: string;
  vatNumber?: string;
}

FiscalMemoryRecord

interface FiscalMemoryRecord {
  number: string;
  date: Date;
  total: number;
}

FiscalDeviceStatus

interface FiscalDeviceStatus {
  connected: boolean;
  paperStatus: PaperStatus;
  fiscalMemoryFull: boolean;
  fiscalReceiptOpen: boolean;
  nonFiscalReceiptOpen: boolean;
  readyToPrint: boolean;
  messages: FiscalResponseMessage[];
}

enum PaperStatus {
  Ok = 'ok',
  Low = 'low',
  Out = 'out'
}

FiscalResponseMessage

interface FiscalResponseMessage {
  type: 'info' | 'warning' | 'error';
  code?: string;
  text: string;
}

Fiscal IPC Errors

Fiscal IPC calls throw a structured FiscalDeviceErrorPayload on failure. Consumers should display the payload message and use optional details, status, and validationErrors for diagnostics. Because Electron IPC serializes thrown values, payloads are encoded as JSON in the error message when crossing the renderer boundary.

ReversalReceipt

interface ReversalReceipt extends FiscalReceipt {
  reason: ReversalReason;
  originalReceiptNumber: string;
  originalReceiptDateTime: Date;
  originalFiscalMemorySerialNumber: string;
}

FiscalDeviceDiagnosticsOptions

interface FiscalDeviceDiagnosticsOptions {
  operator: OperatorInfo;
  amount?: number;
  vatGroup?: FiscalVATGroup;
  itemName?: string;
}

ReversalReason

enum ReversalReason {
  VOID = 'void',
  REFUND = 'refund',
  TAX_BASE_REDUCTION = 'tax-base-reduction'
}

EnvironmentEnum

enum EnvironmentEnum {
  LOCAL = 'local',
  STAGING = 'staging',
  PRODUCTION = 'production'
}

License

Proprietary - Reservation.Studio