unshared-clientjs-sdk 1.0.5 → 1.0.6

package/dist/client.d.ts

@@ -1,9 +1,32 @@
+/**
+ * Configuration object for initializing the UnsharedLabsClient.
+ *
+ * @interface UnsharedLabsClientConfig
+ * @property {string} apiKey - Your API key for authenticating with UnsharedLabs services
+ * @property {string} clientId - Encrypted client ID for authentication
+ * @property {string} [baseUrl] - Optional custom base URL for the API service
+ * @property {string} [emailServiceUrl] - Optional custom URL for the email service
+ */
 export interface UnsharedLabsClientConfig {
     apiKey: string;
     clientId: string;
     baseUrl?: string;
     emailServiceUrl?: string;
 }
+/**
+ * Data structure representing a processed user event.
+ *
+ * @interface ProcessUserEventData
+ * @property {string} id - Unique identifier for the event
+ * @property {string} event_type - Type of event that was processed
+ * @property {string} user_id - Encrypted user identifier
+ * @property {string} email_address - Encrypted email address
+ * @property {string} ip_address - Encrypted IP address
+ * @property {string} device_id - Encrypted device identifier
+ * @property {string} session_hash - Encrypted session hash
+ * @property {string} user_agent - Encrypted user agent string
+ * @property {string} client_timestamp - Timestamp when the event was created on the client
+ */
 export interface ProcessUserEventData {
     id: string;
     event_type: string;
@@ -15,36 +38,217 @@ export interface ProcessUserEventData {
     user_agent: string;
     client_timestamp: string;
 }
+/**
+ * Event processing result containing event data and status information.
+ *
+ * @interface ProcessUserEventEvent
+ * @property {ProcessUserEventData[]} data - Array of processed event data
+ * @property {string} status - Status of the event processing (e.g., 'success', 'error')
+ * @property {string} statusDetails - Detailed status message
+ */
 export interface ProcessUserEventEvent {
     data: ProcessUserEventData[];
     status: string;
     statusDetails: string;
 }
+/**
+ * Analysis result from processing a user event, including flagging information.
+ *
+ * @interface ProcessUserEventAnalysis
+ * @property {string} status - Status of the analysis (e.g., 'success', 'error')
+ * @property {boolean} isUserFlagged - Whether the user has been flagged based on the analysis
+ * @property {string} statusDetails - Detailed status message from the analysis
+ */
 export interface ProcessUserEventAnalysis {
     status: string;
     isUserFlagged: boolean;
     statusDetails: string;
 }
+/**
+ * Complete response data containing both event and analysis results.
+ *
+ * @interface ProcessUserEventResponseData
+ * @property {ProcessUserEventEvent} event - Event processing result
+ * @property {ProcessUserEventAnalysis} analysis - Analysis result
+ */
 export interface ProcessUserEventResponseData {
     event: ProcessUserEventEvent;
     analysis: ProcessUserEventAnalysis;
 }
+/**
+ * Complete response from the processUserEvent API call.
+ *
+ * @interface ProcessUserEventResponse
+ * @property {boolean} success - Whether the API call was successful
+ * @property {ProcessUserEventResponseData} data - Response data containing event and analysis results
+ */
 export interface ProcessUserEventResponse {
     success: boolean;
     data: ProcessUserEventResponseData;
 }
+/**
+ * Client for interacting with UnsharedLabs API services.
+ *
+ * This client provides methods to:
+ * - Process user events for fraud detection and analysis
+ * - Trigger email verification
+ * - Verify email verification codes
+ *
+ * All sensitive data (user IDs, IP addresses, etc.) is automatically encrypted
+ * before being sent to the API using the provided API key.
+ *
+ * @class UnsharedLabsClient
+ * @example
+ * ```typescript
+ * const client = new UnsharedLabsClient({
+ *   apiKey: 'your-api-key',
+ *   clientId: 'base64-encoded-client-id'
+ * });
+ * ```
+ */
 export default class UnsharedLabsClient {
     private _apiKey;
     private _clientId;
     private _apiBaseUrl;
     private _emailServiceUrl;
+    /**
+     * Creates a new instance of UnsharedLabsClient.
+     *
+     * @param {UnsharedLabsClientConfig} config - Configuration object containing API credentials and optional service URLs
+     * @constructor
+     */
     constructor(config: UnsharedLabsClientConfig);
     private _getBasicAuthHeader;
     /**
+     * Submits a user event to the UnsharedLabs API for processing.
+     *
      * @deprecated This method is deprecated and will be removed in a future version. Use `processUserEvent` instead.
+     *
+     * @param {string} eventType - Type of event being submitted (e.g., 'signup', 'login', 'purchase')
+     * @param {string} userId - Unique identifier for the user. Use email address if available.
+     * @param {string} ipAddress - IP address of the user
+     * @param {string} deviceId - Unique identifier for the device
+     * @param {string} sessionHash - Hash of the user's session
+     * @param {string} userAgent - User agent string from the browser/client
+     * @param {string} clientTimestamp - ISO 8601 timestamp when the event occurred on the client
+     * @param {Map<string, any> | null} [eventDetails] - Optional map of additional event details to include
+     *
+     * @returns {Promise<{status: number, statusText: string, data: any}>} Response object containing HTTP status, status text, and response data
+     *
+     * @throws {Error} Throws an error if the API request fails or returns a non-OK status
+     *
+     * @example
+     * ```typescript
+     * const result = await client.submitEvent(
+     *   'signup',
+     *   'user@example.com',
+     *   '192.168.1.1',
+     *   'device456',
+     *   'session789',
+     *   'Mozilla/5.0...',
+     *   '2024-01-01T00:00:00Z',
+     *   new Map([['source', 'web']])
+     * );
+     * ```
      */
     submitEvent(eventType: string, userId: string, ipAddress: string, deviceId: string, sessionHash: string, userAgent: string, clientTimestamp: string, eventDetails?: Map<string, any> | null): Promise<any>;
+    /**
+     * Processes a user event through the UnsharedLabs API, including fraud detection and analysis.
+     *
+     * This method encrypts all sensitive user data (user ID, IP address, device ID, etc.) before
+     * sending it to the API. The response includes both event processing results and analysis
+     * results that indicate if the user has been flagged for suspicious activity.
+     *
+     * @param {string} eventType - Type of event being processed (e.g., 'signup', 'login', 'purchase')
+     * @param {string} userId - Unique identifier for the user. Use email address if available.
+     * @param {string} ipAddress - IP address of the user
+     * @param {string} deviceId - Unique identifier for the device
+     * @param {string} sessionHash - Hash of the user's session
+     * @param {string} userAgent - User agent string from the browser/client
+     * @param {string} emailAddress - Email address of the user
+     * @param {Map<string, any> | null} [eventDetails] - Optional map of additional event details to include
+     *
+     * @returns {Promise<ProcessUserEventResponse>} Response object containing:
+     *   - success: Boolean indicating if the API call was successful
+     *   - data: Object containing:
+     *     - event: Event processing result with status and event data
+     *     - analysis: Analysis result with flagging information (isUserFlagged)
+     *
+     * @throws {Error} Throws an error if the API request fails or returns a non-OK status
+     *
+     * @example
+     * ```typescript
+     * const response = await client.processUserEvent(
+     *   'signup',
+     *   'user@example.com',
+     *   '192.168.1.1',
+     *   'device456',
+     *   'session789',
+     *   'Mozilla/5.0...',
+     *   'user@example.com',
+     *   new Map([['source', 'web']])
+     * );
+     *
+     * if (response.data.analysis.isUserFlagged) {
+     *   console.log('User flagged for suspicious activity');
+     * }
+     * ```
+     */
     processUserEvent(eventType: string, userId: string, ipAddress: string, deviceId: string, sessionHash: string, userAgent: string, emailAddress: string, eventDetails?: Map<string, any> | null): Promise<ProcessUserEventResponse>;
+    /**
+     * Triggers an email verification to be sent to the user.
+     *
+     * This method sends a verification email to the specified user. The email address can be
+     * provided either as the userId parameter (if userId is a valid email) or as the optional
+     * emailAddress parameter.
+     *
+     * @param {string} userId - User identifier (enter email if possible). If this is a valid email address, it will be used as the recipient.
+     *
+     * @param {string} [emailAddress] - Optional email address to send the verification to.
+     *                                  Required if userId is not a valid email address.
+     *
+     * @returns {Promise<any>} Response object from the email service containing verification details
+     *
+     * @throws {Error} Throws an error if:
+     *   - Neither userId nor emailAddress is a valid email address
+     *   - The email service request fails or returns a non-OK status
+     *
+     * @example
+     * ```typescript
+     * // Using userId as email
+     * await client.triggerEmailVerification('user@example.com');
+     *
+     * // Using separate emailAddress
+     * await client.triggerEmailVerification('user@example.com', 'user@example.com');
+     * ```
+     */
     triggerEmailVerification(userId: string, emailAddress?: string): Promise<any>;
+    /**
+     * Verifies an email verification code for a user.
+     *
+     * This method validates a verification code that was sent to the user via email.
+     * The code is typically obtained from the user after they receive the verification email.
+     *
+     * @param {string} userId - User identifier/email address for whom the code is being verified.
+     * @param {string} code - Verification code that was sent to the user's email
+     *
+     * @returns {Promise<any>} Response object from the verification service containing:
+     *   - Verification status (success/failure)
+     *   - Additional verification details
+     *
+     * @throws {Error} Throws an error if:
+     *   - The verification service request fails
+     *   - The service returns a non-OK status (e.g., invalid code, expired code)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await client.verify('user@example.com', '123456');
+     *   console.log('Verification successful:', result);
+     * } catch (error) {
+     *   console.error('Verification failed:', error.message);
+     * }
+     * ```
+     */
     verify(userId: string, code: string): Promise<any>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unshared-clientjs-sdk",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "",
   "main": "dist/client.js",
   "types": "dist/client.d.ts",