# Loox Billing Calculator

<a href="https://github.com/danamsalem/loox-billing-calculator/releases" target="_blank"><img src="https://img.shields.io/badge/version-2.0.2-ff6348?style=flat-square" alt="Version"></a>
<a href="https://loox-billing-calculatorv2.netlify.app" target="_blank"><img src="https://img.shields.io/badge/Chrome-Extension-4285F4?style=flat-square&logo=google-chrome&logoColor=white" alt="Chrome Extension"></a>
<a href="https://loox-billing-calculatorv2.netlify.app" target="_blank"><img src="https://img.shields.io/badge/Landing%20Page-View-003122?style=flat-square" alt="Landing Page"></a>

> <a href="https://loox-billing-calculatorv2.netlify.app#playground" target="_blank"><strong>→ Try the interactive playground</strong></a> · <a href="https://loox-billing-calculatorv2.netlify.app/loox-billing-calculator-latest.zip" target="_blank"><strong>↓ Download latest</strong></a>

A Chrome extension popup that estimates monthly billing for Loox merchants on any usage-based plan. Built for internal use by the Loox support and success teams.

---

## What It Does

Loox's usage-based plans charge a base fee that covers a set number of orders (or emails), then add blocks of usage on top. This tool lets you plug in a merchant's usage volume and any discounts being offered, and instantly see:

- The exact monthly bill under the current plan
- How discounts affect both the base fee and per-block usage charge
- At what usage level the flat-rate Unlimited plan ($299.99/mo) becomes cheaper
- A pre-written discount explanation you can copy directly into a support ticket

### Supported Plans

| Plan | Type | Unit |
|---|---|---|
| Scale | Active | Orders |
| Convert | Active | Orders |
| Growth | Legacy | Emails |
| Growth + Referrals | Legacy | Emails |
| Legacy Scale | Legacy | Orders |
| Enterprise Usage | Legacy | Emails |

---

## How to Install (Unpacked)

1. Download and unzip this folder
2. Open Chrome and go to `chrome://extensions`
3. Enable **Developer mode** (top-right toggle)
4. Click **Load unpacked** and select this folder
5. The Loox icon will appear in your toolbar

To update after changes: click the **↻** icon next to the extension on `chrome://extensions`.

---

## File Reference

This section documents every file so you can verify nothing unexpected is included.

### Core Extension Files

| File | Purpose |
|---|---|
| `manifest.json` | Extension configuration. Declares the name, version, permissions, and which HTML file to open as the popup. |
| `popup.html` | The entire UI — all CSS variables, layout, tab structure, input fields, result cards, and loading overlay are defined here as a single self-contained file. No external stylesheets are fetched. |
| `popup.js` | All application logic — billing calculations, plan switching, state persistence, sound playback, clipboard copy, theming, and event listeners. No external scripts are called at runtime. |
| `icon.png` | The extension's toolbar icon (displayed in Chrome's extension bar). |

### Vendor Libraries (bundled locally)

| File | What it is | Why it's local |
|---|---|---|
| `lottie.min.js` | Lottie Web v5.12.2 — a JSON animation player by Airbnb. Minified. Source: [github.com/airbnb/lottie-web](https://github.com/airbnb/lottie-web) | Chrome extensions block requests to external CDNs under the Content Security Policy. The library is bundled so no outbound network request is ever made. |
| `lottie-logo.json` | The Loox logo loading animation data file (JSON). Played by `lottie.min.js` on first open each browser session. Contains only vector path data — no code, no executables. | Bundled for the same CSP reason above. |

### `logos/`

| File | Purpose |
|---|---|
| `logos/Loox Logo.svg` | The standard Loox wordmark. Displayed in the extension header for all plans. In dark mode, CSS `filter: brightness(0) invert(1)` makes it white — no second file needed. |
| `logos/Loox Ai purple Logo.png` | The Convert / AI plan logo. Included as a reference asset. Currently not swapped in at runtime (same header logo is used for all plans for visual consistency). |

### `sounds/`

All sounds are short, local `.wav` / `.mp3` files. **No audio is ever streamed or fetched from the internet.** Playback only happens on direct user interaction (typing, clicking).

| File | Triggered by |
|---|---|
| `select.wav` | Clicking a tab, clicking a copy button, clicking reset, clicking the logo |
| `disabled.wav` | Pressing a key that isn't accepted in a number field (letters, `e`, `+`) |
| `type_01.wav` – `type_05.wav` | Each accepted keypress in an input field (random pick each time for a natural feel) |
| `unlimited_alert.mp3` | Once, when the bill first crosses the Unlimited plan breakeven threshold |

A mute toggle in the header silences all audio. The muted state is saved and restored across sessions.

---

## Permissions Explained

The extension requests exactly two permissions. Here is what each one does and why it's needed:

### `storage`
**What Chrome allows:** Read and write data to the extension's own private local storage (isolated to this extension only — cannot access cookies, browsing history, other extensions, or any website data).

**Why it's used:** To remember the active plan tab, dark mode preference, mute state, all input field values, and whether the unlimited-plan alert has already played — so the calculator restores exactly where you left off when you reopen the popup.

Two storage APIs are used:
- `chrome.storage.local` — persists across browser restarts (saves your inputs and preferences)
- `chrome.storage.session` — clears when Chrome closes (used only to show the loading animation once per browser session)

### `clipboardWrite`
**What Chrome allows:** Write text to the system clipboard when the user initiates the action (a button click). Cannot read the clipboard.

**Why it's used:** The "Copy Discount Explanation" button and "Copy Breakdown" button copy pre-formatted text into the clipboard so you can paste it directly into a ticket. The logo also copies the Loox pricing page URL on click.

---

## What the Extension Cannot Do

- It does not access any website, tab, or URL
- It does not make any network requests at runtime
- It does not read the clipboard — only writes to it on user action
- It does not track usage or send any data anywhere
- It has no background service worker — it only runs when the popup is open

---

## Billing Formula

```
discountedBase  = baseFee  × (1 − baseDiscount%)
discountedBlock = blockCost × (1 − usageDiscount%)

usageBlocks     = ceil((units − baseUnits) / blockSize)   [0 if units ≤ baseUnits]
totalBill       = min(discountedBase + usageBlocks × discountedBlock, maxBill)
```

Unlimited breakeven (the point at which $299.99/mo flat rate becomes cheaper):

```
blocksToBreakeven = ceil((299.99 − discountedBase) / discountedBlock)
breakevenUnits    = baseUnits + (blocksToBreakeven − 1) × blockSize + 1
```

---

## Version History

| Version | Notes |
|---|---|
| 1.0 | Scale plan only, single-page calculator |
| 2.0 | All 6 plans, dark mode, sound effects, breakeven indicator, copy buttons, reset, mute, Lottie loading animation |
| 2.0.1 | Landing page on Netlify, GitHub Actions CI/CD, blocked `e`/`E`/`+` in number inputs |
| 2.0.2 | Red bottom glow on unlimited warning; mute now persists across sessions; dark mode toggle no longer animates on open; discount % now shown in breakdown copy |

---

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) if you'd like to suggest changes or report a bug.

---

*Built by Dan Amsalem, 2026.*
