### Complete Loyalty Application Example in JavaScript

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

A full loyalty system application demonstrating multiple API features. It integrates with the Poster POS system to manage customer loyalty points, display customer information, and apply bonuses to orders. This example utilizes React for the UI and Poster's API for data retrieval and manipulation.

```javascript
import React from 'react';

export default class LoyaltyApp extends React.Component {
    constructor(props) {
        super(props);
        this.state = {
            currentClient: null,
            currentOrder: null,
            clientGroups: [],
        };
    }

    componentDidMount() {
        // Add button to order screen
        Poster.interface.showApplicationIconAt({
            order: 'Loyalty Points',
        });

        // Subscribe to events
        Poster.on('applicationIconClicked', this.handleButtonClick);
        Poster.on('beforeOrderClose', this.handleBeforeClose);

        // Load client groups
        this.loadClientGroups();
    }

    loadClientGroups = () => {
        Poster.makeApiRequest('clients.getGroups', { method: 'get' }, (groups) => {
            if (groups) {
                this.setState({
                    clientGroups: groups.filter(g => parseInt(g.delete) === 0)
                });
            }
        });
    };

    handleButtonClick = async (data) => {
        if (data.place === 'order') {
            const orderData = await Poster.orders.getActive();

            if (orderData.order?.clientId) {
                const client = await Poster.clients.get(Number(orderData.order.clientId));
                this.setState({
                    currentClient: client,
                    currentOrder: orderData.order
                });
            }

            Poster.interface.popup({
                width: 600,
                height: 400,
                title: 'Customer Loyalty'
            });
        }
    };

    handleBeforeClose = async (data, next) => {
        this.nextCallback = next;
        const orderData = await Poster.orders.getActive();

        if (orderData.order?.clientId) {
            const client = await Poster.clients.get(Number(orderData.order.clientId));

            if (client && parseFloat(client.bonus) > 0) {
                this.setState({
                    currentClient: client,
                    currentOrder: orderData.order
                });
                Poster.interface.popup({
                    width: 500,
                    height: 300,
                    title: 'Redeem Points'
                });
                return;
            }
        }

        next();
    };

    applyBonus = (amount) => {
        const { currentOrder } = this.state;
        Poster.orders.setOrderBonus(currentOrder.id, parseFloat(amount));
        Poster.interface.closePopup();
        this.nextCallback();
    };

    render() {
        const { currentClient, currentOrder } = this.state;

        if (!currentClient) {
            return <div>No customer assigned to order</div>;
        }

        return (
            <div>
                <h3>{currentClient.firstname} {currentClient.lastname}</h3>
                <p>Available bonus: {currentClient.bonus}</p>
                <button onClick={() => this.applyBonus(currentClient.bonus)}>
                    Redeem All Points
                </button>
            </div>
        );
    }
}

```

--------------------------------

### GET /devices

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Retrieves all connected devices of a specific type, such as printers or payment terminals.

```APIDOC
## GET /devices

### Description
Retrieves all connected devices of a specific type (printers, payment terminals, etc.).

### Method
GET

### Endpoint
/devices

### Parameters
#### Query Parameters
- **type** (string) - Required - The type of device to retrieve (e.g., 'printer', 'payTerminal').

### Request Example
```javascript
// Get all printers
const getAllPrinters = async () => {
    const printers = await Poster.devices.getAll({ type: 'printer' });

    printers.forEach(printer => {
        console.log('Printer:', printer.name);
        console.log('IP:', printer.ip);
        console.log('Line length:', printer.textLineLength);
    });

    return printers;
};

// Get all payment terminals
const getAllPaymentTerminals = async () => {
    const terminals = await Poster.devices.getAll({ type: 'payTerminal' });

    // Filter for online terminals only
    const onlineTerminals = terminals.filter(t => t.online && !t.hidden);

    return onlineTerminals;
};
```

### Response
#### Success Response (200)
- **devices** (array) - An array of device objects.
  - **name** (string) - The name of the device.
  - **ip** (string) - The IP address of the device.
  - **textLineLength** (integer) - The number of characters per line for printing.
  - **online** (boolean) - Indicates if the device is online.
  - **hidden** (boolean) - Indicates if the device is hidden.

#### Response Example
```json
{
  "devices": [
    {
      "id": "device-123",
      "name": "Kitchen Printer",
      "type": "printer",
      "ip": "192.168.1.100",
      "textLineLength": 32,
      "online": true,
      "hidden": false
    }
  ]
}
```
```

--------------------------------

### Get Product Information with Tax Details (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Fetches complete product information, including tax settings like tax type, value, and name. This function demonstrates how to access and log these details. It utilizes the Poster.products.get method.

```javascript
const getProductWithTax = async (productId) => {
    const product = await Poster.products.get(productId);

    console.log('Product name:', product.name);
    console.log('Price:', product.price);
    console.log('Tax type:', product.taxType);  // 1=Sales Tax, 2=Turnover, 3=VAT
    console.log('Tax value:', product.taxValue);
    console.log('Tax name:', product.taxName);

    return product;
};
```

--------------------------------

### Create New Customer - JavaScript

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Creates a new customer in the Poster system with provided data including name, phone, group ID, and an initial bonus. It logs the ID of the newly created customer and returns the customer object. An example flow to find or create a customer is also included.

```javascript
const createNewCustomer = async (customerData) => {
    const newCustomer = await Poster.clients.create({
        client: {
            client_name: customerData.name,
            phone: customerData.phone,
            client_sex: 1,  // 1 = male, 2 = female
            client_groups_id_client: customerData.groupId,
            bonus: 2000,  // Initial bonus in cents (20.00)
        }
    });

    console.log('Created customer with ID:', newCustomer.id);
    return newCustomer;
};

const findOrCreateCustomer = async (order, customerInfo) => {
    const result = await Poster.clients.find({ searchVal: customerInfo.phone });

    if (result?.foundClients?.length > 0) {
        return result.foundClients[0];
    }

    return await Poster.clients.create({
        client: {
            client_name: customerInfo.name,
            phone: customerInfo.phone,
            client_groups_id_client: customerInfo.groupId,
            bonus: 2000,
        }
    });
};
```

--------------------------------

### Make Authenticated API Request (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Performs authenticated requests to the Poster API. This example shows how to retrieve client groups and filter out deleted ones. It requires the Poster.makeApiRequest method and processes a callback with the API response.

```javascript
const getClientGroups = () => {
    Poster.makeApiRequest('clients.getGroups', { method: 'get' }, (groups) => {
        if (groups) {
            // Filter out deleted groups
            const activeGroups = groups.filter(g => parseInt(g.delete) === 0);
            console.log('Active client groups:', activeGroups);
        }
    });
};
```

--------------------------------

### Get Full Product Name with Variations (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Retrieves the complete product name, including any applied modifiers and variations. This is useful for displaying full product details in orders. It relies on the Poster.products.getFullName method.

```javascript
const getOrderProductDetails = async (order) => {
    const products = [];

    for (const prodId in order.products) {
        const product = order.products[prodId];
        const fullProduct = await Poster.products.getFullName(product);
        products.push(fullProduct);
    }

    return products;
};
```

--------------------------------

### Apply Bonus Discount to Order - JavaScript

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Applies a specified bonus or discount amount to an order using its ID. The function parses the bonus amount to a float and logs the action. It also includes an example of redeeming customer loyalty points, ensuring the bonus does not exceed the order total.

```javascript
const applyBonusDiscount = (orderId, bonusAmount) => {
    const bonus = parseFloat(bonusAmount);
    Poster.orders.setOrderBonus(orderId, bonus);
    console.log(`Applied ${bonus} bonus to order ${orderId}`);
};

const redeemLoyaltyPoints = (order, customer) => {
    const availableBonus = parseFloat(customer.bonus) || 0;
    const orderTotal = parseFloat(order.total);

    const bonusToApply = Math.min(availableBonus, orderTotal);
    Poster.orders.setOrderBonus(order.id, bonusToApply);

    Poster.interface.closePopup();
};
```

--------------------------------

### Assign Client to Order - JavaScript

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Assigns a client or customer to a specified order using the order ID and client ID. It also includes an example of processing a customer by finding them via phone number and then assigning them to an order.

```javascript
const assignCustomerToOrder = (orderId, clientId) => {
    Poster.orders.setOrderClient(orderId, clientId);
    console.log(`Client ${clientId} assigned to order ${orderId}`);
};

const processCustomer = async (order, phone) => {
    const result = await Poster.clients.find({ searchVal: phone });

    if (result.foundClients && result.foundClients.length > 0) {
        const client = result.foundClients[0];
        Poster.orders.setOrderClient(order.id, client.id);
    }
};
```

--------------------------------

### Get Active Order Details - JavaScript

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Retrieves the currently active order with all its details including ID, name, subtotal, total, products, client ID, and start date. This function asynchronously fetches order data and logs key information if an order is found.

```javascript
const getCurrentOrderDetails = async () => {
    const data = await Poster.orders.getActive();

    if (data.order) {
        const order = data.order;
        console.log('Order ID:', order.id);
        console.log('Order name:', order.orderName);
        console.log('Subtotal:', order.subtotal);
        console.log('Total:', order.total);
        console.log('Products:', order.products);
        console.log('Client ID:', order.clientId);
        console.log('Date started:', order.dateStart);

        return order;
    }

    return null;
};
```

--------------------------------

### Get Customer Details by ID - JavaScript

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Retrieves the details of a specific customer using their unique ID. It logs the customer's name, card number, discount percentage, bonus balance, and total purchase sum. The function returns the customer object if found, otherwise null.

```javascript
const getCustomerDetails = async (clientId) => {
    const customer = await Poster.clients.get(Number(clientId));

    if (customer) {
        console.log('Customer name:', customer.firstname, customer.lastname);
        console.log('Card number:', customer.cardNumber);
        console.log('Discount:', customer.discount, '%');
        console.log('Bonus balance:', customer.bonus);
        console.log('Total purchases:', customer.totalPayedSum);
    }

    return customer;
};
```

--------------------------------

### Poster.clients.create

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Creates a new customer in the Poster system. Allows for adding new clients with their initial details.

```APIDOC
## POST /clients

### Description
Creates a new customer in the Poster system.

### Method
POST

### Endpoint
/clients

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client** (object) - Required - Object containing the new client's details.
  - **client_name** (string) - Required - The full name of the client.
  - **phone** (string) - Required - The client's phone number.
  - **client_sex** (integer) - Optional - The sex of the client (1 for male, 2 for female).
  - **client_groups_id_client** (integer) - Optional - The ID of the client group.
  - **bonus** (float) - Optional - Initial bonus amount for the client.

### Request Example
```json
{
  "client": {
    "client_name": "Jane Doe",
    "phone": "+1122334455",
    "client_sex": 2,
    "client_groups_id_client": 1,
    "bonus": 20.00
  }
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the newly created client.

#### Response Example
```json
{
  "id": 999
}
```
```

--------------------------------

### Access Application Settings and Extras (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Provides access to application configuration and any extra parameters passed during initialization. This snippet shows how to retrieve custom tokens or API keys from the extras object. It uses Poster.settings.

```javascript
const initializeApp = () => {
    const extras = Poster.settings.extras || {};

    // Access custom tokens or configuration
    const posterToken = extras.posterToken;
    const apiKey = extras.apiKey;

    console.log('App initialized with settings:', Poster.settings);
};
```

--------------------------------

### Interface API: showApplicationIconAt

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Adds custom application buttons to various locations within the Poster interface, such as the order, settings, and payment screens.

```APIDOC
## POST /interface/showApplicationIconAt

### Description
Adds custom application buttons to different locations in the Poster interface, including the order screen, settings/functions screen, and payment screen.

### Method
POST

### Endpoint
/interface/showApplicationIconAt

### Parameters
#### Request Body
- **functions** (string) - Optional - Text for the button in the settings/functions screen.
- **order** (string) - Optional - Text for the button in the order screen.
- **payment** (string) - Optional - Text for the button in the payment screen.

### Request Example
```json
{
  "functions": "Settings Button",
  "order": "Loyalty App",
  "payment": "Custom Payment"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### POST /devices/payTerminal

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Creates a new payment terminal device programmatically and configures it for operation.

```APIDOC
## POST /devices/payTerminal

### Description
Creates a new payment terminal device programmatically.

### Method
POST

### Endpoint
/devices/payTerminal

### Parameters
#### Request Body
- **name** (string) - Required - The name for the new payment terminal.

### Request Example
```javascript
// Create and configure a payment terminal
const setupPaymentTerminal = async () => {
    const device = await Poster.devices.createPayTerminal({
        name: "Verifone Terminal"
    });

    await device.setOnline();
    await device.setAuth();

    // Subscribe to payment events
    device.on('makePayment', handlePayment);
    device.on('revertPayment', handleRefund);
    device.on('x-report', handleXReport);
    device.on('z-report', handleZReport);
    device.on('interrupt', handleInterrupt);

    return device;
};
```

### Response
#### Success Response (201)
- **device** (object) - The newly created payment terminal device object.
  - **id** (string) - The unique identifier of the device.
  - **name** (string) - The name of the device.
  - **type** (string) - The type of the device ('payTerminal').
  - **online** (boolean) - Indicates if the device is online.
  - **hidden** (boolean) - Indicates if the device is hidden.

#### Response Example
```json
{
  "device": {
    "id": "payterminal-456",
    "name": "Verifone Terminal",
    "type": "payTerminal",
    "online": false,
    "hidden": false
  }
}
```
```

--------------------------------

### Poster.clients.get

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Retrieves a specific customer by their ID. Provides detailed information about a single client.

```APIDOC
## GET /clients/{clientId}

### Description
Retrieves a specific customer by their ID.

### Method
GET

### Endpoint
/clients/{clientId}

### Parameters
#### Path Parameters
- **clientId** (integer) - Required - The unique identifier of the client to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{ 
  "clientId": 678 
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the client.
- **firstname** (string) - The first name of the client.
- **lastname** (string) - The last name of the client.
- **cardNumber** (string) - The client's card number.
- **discount** (float) - The client's discount percentage.
- **bonus** (float) - The client's current bonus balance.
- **totalPayedSum** (float) - The total amount paid by the client.

#### Response Example
```json
{
  "id": 678,
  "firstname": "John",
  "lastname": "Doe",
  "cardNumber": "1234567890",
  "discount": 5.0,
  "bonus": 50.00,
  "totalPayedSum": 1200.50
}
```
```

--------------------------------

### Poster.clients.find

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Searches for customers by phone number, name, or card number. Returns a list of matching clients.

```APIDOC
## GET /clients/find

### Description
Searches for customers by phone number, name, or card number.

### Method
GET

### Endpoint
/clients/find

### Parameters
#### Path Parameters
None

#### Query Parameters
- **searchVal** (string) - Required - The value to search for (phone number, name, or card number).

#### Request Body
None

### Request Example
```json
{
  "searchVal": "+1234567890"
}
```

### Response
#### Success Response (200)
- **foundClients** (array) - A list of client objects that match the search criteria.
  - **id** (integer) - The unique identifier of the client.
  - **firstname** (string) - The first name of the client.
  - **lastname** (string) - The last name of the client.
  - **bonus** (float) - The current bonus balance of the client.
  - **totalPayedSum** (float) - The total amount paid by the client.

#### Response Example
```json
{
  "foundClients": [
    {
      "id": 678,
      "firstname": "John",
      "lastname": "Doe",
      "bonus": 50.00,
      "totalPayedSum": 1200.50
    }
  ]
}
```
```

--------------------------------

### Interface API: scanBarcode

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Opens the device's camera to scan QR codes or barcodes, returning the decoded value.

```APIDOC
## POST /interface/scanBarcode

### Description
Opens the device camera to scan QR codes or barcodes and returns the scanned value.

### Method
POST

### Endpoint
/interface/scanBarcode

### Parameters
No parameters required.

### Request Example
```json
{} 
```

### Response
#### Success Response (200)
- **barcode** (string) - The decoded value from the scanned barcode or QR code.

#### Response Example
```json
{
  "barcode": "1234567890ABCDEF"
}
```
```

--------------------------------

### Interface API: popup

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Displays a modal popup window containing custom content, typically a React component, with specified dimensions and a title.

```APIDOC
## POST /interface/popup

### Description
Displays a popup window with custom content from your application. The popup renders your React component inside a modal dialog.

### Method
POST

### Endpoint
/interface/popup

### Parameters
#### Request Body
- **width** (number|string) - Required - Width of the popup in pixels or as a percentage string (e.g., '80%').
- **height** (number) - Required - Height of the popup in pixels.
- **title** (string) - Required - The title displayed in the popup header.

### Request Example
```json
{
  "width": 600,
  "height": 400,
  "title": "My Custom Application"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Create New Payment Terminal

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Programmatically creates a new payment terminal device. This function initializes the terminal, sets it to an online state, and configures authentication. It also subscribes to various payment-related events, such as making payments, handling refunds, and generating reports.

```javascript
const setupPaymentTerminal = async () => {
    const device = await Poster.devices.createPayTerminal({
        name: "Verifone Terminal"
    });

    await device.setOnline();
    await device.setAuth();

    // Subscribe to payment events
    device.on('makePayment', handlePayment);
    device.on('revertPayment', handleRefund);
    device.on('x-report', handleXReport);
    device.on('z-report', handleZReport);
    device.on('interrupt', handleInterrupt);

    return device;
};
```

--------------------------------

### Device Print Methods

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Methods for printing formatted receipts and plain text to connected printers.

```APIDOC
## Device Print Methods

### Description
Print receipts and text to connected printers.

### Method: `printOrderReceipt`
Prints a formatted order receipt to a specified printer.

**Parameters:**
- **device** (object) - The printer device object.
- **order** (object) - The order object containing details to print.
  - **products** (object) - An object where keys are product IDs and values are product details.
  - **orderName** (string) - The name or number of the order.
  - **dateStart** (string) - The start date/time of the order.
  - **subtotal** (number) - The total amount of the order.

### Method: `printText`
Prints raw text to a specified printer.

**Parameters:**
- **device** (object) - The printer device object.
- **text** (string) - The text content to print, can include newline characters (`\n`).

### Request Example (Print Order Receipt)
```javascript
// Print formatted order receipt
const printOrderReceipt = async (device, order) => {
    // Get product details with full names
    let products = Object.values(order.products);
    products = await Poster.products.getFullName(products);

    // Using receipt library for formatting
    receipt.config.width = device.textLineLength || 30;
    receipt.config.currency = '$';

    const output = receipt.create([
        {
            type: 'properties',
            lines: [
                { name: 'Order Number', value: order.orderName },
                { name: 'Date', value: order.dateStart },
            ],
        },
        {
            type: 'table',
            lines: products.map(p => ({
                item: p.name,
                qty: p.count,
                cost: p.price,
            })),
        },
        { type: 'empty' },
        {
            type: 'properties',
            lines: [
                { name: 'Total', value: order.subtotal },
            ],
        },
    ]);

    device.printText({ text: output });
};
```

### Request Example (Print Test Page)
```javascript
// Simple text printing
const printTestPage = (device) => {
    device.printText({
        text: `Test Print\nDevice: ${device.name}\nIP: ${device.ip}`
    });
};
```
```

--------------------------------

### Retrieve All Devices by Type

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Fetches all connected devices of a specified type, such as printers or payment terminals. It iterates through the retrieved devices to log their properties like name, IP address, and line length for printers. For payment terminals, it can filter for online and non-hidden devices.

```javascript
const getAllPrinters = async () => {
    const printers = await Poster.devices.getAll({ type: 'printer' });

    printers.forEach(printer => {
        console.log('Printer:', printer.name);
        console.log('IP:', printer.ip);
        console.log('Line length:', printer.textLineLength);
    });

    return printers;
};

// Get all payment terminals
const getAllPaymentTerminals = async () => {
    const terminals = await Poster.devices.getAll({ type: 'payTerminal' });

    // Filter for online terminals only
    const onlineTerminals = terminals.filter(t => t.online && !t.hidden);

    return onlineTerminals;
};
```

--------------------------------

### Scan Barcode or QR Code (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Opens the device's camera to scan QR codes or barcodes. It returns the scanned value asynchronously, allowing integration with customer lookup or product identification.

```javascript
// Scan a QR code to get customer information
const scanCustomerCard = async () => {
    try {
        const barcode = await Poster.interface.scanBarcode();
        console.log('Scanned barcode:', barcode);
        // Process the barcode value
        await findCustomerByCode(barcode);
    } catch (error) {
        console.error('Scan cancelled or failed:', error);
    }
};
```

--------------------------------

### Event Handling API: Poster.on

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Subscribes to various events emitted by the Poster platform, such as UI interactions, order lifecycle changes, and device events.

```APIDOC
## POST /events/subscribe

### Description
Subscribes to various Poster events including button clicks, order lifecycle events, and device events. The events are handled via callbacks.

### Method
POST

### Endpoint
/events/subscribe

### Parameters
#### Request Body
- **eventName** (string) - Required - The name of the event to subscribe to (e.g., 'applicationIconClicked', 'afterOrderClose', 'beforeOrderClose', 'afterPopupClosed').
- **callback** (function) - Required - The function to execute when the event is triggered. The function receives event-specific data as arguments.

### Example Usage (Client-side JavaScript)
```javascript
// Subscribe to application button clicks
Poster.on('applicationIconClicked', (data) => {
    console.log('Button clicked:', data.place, data.order);
    Poster.interface.popup({ width: 500, height: 400, title: 'My App' });
});

// Subscribe to order closed event
Poster.on('afterOrderClose', (data) => {
    console.log('Order closed:', data.order.id);
});

// Subscribe to before order close (can intercept the flow)
Poster.on('beforeOrderClose', (data, next) => {
    if (needsCustomerBonus(data.order)) {
        Poster.interface.popup({ width: 500, height: 300, title: 'Redeem Bonus' });
        this.continueCheckout = next; // Store callback to continue later
    } else {
        next(); // Continue normal checkout flow
    }
});

// Subscribe to popup closed event
Poster.on('afterPopupClosed', () => {
    console.log('Popup was closed');
});
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the subscription was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Device Event Handlers

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Handlers for various payment terminal events, including payments, refunds, reports, and interruptions.

```APIDOC
## Device Event Handlers

### Description
Handle payment terminal events for card payments, refunds, and reports.

### Event: `makePayment`
Triggered when a customer makes a payment using the terminal.

**Parameters:**
- **data** (object)
  - **device** (object) - The device object.
  - **sum** (number) - The amount of the payment.
- **next** (function) - Callback function to send the payment result.

**`next` function arguments:**
- **success** (boolean) - Indicates if the payment was successful.
- **sstParams** (object, optional) - Parameters for successful payment confirmation.
  - **merchantId** (string)
  - **paymentSystemName** (string)
  - **authCode** (string)
  - **signVerify** (integer)
  - **rrn** (string)
  - **operationType** (integer, 1 for payment)
- **error_text** (string, optional) - Error message if payment failed.

### Event: `revertPayment`
Triggered to process a refund for a previous payment.

**Parameters:**
- **data** (object)
  - **device** (object) - The device object.
  - **sstData** (object) - Original transaction data for the refund.
- **next** (function) - Callback function to send the refund result.

**`next` function arguments:**
- **success** (boolean) - Indicates if the refund was successful.
- **sstParams** (object, optional) - Parameters for successful refund confirmation.
  - **merchantId** (string)
  - **paymentSystemName** (string)
  - **authCode** (string)
  - **signVerify** (integer)
  - **rrn** (string)
  - **operationType** (integer, 2 for refund)
- **error_text** (string, optional) - Error message if refund failed.

### Event: `x-report`
Triggered to request an X-report (current sales summary) from the terminal.

**Parameters:**
- **data** (object)
  - **device** (object) - The device object.
- **next** (function) - Callback function to confirm the report request.

**`next` function arguments:**
- **success** (boolean) - Indicates if the request was processed.

### Event: `z-report`
Triggered to request a Z-report (end-of-day report) from the terminal.

**Parameters:**
- **data** (object)
  - **device** (object) - The device object.
- **next** (function) - Callback function to confirm the report request.

**`next` function arguments:**
- **success** (boolean) - Indicates if the request was processed.

### Event: `interrupt`
Triggered when a payment process is cancelled.

**Parameters:**
- **data** (object)
  - **device** (object) - The device object.
- **next** (function) - Callback function to confirm the interruption.

**`next` function arguments:**
- **success** (boolean) - Indicates if the interruption was processed.

### Request Example (Payment Handler)
```javascript
// Payment handler - called when customer pays with card
const handlePayment = (data, next) => {
    const { device, sum } = data;

    // Make request to your payment terminal
    // Poster.makeRequest(device.ip, { amount: sum })

    // Successful payment response
    const sstParams = {
        merchantId: 'MERCHANT123',
        paymentSystemName: 'MasterCard',
        authCode: '111111',
        signVerify: 0,
        rrn: '111111111111',
        operationType: 1  // 1 = payment
    };

    next({ success: true, sstParams });

    // Or for failed payment:
    // next({ success: false, error_text: 'Insufficient funds' });
};
```
```

--------------------------------

### Find Customer by Phone - JavaScript

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Searches for a customer using their phone number. It asynchronously fetches customer data and logs details like name, bonus balance, and total purchases if a customer is found. Returns the customer object or null.

```javascript
const findCustomerByPhone = async (phoneNumber) => {
    const result = await Poster.clients.find({ searchVal: phoneNumber });

    if (result && result.foundClients && result.foundClients.length > 0) {
        const customer = result.foundClients[0];
        console.log('Found customer:', customer.firstname, customer.lastname);
        console.log('Bonus balance:', customer.bonus);
        console.log('Total purchases:', customer.totalPayedSum);
        return customer;
    }

    console.log('No customer found');
    return null;
};
```

--------------------------------

### Print Order Receipts and Text

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Provides methods for printing formatted order receipts and simple text to connected devices. It utilizes a receipt formatting library to structure order details, product lists, and totals. A separate function demonstrates basic text printing with device information.

```javascript
// Print formatted order receipt
const printOrderReceipt = async (device, order) => {
    // Get product details with full names
    let products = Object.values(order.products);
    products = await Poster.products.getFullName(products);

    // Using receipt library for formatting
    receipt.config.width = device.textLineLength || 30;
    receipt.config.currency = '$';

    const output = receipt.create([
        {
            type: 'properties',
            lines: [
                { name: 'Order Number', value: order.orderName },
                { name: 'Date', value: order.dateStart },
            ],
        },
        {
            type: 'table',
            lines: products.map(p => ({
                item: p.name,
                qty: p.count,
                cost: p.price,
            })),
        },
        { type: 'empty' },
        {
            type: 'properties',
            lines: [
                { name: 'Total', value: order.subtotal },
            ],
        },
    ]);

    device.printText({ text: output });
};

// Simple text printing
const printTestPage = (device) => {
    device.printText({
        text: `Test Print\nDevice: ${device.name}\nIP: ${device.ip}`
    });
};
```

--------------------------------

### Subscribe to Poster Events (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Subscribes to various events emitted by the Poster POS system, such as button clicks, order lifecycle changes, and device events. Allows custom logic to be triggered based on these events.

```javascript
// Subscribe to application button clicks
Poster.on('applicationIconClicked', (data) => {
    if (data.place === 'order') {
        console.log('Clicked from order screen');
        console.log('Current order:', data.order);
    } else if (data.place === 'functions') {
        console.log('Clicked from settings screen');
    } else if (data.place === 'payment') {
        console.log('Clicked from payment screen');
    }

    // Show your popup
    Poster.interface.popup({ width: 500, height: 400, title: 'My App' });
});

// Subscribe to order closed event
Poster.on('afterOrderClose', (data) => {
    const { order, paymentPlace } = data;
    console.log('Order closed:', order.id);
    console.log('Payment method:', order.payedCash ? 'cash' : 'card');
});

// Subscribe to before order close (can intercept the flow)
Poster.on('beforeOrderClose', (data, next) => {
    const { order } = data;

    // Check if order has a special condition
    if (needsCustomerBonus(order)) {
        // Show your bonus redemption UI
        Poster.interface.popup({ width: 500, height: 300, title: 'Redeem Bonus' });
        // Store the next callback to continue later
        this.continueCheckout = next;
    } else {
        // Continue with normal checkout flow
        next();
    }
});

// Subscribe to popup closed event
Poster.on('afterPopupClosed', () => {
    console.log('Popup was closed');
    // Reset state
    this.setState({ activePage: null });
});
```

--------------------------------

### Poster.orders.setOrderClient

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Assigns a client/customer to the current order. This is essential for tracking orders to specific customers and applying client-specific discounts or bonuses.

```APIDOC
## POST /orders/{orderId}/client

### Description
Assigns a client/customer to the current order.

### Method
POST

### Endpoint
/orders/{orderId}/client

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - The ID of the order to which the client will be assigned.

#### Query Parameters
- **clientId** (integer) - Required - The ID of the client to assign to the order.

#### Request Body
None

### Request Example
```json
{ 
  "clientId": 678 
}
```

### Response
#### Success Response (200)
Indicates successful assignment of the client to the order.

#### Response Example
```json
{
  "message": "Client 678 assigned to order 12345"
}
```
```

--------------------------------

### Display Custom Popups (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Displays a modal popup window within the Poster POS interface to render custom application content, typically React components. Supports setting dimensions and titles for the popup.

```javascript
Poster.interface.popup({
    width: 600,      // Width in pixels or percentage string like '80%'
    height: 400,     // Height in pixels
    title: 'My Custom Application'
});

// Example with percentage width
Poster.interface.popup({
    title: 'Assign hotel guest',
    width: '80%',
    height: 328,
});
```

--------------------------------

### Interface API: closePopup

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Closes the currently active popup window.

```APIDOC
## POST /interface/closePopup

### Description
Closes the currently open popup window.

### Method
POST

### Endpoint
/interface/closePopup

### Parameters
No parameters required.

### Request Example
```json
{} 
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Add Custom Buttons to Poster UI (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Adds custom application buttons to various locations within the Poster POS interface, such as the order, settings, and payment screens. This function is part of the Poster.interface API.

```javascript
Poster.interface.showApplicationIconAt({
    functions: 'Settings Button',    // Button in settings/functions screen
    order: 'Loyalty App',            // Button in order screen
    payment: 'Custom Payment',       // Button in payment screen
});
```

--------------------------------

### Handle Payment Terminal Events

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Provides handler functions for various payment terminal events, including successful payments, refunds, X-reports, Z-reports, and payment interruptions. These handlers process incoming event data and communicate results back to the system, optionally including transaction details like authorization codes and RRNs.

```javascript
// Payment handler - called when customer pays with card
const handlePayment = (data, next) => {
    const { device, sum } = data;

    // Make request to your payment terminal
    // Poster.makeRequest(device.ip, { amount: sum })

    // Successful payment response
    const sstParams = {
        merchantId: 'MERCHANT123',
        paymentSystemName: 'MasterCard',
        authCode: '111111',
        signVerify: 0,
        rrn: '111111111111',
        operationType: 1  // 1 = payment
    };

    next({ success: true, sstParams });

    // Or for failed payment:
    // next({ success: false, error_text: 'Insufficient funds' });
};

// Refund handler
const handleRefund = (data, next) => {
    const { device, sstData } = data;

    // Use original transaction data for refund
    const refundParams = {
        rrn: sstData.rrn,
        amount: sstData.amount,
    };

    // Process refund with terminal...

    const sstParams = {
        merchantId: 'MERCHANT123',
        paymentSystemName: 'MasterCard',
        authCode: '222222',
        signVerify: 0,
        rrn: '222222222222',
        operationType: 2  // 2 = refund
    };

    next({ success: true, sstParams });
};

// X-Report and Z-Report handlers
const handleXReport = (data, next) => {
    const { device } = data;
    // Request X-report from terminal
    next({ success: true });
};

const handleZReport = (data, next) => {
    const { device } = data;
    // Request Z-report (end of day) from terminal
    next({ success: true });
};

// Interrupt handler - when payment is cancelled
const handleInterrupt = (data, next) => {
    const { device } = data;
    // Cancel pending payment on terminal
    next({ success: true });
};
```

--------------------------------

### Poster.orders.getActive

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Retrieves the currently active order with all its details. This is useful for fetching the latest order status and information.

```APIDOC
## GET /orders/active

### Description
Retrieves the currently active order with all its details.

### Method
GET

### Endpoint
/orders/active

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **order** (object) - Contains the details of the active order.
  - **id** (integer) - The unique identifier of the order.
  - **orderName** (string) - The name of the order.
  - **subtotal** (float) - The subtotal amount of the order.
  - **total** (float) - The total amount of the order.
  - **products** (array) - A list of products in the order.
  - **clientId** (integer) - The ID of the client associated with the order.
  - **dateStart** (string) - The date and time the order was started.

#### Response Example
```json
{
  "order": {
    "id": 12345,
    "orderName": "Table 5 Order",
    "subtotal": 150.50,
    "total": 165.55,
    "products": [
      {
        "productId": 101,
        "name": "Burger",
        "quantity": 1,
        "price": 15.50
      }
    ],
    "clientId": 678,
    "dateStart": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### Poster.orders.setOrderBonus

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Applies a bonus or discount amount to the current order. This can be used for loyalty programs or special promotions.

```APIDOC
## POST /orders/{orderId}/bonus

### Description
Applies a bonus/discount amount to the current order.

### Method
POST

### Endpoint
/orders/{orderId}/bonus

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - The ID of the order to which the bonus will be applied.

#### Query Parameters
- **bonusAmount** (float) - Required - The amount of the bonus or discount to apply.

#### Request Body
None

### Request Example
```json
{ 
  "bonusAmount": 10.50 
}
```

### Response
#### Success Response (200)
Indicates successful application of the bonus to the order.

#### Response Example
```json
{
  "message": "Applied 10.50 bonus to order 12345"
}
```
```

--------------------------------

### Close Current Popup (JavaScript)

Source: https://context7.com/joinposter/pos-platform-boilerplate/llms.txt

Closes the currently active popup window displayed by the Poster POS application. This is typically called after an action is completed within the popup.

```javascript
// Close popup after completing an action
const handleCancel = () => {
    Poster.interface.closePopup();
};

// Usage in a button
<button
    className="btn btn-default"
    onClick={Poster.interface.closePopup}
>
    Cancel
</button>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.