Bitrefill Plugin for SperaxOS

Four plugin types covering all Bitrefill API actions — built for plugin.delivery.

Plugins

Plugin	Type	Identifier	Description
Bitrefill	Default	`sperax-bitrefill`	Full API: search, invoice, orders, eSIMs, deposits
Bitrefill Catalog	Markdown	`bitrefill-catalog`	Formatted product tables, order reports, receipts
Bitrefill Store	Standalone	`bitrefill-store`	Interactive full-screen storefront with checkout
Bitrefill API	OpenAPI	`bitrefill-openapi`	Auto-generated from OpenAPI 3.0 spec

File Structure

src/
  sperax-bitrefill.json       ← Default plugin definition
  bitrefill-catalog.json      ← Markdown plugin definition
  bitrefill-store.json        ← Standalone plugin definition
  bitrefill-openapi.json      ← OpenAPI plugin definition

api/
  _utils.ts                   ← Shared auth + CORS + response helpers
  sperax-bitrefill/
    manifest.ts               ← Manifest handler (served with CORS)
    search.ts                 ← Search products
    product.ts                ← Get product details
    balance.ts                ← Account balance
    invoice.ts                ← Create invoice
    invoice-status.ts         ← Get invoice status
    order.ts                  ← Get order + redemption codes
    orders.ts                 ← List orders
    phone-check.ts            ← Validate phone number
    esims.ts                  ← Purchase / top-up eSIM
    deposit.ts                ← Crypto deposit (Business API)
  bitrefill-catalog/
    manifest.ts               ← Manifest handler
    catalog.ts                ← Formatted product catalog (markdown)
    report.ts                 ← Order history report (markdown)
    receipt.ts                ← Order receipt with redemption codes (markdown)
  bitrefill-store/
    manifest.ts               ← Manifest handler
    app.ts                    ← Serves full standalone HTML storefront
  bitrefill-openapi/
    manifest.ts               ← Manifest handler
    spec.ts                   ← Serves OpenAPI 3.0 spec (inlined, edge-safe)

locales/
  sperax-bitrefill.en-US.json
  bitrefill-catalog.en-US.json
  bitrefill-store.en-US.json
  bitrefill-openapi.en-US.json

scripts/
  build.ts                    ← Generates public/index.json from src/*.json

public/
  index.json                  ← Generated plugin registry (bun run build)

vercel.json                   ← Rewrites + CORS headers
tsconfig.json                 ← TypeScript config (edge-compatible)

Plugin 1: Bitrefill (Default) — `sperax-bitrefill`

Server-rendered JSON — AI formats responses naturally.

10 actions:

Action	Endpoint	Description
`searchProducts`	`/api/sperax-bitrefill/search`	Keyword + country + type filter
`getProductDetails`	`/api/sperax-bitrefill/product`	Denominations for any product ID
`getAccountBalance`	`/api/sperax-bitrefill/balance`	Current balance
`createInvoice`	`/api/sperax-bitrefill/invoice`	Purchase up to 20 products
`getInvoice`	`/api/sperax-bitrefill/invoice-status`	Invoice status + payment details
`getOrder`	`/api/sperax-bitrefill/order`	Redemption codes, PINs, links
`listOrders`	`/api/sperax-bitrefill/orders`	Order history with date filters
`checkPhoneNumber`	`/api/sperax-bitrefill/phone-check`	Validate E.164 number, find operators
`purchaseESIM`	`/api/sperax-bitrefill/esims`	Buy or top-up eSIM
`createDeposit`	`/api/sperax-bitrefill/deposit`	Fund balance via crypto (Business API)

Plugin 2: Bitrefill Catalog (Markdown) — `bitrefill-catalog`

Pre-formatted rich text returned directly — no AI post-processing.

3 actions:

Action	Endpoint	Output
`getProductCatalog`	`/api/bitrefill-catalog/catalog`	Markdown table: name, ID, type, country, denominations
`getOrderHistoryReport`	`/api/bitrefill-catalog/report`	Order history with status summary
`getOrderReceipt`	`/api/bitrefill-catalog/receipt`	Full receipt with redemption code, PIN, instructions

Plugin 3: Bitrefill Store (Standalone) — `bitrefill-store`

Full dark-mode React/HTML storefront in an iframe.

Features:

Product search with country + type filters
Denomination picker (fixed packages + range input)
Phone number input for top-ups
Payment method selector (Balance, BTC, Lightning, ETH, USDC, USDT, SOL)
Invoice creation with live payment status
postMessage bridge to notify parent AI frame on purchase

Served by api/bitrefill-store/app.ts — single self-contained HTML file, no build step.

Settings injection: reads API_KEY / API_ID / API_SECRET via postMessage from plugin host frame, or ?apiKey= URL param for local testing.

Plugin 4: Bitrefill API (OpenAPI) — `bitrefill-openapi`

Auto-generated from a full OpenAPI 3.0 spec — no custom handlers beyond spec serving.

Endpoints covered:

Group	Endpoints
Account	`/ping`, `/accounts/balance`, `/accounts/deposit`
Products	`/products`, `/products/search`, `/products/{id}`
eSIM Products	`/products/esims`, `/products/esims/{id}`
Phone	`/check_phone_number`
Invoices	`POST /invoices`, `GET /invoices`, `GET /invoices/{id}`
Orders	`GET /orders`, `GET /orders/{id}`
eSIMs	`POST /esims`, `GET /esims`, `GET /esims/{id}`
Batches	`POST /brgc-batches`, `GET /brgc-batches`, `GET /brgc-batches/{id}`
Affiliate	`GET /commissions`

Spec handler: api/bitrefill-openapi/spec.ts (edge-safe, inlined, no dynamic imports). It is served at /api/bitrefill-openapi/spec on whichever host runs this project.

The previous public host, plugin.delivery, currently returns HTTP 402 while hosting is being migrated. Until the new host is live, read the spec from the source file above or run the project locally with bun run dev.

Authentication

All plugins support two auth modes via plugin settings:

Setting	Type	Description
`apiKey`	password	Personal API Bearer token
`apiId`	string	Business/Affiliate API ID
`apiSecret`	password	Business/Affiliate API Secret

Get credentials at bitrefill.com/account/developers.

Architecture

All API handlers use api/_utils.ts for:

getAuthHeader() — supports both Bearer (Personal) and Basic (Business/Affiliate)
handleOptions() — CORS preflight (OPTIONS → 204)
jsonResponse() / errorResponse() / markdownResponse() — consistent response format with CORS headers
All handlers run on Vercel Edge Runtime

Adding to plugin.delivery

Copy these files into nirholas/plugin.delivery:

src/sperax-bitrefill.json → src/sperax-bitrefill.json
src/bitrefill-catalog.json → src/bitrefill-catalog.json
src/bitrefill-store.json → src/bitrefill-store.json
src/bitrefill-openapi.json → src/bitrefill-openapi.json
api/sperax-bitrefill/ → api/sperax-bitrefill/
api/bitrefill-catalog/ → api/bitrefill-catalog/
api/bitrefill-store/ → api/bitrefill-store/
api/bitrefill-openapi/ → api/bitrefill-openapi/
api/_utils.ts → api/_utils.ts (or merge with existing utils)
locales/sperax-bitrefill.en-US.json → locales/
All other locales/bitrefill-*.en-US.json → locales/

Wiring an agent to these plugins

This repository ships the four plugins only — no agent definition is included here. To let an agent use them, add the plugin identifier to the agent's plugins array in whichever agent repository the agent lives in:

{
  "plugins": ["sperax-bitrefill"]
}

Use bitrefill-catalog, bitrefill-store, or bitrefill-openapi instead of (or alongside) sperax-bitrefill depending on which plugin type the agent should call.

Development

bun install
bun run build      # Regenerate public/index.json from src/*.json
bun run dev        # Vercel local dev server
bun run format     # Format all JSON files
bun run lint       # tsc --noEmit type check
bun run deploy     # Deploy to Vercel production

bun run build is the only build step. It reads every plugin definition in src/ and writes the discovery registry to public/index.json. CI runs it on every push and fails if the file is not produced, so re-run it whenever you add or edit a plugin definition.

API Reference

Full Bitrefill API docs: docs.bitrefill.com/docs

License

Documentation

Full documentation site: https://nirholas.github.io/bitrefill-plugin/

Getting started covers install and first run.
Examples has copy-paste snippets.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
api		api
docs		docs
locales		locales
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Navigation Menu

Repository navigation

About

Repository files navigation

Bitrefill Plugin for SperaxOS

Plugins

File Structure

Plugin 1: Bitrefill (Default) — `sperax-bitrefill`

Plugin 2: Bitrefill Catalog (Markdown) — `bitrefill-catalog`

Plugin 3: Bitrefill Store (Standalone) — `bitrefill-store`

Plugin 4: Bitrefill API (OpenAPI) — `bitrefill-openapi`

Authentication

Architecture

Adding to plugin.delivery

Wiring an agent to these plugins

Development

API Reference

License

Documentation

Star History

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Bitrefill Plugin for SperaxOS

Plugins

File Structure

Plugin 1: Bitrefill (Default) — sperax-bitrefill

Plugin 2: Bitrefill Catalog (Markdown) — bitrefill-catalog

Plugin 3: Bitrefill Store (Standalone) — bitrefill-store

Plugin 4: Bitrefill API (OpenAPI) — bitrefill-openapi

Authentication

Architecture

Adding to plugin.delivery

Wiring an agent to these plugins

Development

API Reference

License

Documentation

Star History

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Plugin 1: Bitrefill (Default) — `sperax-bitrefill`

Plugin 2: Bitrefill Catalog (Markdown) — `bitrefill-catalog`

Plugin 3: Bitrefill Store (Standalone) — `bitrefill-store`

Plugin 4: Bitrefill API (OpenAPI) — `bitrefill-openapi`