npm package: @nwhau/pos-giftcards
Description: > Convert REX (from Shopify POS Tile) gift cards into native Shopify physical gift cards with seamless cashier flow.
Author: NWH
Latest version: 0.1.2

# @nwhau/pos-giftcards

> Convert REX (from Shopify POS Tile) gift cards into native Shopify physical gift cards with seamless cashier flow.

---

### 🧩 Overview

The `@nwhau/pos-giftcards` module enables integration between **Retail Express (REX)** and **Shopify POS**.  
It allows cashiers to convert a REX gift card into a native **Shopify physical gift card** directly during checkout.

Once a customer is selected (or the system defaults to a cash sale customer), the conversion triggers an **app flow** named `convert-rex-gift-card`, completing the migration automatically.

This package simplifies hybrid POS environments, ensuring a unified customer experience and reducing manual reconciliation.

---

### ⚙️ Installation

```bash
npm install @nwhau/pos-giftcards
# or
yarn add @nwhau/pos-giftcards
```

---

### 🧠 Usage Example

Below is an example of using the module in a Shopify POS extension:

```ts
import { useExtensionApi } from '@shopify/ui-extensions-react';
import { convertRexGiftCard } from '@nwhau/pos-giftcards';

export default function ConvertRexGiftCardButton() {
  const api = useExtensionApi();

  const handleConvert = async () => {
    const payload = {
      ShopifyGiftCardCode: '4RMIIQNGZ9728M2C',
      RexGiftCardCode: '38301',
      amount: 5,
      customer_id: 6805489614914,
    };

    await convertRexGiftCard(api, payload);
  };

  return (
    <Button onPress={handleConvert}>
      Convert REX Gift Card
    </Button>
  );
}
```

When executed, this triggers the flow:
```toml
[[extensions]]
name = "NWH Convert REX Gift Card"
handle = "nwh-convert-rex-gift-card"
type = "flow_trigger"
uid = "8324df42-a986-e9cf-5d5e-xxxx"
```

Once completed, the cashier continues the transaction as normal — using the Shopify gift card through the native POS flow.

---

### 🧰 API Reference

#### `convertRexGiftCard(api, payload)`

Converts a REX gift card into a Shopify gift card.

| Parameter | Type | Required | Description |
|------------|------|-----------|-------------|
| `api` | `ExtensionApi` | ✅ | Shopify POS Extension API instance |
| `payload` | `object` | ✅ | Contains gift card and customer details |
| `payload.ShopifyGiftCardCode` | `string` | ✅ | Shopify gift card code |
| `payload.RexGiftCardCode` | `string` | ✅ | REX gift card code |
| `payload.amount` | `number` | ✅ | Amount to transfer |
| `payload.customer_id` | `number` | ✅ | Shopify customer ID |

---

### 🧾 Example Flow Trigger in `shopify.extension.toml`

```toml
[[extensions]]
name = "NWH Convert REX Gift Card"
handle = "nwh-convert-rex-gift-card"
type = "flow_trigger"
description = "Triggers when a REX gift card is converted to Shopify"
```

---

### 🧱 Build Commands

```bash
# Build
npm run build

# Clean dist folder
npm run clean

# Watch mode for development
npm run dev
```

---

### 🚀 Publishing Workflow

#### 1. **Login and Build**
```bash
npm login
npm run build
```

#### 2. **Publish a Beta Version**
Used for internal or testing releases.
```bash
npm version prerelease --preid=beta
npm publish --tag beta
```
This will publish under the `beta` dist-tag:
```
@latest -> 0.1.1
@beta   -> 0.1.2-beta.0
```

#### 3. **Publish a Release Candidate**
For final testing before a stable release:
```bash
npm version prerelease --preid=rc
npm publish --tag rc
```
Creates a version like `0.1.2-rc.0` published under `@rc`.

#### 4. **Publish a Stable (Latest) Release**
Once tested and verified:
```bash
npm version patch    # or minor / major
npm publish --tag latest
```

---

### 🔁 Promoting Between Lanes

If a `beta` or `rc` build is approved for production, **promote it to `latest`** without republishing:

```bash
# Promote an existing rc build to latest
npm dist-tag add @nwhau/pos-giftcards@0.1.2-rc.0 latest
```

You can list and manage all tags with:
```bash
npm dist-tag ls @nwhau/pos-giftcards
npm dist-tag rm @nwhau/pos-giftcards beta
```

---

### 🧩 Example Version Flow

| Stage | Command | Resulting Tag | Example Version |
|--------|----------|---------------|-----------------|
| Development | `npm publish --tag beta` | `beta` | 0.1.2-beta.0 |
| Candidate | `npm publish --tag rc` | `rc` | 0.1.2-rc.0 |
| Stable | `npm publish --tag latest` | `latest` | 0.1.2 |

---

### 🪪 License
MIT © [NWH](https://nwh.com.au)

---

### 💬 Support
For issues or feature requests, please open a GitHub issue or contact support via internal channels.