@basis-theory/web-elements 2.11.2 → 3.0.0-beta.3

package/README.md

@@ -1,3 +1,344 @@
-# Basis Theory Web Elements
+# @basis-theory/web-elements
 
-## [Documentation](https://developers.basistheory.com/docs/sdks/web/web-elements/)
+Secure, PCI-compliant iframe elements for collecting sensitive data in web applications. Card data never touches your servers.
+
+## Installation
+
+### npm
+
+```bash
+npm install @basis-theory/web-elements@beta
+```
+
+### yarn
+
+```bash
+yarn add @basis-theory/web-elements@beta
+```
+
+### CDN
+
+```html
+<script src="https://js.basistheory.com/3.0.0-beta.2/web-elements/basis-theory.js"></script>
+```
+
+## Quick Start
+
+```typescript
+import BasisTheory from '@basis-theory/web-elements';
+
+// Initialize (synchronous -- returns immediately)
+const bt = BasisTheory('pk_test_...');
+
+// Create elements
+const cardNumberEl = bt.createElement('cardNumber', {
+  placeholder: '4242 4242 4242 4242',
+});
+const expiryEl = bt.createElement('expiry', {
+  placeholder: 'MM/YY',
+});
+const cvvEl = bt.createElement('cvv', {
+  placeholder: '123',
+});
+
+// Mount to DOM (async -- creates secure iframes)
+await Promise.all([
+  cardNumberEl.mount('#card-number'),
+  expiryEl.mount('#expiry'),
+  cvvEl.mount('#cvv'),
+]);
+
+// Listen for validation changes
+cardNumberEl.on('change', (event) => {
+  console.log('Valid:', event.detail.isValid);
+  console.log('Brand:', event.detail.cardBrand);
+});
+
+// Tokenize on form submission
+const token = await bt.tokens.create({
+  type: 'card',
+  data: {
+    number: cardNumberEl,
+    expiration_month: expiryEl,
+    expiration_year: expiryEl,
+    cvc: cvvEl,
+  },
+});
+
+console.log('Token ID:', token.id);
+```
+
+### CDN Usage
+
+```html
+<script src="https://js.basistheory.com/3.0.0-beta.2/web-elements/basis-theory.js"></script>
+<script>
+  document.addEventListener('DOMContentLoaded', async () => {
+    const bt = BasisTheory('pk_test_...');
+
+    const cardNumberEl = bt.createElement('cardNumber');
+    const expiryEl = bt.createElement('expiry');
+    const cvvEl = bt.createElement('cvv');
+
+    await Promise.all([
+      cardNumberEl.mount('#card-number'),
+      expiryEl.mount('#expiry'),
+      cvvEl.mount('#cvv'),
+    ]);
+  });
+</script>
+```
+
+## Element Types
+
+| Type | `createElement` key | Description |
+|------|---------------------|-------------|
+| Card Number | `'cardNumber'` | PAN input with Luhn validation and brand detection |
+| Expiry | `'expiry'` | MM/YY expiration date input |
+| CVV | `'cvv'` | Card verification code input |
+| Text | `'text'` | General-purpose secure text input (SSN, routing numbers, etc.) |
+
+### Shared Options
+
+All element types accept these options in `createElement()` and `element.update()`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `placeholder` | `string` | -- | Placeholder text shown when the input is empty |
+| `ariaLabel` | `string` | Element-specific | ARIA label for screen readers |
+| `disabled` | `boolean` | `false` | Disables the input |
+| `readOnly` | `boolean` | `false` | Makes the input read-only |
+
+### Text Element Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `validation` | `RegExp` | Pattern the value must match to be valid |
+| `required` | `boolean` | Whether the field is required |
+| `maxLength` | `number` | Maximum character length |
+| `password` | `boolean` | Renders as a password field |
+| `inputMode` | `string` | Mobile keyboard hint (`'numeric'`, `'tel'`, etc.) |
+| `mask` | `(RegExp \| string)[]` | Character-by-character input mask |
+| `transform` | `[RegExp, string]` | Transform applied before tokenization |
+
+### CVV Element Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `showToggle` | `boolean` | `false` | Renders a show/hide toggle button inside the field |
+
+## Element Methods
+
+Every element exposes the same interface:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `mount` | `(selector: string \| HTMLElement) => Promise<void>` | Attaches the iframe to the DOM |
+| `unmount` | `() => void` | Removes the iframe from the DOM |
+| `update` | `(options) => Promise<void>` | Updates options on a mounted element |
+| `focus` | `() => void` | Focuses the input |
+| `blur` | `() => void` | Blurs the input |
+| `clear` | `() => void` | Clears the current value |
+| `on` | `(event, listener) => () => void` | Subscribes to an event; returns an unsubscribe function |
+
+Properties: `id` (string), `type` (ElementType), `mounted` (boolean).
+
+## Events
+
+| Event | Fires when |
+|-------|-----------|
+| `ready` | Element iframe is loaded and interactive |
+| `change` | Input value changes |
+| `focus` | Element receives focus |
+| `blur` | Element loses focus |
+| `error` | An infrastructure or API error occurs |
+
+### change Event Payload
+
+All elements include these fields in `event.detail`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isValid` | `boolean` | Input passes all validation rules |
+| `isEmpty` | `boolean` | Input is empty |
+| `error` | `ValidationError \| null` | Validation error, or `null` if valid |
+| `elementType` | `string` | Element type that fired the event |
+| `elementId` | `string` | Unique element ID |
+| `timestamp` | `number` | Unix timestamp (ms) |
+
+The `cardNumber` element adds: `cardBrand`, `last4`, `bin`, `cvvLengths`, `potentialBrands`, and `matchStrength`.
+
+```typescript
+cardNumberEl.on('change', (event) => {
+  const { isValid, cardBrand, last4 } = event.detail;
+  console.log(`${cardBrand} ...${last4}`, isValid);
+});
+```
+
+### error Event Codes
+
+| Code | Description |
+|------|-------------|
+| `MOUNT_ERROR` | Failed to mount the element iframe |
+| `POSTMESSAGE_TIMEOUT` | PostMessage timeout |
+| `IFRAME_LOAD_ERROR` | Element iframe failed to load |
+| `INITIALIZATION_ERROR` | SDK or coordinator failed to initialize |
+| `API_ERROR` | Basis Theory API returned an error |
+| `NETWORK_ERROR` | Network request failed |
+| `VALIDATION_ERROR` | Input failed client-side validation |
+| `INVALID_CONFIGURATION` | Invalid SDK or element options |
+| `UNKNOWN_ERROR` | Unexpected error |
+
+## SDK Options
+
+```typescript
+const bt = BasisTheory('pk_test_...', {
+  debug: false,            // Enable verbose debug logging
+  themeMode: 'auto',       // 'light' | 'dark' | 'auto'
+  theme: { /* ThemeTokens */ },
+  darkTheme: { /* ThemeTokens */ },
+  timeoutMs: 30000,        // PostMessage timeout (ms)
+});
+```
+
+## Services
+
+### tokens
+
+```typescript
+// Create a token
+const token = await bt.tokens.create({
+  type: 'card',
+  data: {
+    number: cardNumberEl,
+    expiration_month: expiryEl,
+    expiration_year: expiryEl,
+    cvc: cvvEl,
+  },
+});
+
+// Retrieve a token
+const retrieved = await bt.tokens.retrieve(token.id, {
+  apiKey: sessionApiKey, // from an authorized session
+});
+
+// Update a token
+await bt.tokens.update(token.id, {
+  metadata: { source: 'updated' },
+});
+
+// Encrypt with client-side JWE
+const encrypted = await bt.tokens.encrypt(
+  { type: 'card', data: { number: cardNumberEl, cvc: cvvEl } },
+  publicKeyPEM,
+  'key-id-123'
+);
+```
+
+### tokenize
+
+```typescript
+const result = await bt.tokenize({
+  number: cardNumberEl,
+  cvv: cvvEl,
+  expiry: expiryEl,
+});
+```
+
+### tokenIntents
+
+```typescript
+const intent = await bt.tokenIntents.create({
+  type: 'card',
+  data: {
+    number: cardNumberEl,
+    expiration_month: expiryEl,
+    expiration_year: expiryEl,
+    cvc: cvvEl,
+  },
+});
+
+const retrieved = await bt.tokenIntents.get(intent.id);
+```
+
+### sessions
+
+```typescript
+const session = await bt.sessions.create();
+// Send session.nonce to your backend to authorize
+// Backend returns an apiKey for elevated access
+
+const token = await bt.tokens.retrieve(tokenId, {
+  apiKey: sessionApiKey,
+});
+```
+
+## Theming
+
+Pass design tokens at initialization and switch modes at runtime:
+
+```typescript
+const bt = BasisTheory('pk_test_...', {
+  themeMode: 'auto',
+  theme: {
+    colors: {
+      primary: '#007bff',
+      error: '#dc3545',
+      success: '#28a745',
+      text: { primary: '#1a1a1a', placeholder: '#6c757d' },
+      background: { default: '#ffffff' },
+      border: { default: '#dee2e6', focus: '#007bff' },
+    },
+    typography: {
+      fontFamily: 'Inter, sans-serif',
+      fontSize: { base: '16px' },
+      fontWeight: { normal: '400' },
+    },
+    spacing: { sm: '8px', md: '12px', lg: '16px' },
+    borders: {
+      radius: { base: '6px' },
+      width: { base: '1px' },
+    },
+  },
+});
+
+// Switch theme mode at runtime
+await bt.updateThemeMode('dark');
+```
+
+## TypeScript
+
+The package ships full type definitions. Key exports:
+
+```typescript
+import type {
+  BasisTheorySDK,
+  Element,
+  ElementType,
+  ElementOptions,
+  SDKOptions,
+  ChangeEventDetail,
+  CardNumberChangeEventDetail,
+  ReadyEventDetail,
+  ErrorEventDetail,
+  ErrorCode,
+  ValidationError,
+  TokenizeResult,
+  Session,
+} from '@basis-theory/web-elements';
+```
+
+## Documentation
+
+Full documentation: [https://developers.basistheory.com/docs/sdks/web/web-elements/](https://developers.basistheory.com/docs/sdks/web/web-elements/)
+
+- [Getting Started](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/getting-started)
+- [Element Types](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/components)
+- [Events](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/events)
+- [Services](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/services)
+- [Theming](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/theming)
+- [Migration Guide (v2 to v3)](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/migration)
+
+## License
+
+Apache-2.0

package/dist/.vite/manifest.json

@@ -0,0 +1,27 @@
+{
+  "_index-BBfuUaLw.js": {
+    "file": "index-BBfuUaLw.js",
+    "name": "index",
+    "dynamicImports": [
+      "src/elements/create-card.ts"
+    ],
+    "integrity": "sha384-uSoWS5QGRB9FD+tnc9SotWKHHU5/nLmr2IVmjU/YMnBOBwg3MOXjsj7VYlFw+Rpm"
+  },
+  "src/elements/create-card.ts": {
+    "file": "create-card-DipDWgph.js",
+    "name": "create-card",
+    "src": "src/elements/create-card.ts",
+    "isDynamicEntry": true,
+    "imports": [
+      "_index-BBfuUaLw.js"
+    ],
+    "integrity": "sha384-ghGZpmJtjKvmURaj6QaLxtRDDbnc+4EKBMsgYO68iicGxqHHmGAsWyjbWhxBmreJ"
+  },
+  "src/index.ts": {
+    "file": "basis-theory-sdk.umd.js",
+    "name": "index",
+    "src": "src/index.ts",
+    "isEntry": true,
+    "integrity": "sha384-ddyMdTUvEA0NROPra0/eWz+jWaUMNSsyhhlM1rCTNGdqTMkLAHqd5G/QQPZ/uJbv"
+  }
+}

package/dist/api-client/src/api-client.d.ts

@@ -0,0 +1,11 @@
+/**
+ * BasisTheory API Client
+ *
+ * Provides tokenization, BIN lookup, and proxy services
+ */
+import type { BasisTheoryClient, HttpClientConfig } from './types';
+/**
+ * Create BasisTheory API client
+ */
+export declare const createBasisTheoryClient: (apiKey: string, options?: Partial<HttpClientConfig>) => BasisTheoryClient;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client/src/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../../api-client/src/api-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EACV,iBAAiB,EAEjB,gBAAgB,EAKjB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ,MAAM,EACd,UAAS,OAAO,CAAC,gBAAgB,CAAM,KACtC,iBA0KF,CAAC"}

package/dist/api-client/src/http-client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HTTP Client with retry, timeout, and caching
+ */
+import type { DebugLogger } from '@basis-theory-elements/shared';
+import type { HttpClientConfig, HttpResponse, RequestOptions } from './types';
+/**
+ * Create HTTP client with retry, timeout, and caching
+ */
+export declare const createHttpClient: (config: HttpClientConfig) => {
+    /**
+     * Make HTTP request
+     */
+    request<T = unknown>(url: string, options?: RequestOptions, log?: DebugLogger): Promise<HttpResponse<T>>;
+    /**
+     * Clear cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache size
+     */
+    getCacheSize(): number;
+};
+export type HttpClient = ReturnType<typeof createHttpClient>;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/api-client/src/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../../../../api-client/src/http-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,OAAO,KAAK,EAEV,gBAAgB,EAEhB,YAAY,EACZ,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,gBAAgB;IA0QrD;;OAEG;YACW,CAAC,iBACR,MAAM,YACF,cAAc,QACjB,WAAW,GAChB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAkE3B;;OAEG;kBACW,IAAI;IAIlB;;OAEG;oBACa,MAAM;CAIzB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/api-client/src/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @basis-theory-elements/api-client
+ *
+ * Standalone HTTP client for BasisTheory API with tokenization, BIN lookup, and proxy
+ */
+export { createBasisTheoryClient } from './api-client';
+export { createHttpClient } from './http-client';
+export type { BasisTheoryClient, BinInfo, CacheEntry, HttpClientConfig, HttpError, HttpResponse, ProxyRequest, RequestOptions, Token, TokenCreateRequest, TokenData, TokenIntent, TokenIntentCreateRequest, TokenUpdateRequest, TokenizeRequest, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/api-client/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../api-client/src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,YAAY,EAEV,iBAAiB,EAEjB,OAAO,EAEP,UAAU,EAEV,gBAAgB,EAChB,SAAS,EAET,YAAY,EAEZ,YAAY,EACZ,cAAc,EAEd,KAAK,EACL,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/api-client/src/services/sessions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sessions Service
+ *
+ * Handles session creation for temporary elevated access to tokenized data
+ * Sessions must be authorized on the backend by a Private Application
+ */
+import type { HttpClient } from '../http-client';
+import type { RequestOptions, Session } from '../types';
+/**
+ * Sessions Service Interface
+ */
+export interface SessionsService {
+    create(options?: RequestOptions): Promise<Session>;
+}
+/**
+ * Create sessions service
+ */
+export declare const createSessionsService: (httpClient: HttpClient) => SessionsService;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/api-client/src/services/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../../../../api-client/src/services/sessions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAChC,YAAY,UAAU,KACrB,eAmDF,CAAC"}

package/dist/api-client/src/services/token-intents.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Token Intents Service
+ *
+ * Handles token intent operations (create, get)
+ * Token Intents are short-lived placeholders for sensitive data validation
+ */
+import type { HttpClient } from '../http-client';
+import type { RequestOptions, TokenIntent, TokenIntentCreateRequest } from '../types';
+export interface TokenIntentsService {
+    create(data: TokenIntentCreateRequest, options?: RequestOptions): Promise<TokenIntent>;
+    get(id: string, options?: RequestOptions): Promise<TokenIntent>;
+}
+/**
+ * Create token intents service bound to HTTP client
+ */
+export declare const createTokenIntentsService: (httpClient: HttpClient) => TokenIntentsService;
+//# sourceMappingURL=token-intents.d.ts.map

package/dist/api-client/src/services/token-intents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-intents.d.ts","sourceRoot":"","sources":["../../../../../api-client/src/services/token-intents.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,wBAAwB,EACzB,MAAM,UAAU,CAAC;AAalB,MAAM,WAAW,mBAAmB;IAClC,MAAM,CACJ,IAAI,EAAE,wBAAwB,EAC9B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACjE;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACpC,YAAY,UAAU,KACrB,mBA4DF,CAAC"}

package/dist/api-client/src/services/tokens.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tokens Service
+ *
+ * Handles all token-related API operations (CRUD)
+ * Uses snake_case to match BasisTheory API directly
+ * Separated from main API client to keep bundle size lean
+ */
+import type { HttpClient } from '../http-client';
+import type { RequestOptions, Token, TokenCreateRequest, TokenUpdateRequest } from '../types';
+export interface TokensService {
+    create(data: TokenCreateRequest, options?: RequestOptions): Promise<Token>;
+    update(id: string, data: TokenUpdateRequest, options?: RequestOptions): Promise<Token>;
+    retrieve(id: string, options?: RequestOptions): Promise<Token>;
+}
+/**
+ * Create tokens service bound to HTTP client
+ */
+export declare const createTokensService: (httpClient: HttpClient) => TokensService;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/api-client/src/services/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../../../api-client/src/services/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,UAAU,CAAC;AAalB,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3E,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,kBAAkB,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,KAAK,CAAC,CAAC;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;CAChE;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,YAAY,UAAU,KAAG,aAsH5D,CAAC"}