ext-es-client

Utilities SDK for browser extension background scripts

ext-es-client is a plug-and-play SDK for browser extensions that provides:

• Extension install & uninstall tracking
• Unique extension identity management
• Backend-powered URL resolution
• Safe tab redirect handling
• Works out-of-the-box with Chrome, Firefox, Edge (MV3)

✅ No extra setup required ✅ No explicit webextension-polyfill install for consumers ✅ One-line initialization

✨ Features

• 🔁 Safe redirect handling

  • Prevents infinite redirect loops
  • Only redirects valid HTTP/HTTPS URLs

• 🆔 Persistent extension UUID

  • Generated once and stored locally

• 📡 Install & uninstall tracking

  • Auto-calls backend on install
  • Redirects users on uninstall (optional feedback URL)

• 🌍 Cross-browser support

  • Chrome / Firefox / Edge

• 🧩 Framework-agnostic

  • Works with Plasmo, Vite, Webpack, Rollup

📦 Installation

npm install ext-es-client

That’s it. No additional dependencies required.

🚀 Quick Start

Use this in your background script / service worker.

import { initESClient } from "ext-es-client";

initESClient({
  apiEndpoint: "https://api.example.com",
  apiKey: "your-api-key",
  uninstallFeedbackUrl: "https://example.com/feedback" // optional
});

⚙️ Configuration

ESClientConfig

interface ESClientConfig {
  apiEndpoint: string;          // Backend base URL
  apiKey: string;               // API key for backend
  uninstallFeedbackUrl?: string; // Optional feedback page
}

Required

• apiEndpoint
• apiKey

Optional

• uninstallFeedbackUrl

🔄 What Happens Internally

When initESClient() is called:

1. A unique extension UUID is generated (once)

2. Extension install is reported to:

   POST /extensions/install

3. Uninstall redirect URL is set:

   /extensions/uninstall/:uuid

4. Background listeners are registered:

   • tabs.onUpdated
   • tabs.onCreated
   • tabs.onRemoved

5. URLs are resolved via:

   GET /resolve?url=<url>&uuid=<extensionUUID>

All logic is handled safely inside the SDK.

🔐 Permissions Required

Your extension must include:

{
  "permissions": ["tabs", "storage"]
}

🧠 Redirect Safety

The SDK automatically:

• Ignores non-http(s) URLs
• Prevents redirect loops per tab
• Aborts slow backend requests
• Handles tab cleanup on close

🌐 Browser Support

| Browser | Status | | ------- | ------------------------------------ | | Chrome | ✅ | | Firefox | ✅ | | Edge | ✅ | | Brave | ✅ | | Safari | ⚠️ (depends on WebExtension support) |

🔒 Security Notes

• API key is sent only from background context
• No data is exposed to content scripts
• No tracking occurs without explicit SDK initialization

🔐 License & Usage

ext-es-client is a proprietary SDK.

Use of this SDK requires:

• Registration as a developer
• A valid API key issued by EasySecure

Unauthorized use, redistribution, or reverse engineering is prohibited.

🤝 Support

If you’re using ext-es-client across multiple extensions, this SDK is designed to keep your background logic DRY, consistent, and secure.