Receipts Book Node.js SDK (v2.0)

Official Node.js SDK for rec-book services inc. Modern, simple, and built for a premium developer experience.

✨ Features

• Single Credentials: Move away from AppID/Secret pairs to a single apiKey.
• Fluent API: Build complex receipts with an intuitive, chainable syntax.
• Strict Validation: Catch schema errors locally before they ever reach the network.
• Modern Security: Simplified HMAC signatures that work across any environment.

🚀 Quick Start

1. Installation

npm install e-receiptsbook-sdk

2. Initialize Client

const { RecBook } = require('e-receiptsbook-sdk');

const client = new RecBook('sk_live_v2_xxxxxxxxxxxx');

3. Build and Send a Receipt

This example shows how all tags are nested together using the Fluent API.

const { Receipt } = require('e-receiptsbook-sdk');

const receipt = new Receipt()
    .setHeader({
        businessName: 'Modern Tech Solutions',
        businessNumber: 'BN-123456789',
        businessAddress: '123 Innovation Drive',
        city: 'New York',
        postalCode: '10001'
    })
    .setCustomer({
        firstName: 'John',
        lastName: 'Doe',
        email: '[email protected]',
        phone: '+1-555-0123'
    })
    .addItem({
        productName: 'Smart Watch Series 9',
        sku: 'SW9-BLK-45',
        price: 399.99,
        quantity: 1,
        variantTitle: 'Size: 45mm, Color: Midnight Black'
    })
    .addItem({
        productName: 'USB-C Charging Cable',
        price: 19.99,
        quantity: 2
    })
    .setTotal({
        subtotal: 454.97,
        totalDiscount: 20.00,
        totalAmount: 509.57,
        paidAmount: 509.57,
        taxes: [
            { taxLabel: 'NY STATE TAX', taxAmount: 36.40 },
            { taxLabel: 'CITY TAX', taxAmount: 18.20 }
        ]
    })
    .setTransaction({
        transactionType: 'CreditCard',
        invoice: 'INV-2026-001',
        purchase: 509.57,
        transactionDateTime: new Date().toISOString()
    })
    .setFulfillment({
        trackingNumber: '1Z9999999999999999',
        shippingCompany: 'UPS',
        status: 'shipped'
    });

// Send via Async/Await
client.sendReceipt(receipt)
    .then(res => console.log('Successfully Sent!', res))
    .catch(err => console.error('Upload Failed:', err.message));

📊 Receipt Data Dictionary

Below are all the supported tags according to the Unified Receipt Specification.

1. Root & Header Details

| Tag | Type | Description | | :--- | :--- | :--- | | receiptDate | String | ISO 8601 date of the transaction. | | receiptId | String | Unique identifier for this receipt. | | header.businessName | String | Legal name of the business. | | header.businessAddress | String | Physical address of the business. | | header.taxInfo | String | GST/VAT registration details. | | header.logoURL | String | URL to the business logo for display. |

2. Order Items (Line Items)

| Tag | Type | Description | | :--- | :--- | :--- | | productName | String | Name of the item sold. | | sku | String | Stock Keeping Unit. | | price | Number | Unit price before taxes/discounts. | | quantity | Number | Number of units sold. | | variantTitle | String | e.g., "Size: M, Color: Blue". | | quantityUnit | String | e.g., "kg", "pcs", "meter". |

3. Order Total (Crucial)

Note: rec-book services inc. does not calculate totals. Vendors must provide exact amounts as they should appear to the customer.

| Tag | Type | Description | | :--- | :--- | :--- | | subtotal | Number | Amount before taxes and tips. | | totalDiscount | Number | Sum of all discounts applied. | | totalAmount | Number | Final total displayed to customer. | | paidAmount | Number | Actual amount collected from customer. | | taxes | Array | Objects with taxLabel and taxAmount. | | serviceCharges | Array | Objects with label and amount. |

4. Transaction & Payment

| Tag | Type | Description | | :--- | :--- | :--- | | transactionType | String | (Cash, CreditCard, UPI, DebitCard). | | invoice | String | Official invoice number. | | purchase | Number | Total amount of the transaction. | | transactionRecord.otherInfo | Array | Extended payment metadata (AuthId, RefId, etc). |

5. Customer & Fulfillment

| Tag | Type | Description | | :--- | :--- | :--- | | customer.email | String | Essential for digital delivery. | | customer.phone | String | Used for SMS receipts. | | fulfillment.trackingNumber | String | Courier tracking ID. | | fulfillment.shippingCompany | String | Name of the carrier (e.g., BlueDart, FedEx). |

🛠 Advanced Usage

Strict Validation

The SDK prevents "unnecessary JSON tags" by throwing an error if you try to add fields not defined in the specification.

try {
    receipt.setCustomer({ internal_secret_id: '123' }); 
} catch (e) {
    // Error: Invalid property 'internal_secret_id' for Customer.
}

⚖️ Disclaimer

rec-book services inc. acts solely as a technological medium/platform for the transmission of digital receipts between a Vendor (Business) and their Customer.

1. Issuance & Ownership: rec-book is NOT the issuer or generator of the receipt. The Vendor is the sole "Issuer" and is entirely responsible for the accuracy of the data provided (including pricing, taxation, and item descriptions).
2. Accuracy & Calculation: As a "Pass-through" service, rec-book displays exactly the data provided by the Vendor. We do not re-calculate totals or verify tax compliance.
3. No Liability: Any warranties, return policies, or commercial promises made by the Vendor within a receipt are strictly between the Vendor and the Customer. rec-book shall not be held liable for disputes, inaccuracies, or contractual defaults arising from the contents of a receipt.

📄 License

MIT © rec-book services inc.