Rebill Web Components SDK (v3.1)

A framework‑agnostic Web Components SDK (built with Stencil) to embed Rebill checkout, payments, and renewal flows in any website or app.

This SDK provides production‑ready components (checkout form, payment method selector, card iframe, OTP, discounts, summary, renewal), dynamic runtime configuration, i18n support, and a lightweight loader for easy integration.

🚀 Quick Start

1. Install the SDK

npm install v3-1-sdk

2. Use Components (No initialization required!)

<!-- Your HTML - works out of the box with production settings -->
<rebill-checkout></rebill-checkout>

// Or programmatically
import { defineCustomElements } from 'v3-1-sdk/loader';
defineCustomElements(window);

3. Optional: Configure for Different Environments

import { initializeRebillSDK } from 'v3-1-sdk';

// Only needed if you want to use staging or development
initializeRebillSDK({
  environment: 'staging', // 'development' | 'staging' | 'production'
  debug: true,
});

🔧 Configuration

The SDK works out of the box with production settings. Configuration is optional and only needed for staging or development environments.

Default Behavior

• Production environment by default
• No initialization required for client applications
• Production API endpoints automatically used

Optional Environment Configuration

import { initializeRebillSDK } from 'v3-1-sdk';

// For staging (optional)
initializeRebillSDK({
  environment: 'staging',
  debug: true,
});

// For development (optional)
initializeRebillSDK({
  environment: 'development',
  debug: true,
});

// For production (optional - this is the default)
initializeRebillSDK({
  environment: 'production',
  debug: false,
});

Quick Helpers

import { RebillSDK } from 'v3-1-sdk';

// Quick setup (all optional)
RebillSDK.forProduction(); // Default behavior
RebillSDK.forStaging(); // For testing
RebillSDK.forDevelopment(); // For local development

🚀 Publishing

Prerequisites

• Access: write permissions to the repository and the NPM package.
• Secrets: NPM_TOKEN configured in the repository Secrets (used to publish). GITHUB_TOKEN is provided by Actions by default.

GitHub Actions Workflow

Publish Package to NPM

Use the "Publish package to NPM" workflow for both staging and production releases.

1. In GitHub, go to Actions → "Publish package to NPM" → Run workflow.
2. Fill in the inputs:
   • release_type: staging or production.
   • version_strategy: patch, minor, major, or prerelease (only for staging).

Examples:

• staging + patch → 1.1.14-beta.0 (new patch prerelease)
• staging + prerelease → 1.1.14-beta.1 (increment prerelease)
• production + patch → 1.1.14 (stable release)

3. The workflow will automatically:
   • Build the SDK (environment-agnostic)
   • Run tests
   • Bump version (prerelease for staging, stable for production)
   • Publish with appropriate tag (stage or latest)
   • Create git tag and GitHub release

Installation from NPM

# Staging (prerelease channel)
npm install v3-1-sdk@stage

# Production (stable channel)
npm install v3-1-sdk@latest

Manual Publishing (Alternative)

# Install dependencies
npm ci

# Build (environment-agnostic)
npm run build

# Test
npm test

# Pack and verify (optional but recommended)
npm pack

# Publish staging
npm version prepatch --preid beta
npm publish --tag stage

# Publish staging (new prerelease)
npm version prepatch --preid beta
npm publish --tag stage

# Publish staging (increment prerelease)
npm version prerelease --preid beta
npm publish --tag stage

# Publish production
npm version patch
npm publish

Note: The GitHub Actions workflow follows these exact same steps automatically.

Key Changes

• Single build for all environments (environment-agnostic)
• Runtime configuration instead of compile-time
• Simplified workflows with fewer inputs
• Consistent versioning across environments

Assets path in consumers

En Stencil v4 el loader no exporta setAssetPath. Para que los componentes resuelvan getAssetPath('./assets/...') cuando tu aplicación bundlea el paquete, utiliza la opción resourcesUrl de defineCustomElements y apunta al lugar donde sirves la carpeta dist/ del paquete.

Ejemplos:

// Vite/Webpack/Next/etc.
import { defineCustomElements } from 'v3-1-sdk/loader';

// Dónde tu app sirve el contenido de la librería (carpeta que contiene `assets/`)
// Ejemplo si copiaste `node_modules/v3-1-sdk/dist/` a /public/vendor/v3-1-sdk/
defineCustomElements(window, { resourcesUrl: '/vendor/v3-1-sdk/' });

<!-- Cargando el ESM directamente desde una URL (CDN o estático) -->
<script type="module" src="/vendor/v3-1-sdk/v3-1-sdk.esm.js"></script>
<!-- En este caso Stencil detecta el base path automáticamente, no hace falta configurar nada -->

Alternativa sin resourcesUrl: copiar dist/assets/ al path público /assets de tu app para que las URLs /assets/... funcionen tal cual. Sin embargo, la opción recomendada es configurar resourcesUrl para evitar acoplamientos con rutas absolutas.