gigafibre-fsm/docs/giftbit-integration-overview.md

# Giftbit API Integration — TARGO Communications

**Prepared for:** Giftbit Integration Review Team
**Submitted by:** TARGO Communications (operating as Gigafibre)
**Company website:** https://www.targo.ca
**Primary technical contact:** Louis Paul — louis@targo.ca
**Last updated:** 2026-05-22

---

## 1 · Company and Use Case

TARGO Communications is a Quebec-based fibre-optic Internet Service Provider headquartered in Sainte-Clotilde-de-Châteauguay (Montérégie region). We operate under the consumer-facing brand **Gigafibre** and serve residential and commercial customers across several municipalities in southwestern Quebec.

Our intended use of the Giftbit API is a **customer retention and loyalty program**. We send gift-card emails to **existing TARGO customers** as a thank-you and a soft incentive to maintain their service term. Recipients are exclusively current customers in our billing system (ERPNext); we never send to leads, prospects, or purchased lists. All recipients have an active service agreement that includes consent to receive transactional and relationship-related communications from TARGO (Canada CASL implied consent for current business relationships).

Typical campaign profile:

| Parameter | Value |
|---|---|
| Volume per campaign | 150 – 300 recipients |
| Frequency | 1 – 2 campaigns per year, per region |
| Face value per gift | CAD 50 – 60 |
| Brand mix | Canadian retailers — Tim Hortons, Walmart Canada, Home Depot Canada, IGA, Home Hardware (Amazon was intentionally removed from our brand selection to reinforce the "buy local" messaging in our copy) |
| Recipient profile | Existing residential fibre customers in Quebec |

---

## 2 · Why We Need the API (vs. Giftbit's Standard Email Delivery)

We selected `delivery_type=SHORTLINK` for three reasons that we believe align with Giftbit's intent:

1. **Brand and language consistency.** Our customer base is primarily French-speaking. The email a TARGO customer receives needs to be in French, match our visual brand (Plus Jakarta Sans typography, our green `#00C853`, our footer with mailing address and support contact), and read in our informal Quebec voice (tutoyer). Giftbit's default English templates would feel jarring and erode the trust we have with our customers.

2. **Deliverability ownership.** Our domain `targo.ca` has SPF/DKIM/DMARC alignment with Mailjet, our ESP. Sending all customer communications through our own validated infrastructure keeps our sender reputation consistent and avoids domain-spoofing risk that recipients might (legitimately) flag.

3. **Engagement attribution.** We need to know whether our specific creative succeeded. The data we get from Mailjet's webhook (open, click on the gift CTA specifically, bounce) feeds our internal analytics and informs the next campaign's copy.

We do **not** use the API to bulk-create gifts that we then redistribute, resell, or use as marketing prospect bait — every gift is tied 1:1 to a named existing customer record in our ERP at the moment of campaign creation.

---

## 3 · Technical Implementation Overview

### 3.1 · Architecture

```
   ┌─────────────────────┐
   │ Our ops console     │   internal Vue/Quasar SPA at
   │ (CampaignNewPage)   │   https://erp.gigafibre.ca/ops
   └──────────┬──────────┘
              │ 1) operator triggers Giftbit campaign create
              ▼
   ┌─────────────────────┐   create_giftbit_campaign.js
   │ Node script (CLI)   │   • POST /papi/v1/campaign with
   │ create_giftbit…js   │     delivery_type=SHORTLINK
   └──────────┬──────────┘   • polls /papi/v1/gifts until shortlinks created
              │ 2) writes giftbit-gifts-<id>.csv to disk
              ▼
   ┌─────────────────────┐
   │ Our hub service     │   3) operator uploads the Giftbit CSV alongside
   │ (Node, Mailjet SMTP)│      a customer-contact CSV; the hub pairs them
   └──────────┬──────────┘      and sends one personalized FR/EN email
              │                 per recipient via Mailjet
              ▼
   ┌─────────────────────┐
   │ Customer's inbox    │
   └──────────┬──────────┘
              │ click on CTA → opens Giftbit shortlink
              ▼
   ┌─────────────────────┐
   │ Giftbit's branded   │   recipient chooses brand, redeems on
   │ redemption page     │   Giftbit-hosted UI (we never touch the code)
   └─────────────────────┘
```

### 3.2 · API Endpoints Used

All requests go to:
- **Production:** `https://api.giftbit.com/papi/v1`
- **Sandbox:** `https://api-testbed.giftbit.com/papi/v1`

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/ping` | Token sanity check at startup of every CLI run |
| `POST` | `/campaign` | Create a new gift campaign with `delivery_type: "SHORTLINK"` |
| `GET` | `/gifts?campaign_uuid=…` | Poll for generated shortlinks (Giftbit creates them asynchronously) |
| `GET` | `/gifts/{uuid}` | **(Planned, see §6)** Periodic redemption-status polling per gift |

### 3.3 · `POST /campaign` payload (production-shape)

```json
{
  "id": "targo-2026-q2-loyalty",
  "subject": "Cadeau TARGO — merci",
  "message": "Merci d'être client TARGO. Voici une carte-cadeau pour vous remercier.",
  "expiry": "2026-12-31",
  "price_in_cents": 6000,
  "brand_codes": ["timhortonsca", "walmartca", "homedepotca", "igacaca", "homehardwareca"],
  "contacts": [
    { "id": "ERPNEXT-CUST-001234", "firstname": "Marie", "lastname": "Tremblay", "email": "marie@example.com" },
    { "id": "ERPNEXT-CUST-001235", "firstname": "Jean",  "lastname": "Bouchard", "email": "jean@example.com" }
  ],
  "delivery_type": "SHORTLINK"
}
```

The `id` field on each contact carries our internal ERPNext Customer ID. This is what lets us reconcile redemption events back to a specific customer record without any PII (postal code, phone, address) ever crossing the API boundary.

### 3.4 · What we send / what we don't send

| Field sent to Giftbit | Sent? | Notes |
|---|:---:|---|
| First name | ✅ | Used only for the shortlink landing page personalization |
| Last name | ✅ | Same |
| Email address | ✅ | Required by Giftbit's data model even with SHORTLINK; never used for outbound mail by Giftbit when SHORTLINK is set |
| Internal customer ID | ✅ | Opaque string, no PII embedded |
| Phone number | ❌ | Never |
| Postal address | ❌ | Never |
| Service plan / billing info | ❌ | Never |
| Demographics | ❌ | Never |

---

## 4 · Security Posture

### 4.1 · Credential handling
- Giftbit API token is stored only in the environment of our production hub container (`GIFTBIT_TOKEN` env var, loaded from a `.env` file with `chmod 600`). The token never appears in source code or in our Gitea repository.
- All API calls are made over HTTPS using Node's native `https` module with default TLS validation. We do **not** disable certificate verification.

### 4.2 · Sandbox isolation
- During all development and pre-flight QA we use `api-testbed.giftbit.com` exclusively (`--sandbox` CLI flag enforces this).
- When the sandbox flag is set, every contact email in the CSV is overridden to a single internal test inbox (`louis@targo.ca`). This means even if a developer mistakenly uses real customer data while testing, no test gift can be sent to a real customer.
- Production runs require explicit removal of the `--sandbox` flag and are gated by a manual operator confirmation step in our ops console.

### 4.3 · Shortlink integrity
- Each shortlink is consumed at most once on Giftbit's side. We do not log shortlinks in any plain-text channel (no Slack, no email, no analytics dashboards).
- The shortlink only travels through:
  1. Our hub's JSON campaign file on disk (filesystem perms `600`, Docker volume not exposed to internet)
  2. The outbound Mailjet email to the named recipient
  3. The Mailjet click webhook event (where Mailjet provides the URL alongside `CustomID = <campaign>:<row>` so we can reconcile without re-exposing the link in logs)

### 4.4 · Webhook authenticity
- We are aware that Mailjet click events carry the original URL. We use this only to distinguish gift-CTA clicks from other link clicks for our analytics; the shortlink itself is **not** echoed back to any external system from our webhook handler.

---

## 5 · Compliance and Customer Experience

### 5.1 · Consent (CASL — Canada Anti-Spam Legislation)
- 100% of recipients have an active service agreement with TARGO containing implied consent for relationship and transactional messages.
- Every campaign email includes our physical mailing address and a working `support@targo.ca` contact, satisfying CASL section 6(2)(c) identification requirements.
- We provide a one-click way to refuse or request a replacement gift by replying to support@targo.ca. Refused gifts are returned to our Giftbit balance (`/gifts/{uuid}` cancellation, planned in §6).

### 5.2 · Recipient experience
1. Customer opens the email in their inbox. Sender is `TARGO <noreply@targo.ca>`, subject "🎁 Un cadeau pour toi, de la part de TARGO" (or English equivalent based on the customer's preferred language flag in ERPNext).
2. Email displays the customer's first name, the gift face value (e.g. "60 $"), the brand selection (rendered as small inline logos), a single primary CTA button leading to the Giftbit shortlink, and a brief plain-language disclosure of any commitment terms.
3. On click, the customer lands on Giftbit's hosted redemption page. They select a brand from the campaign's allowed list and follow Giftbit's standard redemption flow. We have no visibility into the redemption form itself.
4. The customer's record in our system is annotated with `gift_link_clicked = true` and timestamp upon return webhook from Mailjet. Redemption confirmation will (per §6) be polled directly from `/gifts/{uuid}`.

### 5.3 · Data retention
- Campaign JSON files (including shortlinks) are retained on the hub for 24 months for accounting and customer-support traceability, after which they are archived to encrypted cold storage and removed from the live system.
- We do not share, sell, or otherwise distribute any data collected from this integration to third parties.

---

## 6 · Planned Next Steps — Redemption Status Polling

We intend to add a recurring background poll against `GET /gifts/{uuid}` for each issued shortlink in an active campaign window. The plan:

| Cadence | Action |
|---|---|
| **T + 1 hour** | First poll for every gift after campaign send completes |
| **T + 1 day, +7 d, +30 d** | Subsequent polls until either the gift is `REDEEMED` or `expiry` passes |
| **On expiry + 1 day** | Final reconciliation poll, then move the recipient row to a "closed" state |

The polled status (`NEW` / `LINKCREATED` / `REDEEMED` / `REFUNDED`) and the brand the recipient selected will be persisted on the same per-recipient JSON row alongside `gift_link_clicked_at`. This lets us produce a single CSV report covering the full lifecycle:

```
row, firstname, email, gift_url, gift_clicked_at,
gift_status (REDEEMED/etc), gift_redeemed_at, gift_brand_selected
```

We will respect Giftbit's published rate limits and apply exponential backoff on 429/5xx responses. Polling will be batched (single request returns up to 500 gifts via `?campaign_uuid=…&limit=500`), so even a 1000-recipient campaign costs at most two requests per polling cycle.

---

## 7 · Source Code References (read-only access available on request)

| File | Purpose |
|---|---|
| `scripts/campaigns/create_giftbit_campaign.js` | The `POST /campaign` + shortlink-polling CLI that talks to Giftbit |
| `services/targo-hub/lib/campaigns.js` | Hub service: CSV pairing, Mailjet send, webhook receiver, planned `/gifts/{uuid}` poller |
| `apps/ops/src/modules/campaigns/` | Internal Vue/Quasar console where operators create and monitor campaigns |
| `services/targo-hub/templates/gift-email-fr.html` | The French email template (HTML) |
| `services/targo-hub/templates/gift-email-en.html` | The English email template |

Repository (Giftbit reviewers can be added on request): `https://git.targo.ca/louis/gigafibre-fsm`

---

## 8 · Contacts

| Role | Name | Email |
|---|---|---|
| Owner / Lead developer | Louis Paul | louis@targo.ca |
| Customer support (recipients use this) | TARGO Support | support@targo.ca |
| Mailing address | TARGO Communications, 1867 ch. de la rivière, Sainte-Clotilde, QC, Canada | |

We are happy to walk through the code, demonstrate the ops console live, or send a small sample campaign through the sandbox if that would help your review. Please let us know what level of detail or evidence would be most useful.

Thank you for your time.

— *TARGO Communications · 2026*