@reservation-studio/electron-types/README.md

TypeScript типове за ReservationStudioElectron

# @reservation-studio/electron-types

TypeScript type definitions for the Reservation.Studio Electron application.

## Installation

```bash
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`.

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

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

### Certificates

Methods for working with certificates:

```typescript
// 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:

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

### HTTP Requests

Methods for making HTTP requests:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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

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

### HttpResponse

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

### HttpOptions

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

### OperatorInfo

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

### FiscalReceipt

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

### NonFiscalReceipt

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

### FiscalReceiptItem

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

### FiscalPayment

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

### FiscalPaymentType

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

### FiscalVATGroup

```typescript
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

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

### FiscalMemoryRecord

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

### FiscalDeviceStatus

```typescript
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

```typescript
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

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

### FiscalDeviceDiagnosticsOptions

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

### ReversalReason

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

### EnvironmentEnum

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

## License

Proprietary - Reservation.Studio