@credit-engine/widget

Embeddable credit balance and history components for any framework. Built with Web Components — works in React, Vue, Svelte, or vanilla HTML.

Install

npm:

npm install @credit-engine/widget

import '@credit-engine/widget'; // Auto-registers all components

CDN:

<script src="https://unpkg.com/@credit-engine/widget"></script>

Components

<credit-engine-badge>

Compact balance display for navbars and headers.

<credit-engine-badge
  api-key="ce_pub_xxx"
  customer-id="cus_xxx"
  theme="light"
  poll-interval="30000"
/>

<credit-engine-widget>

Full dashboard widget with balance, progress bar, recent history, and top-up button.

<credit-engine-widget
  api-key="ce_pub_xxx"
  customer-id="cus_xxx"
  theme="dark"
  show-topup="true"
  show-history="true"
  poll-interval="30000"
/>

<credit-engine-history>

Paginated transaction history table.

<credit-engine-history
  api-key="ce_pub_xxx"
  customer-id="cus_xxx"
  theme="light"
  page-size="10"
/>

Attributes

| Attribute | Components | Description | Default | |-----------|-----------|-------------|---------| | api-key | All | Publishable API key (ce_pub_xxx) | Required | | customer-id | All | Customer identifier | Required | | base-url | All | Custom API URL | https://api.creditengine.dev | | theme | All | "light" or "dark" | "light" | | poll-interval | Badge, Widget | Auto-refresh interval in ms | 30000 | | show-topup | Widget | Show "Buy more" button | "true" | | show-history | Widget | Show recent transactions | "true" | | page-size | History | Rows per page | 10 |

Theming

Override styles with CSS variables:

credit-engine-widget {
  --ce-primary: #6366f1;
  --ce-bg: #ffffff;
  --ce-text: #1f2937;
  --ce-text-secondary: #6b7280;
  --ce-border: #e5e7eb;
  --ce-radius: 8px;
  --ce-font: inherit;
  --ce-success: #10b981;
  --ce-danger: #ef4444;
}

All components use Shadow DOM — your page styles won't leak in, and widget styles won't leak out.

Authentication

Widget components use publishable keys (ce_pub_xxx), safe to expose in frontend code. These keys only allow read operations (balance, transactions) and checkout session creation.

License

MIT