@expresta/sdk/README.md

A lightweight JS SDK for embedding Expresta's order button into websites using HTML or JavaScript.

# 🧩 Expresta Buttons JS SDK

The **Expresta Buttons JS SDK** allows seamless integration of Expresta’s print-on-demand ordering system directly into your website or web application.

It provides a dynamic, customizable **"Order Now"** button that lets your users order printed products securely — with no server-side integration required.

---

## ✨ Features

- 🚀 **Simple JavaScript integration** – add with a single snippet  
- 🎨 **Customizable** – freely adjust button style and placement  
- 🧾 **Dynamic product configuration** – define SKUs, quantities, and metadata  
- 🔄 **Direct backend communication** – handles order processing automatically  
- ⚡ **Lightweight and scalable** – optimized for large-scale partner integrations  

---

## 🖼️ Screenshots

**Dark theme**

![Dark Button Screenshot](https://cdn.expresta.com/sdk/screenshots/button-dark.png)

**Light theme**

![Light Button Screenshot](https://cdn.expresta.com/sdk/screenshots/button-light.png)

---

## 🧪 Demo

- **Init by JS object:**  
  [https://cdn.expresta.com/sdk/demo/init_by_js.html](https://cdn.expresta.com/sdk/demo/init_by_js.html)

- **Init by HTML attributes:**  
  [https://cdn.expresta.com/sdk/demo/init_by_attributes.html](https://cdn.expresta.com/sdk/demo/init_by_attributes.html)

---

## 🧭 Getting Started

Before getting started, please contact  
📧 **[cooperation@expresta.eu](mailto:cooperation@expresta.eu)**  
to set up your **business account** and receive your integration credentials.

---

## ⚙️ Configuration Parameters

### Common Parameters (JS Object or HTML Attributes)

| Parameter | Description | Accepted Values / Example |
|------------|--------------|----------------------------|
| `lang` | Language and domain of the product page | `sk`, `cz`, `at`, `de`, `hu`, `en` |
| `class` | Button theme | `dark`, `light` |
| `qty` | Quantity of products | 50
| `account-id` | Your Expresta business account ID | e.g. `55555` |
| `public-key` | Public key provided by Expresta | e.g. `XXXX-1111-YYYY-2222` |
| `utm-source` | UTM source (optional) | `example-source` |
| `utm-medium` | UTM medium (optional) | `example-medium` |
| `utm-campaign` | UTM campaign (optional) | `example-campaign` |
| `utm-content` | UTM content (optional) | `example-content` |

For multiple products, you can define an array of configurations, each containing a valid `product_type_id` (provided by Expresta) and desired `qty`.

---

## 🧩 Example: Creating Product from Scratch

### Load the SDK from Expresta CDN

- **Production (minified):**  
  [https://cdn.expresta.com/sdk/dist/js/buttons.min.js](https://cdn.expresta.com/sdk/dist/js/buttons.min.js)

- **Development (non-minified):**  
  [https://cdn.expresta.com/sdk/src/js/buttons.js](https://cdn.expresta.com/sdk/src/js/buttons.js)

---

### Initialization via JavaScript

```html
<!-- Empty Div for Expresta Order Button -->
<div class="expresta-button-1"></div>

<!-- Expresta Buttons JS SDK -->
<script src="https://cdn.expresta.com/sdk/dist/js/buttons.min.js"></script>

<!-- Initialization -->
<script>
    OrderButton.init({
        'lang': 'en',
        'class': 'dark',
        'wrap': 'expresta-button-1',
        'account': 55555,
        'public_key': 'XXXX-1111-YYYY-2222',
        'utm_source': 'example-source',
        'utm_medium': 'example-medium',
        'utm_campaign': 'example-campaign',
        'utm_content': 'example-content',
        'product_types': [
            { 'product_type_id': 1111, 'qty': 10 },
            { 'product_type_id': 2222, 'qty': 20 }
        ]
    });
</script>
```
### Initialization via HTML Attributes
```html
<!-- Container for Expresta Order Button -->
<div class="expresta-order-button"
     data-lang="en"
     data-account="55555"
     data-public_key="XXXX-1111-YYYY-2222"
     data-utm_source="example-source"
     data-utm_medium="example-medium"
     data-utm_campaign="example-campaign"
     data-utm_content="example-content">
    <div data-product_type_id="1111" data-qty="10"></div>
    <div data-product_type_id="2222" data-qty="20"></div>
</div>

<!-- Expresta Buttons JS SDK -->
<script src="https://cdn.expresta.com/sdk/dist/js/buttons.min.js"></script>
```

## 📚 Example: Recreating a Previously Ordered Product
You can also recreate an existing order with a custom `product_id`, `document_url`, `page_range`, `preview_image_url` and `product_name`

### Initialization via JavaScript
```html
<div class="expresta-button-1"></div>

<script src="https://cdn.expresta.com/sdk/dist/js/buttons.min.js"></script>

<script>
   OrderButton.init({
        'lang': 'en',
        'class': 'dark',
        'wrap': 'expresta-button-2',
        'account': 55555,
        'qty': 25,
        'public_key': 'XXXX-1111-YYYY-2222',
        'utm_source': 'example-source',
        'utm_medium': 'example-medium',
        'utm_campaign': 'example-campaign',
        'utm_content': 'example-content',
        'product_id': '545675',
        'document_url': 'https://example.com/document.pdf',
        'page_range': '1-120',
        'preview_image_url': 'https://example.com/preview.jpg',
        'product_name': 'Book Title'
    });
</script>
```

### Initialization via HTML Attributes
``` html
<div class="expresta-order-button dark"
     data-lang="en"
     data-account="55555"
     data-public_key="XXXX-1111-YYYY-2222"
     data-utm_source="example-source"
     data-utm_medium="example-medium"
     data-utm_campaign="example-campaign"
     data-utm_content="example-content"
     data-product_id="545675"
     data-qty="5"
     data-document_url="https://example.com/document.pdf"
     data-page_range="1-120"
     data-preview_image_url="https://example.com/preview.jpg"
     data-product_name="Book Title">
</div>
```

## 🛠️ Support
- **Technical inquiries:** api@expresta.com
- **Partnership & business:** cooperation@expresta.eu

## 👥 Authors
- [Expresta Collective](https://career.expresta.com/people)
- [@expresta on npm](https://www.npmjs.com/org/expresta)