npm - @mygigsters/card-sdk - Versions diffs - 1.0.2 → 1.0.3 - Mend

@mygigsters/card-sdk 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md CHANGED Viewed

@@ -1,647 +1,519 @@
-# @mygigsters/card-sdk
-> Embed a secure, single-step card saving form into any web application — powered by Airwallex Payment Elements.
-[![npm version](https://img.shields.io/npm/v/@mygigsters/card-sdk)](https://www.npmjs.com/package/@mygigsters/card-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
----
-## Table of Contents
-- [Overview](#overview)
-- [Features](#features)
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Get Client Info (API)](#get-client-info-api)
-- [Quick Start](#quick-start)
-- [Module Formats](#module-formats)
-- [Usage Examples](#usage-examples)
-  - [ES Modules (Recommended)](#es-modules-recommended)
-  - [CommonJS](#commonjs)
-  - [CDN / Browser Script Tag](#cdn--browser-script-tag)
-  - [React (useEffect)](#react-useeffect)
-- [Configuration Reference](#configuration-reference)
-- [API Reference](#api-reference)
-  - [init(config)](#initconfig)
-  - [show()](#show)
-  - [hide()](#hide)
-  - [setTheme(mode)](#setthememode)
-  - [destroy()](#destroy)
-  - [getInstance()](#getinstance-cdn-only)
-- [Success Response](#success-response)
-- [Callback Reference](#callback-reference)
-- [Environments](#environments)
-- [Theming](#theming)
-- [Error Handling](#error-handling)
-- [Security](#security)
-- [TypeScript](#typescript)
-- [Troubleshooting](#troubleshooting)
-- [Changelog](#changelog)
----
-## Overview
-The **MyGigsters Card SDK** renders a secure, self-contained modal that lets your customers save their payment card in a single step. The SDK:
-- Authenticates with the MyGigsters backend using your API credentials.
-- Embeds an **Airwallex Payment Element** inside a **closed Shadow DOM** — your host page styles never leak in and vice versa.
-- Returns a `paymentConsentId` on success — no raw card data ever touches your server.
----
-## Features
-- **Airwallex-powered card tokenization** — PCI-compliant card element embedded in an isolated iframe.
-- **Shadow DOM isolation** — No CSS conflicts with your app.
-- **Light & Dark themes** — Toggle at init time or at runtime.
-- **Zero React dependency** — Works in any JavaScript app (React, Vue, Angular, plain HTML).
-- **Multiple module formats** — ESM, CJS, CDN (UMD).
-- **TypeScript** — Full type definitions included (`dist/index.d.ts`).
-- **Webhook support** — Optionally POST the success payload to your own endpoint.
----
-## Requirements
-| Requirement | Version |
-|-------------|---------|
-| Browser | Chrome 80+, Firefox 78+, Safari 14+, Edge 80+ |
-| Node.js (build/dev only) | ≥ 14.0.0 |
-| React (optional) | ≥ 18.0.0 |
-> **Note:** The SDK must be served over **HTTPS** (or `localhost` for development). Airwallex payment elements require a secure context.
----
-## Installation
-```bash
-# npm
-npm install @mygigsters/card-sdk
-# yarn
-yarn add @mygigsters/card-sdk
-# pnpm
-pnpm add @mygigsters/card-sdk
-```
----
-## Get Client Info (API)
-Before initializing the Card SDK, you need your **`myGigsterId`** and the customer's **`customerId`**. Call the `GET /api/v1/client/me` endpoint using your API credentials (HTTP Basic Auth `uuid:randomPasswordShowOnce`) to retrieve your client account profile and `myGigsterId`. Obtain the `customerId` by creating a customer via `POST /api/v1/customer`.
-### Endpoint
-```http
-GET /api/v1/client/me
-```
-| Environment | URL |
-|-------------|-----|
-| Demo / QA | `https://qa-payments.mygigsters.com.au/api/v1/client/me` |
-| Production | `https://prod-payments.mygigsters.com.au/api/v1/client/me` |
-### Headers
-```http
-Content-Type: application/json
-x-api-version: 1.2
-Authorization: Basic {base64_encoded_combination of uuid:randomPasswordShowOnce}
-```
-### Example Request
-```bash
-curl --location 'https://qa-payments.mygigsters.com.au/api/v1/client/me' \
-  --header 'Content-Type: application/json' \
-  --header 'x-api-version: 1.2' \
-  --header 'Authorization: Basic MGI3YjFiMTctOTJhZC00Yjc4LWFhN2ItNjI2ODBhOWUzOGExOkt1aFNEa3NCVmFXQFNPQyhZQCFh'
-```
-### Example Response (200 OK)
-```json
-{
-  "success": true,
-  "status": 200,
-  "data": {
-    "id": 1,
-    "myGigsterId": "4407c3ba-10c9-4822-9f51-c2c96692f8d7",
-    "fullName": "Nitesh ",
-    "email": "nitesh@megamindcreations.com",
-    "businessName": "MG Nitesh Agrwal Deswal",
-    "address": null,
-    "acn": "123456789",
-    "phone": "9876543210"
-  }
-}
-```
-### Response Fields for Card SDK
-| Field | Type | Description |
-|-------|------|-------------|
-| `data.myGigsterId` | `string` | **Required by SDK:** Your unique MyGigsters client account identifier. Pass as `myGigsterId` in `init()`. |
-| `data.fullName` | `string` | Registered full name of the client. |
-| `data.email` | `string` | Registered contact email address. |
-| `data.businessName` | `string` | Registered business or entity name. |
-| `data.phone` | `string` | Contact phone number. |
-| `data.acn` | `string` | Australian Company Number (if applicable). |
----
-## Quick Start
-**1. Add a container element in your HTML:**
-```html
-<div id="mygigsters-card"></div>
-```
-**2. Initialize the SDK:**
-```javascript
-import { MygigstersCardSDK } from '@mygigsters/card-sdk';
-const sdk = new MygigstersCardSDK();
-await sdk.init({
-  apiKey:      'your_api_key',
-  apiSecret:   'your_api_secret',
-  customerId:  'cus_hkdmcdjshhknkk4lc2t',
-  myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
-  containerId: 'mygigsters-card',
-  env:         'demo',
-  onSuccess: (res) => console.log('Card saved! Consent ID:', res.paymentConsentId),
-  onError:   (err) => console.error('Error:', err.message),
-  onClose:   ()    => console.log('Modal closed'),
-});
-```
-The card modal opens automatically after `init()` resolves.
----
-## Module Formats
-| Format | Path | Use Case |
-|--------|------|----------|
-| **ESM** | `dist/index.esm.js` | Modern bundlers (Vite, Webpack 5, Rollup) |
-| **CommonJS** | `dist/index.cjs.js` | Node.js / `require()` environments |
-| **CDN (UMD)** | `cdn/card-sdk-entry.js` | Browser `<script>` tag / self-hosted CDN |
-| **TypeScript** | `dist/index.d.ts` | Type definitions |
----
-## Usage Examples
-### ES Modules (Recommended)
-```javascript
-import { MygigstersCardSDK } from '@mygigsters/card-sdk';
-const sdk = new MygigstersCardSDK();
-await sdk.init({
-  apiKey:      'your_api_key',
-  apiSecret:   'your_api_secret',
-  customerId:  'cus_hkdmcdjshhknkk4lc2t',
-  myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
-  containerId: 'mygigsters-card',
-  env:         'demo',           // 'demo' | 'prod'
-  mode:        'dark',           // optional: 'dark' (default) | 'light'
-  onSuccess: (res) => {
-    console.log('✅ Card saved:', res.paymentConsentId);
-    // Pass res.paymentConsentId to the MyGigsters API to charge the customer
-  },
-  onError: (err) => {
-    console.error('❌ Error:', err.message);
-  },
-  onClose: () => {
-    console.log('Modal closed by user');
-  },
-});
-```
----
-### CommonJS
-```javascript
-const { MygigstersCardSDK } = require('@mygigsters/card-sdk');
-const sdk = new MygigstersCardSDK();
-sdk.init({
-  apiKey:      'your_api_key',
-  apiSecret:   'your_api_secret',
-  customerId:  'cus_hkdmcdjshhknkk4lc2t',
-  myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
-  containerId: 'mygigsters-card',
-  onSuccess: (res) => console.log('Card saved:', res.paymentConsentId),
-  onError:   (err) => console.error('Error:', err.message),
-  onClose:   ()    => console.log('Closed'),
-});
-```
----
-### CDN / Browser Script Tag
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <title>My App</title>
-</head>
-<body>
-  <!-- 1. Mount target -->
-  <div id="mygigsters-card"></div>
-  <!-- 2. Trigger button (optional) -->
-  <button onclick="openCardForm()">Save Card</button>
-  <!-- 3. Load the SDK -->
-  <script src="https://qa-payments.mygigsters.com.au/card-sdk-entry.js"></script>
-  <script>
-    async function openCardForm() {
-      await MygigstersCard.init({
-        apiKey:      'your_api_key',
-        apiSecret:   'your_api_secret',
-        customerId:  'cus_hkdmcdjshhknkk4lc2t',
-        myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
-        containerId: 'mygigsters-card',
-        env:         'demo',
-        mode:        'dark',
-        onSuccess: (res) => console.log('✅ Card saved:', res.paymentConsentId),
-        onError:   (err) => console.error('❌ Error:', err.message),
-        onClose:   ()    => console.log('Closed'),
-      });
-    }
-  </script>
-</body>
-</html>
-```
-> **CDN global:** The CDN build exposes `window.MygigstersCard` (not `MygigstersCardSDK`).
----
-### React (useEffect)
-```jsx
-import { useEffect } from 'react';
-import { MygigstersCardSDK } from '@mygigsters/card-sdk';
-function SaveCardForm({ customerId, myGigsterId }) {
-  useEffect(() => {
-    const sdk = new MygigstersCardSDK();
-    sdk.init({
-      apiKey:      'your_api_key',
-      apiSecret:   'your_api_secret',
-      customerId,
-      myGigsterId,
-      containerId: 'mygigsters-card',
-      env:         'demo',
-      mode:        'dark',
-      onSuccess: (res) => console.log('Card saved!', res.paymentConsentId),
-      onError:   (err) => console.error(err),
-      onClose:   ()    => console.log('Closed'),
-    });
-    // Cleanup on unmount
-    return () => sdk.destroy();
-  }, [customerId, myGigsterId]);
-  return <div id="mygigsters-card" />;
-}
-```
----
-## Configuration Reference
-Pass these options to `init()`:
-| Parameter | Type | Required | Default | Description |
-|-----------|------|:--------:|---------|-------------|
-| `apiKey` | `string` | ✅ | — | UUID-style API key issued by MyGigsters |
-| `apiSecret` | `string` | ✅ | — | One-time API secret (shown once at creation) |
-| `customerId` | `string` | ✅ | — | MyGigsters customer ID for whom the card is saved (from `POST /api/v1/customer`) |
-| `myGigsterId` | `string` | ✅ | — | Unique client account identifier (from `GET /api/v1/client/me`) |
-| `containerId` | `string` | ✅ | — | `id` of the DOM element to mount the SDK into |
-| `env` | `'demo' \| 'prod'` | ❌ | `'demo'` | Target environment |
-| `baseUrl` | `string` | ❌ | — | Custom base URL override (for self-hosted deployments) |
-| `mode` | `'light' \| 'dark'` | ❌ | `'dark'` | UI color theme |
-| `onSuccess` | `(res) => void` | ❌ | no-op | Fired after the card is saved successfully |
-| `onError` | `(error) => void` | ❌ | `console.error` | Fired on any SDK or network error |
-| `onClose` | `() => void` | ❌ | no-op | Fired when the user closes the modal |
-| `webhookUrl` | `string` | ❌ | — | URL to POST the success payload to automatically |
-| `onWebhook` | `(payload) => void` | ❌ | no-op | JS callback for receiving the webhook payload in real-time |
----
-## API Reference
-### `init(config)`
-Authenticates with the MyGigsters backend, builds the Shadow DOM modal, initializes the Airwallex card element, and automatically calls `show()`.
-```javascript
-import { MygigstersCardSDK } from '@mygigsters/card-sdk';
-const sdk = new MygigstersCardSDK();
-await sdk.init(config);
-// or, via CDN:
-await MygigstersCard.init(config);
-```
-- **Returns:** `Promise<void>`
-- **Throws:** if `apiKey`, `apiSecret`, `customerId`, `myGigsterId`, or `containerId` are missing; if the container element is not found; or if authentication fails.
-- Each SDK instance maintains its own internal state.
-- CDN builds expose a singleton instance automatically.
----
-### `show()`
-Shows the card modal. Called automatically by `init()`, but can be called again after `hide()`.
-```javascript
-sdk.show();
-```
-Throws `Error: SDK not initialized. Call init() first.` if called before `init()`.
----
-### `hide()`
-Hides the modal without destroying the SDK instance. The Airwallex card element state is preserved.
-```javascript
-sdk.hide();
-```
----
-### `setTheme(mode)`
-Switch the UI theme at runtime — no need to re-initialize.
-```javascript
-sdk.setTheme('dark');  // or 'light'
-```
-```javascript
-// Example: sync with OS preference
-const mq = window.matchMedia('(prefers-color-scheme: dark)');
-mq.addEventListener('change', (e) => {
-  sdk.setTheme(e.matches ? 'dark' : 'light');
-});
-```
----
-### `destroy()`
-Removes the modal from the DOM and resets all internal state. Call this when navigating away or unmounting the host component.
-```javascript
-sdk.destroy();
-```
----
-### `getInstance()` *(CDN only)*
-Returns the underlying SDK instance for advanced use.
-```javascript
-const sdk = MygigstersCard.getInstance();
-```
----
-## Success Response
-The `onSuccess` callback receives a `CardSuccessResponse` object:
-```javascript
-onSuccess: (res) => {
-  // res.paymentConsentId  — Airwallex payment consent ID
-  //                         Pass this to the MyGigsters API when creating a charge
-  // res.customerId        — Customer ID associated with this consent
-  // res.myGigsterId       — MyGigster ID associated with this consent
-  // res.timestamp         — ISO-8601 timestamp of the save event
-  // res.event             — 'card.saved'
-  console.log('Payment Consent ID:', res.paymentConsentId);
-}
-```
----
-## Callback Reference
-### `onSuccess(res)`
-Called after the card is saved and the Airwallex element confirms the payment consent.
-```javascript
-onSuccess: (res) => {
-  // res.paymentConsentId → use to charge the customer via Payment Intents API
-  console.log('Saved!', res);
-}
-```
-### `onError(error)`
-Called when any error occurs — authentication failures, Airwallex element errors, or server rejections.
-```javascript
-onError: (error) => {
-  // error is a standard JS Error object
-  console.error(error.message);
-}
-```
-### `onClose()`
-Called when the user dismisses the modal (close button ×, backdrop click, or Escape key).
-```javascript
-onClose: () => {
-  // Re-show a trigger button, update UI state, etc.
-}
-```
----
-## Environments
-| Environment | SDK Script URL | `env` Value |
-|-------------|----------------|-------------|
-| Demo / QA | `https://qa-payments.mygigsters.com.au/card-sdk-entry.js` | `"demo"` |
-| Production | `https://prod-payments.mygigsters.com.au/card-sdk-entry.js` | `"prod"` |
----
-## Theming
-Set `mode: 'light'` or `mode: 'dark'` in the config object (defaults to `'dark'`).
-You can also switch themes after initialization using [`setTheme()`](#setthememode).
-```javascript
-// Toggle dark mode on a button click
-const sdk = new MygigstersCardSDK();
-document.getElementById('toggle-theme').addEventListener('click', () => {
-  sdk.setTheme(
-    document.body.classList.toggle('dark') ? 'dark' : 'light'
-  );
-});
-```
----
-## Error Handling
-Wrap `init()` in a `try/catch` to handle initialization errors:
-```javascript
-try {
-  const sdk = new MygigstersCardSDK();
-  await sdk.init({ ... });
-} catch (err) {
-  // Common errors:
-  // "apiKey is required"
-  // "customerId is required"
-  // "myGigsterId is required"
-  // "Container element with ID '...' not found"
-  // "Invalid API credentials: Please check your apiKey and apiSecret."
-  // "Authentication failed: ..."
-  console.error('SDK failed to initialize:', err.message);
-}
-```
-Runtime errors (Airwallex element failures, network issues, server rejections) are surfaced via the `onError` callback and displayed inline in the modal.
----
-## Security
-- **Credentials are never stored** in `localStorage` or `sessionStorage`. The auth token lives in memory only.
-- **Authentication** uses HTTP Basic Auth (`base64(apiKey:apiSecret)`) over HTTPS. Never expose your `apiSecret` in client-side code committed to a public repository — use environment variables or a backend-for-frontend pattern.
-- **PCI-compliant card handling** — Raw card data is handled exclusively by Airwallex's PCI-certified payment element embedded inside an Airwallex-controlled iframe. Your server never receives raw card numbers or CVVs.
-- **Shadow DOM** (`mode: 'closed'`) prevents host-page scripts from reaching into the SDK's DOM.
----
-## TypeScript
-Type definitions are included at `dist/index.d.ts`.
-Import the SDK and its types:
-```tsx
-import { useEffect } from 'react';
-import { MygigstersCardSDK } from '@mygigsters/card-sdk';
-import type {
-  MygigstersCardConfig,
-  CardSuccessResponse,
-} from '@mygigsters/card-sdk';
-function SaveCardForm() {
-  useEffect(() => {
-    const initializeSDK = async () => {
-      const config: MygigstersCardConfig = {
-        apiKey: 'YOUR_API_KEY',
-        apiSecret: 'YOUR_API_SECRET',
-        customerId: 'cus_hkdmcdjshhknkk4lc2t',
-        myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
-        containerId: 'mygigsters-card',
-        env: 'demo',
-        mode: 'dark',
-        onSuccess: (res: CardSuccessResponse) => {
-          console.log('Card saved!');
-          console.log('Consent ID:', res.paymentConsentId);
-        },
-        onError: (err) => {
-          console.error('Card SDK error:', err);
-        },
-        onClose: () => {
-          console.log('Card form closed');
-        },
-      };
-      const sdk = new MygigstersCardSDK();
-      await sdk.init(config);
-    };
-    initializeSDK();
-  }, []);
-  return <div id="mygigsters-card" />;
-}
-export default SaveCardForm;
-```
----
-## Troubleshooting
-**`Container element with ID '...' not found`**
-Make sure the target `<div>` exists in the DOM before calling `init()`. If you are using a framework, call `init()` after the component mounts (e.g., inside `useEffect` or `mounted()`).
-**`Invalid API credentials`**
-Double-check that `apiKey` and `apiSecret` match the values shown in your MyGigsters dashboard. The secret is shown only once — if lost, generate a new one.
-**`myGigsterId is required`**
-Make sure `myGigsterId` is provided in the configuration object passed to `init()`. You can retrieve your `myGigsterId` by calling `GET /api/v1/client/me`. To obtain `customerId`, create a customer via `POST /api/v1/customer`.
-**Airwallex card element fails to load**
-Ensure your page is served over **HTTPS**. Also verify that your Airwallex account has card tokenization enabled, and that the `env` setting matches the environment your account credentials belong to.
-**Card modal appears behind other elements**
-The modal is mounted on `<body>` with `z-index: 2147483647`. If another element on your page has a higher stacking context, adjust accordingly. Because the SDK uses Shadow DOM, your global CSS reset will not affect it.
----
-## Changelog
-### 1.0.0
-- Initial public release
-- Single-step card saving via Airwallex Payment Elements
-- Shadow DOM isolation
-- Light / dark theming with runtime `setTheme()` support
-- ESM, CJS, and CDN (UMD) builds
-- TypeScript definitions
-- Webhook support via `webhookUrl` and `onWebhook` options
----
-## License
-MIT © [MyGigsters](https://www.mygigsters.com.au)
+# @mygigsters/card-sdk
+> Embed a secure, single-step card saving form into any web application — powered by Airwallex Payment Elements.
+[![npm version](https://img.shields.io/npm/v/@mygigsters/card-sdk)](https://www.npmjs.com/package/@mygigsters/card-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+---
+## Table of Contents
+- [Overview](#overview)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Get Client Info (API)](#get-client-info-api)
+- [Quick Start](#quick-start)
+- [Module Formats](#module-formats)
+- [Usage Examples](#usage-examples)
+  - [ES Modules (Recommended)](#es-modules-recommended)
+  - [CommonJS](#commonjs)
+  - [CDN / Browser Script Tag](#cdn--browser-script-tag)
+  - [React (useEffect)](#react-useeffect)
+- [Configuration Reference](#configuration-reference)
+- [API Reference](#api-reference)
+  - [init(config)](#initconfig)
+  - [show()](#show)
+  - [hide()](#hide)
+  - [setTheme(mode)](#setthememode)
+  - [destroy()](#destroy)
+  - [getInstance()](#getinstance-cdn-only)
+- [Success Response](#success-response)
+- [Callback Reference](#callback-reference)
+- [Environments](#environments)
+- [Theming](#theming)
+- [Error Handling](#error-handling)
+- [Security](#security)
+- [TypeScript](#typescript)
+- [Troubleshooting](#troubleshooting)
+- [Changelog](#changelog)
+---
+## Overview
+The **MyGigsters Card SDK** renders a secure, self-contained modal that lets your customers save their payment card in a single step. The SDK:
+- Uses a **pre-fetched Bearer token** retrieved from `GET /api/v1/client/me` — no API keys or secrets are ever shared with or stored inside the SDK.
+- Embeds an **Airwallex Payment Element** inside a **closed Shadow DOM** — your host page styles never leak in and vice versa.
+- Returns a `paymentConsentId` on success — no raw card data ever touches your server.
+---
+## Features
+- **Pre-fetched Token Auth** — Client pre-fetches a JWT token via `/client/me` before passing it to the SDK.
+- **Airwallex-powered card tokenization** — PCI-compliant card element embedded in an isolated iframe.
+- **Shadow DOM isolation** — No CSS conflicts with your app.
+- **Light & Dark themes** — Toggle at init time or at runtime.
+- **Zero React dependency** — Works in any JavaScript app (React, Vue, Angular, plain HTML).
+- **Multiple module formats** — ESM, CJS, CDN (UMD).
+- **TypeScript** — Full type definitions included (`dist/index.d.ts`).
+- **Webhook support** — Optionally POST the success payload to your own endpoint.
+---
+## Requirements
+| Requirement | Version |
+|-------------|---------|
+| Browser | Chrome 80+, Firefox 78+, Safari 14+, Edge 80+ |
+| Node.js (build/dev only) | ≥ 14.0.0 |
+| React (optional) | ≥ 18.0.0 |
+> **Note:** The SDK must be served over **HTTPS** (or `localhost` for development). Airwallex payment elements require a secure context.
+---
+## Installation
+```bash
+# npm
+npm install @mygigsters/card-sdk
+# yarn
+yarn add @mygigsters/card-sdk
+# pnpm
+pnpm add @mygigsters/card-sdk
+```
+---
+## Get Client Info (API)
+Before initializing the Card SDK, you need your Bearer **`token`**, **`myGigsterId`**, and the customer's **`customerId`**. Call `GET /api/v1/client/me` using HTTP Basic Auth (`uuid:randomPasswordShowOnce`) to retrieve your `token` and `myGigsterId`. Obtain `customerId` by creating a customer via `POST /api/v1/customer`.
+### Endpoint
+```http
+GET /api/v1/client/me
+```
+| Environment | URL |
+|-------------|-----|
+| Demo / QA | `https://qa-payments.mygigsters.com.au/api/v1/client/me` |
+| Production | `https://prod-payments.mygigsters.com.au/api/v1/client/me` |
+### Headers
+```http
+Content-Type: application/json
+x-api-version: 1.1
+Authorization: Basic {base64_encoded_combination of uuid:randomPasswordShowOnce}
+```
+### Example Request
+```bash
+curl --location 'https://qa-payments.mygigsters.com.au/api/v1/client/me' \
+  --header 'Content-Type: application/json' \
+  --header 'x-api-version: 1.1' \
+  --header 'Authorization: Basic MGI3YjFiMTctOTJhZC00Yjc4LWFhN2ItNjI2ODBhOWUzOGExOkt1aFNEa3NCVmFXQFNPQyhZQCFh'
+```
+### Example Response (200 OK)
+```json
+{
+  "success": true,
+  "status": 200,
+  "data": {
+    "id": 1,
+    "myGigsterId": "4407c3ba-10c9-4822-9f51-c2c96692f8d7",
+    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "fullName": "Nitesh ",
+    "email": "nitesh@megamindcreations.com",
+    "businessName": "MG Nitesh Agrwal Deswal",
+    "address": null,
+    "acn": "123456789",
+    "phone": "9876543210"
+  }
+}
+```
+### Response Fields for Card SDK
+| Field | Type | Description |
+|-------|------|-------------|
+| `data.token` | `string` | **Required by SDK:** Bearer JWT token required to authenticate SDK requests. Pass as `token` in `init()`. |
+| `data.myGigsterId` | `string` | **Required by SDK:** Your unique MyGigsters client account identifier. Pass as `myGigsterId` in `init()`. |
+| `data.fullName` | `string` | Registered full name of the client. |
+| `data.email` | `string` | Registered contact email address. |
+| `data.businessName` | `string` | Registered business or entity name. |
+---
+## Quick Start
+**1. Add a container element in your HTML:**
+```html
+<div id="mygigsters-card"></div>
+```
+**2. Initialize the SDK:**
+```javascript
+import { MygigstersCardSDK } from '@mygigsters/card-sdk';
+const sdk = new MygigstersCardSDK();
+await sdk.init({
+  token:       'your_jwt_token',          // from GET /api/v1/client/me
+  customerId:  'cus_hkdmcdjshhknkk4lc2t',
+  myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
+  containerId: 'mygigsters-card',
+  env:         'demo',
+  onSuccess: (res) => console.log('Card saved! Consent ID:', res.paymentConsentId),
+  onError:   (err) => console.error('Error:', err.message),
+  onClose:   ()    => console.log('Modal closed'),
+});
+```
+The card modal opens automatically after `init()` resolves.
+---
+## Module Formats
+| Format | Path | Use Case |
+|--------|------|----------|
+| **ESM** | `dist/index.esm.js` | Modern bundlers (Vite, Webpack 5, Rollup) |
+| **CommonJS** | `dist/index.cjs.js` | Node.js / `require()` environments |
+| **CDN (UMD)** | `cdn/card-sdk-entry.js` | Browser `<script>` tag / self-hosted CDN |
+| **TypeScript** | `dist/index.d.ts` | Type definitions |
+---
+## Usage Examples
+### ES Modules (Recommended)
+```javascript
+import { MygigstersCardSDK } from '@mygigsters/card-sdk';
+const sdk = new MygigstersCardSDK();
+await sdk.init({
+  token:       'your_jwt_token',          // from GET /api/v1/client/me
+  customerId:  'cus_hkdmcdjshhknkk4lc2t',
+  myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
+  containerId: 'mygigsters-card',
+  env:         'demo',           // 'demo' | 'prod'
+  mode:        'dark',           // optional: 'dark' (default) | 'light'
+  onSuccess: (res) => {
+    console.log('✅ Card saved:', res.paymentConsentId);
+    // Pass res.paymentConsentId to the MyGigsters API to charge the customer
+  },
+  onError: (err) => {
+    console.error('❌ Error:', err.message);
+  },
+  onClose: () => {
+    console.log('Modal closed by user');
+  },
+});
+```
+---
+### CommonJS
+```javascript
+const { MygigstersCardSDK } = require('@mygigsters/card-sdk');
+const sdk = new MygigstersCardSDK();
+sdk.init({
+  token:       'your_jwt_token',          // from GET /api/v1/client/me
+  customerId:  'cus_hkdmcdjshhknkk4lc2t',
+  myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
+  containerId: 'mygigsters-card',
+  onSuccess: (res) => console.log('Card saved:', res.paymentConsentId),
+  onError:   (err) => console.error('Error:', err.message),
+  onClose:   ()    => console.log('Closed'),
+});
+```
+---
+### CDN / Browser Script Tag
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>My App</title>
+</head>
+<body>
+  <!-- 1. Mount target -->
+  <div id="mygigsters-card"></div>
+  <!-- 2. Load the SDK -->
+  <script src="https://qa-payments.mygigsters.com.au/card-sdk-entry.js"></script>
+  <script>
+    async function openCardForm(token) {
+      await MygigstersCard.init({
+        token:       token,                     // from GET /api/v1/client/me
+        customerId:  'cus_hkdmcdjshhknkk4lc2t',
+        myGigsterId: '4407c3ba-10c9-4822-9f51-c2c96692f8d7',
+        containerId: 'mygigsters-card',
+        env:         'demo',
+        mode:        'dark',
+        onSuccess: (res) => console.log('✅ Card saved:', res.paymentConsentId),
+        onError:   (err) => console.error('❌ Error:', err.message),
+        onClose:   ()    => console.log('Closed'),
+      });
+    }
+  </script>
+</body>
+</html>
+```
+> **CDN global:** The CDN build exposes `window.MygigstersCard` (not `MygigstersCardSDK`).
+---
+### React (useEffect)
+```jsx
+import { useEffect } from 'react';
+import { MygigstersCardSDK } from '@mygigsters/card-sdk';
+function SaveCardForm({ token, customerId, myGigsterId }) {
+  useEffect(() => {
+    if (!token) return;
+    const sdk = new MygigstersCardSDK();
+    sdk.init({
+      token,
+      customerId,
+      myGigsterId,
+      containerId: 'mygigsters-card',
+      env:         'demo',
+      mode:        'dark',
+      onSuccess: (res) => console.log('Card saved!', res.paymentConsentId),
+      onError:   (err) => console.error(err),
+      onClose:   ()    => console.log('Closed'),
+    });
+    // Cleanup on unmount
+    return () => sdk.destroy();
+  }, [token, customerId, myGigsterId]);
+  return <div id="mygigsters-card" />;
+}
+```
+---
+## Configuration Reference
+Pass these options to `init()`:
+| Parameter | Type | Required | Default | Description |
+|-----------|------|:--------:|---------|-------------|
+| `token` | `string` | ✅ | — | Bearer JWT token obtained from `GET /api/v1/client/me` |
+| `customerId` | `string` | ✅ | — | MyGigsters customer ID for whom the card is saved (from `POST /api/v1/customer`) |
+| `myGigsterId` | `string` | ✅ | — | Unique client account identifier (from `GET /api/v1/client/me`) |
+| `containerId` | `string` | ✅ | — | `id` of the DOM element to mount the SDK into |
+| `env` | `'dev' \| 'demo' \| 'prod'` | ❌ | `'demo'` | Target environment |
+| `baseUrl` | `string` | ❌ | — | Custom base URL override (for self-hosted deployments) |
+| `mode` | `'light' \| 'dark'` | ❌ | `'dark'` | UI color theme |
+| `onSuccess` | `(res) => void` | ❌ | no-op | Fired after the card is saved successfully |
+| `onError` | `(error) => void` | ❌ | `console.error` | Fired on any SDK or network error |
+| `onClose` | `() => void` | ❌ | no-op | Fired when the user closes the modal |
+| `webhookUrl` | `string` | ❌ | — | URL to POST the success payload to automatically |
+| `onWebhook` | `(payload) => void` | ❌ | no-op | JS callback for receiving the webhook payload in real-time |
+---
+## API Reference
+### `init(config)`
+Validates configuration, builds the Shadow DOM modal, initializes the Airwallex card element, and automatically calls `show()`.
+```javascript
+import { MygigstersCardSDK } from '@mygigsters/card-sdk';
+const sdk = new MygigstersCardSDK();
+await sdk.init(config);
+// or, via CDN:
+await MygigstersCard.init(config);
+```
+- **Returns:** `Promise<void>`
+- **Throws:** if `token`, `customerId`, `myGigsterId`, or `containerId` are missing; or if the container element is not found.
+---
+### `show()`
+Shows the card modal. Called automatically by `init()`, but can be called again after `hide()`.
+```javascript
+sdk.show();
+```
+---
+### `hide()`
+Hides the modal without destroying the SDK instance. The Airwallex card element state is preserved.
+```javascript
+sdk.hide();
+```
+---
+### `setTheme(mode)`
+Switch the UI theme at runtime — no need to re-initialize.
+```javascript
+sdk.setTheme('dark');  // or 'light'
+```
+---
+### `destroy()`
+Removes the modal from the DOM and resets all internal state. Call this when navigating away or unmounting the host component.
+```javascript
+sdk.destroy();
+```
+---
+## Success Response
+The `onSuccess` callback receives a `CardSuccessResponse` object:
+```javascript
+onSuccess: (res) => {
+  // res.paymentConsentId  — Airwallex payment consent ID
+  // res.customerId        — Customer ID associated with this consent
+  // res.myGigsterId       — MyGigster ID associated with this consent
+  // res.timestamp         — ISO-8601 timestamp of the save event
+  // res.event             — 'card.saved'
+  console.log('Payment Consent ID:', res.paymentConsentId);
+}
+```
+---
+## Error Handling
+Wrap `init()` in a `try/catch` to handle initialization errors:
+```javascript
+try {
+  const sdk = new MygigstersCardSDK();
+  await sdk.init({
+    token:       'your_jwt_token',
+    customerId:  'cus_...',
+    myGigsterId: '4407c3ba-...',
+    containerId: 'mygigsters-card',
+    env:         'demo',
+  });
+} catch (err) {
+  // Common errors:
+  // "token is required. Call GET /api/v1/client/me first..."
+  // "customerId is required"
+  // "myGigsterId is required"
+  // "Container element with ID '...' not found"
+  console.error('SDK failed to initialize:', err.message);
+}
+```
+---
+## Security
+- **Pre-fetched Token Auth** — Clients authenticate with `GET /api/v1/client/me` using Basic Auth (`apiKey:apiSecret`) on their server or frontend to retrieve a JWT token. API credentials are never passed to or exposed inside the SDK.
+- **Credentials are never stored** in `localStorage` or `sessionStorage`.
+- **PCI-compliant card handling** — Raw card data is handled exclusively by Airwallex's PCI-certified payment element embedded inside an Airwallex-controlled iframe.
+- **Shadow DOM** (`mode: 'closed'`) prevents host-page scripts from reaching into the SDK's DOM.
+---
+## TypeScript
+Type definitions are included at `dist/index.d.ts`.
+```tsx
+import { useEffect } from 'react';
+import { MygigstersCardSDK } from '@mygigsters/card-sdk';
+import type { MygigstersCardConfig, CardSuccessResponse } from '@mygigsters/card-sdk';
+function SaveCardForm({ token, customerId, myGigsterId }: { token: string; customerId: string; myGigsterId: string }) {
+  useEffect(() => {
+    if (!token) return;
+    const config: MygigstersCardConfig = {
+      token,
+      customerId,
+      myGigsterId,
+      containerId: 'mygigsters-card',
+      env: 'demo',
+      mode: 'dark',
+      onSuccess: (res: CardSuccessResponse) => {
+        console.log('Card saved! Consent ID:', res.paymentConsentId);
+      },
+      onError: (err) => {
+        console.error('Card SDK error:', err);
+      },
+    };
+    const sdk = new MygigstersCardSDK();
+    sdk.init(config);
+    return () => sdk.destroy();
+  }, [token, customerId, myGigsterId]);
+  return <div id="mygigsters-card" />;
+}
+export default SaveCardForm;
+```
+---
+## Changelog
+### 1.0.3
+- Added automatic identity verification step calling `profileDetails` API during `init()`.
+- Validates that `myGigsterId` returned by `profileDetails` matches the `myGigsterId` passed into `init()`. If it does not match, SDK initialization is blocked and an error is raised.
+### 1.0.2
+- **Breaking Change:** Updated authentication model to **Pre-fetched Token (Flow B)**.
+- `init()` now accepts `token` (retrieved via `GET /api/v1/client/me`) instead of `apiKey` / `apiSecret`.
+- Updated TypeScript definitions and documentation.
+### 1.0.0
+- Initial public release.
+---
+## License
+MIT © [MyGigsters](https://www.mygigsters.com.au)