@connect-xyz/auth-js 1.0.0

package/README.md

@@ -0,0 +1,245 @@
+# @connect-xyz/auth-js
+
+A JavaScript SDK that enables frontend applications to seamlessly integrate with the Connect Auth product.
+
+Connect Auth provides a secure, customizable authentication flow for crypto deposits. Learn more in the [Connect Auth documentation](https://docs.zerohash.com/docs/auth).
+
+## Installation
+
+### Via NPM (recommended)
+
+```bash
+npm install @connect-xyz/auth-js
+```
+
+```javascript
+import { Auth } from '@connect-xyz/auth-js';
+```
+
+### Via CDN
+
+You can import the script in your index file and use the Auth class provided by it.
+
+```html
+<script
+  type="module"
+  src="https://sdk.connect.xyz/auth-js/index.js"
+></script>
+```
+
+Or you can directly import in your javascript code.
+
+```javascript
+import { Auth } from 'https://sdk.connect.xyz/auth-js/index.js';
+```
+
+## Getting Started
+
+Follow these simple steps to integrate Connect Auth into your frontend application:
+
+### 1. Import the Auth module
+
+```tsx
+import { Auth } from '@connect-xyz/auth-js';
+```
+
+### 1.1 Or import via CDN
+
+```javascript
+import { Auth } from 'https://sdk.connect.xyz/auth-js/index.js';
+```
+
+### 2. Initialize the Auth module into Your App
+
+```javascript
+// Create an Auth instance with configuration
+const auth = new Auth({
+  jwt: 'your-jwt-token',
+  env: 'production', // or 'sandbox'
+  onError: ({ error, reason }) => {
+    console.error('Auth error:', error, 'Reason:', reason);
+  },
+  onClose: () => {
+    console.log('Auth widget closed');
+  },
+  onDeposit: ({ data }) => {
+    console.log('Deposit initiated:', data);
+  },
+  onEvent: ({ type, data }) => {
+    console.log('Event received:', type, data);
+  },
+});
+
+// Render the widget to a container element
+const container = document.getElementById('auth-container');
+await auth.render(container);
+
+// Update configuration dynamically
+auth.updateConfig({
+  jwt: 'new-jwt-token',
+  onError: newErrorHandler,
+});
+
+// Check if rendered
+if (auth.isRendered()) {
+  console.log('Widget is active');
+}
+
+// Clean up when done
+auth.destroy();
+```
+
+### 2.1 Using Typescript (optional)
+
+```typescript
+import { Auth, AuthConfig, ErrorData, DepositData } from '@connect/auth-js';
+
+const config: AuthConfig = {
+  jwt: 'your-jwt-token',
+  env: 'sandbox',
+  onError: ({ error, reason }: ErrorData) => {
+    // Handle error with type safety
+  },
+  onDeposit: ({ data }: DepositData) => {
+    // Handle deposit with type safety
+  },
+};
+
+const auth = new Auth(config);
+```
+
+## API Reference
+
+### Auth widget Props
+
+| Prop        | Type                              | Required | Default        | Description                                    |
+| ----------- | --------------------------------- | -------- | -------------- | ---------------------------------------------- |
+| `jwt`       | `string`                          | Yes      | -              | JWT token for authentication with Connect Auth |
+| `env`       | `"production" \| "sandbox"`       | No       | `"production"` | Target environment                             |
+| `onError`   | `({ errorCode, reason }) => void` | No       | -              | Callback for error events                      |
+| `onClose`   | `() => void`                      | No       | -              | Callback when the widget is closed             |
+| `onDeposit` | `({ data }) => void`              | No       | -              | Callback for deposit received                  |
+| `onEvent`   | `({ type, data }) => void`        | No       | -              | Callback for general events                    |
+
+### Constructor
+
+```javascript
+new Auth(config: AuthConfig)
+```
+
+Creates a new Auth instance with the provided configuration.
+
+#### Parameters
+
+- `config` (AuthConfig): Configuration object
+  - `jwt` (string, required): JWT token for authentication
+  - `env` (string, optional): Environment - 'production' (default) or 'sandbox'
+  - `onError` (function, optional): Error callback
+  - `onClose` (function, optional): Close callback
+  - `onDeposit` (function, optional): Deposit callback
+  - `onEvent` (function, optional): General event callback
+
+### Methods
+
+#### `render(container: HTMLElement): Promise<void>`
+
+Renders the Auth widget to the specified container element.
+
+```javascript
+await auth.render(document.getElementById('auth-container'));
+```
+
+#### `updateConfig(config: Partial<AuthConfig>): void`
+
+Updates the configuration of an already rendered widget.
+
+```javascript
+auth.updateConfig({
+  jwt: 'new-token',
+  onError: newErrorHandler,
+});
+```
+
+#### `destroy(): void`
+
+Removes the widget from the DOM and cleans up resources.
+
+```javascript
+auth.destroy();
+```
+
+#### `isRendered(): boolean`
+
+Returns whether the widget is currently rendered.
+
+```javascript
+if (auth.isRendered()) {
+  // Widget is active
+}
+```
+
+#### `getConfig(): AuthConfig`
+
+Returns a copy of the current configuration.
+
+```javascript
+const config = auth.getConfig();
+console.log('Current JWT:', config.jwt);
+```
+
+## Callback Functions
+
+For detailed information about callback events and their payloads, see the [Auth SDK Callbacks documentation](https://docs.zerohash.com/docs/auth-standalone#4-organization-frontend-listens-to-auth-sdk-callbacks).
+
+### onError
+
+Called when an error occurs in the Auth widget.
+
+```javascript
+onError: ({ errorCode, reason }) => {
+  // errorCode: Error code
+  // reason: Human-readable error description
+};
+```
+
+### onClose
+
+Called when the Auth widget is closed by the user.
+
+```javascript
+onClose: () => {
+  // Handle close event
+};
+```
+
+### onDeposit
+
+Called when a deposit is received.
+
+```javascript
+onDeposit: ({ data }) => {
+  // data: Object containing deposit details
+};
+```
+
+### onEvent
+
+Called for general events from the Auth widget.
+
+```javascript
+onEvent: ({ type, data }) => {
+  // type: Event type string
+  // data: Event-specific data object
+};
+```
+
+## Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- All modern browsers with Web Components support
+
+## More Information & Support
+
+For comprehensive documentation or support about Connect Auth, visit our [ Documentation Page](https://docs.zerohash.com/).

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Connect Auth JavaScript SDK
+ *
+ * A programmatic JavaScript SDK for integrating the Connect Auth widget
+ * into web applications without requiring HTML custom elements.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Generic app event structure
+ * @template TType - Event type string
+ * @template TData - Event data payload
+ */
+declare type AppEvent<TType extends string = string, TData = Record<string, unknown>> = {
+    /** The type of event that occurred */
+    type: TType;
+    /** Data associated with the event */
+    data: TData;
+};
+
+/**
+ * Auth SDK class for programmatic control of the Connect Auth widget
+ *
+ * @example
+ * ```javascript
+ * const auth = new Auth({
+ *   jwt: 'your-jwt-token',
+ *   env: 'production',
+ *   onError: ({ error, reason }) => console.error(error, reason),
+ *   onClose: () => console.log('Auth closed'),
+ *   onDeposit: ({ data }) => console.log('Deposit', data),
+ *   onEvent: ({ type, data }) => console.log('Event', type, data)
+ * });
+ *
+ * // Render to a container
+ * await auth.render(document.getElementById('auth-container'));
+ *
+ * // Update configuration
+ * auth.updateConfig({ jwt: 'new-token' });
+ *
+ * // Clean up
+ * auth.destroy();
+ * ```
+ */
+declare class Auth {
+    private config;
+    private state;
+    /**
+     * Create a new Auth instance
+     * @param config - Configuration options for the Auth SDK
+     */
+    constructor(config: AuthConfig);
+    /**
+     * Get the current environment
+     */
+    private get environment();
+    /**
+     * Load the web component script if not already loaded
+     */
+    private ensureScriptLoaded;
+    /**
+     * Create the web component element
+     */
+    private createWebComponent;
+    /**
+     * Render the Auth widget to a container element
+     * @param container - The container element to render the widget into
+     * @returns Promise that resolves when the widget is rendered
+     */
+    render(container: HTMLElement): Promise<void>;
+    /**
+     * Update the configuration of the Auth widget
+     * @param config - Partial configuration to update
+     */
+    updateConfig(config: Partial<AuthConfig>): void;
+    /**
+     * Destroy the Auth widget and clean up resources
+     */
+    destroy(): void;
+    /**
+     * Check if the Auth widget is currently rendered
+     * @returns True if the widget is rendered, false otherwise
+     */
+    isRendered(): boolean;
+    /**
+     * Get the current configuration
+     * @returns The current configuration object
+     */
+    getConfig(): Readonly<AuthConfig>;
+}
+export { Auth }
+export default Auth;
+
+/**
+ * Callback function types for Connect Auth components
+ * Extends common callbacks with auth-specific callbacks
+ */
+declare type AuthCallbacks = CommonCallbacks<AuthEvent> & {
+    /** Called when a deposit action occurs */
+    onDeposit?: (deposit: DepositCompletedPayload) => void;
+};
+
+/**
+ * Configuration options for the Auth SDK
+ */
+export declare interface AuthConfig extends AuthCallbacks {
+    /**
+     * JWT token used for authentication with the Connect Auth service
+     */
+    jwt: string;
+    /**
+     * Target environment for the Connect Auth service
+     * @default 'production'
+     */
+    env?: Environment;
+}
+
+/**
+ * Auth event structure for auth-specific events
+ */
+declare type AuthEvent = AppEvent<AuthEventType, DepositSubmittedEventData>;
+
+/**
+ * Auth event type literals
+ */
+declare type AuthEventType = 'deposit.submitted';
+
+/**
+ * Internal state of the Auth SDK
+ */
+export declare interface AuthState {
+    /** Whether the SDK is initialized */
+    initialized: boolean;
+    /** Whether the web component script is loaded */
+    scriptLoaded: boolean;
+    /** The container element where the auth widget is rendered */
+    container: HTMLElement | null;
+    /** The web component element */
+    element: HTMLElement | null;
+}
+
+/**
+ * Common callback function types shared across all Connect apps
+ * @template TEvent - The event type for onEvent callback
+ */
+declare type CommonCallbacks<TEvent = AppEvent> = {
+    /** Called when an error occurs */
+    onError?: (error: ErrorPayload) => void;
+    /** Called when the component is closed */
+    onClose?: () => void;
+    /** Called when a general event occurs */
+    onEvent?: (event: TEvent) => void;
+};
+
+/**
+ * ConnectAuth element interface
+ */
+export declare interface ConnectAuthElement extends HTMLElement {
+    jwt: string;
+    env?: Environment;
+    onError?: (errorData: ErrorPayload) => void;
+    onClose?: () => void;
+    onDeposit?: (depositData: DepositCompletedPayload) => void;
+    onEvent?: (eventData: AuthEvent) => void;
+}
+
+/**
+ * Deposit completed payload structure for deposit callbacks
+ */
+declare type DepositCompletedPayload = {
+    /** Data associated with the deposit */
+    data: {
+        /** Unique identifier for the deposit */
+        depositId: string;
+        /** Current status of the deposit */
+        status: DepositStatus;
+        /** Asset identifier (e.g., 'btc', 'eth') */
+        assetId: string;
+        /** Network identifier (e.g., 'bitcoin', 'ethereum') */
+        networkId: string;
+        /** Amount being deposited */
+        amount: string;
+    };
+};
+
+/**
+ * Deposit status object structure
+ */
+declare type DepositStatus = {
+    /** Status value */
+    value: string;
+    /** Human-readable details about the status */
+    details: string;
+    /** Timestamp when the status occurred (ISO 8601 format) */
+    occurredAt: string;
+};
+
+/**
+ * Deposit submitted event data
+ */
+declare type DepositSubmittedEventData = {
+    /** Unique identifier for the deposit */
+    depositId: string;
+};
+
+/**
+ * Environment configuration for the Auth SDK
+ */
+export declare type Environment = 'sandbox' | 'production';
+
+/**
+ * Generic error codes for all Connect applications
+ */
+declare enum ErrorCode {
+    /** Network connectivity error */
+    NETWORK_ERROR = 'network_error',
+    /** Authentication or session expired error */
+    AUTH_ERROR = 'auth_error',
+    /** Resource not found error */
+    NOT_FOUND_ERROR = 'not_found_error',
+    /** Validation error from user input */
+    VALIDATION_ERROR = 'validation_error',
+    /** Server error (5xx) */
+    SERVER_ERROR = 'server_error',
+    /** Client error (4xx) */
+    CLIENT_ERROR = 'client_error',
+    /** Unknown or unexpected error */
+    UNKNOWN_ERROR = 'unknown_error',
+}
+
+/**
+ * Generic error payload structure for error callbacks
+ */
+declare type ErrorPayload = {
+    /** Error code indicating the type of error */
+    errorCode: ErrorCode;
+    /** Human-readable reason for the error */
+    reason: string;
+};
+
+export { }

package/dist/index.js

@@ -0,0 +1,158 @@
+var h = Object.defineProperty;
+var E = (n, t, e) => t in n ? h(n, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : n[t] = e;
+var c = (n, t, e) => E(n, typeof t != "symbol" ? t + "" : t, e);
+const u = {
+  sandbox: "https://sdk.sandbox.connect.xyz/auth-web/index.js",
+  production: "https://sdk.connect.xyz/auth-web/index.js"
+}, m = "connect-auth-script", p = "connect-auth", d = "production", r = {
+  ALREADY_RENDERED: "Auth widget is already rendered. Call destroy() before rendering again.",
+  NOT_RENDERED: "Auth widget is not rendered. Call render() first.",
+  INVALID_CONTAINER: "Invalid container element provided.",
+  SCRIPT_LOAD_FAILED: "Failed to load the Connect Auth script.",
+  WEB_COMPONENT_NOT_DEFINED: "Web component is not defined. Script may not be loaded.",
+  INVALID_JWT: "JWT token is required and must be a string."
+}, a = /* @__PURE__ */ new Map();
+function f(n) {
+  return u[n];
+}
+function l(n) {
+  return `${m}-${n}`;
+}
+function w(n) {
+  const t = l(n);
+  return !!document.getElementById(t);
+}
+async function D(n) {
+  const t = l(n);
+  if (w(n))
+    return Promise.resolve();
+  if (a.has(t))
+    return a.get(t);
+  const e = new Promise((i, s) => {
+    const o = document.createElement("script");
+    o.id = t, o.src = f(n), o.type = "module", o.async = !0, o.onload = () => {
+      setTimeout(() => {
+        customElements.get("connect-auth") ? i() : s(new Error(r.WEB_COMPONENT_NOT_DEFINED));
+      }, 0);
+    }, o.onerror = () => {
+      a.delete(t), s(new Error(`${r.SCRIPT_LOAD_FAILED} (${n})`));
+    }, document.head.appendChild(o);
+  });
+  a.set(t, e);
+  try {
+    await e;
+  } catch (i) {
+    throw a.delete(t), i;
+  }
+  return e;
+}
+async function N(n = 5e3) {
+  const t = "connect-auth";
+  return customElements.get(t) ? Promise.resolve() : new Promise((e, i) => {
+    const s = setTimeout(() => {
+      i(new Error(`Timeout waiting for ${t} to be defined`));
+    }, n);
+    customElements.whenDefined(t).then(() => {
+      clearTimeout(s), e();
+    }).catch((o) => {
+      clearTimeout(s), i(o);
+    });
+  });
+}
+class I {
+  /**
+   * Create a new Auth instance
+   * @param config - Configuration options for the Auth SDK
+   */
+  constructor(t) {
+    c(this, "config");
+    c(this, "state");
+    if (!t.jwt || typeof t.jwt != "string")
+      throw new Error(r.INVALID_JWT);
+    this.config = {
+      ...t,
+      env: t.env || d
+    }, this.state = {
+      initialized: !1,
+      scriptLoaded: !1,
+      container: null,
+      element: null
+    };
+  }
+  /**
+   * Get the current environment
+   */
+  get environment() {
+    return this.config.env || d;
+  }
+  /**
+   * Load the web component script if not already loaded
+   */
+  async ensureScriptLoaded() {
+    if (!this.state.scriptLoaded)
+      try {
+        await D(this.environment), await N(), this.state.scriptLoaded = !0;
+      } catch (t) {
+        throw console.error("Failed to load Connect Auth script:", t), t;
+      }
+  }
+  /**
+   * Create the web component element
+   */
+  createWebComponent() {
+    const t = document.createElement(p);
+    return t.jwt = this.config.jwt, this.config.env && (t.env = this.config.env), this.config.onError && (t.onError = this.config.onError), this.config.onClose && (t.onClose = this.config.onClose), this.config.onDeposit && (t.onDeposit = this.config.onDeposit), this.config.onEvent && (t.onEvent = this.config.onEvent), t;
+  }
+  /**
+   * Render the Auth widget to a container element
+   * @param container - The container element to render the widget into
+   * @returns Promise that resolves when the widget is rendered
+   */
+  async render(t) {
+    if (!t || !(t instanceof HTMLElement))
+      throw new Error(r.INVALID_CONTAINER);
+    if (this.state.initialized)
+      throw new Error(r.ALREADY_RENDERED);
+    try {
+      await this.ensureScriptLoaded();
+      const e = this.createWebComponent();
+      t.innerHTML = "", t.appendChild(e), this.state.container = t, this.state.element = e, this.state.initialized = !0;
+    } catch (e) {
+      throw console.error("Failed to render Auth widget:", e), e;
+    }
+  }
+  /**
+   * Update the configuration of the Auth widget
+   * @param config - Partial configuration to update
+   */
+  updateConfig(t) {
+    if (!this.state.initialized || !this.state.element)
+      throw new Error(r.NOT_RENDERED);
+    const e = this.state.element;
+    t.jwt && (this.config.jwt = t.jwt, e.jwt = t.jwt), t.onError !== void 0 && (this.config.onError = t.onError, e.onError = t.onError), t.onClose !== void 0 && (this.config.onClose = t.onClose, e.onClose = t.onClose), t.onDeposit !== void 0 && (this.config.onDeposit = t.onDeposit, e.onDeposit = t.onDeposit), t.onEvent !== void 0 && (this.config.onEvent = t.onEvent, e.onEvent = t.onEvent);
+  }
+  /**
+   * Destroy the Auth widget and clean up resources
+   */
+  destroy() {
+    this.state.initialized && (this.state.element && this.state.element.parentNode && this.state.element.parentNode.removeChild(this.state.element), this.state.container && (this.state.container.innerHTML = ""), this.state.container = null, this.state.element = null, this.state.initialized = !1);
+  }
+  /**
+   * Check if the Auth widget is currently rendered
+   * @returns True if the widget is rendered, false otherwise
+   */
+  isRendered() {
+    return this.state.initialized;
+  }
+  /**
+   * Get the current configuration
+   * @returns The current configuration object
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+}
+export {
+  I as Auth,
+  I as default
+};

package/dist/index.umd.cjs

@@ -0,0 +1 @@
+(function(n,o){typeof exports=="object"&&typeof module<"u"?o(exports):typeof define=="function"&&define.amd?define(["exports"],o):(n=typeof globalThis<"u"?globalThis:n||self,o(n.Auth={}))})(this,function(n){"use strict";var T=Object.defineProperty;var C=(n,o,s)=>o in n?T(n,o,{enumerable:!0,configurable:!0,writable:!0,value:s}):n[o]=s;var h=(n,o,s)=>C(n,typeof o!="symbol"?o+"":o,s);const o={sandbox:"https://sdk.sandbox.connect.xyz/auth-web/index.js",production:"https://sdk.connect.xyz/auth-web/index.js"},s="connect-auth-script",m="connect-auth",u="production",a={ALREADY_RENDERED:"Auth widget is already rendered. Call destroy() before rendering again.",NOT_RENDERED:"Auth widget is not rendered. Call render() first.",INVALID_CONTAINER:"Invalid container element provided.",SCRIPT_LOAD_FAILED:"Failed to load the Connect Auth script.",WEB_COMPONENT_NOT_DEFINED:"Web component is not defined. Script may not be loaded.",INVALID_JWT:"JWT token is required and must be a string."},c=new Map;function p(i){return o[i]}function E(i){return`${s}-${i}`}function w(i){const t=E(i);return!!document.getElementById(t)}async function D(i){const t=E(i);if(w(i))return Promise.resolve();if(c.has(t))return c.get(t);const e=new Promise((d,l)=>{const r=document.createElement("script");r.id=t,r.src=p(i),r.type="module",r.async=!0,r.onload=()=>{setTimeout(()=>{customElements.get("connect-auth")?d():l(new Error(a.WEB_COMPONENT_NOT_DEFINED))},0)},r.onerror=()=>{c.delete(t),l(new Error(`${a.SCRIPT_LOAD_FAILED} (${i})`))},document.head.appendChild(r)});c.set(t,e);try{await e}catch(d){throw c.delete(t),d}return e}async function N(i=5e3){const t="connect-auth";return customElements.get(t)?Promise.resolve():new Promise((e,d)=>{const l=setTimeout(()=>{d(new Error(`Timeout waiting for ${t} to be defined`))},i);customElements.whenDefined(t).then(()=>{clearTimeout(l),e()}).catch(r=>{clearTimeout(l),d(r)})})}class f{constructor(t){h(this,"config");h(this,"state");if(!t.jwt||typeof t.jwt!="string")throw new Error(a.INVALID_JWT);this.config={...t,env:t.env||u},this.state={initialized:!1,scriptLoaded:!1,container:null,element:null}}get environment(){return this.config.env||u}async ensureScriptLoaded(){if(!this.state.scriptLoaded)try{await D(this.environment),await N(),this.state.scriptLoaded=!0}catch(t){throw console.error("Failed to load Connect Auth script:",t),t}}createWebComponent(){const t=document.createElement(m);return t.jwt=this.config.jwt,this.config.env&&(t.env=this.config.env),this.config.onError&&(t.onError=this.config.onError),this.config.onClose&&(t.onClose=this.config.onClose),this.config.onDeposit&&(t.onDeposit=this.config.onDeposit),this.config.onEvent&&(t.onEvent=this.config.onEvent),t}async render(t){if(!t||!(t instanceof HTMLElement))throw new Error(a.INVALID_CONTAINER);if(this.state.initialized)throw new Error(a.ALREADY_RENDERED);try{await this.ensureScriptLoaded();const e=this.createWebComponent();t.innerHTML="",t.appendChild(e),this.state.container=t,this.state.element=e,this.state.initialized=!0}catch(e){throw console.error("Failed to render Auth widget:",e),e}}updateConfig(t){if(!this.state.initialized||!this.state.element)throw new Error(a.NOT_RENDERED);const e=this.state.element;t.jwt&&(this.config.jwt=t.jwt,e.jwt=t.jwt),t.onError!==void 0&&(this.config.onError=t.onError,e.onError=t.onError),t.onClose!==void 0&&(this.config.onClose=t.onClose,e.onClose=t.onClose),t.onDeposit!==void 0&&(this.config.onDeposit=t.onDeposit,e.onDeposit=t.onDeposit),t.onEvent!==void 0&&(this.config.onEvent=t.onEvent,e.onEvent=t.onEvent)}destroy(){this.state.initialized&&(this.state.element&&this.state.element.parentNode&&this.state.element.parentNode.removeChild(this.state.element),this.state.container&&(this.state.container.innerHTML=""),this.state.container=null,this.state.element=null,this.state.initialized=!1)}isRendered(){return this.state.initialized}getConfig(){return{...this.config}}}n.Auth=f,n.default=f,Object.defineProperties(n,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@connect-xyz/auth-js",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "nx": {
+    "name": "auth-js",
+    "targets": {
+      "build-static": {}
+    }
+  }
+}