@mygigsters/card-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * @mygigsters/card-sdk TypeScript Declarations
+ * MyGigsters Card SDK - Secure single-step card saving payment elements integration.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+export type CardEnvironment = 'dev' | 'demo' | 'prod';
+export type CardThemeMode = 'light' | 'dark';
+
+export interface CardSuccessResponse {
+  /** The unique Airwallex payment consent identifier */
+  paymentConsentId: string;
+  /** Customer ID associated with this payment consent */
+  customerId: string;
+  /** MyGigster ID associated with this payment consent */
+  myGigsterId?: string;
+  /** Account ID associated with this payment consent */
+  accountId?: string;
+  /** ISO-8601 timestamp when the card was successfully saved */
+  timestamp: string;
+  /** Event identifier ('card.saved') */
+  event: 'card.saved' | string;
+  /** Additional backend response properties */
+  [key: string]: any;
+}
+
+export interface MygigstersCardConfig {
+  /**
+   * Your MyGigsters API Key.
+   * Required for authentication.
+   * Example: "3113ee27-ba11-48f7-81e2-f5a2f0e54340"
+   */
+  apiKey: string;
+
+  /**
+   * Your MyGigsters API Secret.
+   * Required for authentication.
+   * Example: "HUdxQCCrOFuF9fSkQRbd"
+   */
+  apiSecret: string;
+
+  /**
+   * ID of the DOM element container where the SDK is mounted or validated.
+   * Example: "card-mount"
+   */
+  containerId: string;
+
+  /**
+   * Customer ID for whom the card will be saved.
+   * Required.
+   * Example: "cus_hkdmcdjshhknkk4lc2t"
+   */
+  customerId: string;
+
+  /**
+   * MyGigster ID for whom the payment consent is created (Frontend identifier).
+   * Either `myGigsterId` or `accountId` is required.
+   * Example: "4407c3ba-10c9-4822-9f51-c2c96692f8d7"
+   */
+  myGigsterId?: string;
+
+  /**
+   * Account ID for whom the payment consent is created (Legacy alias for myGigsterId).
+   * Example: "4407c3ba-10c9-4822-9f51-c2c96692f8d7"
+   */
+  accountId?: string;
+
+  /**
+   * Target environment.
+   * - 'demo': Demo server (QA: https://qa-payments.mygigsters.com.au) [Default]
+   * - 'dev': Development server (http://3.108.128.110:5000)
+   * - 'prod': Production server (https://prod-payments.mygigsters.com.au)
+   * @default 'demo'
+   */
+  env?: CardEnvironment;
+
+  /**
+   * Custom base URL to override the environment default URL.
+   */
+  baseUrl?: string;
+
+  /**
+   * Theme mode for the card modal popup.
+   * - 'dark': Modern sleek dark slate theme [Default]
+   * - 'light': Clean high-contrast light theme
+   * @default 'dark'
+   */
+  mode?: CardThemeMode;
+
+  /**
+   * Callback fired upon successful card entry and verification.
+   * @param res Enriched response payload containing paymentConsentId, customerId, myGigsterId, accountId, timestamp.
+   */
+  onSuccess?: (res: CardSuccessResponse) => void;
+
+  /**
+   * Callback fired if an error occurs during initialization, authentication, or card submission.
+   * @param err The error instance or error details.
+   */
+  onError?: (err: Error | any) => void;
+
+  /**
+   * Callback fired when the user closes the modal (via Close button 'X', backdrop click, or Escape key).
+   */
+  onClose?: () => void;
+
+  /**
+   * Optional webhook URL. The SDK will automatically POST the success payload to this URL.
+   */
+  webhookUrl?: string;
+
+  /**
+   * Optional JS callback for receiving the webhook payload in real-time.
+   */
+  onWebhook?: (payload: CardSuccessResponse) => void;
+}
+
+export class MygigstersCardSDK {
+  constructor();
+
+  /** Current SDK configuration */
+  config: MygigstersCardConfig | null;
+
+  /** Whether the SDK has been successfully initialized */
+  isInitialized: boolean;
+
+  /**
+   * Initialize the Card SDK and display the single-step Card Details modal.
+   *
+   * @example
+   * ```ts
+   * const sdk = new MygigstersCardSDK();
+   * await sdk.init({
+   *   containerId: "card-mount",
+   *   apiKey: "3113ee27-ba11-48f7-81e2-f5a2f0e54340",
+   *   apiSecret: "HUdxQCCrOFuF9fSkQRbd",
+   *   customerId: "cus_hkdmcdjshhknkk4lc2t",
+   *   myGigsterId: "4407c3ba-10c9-4822-9f51-c2c96692f8d7",
+   *   env: "demo",
+   *   mode: "light",
+   *   onSuccess: (res) => console.log("Card saved!", res),
+   *   onError: (err) => console.error("Error:", err),
+   *   onClose: () => console.log("Modal closed")
+   * });
+   * ```
+   */
+  init(config: MygigstersCardConfig): Promise<void>;
+
+  /**
+   * Display the card modal.
+   */
+  show(): void;
+
+  /**
+   * Hide the card modal without destroying instance.
+   */
+  hide(): void;
+
+  /**
+   * Switch the UI theme dynamically.
+   */
+  setTheme(mode: CardThemeMode): void;
+
+  /**
+   * Fully teardown and remove the SDK from DOM.
+   */
+  destroy(): void;
+}
+
+export interface MygigstersCardGlobal {
+  /**
+   * Initialize the singleton Card SDK instance and display the single-step Card Details modal.
+   *
+   * @example
+   * ```js
+   * MygigstersCard.init({
+   *   containerId: "card-mount",
+   *   apiKey: "3113ee27-ba11-48f7-81e2-f5a2f0e54340",
+   *   apiSecret: "HUdxQCCrOFuF9fSkQRbd",
+   *   customerId: "cus_hkdmcdjshhknkk4lc2t",
+   *   myGigsterId: "4407c3ba-10c9-4822-9f51-c2c96692f8d7",
+   *   env: "demo",
+   *   mode: "dark",
+   *   onSuccess: (res) => console.log("Card saved!", res),
+   *   onError: (err) => console.error("Error:", err),
+   *   onClose: () => console.log("Modal closed")
+   * });
+   * ```
+   */
+  init(config: MygigstersCardConfig): Promise<MygigstersCardSDK>;
+
+  /**
+   * Display the card modal.
+   */
+  show(): void;
+
+  /**
+   * Hide the card modal.
+   */
+  hide(): void;
+
+  /**
+   * Destroy the current instance and clean up DOM.
+   */
+  destroy(): void;
+
+  /**
+   * Update the modal theme.
+   */
+  setTheme(mode: CardThemeMode): void;
+
+  /**
+   * Get current SDK instance.
+   */
+  getInstance(): MygigstersCardSDK | null;
+}
+
+/** Global singleton available in browser / CDN builds and package import */
+export const MygigstersCard: MygigstersCardGlobal;
+
+export default MygigstersCardSDK;
+
+declare global {
+  interface Window {
+    MygigstersCard: MygigstersCardGlobal;
+    MygigstersCardSDK: typeof MygigstersCardSDK;
+  }
+}