@crmcom/self-service-sdk 2.1.2 → 3.0.0-build.11

package/README.md

@@ -0,0 +1,165 @@
+# @crmcom/self-service-sdk
+
+Official CRM.COM Self-Service JavaScript SDK for consumer-facing API integration.
+
+## Installation
+
+```bash
+npm install @crmcom/self-service-sdk
+```
+
+### Peer Dependencies
+
+```bash
+npm install jwt-decode js-sha256 xml2js
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+
+You **must** call `init()` before using any other SDK method. This configures the HTTP layer with your API credentials and session management callbacks.
+
+```js
+import { init } from '@crmcom/self-service-sdk';
+
+await init({
+  apiKey: 'YOUR_API_KEY',
+  host: 'https://api.crm.com',
+  storeKVFn: (key, value) => localStorage.setItem(key, value),
+  getKVFn: (key) => localStorage.getItem(key),
+  sessionInvalidCallback: (shouldLogout) => {
+    if (shouldLogout) {
+      // redirect to login
+    }
+  },
+});
+```
+
+### 2. Use SDK modules
+
+Once initialized, import and use any module:
+
+```js
+import { authentication, contacts, orders, wallet } from '@crmcom/self-service-sdk';
+
+// Authenticate
+const authResult = await authentication.authenticateEmail({
+  username: 'user@example.com',
+  password: 'password',
+});
+
+// Get contact profile
+const profile = await contacts.getContact();
+
+// Browse products
+const products = await orders.getProducts({ page: 1, size: 20 });
+
+// Check wallet balance
+const myWallet = await wallet.getWallet();
+```
+
+### React Example
+
+```jsx
+// App.jsx
+import { useEffect, useState } from 'react';
+import { init } from '@crmcom/self-service-sdk';
+
+function App() {
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    init({
+      apiKey: process.env.REACT_APP_CRM_API_KEY,
+      host: process.env.REACT_APP_CRM_HOST,
+      storeKVFn: (key, value) => localStorage.setItem(key, JSON.stringify(value)),
+      getKVFn: (key) => JSON.parse(localStorage.getItem(key)),
+      sessionInvalidCallback: () => {
+        window.location.href = '/login';
+      },
+    }).then(() => setReady(true));
+  }, []);
+
+  if (!ready) return <div>Loading...</div>;
+
+  return <YourApp />;
+}
+```
+
+## Init Options
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `apiKey` | `string` | Yes | Your CRM.COM API key |
+| `host` | `string` | Yes | Base API URL (e.g. `https://api.crm.com`) |
+| `storeKVFn` | `(key, value) => void \| Promise<void>` | Yes | Function to persist key-value pairs (tokens, session data) |
+| `getKVFn` | `(key) => any \| Promise<any>` | Yes | Function to retrieve persisted values |
+| `sessionInvalidCallback` | `(shouldLogout) => void` | Yes | Called when session is invalid and refresh fails |
+| `fetchFn` | `typeof fetch` | No | Custom fetch implementation (defaults to global `fetch`) |
+| `enableSslPinning` | `boolean` | No | Enable SSL pinning (mobile apps) |
+| `sslPinningOptions` | `Record<string, any>` | No | SSL pinning configuration |
+| `isBackend` | `boolean` | No | Set `true` for backend/server usage |
+| `middlewareHost` | `string` | No | Middleware service host URL |
+| `middlewareApiKey` | `string` | No | Middleware API key |
+| `mwNodejsHost` | `string` | No | Node.js middleware host URL |
+| `mwNodejsApiKey` | `string` | No | Node.js middleware API key |
+
+## Available Modules
+
+| Module | Description |
+|--------|-------------|
+| `authentication` | Phone, email, Facebook, SSO/OIDC auth flows |
+| `contacts` | Contact profile, addresses, preferences |
+| `orders` | Catalogue, products, order estimation and placement |
+| `wallet` | Balance, transactions, top-ups, transfers |
+| `payment` | Payment methods, forms, top-ups |
+| `subscriptions` | Services, devices, billing |
+| `rewards` | Offers, promotions, schemes |
+| `account` | Journals, balances, rewards |
+| `communications` | Messages, notifications |
+| `community` | Members, relations, groups |
+| `config` | App config, languages, address lookup |
+| `organisations` | Organisation search, locations |
+| `servicerequest` | Support tickets |
+| `connectx` | SIM management |
+| `jcccards` | Card operations |
+| `mobilepass` | Mobile wallet passes |
+| `paymentgateway` | Payment gateway client tokens |
+| `payouts` | Payout creation |
+
+## Error Handling
+
+All SDK methods return an `SDKResult` object:
+
+```js
+const result = await contacts.getContact();
+
+if (result.code === 'OK') {
+  console.log(result.data);
+} else {
+  console.error('Error:', result.code, result.error);
+}
+```
+
+If the SDK is used before calling `init()`, it throws:
+
+```
+Error: CRM.COM SDK not initialized. Call init() before using any SDK methods.
+```
+
+## Migration from v2
+
+If you were using `setupChannel`, it still works but is deprecated:
+
+```diff
+- import { httpUtil } from '@crmcom/self-service-sdk';
+- await httpUtil.setupChannel({ apiKey, host, ... });
+
++ import { init } from '@crmcom/self-service-sdk';
++ await init({ apiKey, host, ... });
+```
+
+## License
+
+MIT

package/authentication.js

@@ -88,7 +88,6 @@ async function authenticate(contact, startSession = true) {
         if (startSession == true && response.code == "OK" && response.data && response.data.access_token) {
             httpUtil.startSession(response.data);
         }
-        //check return code here instead of put as there would be different intepretation for different API
         if (response.code == "OK") {
             if (response.data.auth_otp || response.data.access_token) {
                 return createResult(ErrorCodes.OK, response.data);
@@ -96,20 +95,7 @@ async function authenticate(contact, startSession = true) {
                 return createResult(ErrorCodes.INVALID_LOGIN, response.error);
             }
         } else {
-            if (
-                response.error &&
-                response.error.message == "COM.CRM.EXCEPTIONS.INVALIDLOGINEXCEPTION"
-            ) {
-                return createResult(ErrorCodes.INVALID_LOGIN, response.error);
-            } else if (response.error &&
-                response.error.error == "COM.CRM.EXCEPTIONS.EMAILNOTVERIFIEDEXCEPTION") {
-                return createResult(ErrorCodes.EMAIL_NOT_VERIFIED, response.error);
-            } else if (response.code == '429' || response.code === 429) {
-                return createResult(ErrorCodes.TOO_MANY_REQUESTS, response.error);
-            } else if (response.error && response.error.error == "COM.CRM.EXCEPTIONS.CIMALREADYEXISTSFORANOTHERCONTACTEXCEPTION") {
-                return createResult(ErrorCodes.CIMALREADYEXISTSFORANOTHERCONTACTEXCEPTION, response.error);
-            }
-            else return createResult(ErrorCodes.UNCLASSIFIED_ERROR, response.error);
+            return createCommonResult(response);
         }
     } catch (e) {
         logger.error("Exception register:", e);
@@ -165,16 +151,7 @@ async function validateOTP({ auth_otp,otp }, startSession = true) {
         if (startSession == true && response.code == "OK") {
             httpUtil.startSession(response.data);
         }
-        if (response.code == "OK")
-            return createResult(ErrorCodes.OK, response.data);
-        else {
-            if (
-                response.error &&
-                response.error.message == "COM.CRM.EXCEPTIONS.INVALIDLOGINEXCEPTION"
-            ) {
-                return createResult(ErrorCodes.INVALID_LOGIN, response.error);
-            } else return createResult(ErrorCodes.UNCLASSIFIED_ERROR, response.error);
-        }
+        return createCommonResult(response);
     } catch (e) {
         logger.error("Exception register:", e);
         return createResult(ErrorCodes.UNKNOWN, e);
@@ -195,7 +172,8 @@ async function registerByPhone(
         custom_fields,
         accept_term_conditions=true,
         validation_required,
-        pass_code
+        pass_code,
+        pass_pin
     },
     startSession = false
 ) {
@@ -216,7 +194,8 @@ async function registerByPhone(
         language_code,
         custom_fields,
         validation_required,
-        pass_code
+        pass_code,
+        pass_pin
     };
     if (referral_code) {
         body.referral_code = referral_code;
@@ -239,7 +218,8 @@ async function registerByEmail(
         custom_fields,
         accept_term_conditions=true,
         validation_required,
-        pass_code
+        pass_code,
+        pass_pin
     },
     startSession = false
 ) {
@@ -258,7 +238,8 @@ async function registerByEmail(
         language_code,
         custom_fields,
         validation_required,
-        pass_code
+        pass_code,
+        pass_pin
     };
     if (referral_code) {
         body.referral_code = referral_code;
@@ -300,43 +281,18 @@ async function register(body,startSession = true) {
             httpUtil.startSession(response.data);
         }
         //check return code here instead of put as there would be different intepretation for different API
-        if (response.code == "OK")
+        if (response.code == "OK") {
             return createResult(ErrorCodes.OK, response.data);
-        else {
-            if (
-                response.error && (response.error.error == "COM.CRM.EXCEPTIONS.MORETHANONEENTITYEXISTSEXCEPTION" || response.error.error == 'CRM.EXCEPTIONS.MORETHANONEENTITYEXISTSEXCEPTION')
-            ) {
-                return createResult(
-                    ErrorCodes.REGISTRATION_FAIL_CONTACT_EXISTS,
-                    response.error
-                );
-            }else if(response.error && response.error.error == "CRM.EXCEPTIONS.INVALIDVALUEEXCEPTION"){
-                return createResult(
-                    ErrorCodes.INVALIDVALUEEXCEPTION,
-                    response.error
-                );
-            }
-            else if(response.error && response.error.error == "CRM.EXCEPTIONS.NOTFOUNDEXCEPTION"){
-                return createResult(
-                    ErrorCodes.REDEEM_PASS_INVALID,
-                    response.error
-                );
-            }
-            else if(response.error && response.error.error == "COM.CRM.EXCEPTIONS.THISPASSHASALREADYBEENREDEEMEDEXCEPTION"){
-                return createResult(
-                    ErrorCodes.REDEEM_PASS_USED,
-                    response.error
-                );
-            }
-            else if(response.error && response.error.error === "COM.CRM.EXCEPTIONS.ONLYACTIVEPASSESCANBEREDEEMEDEXCEPTION"){
-                return createResult(
-                    ErrorCodes.REDEEM_PASS_NOT_ACTIVE,
-                    response.error
-                );
-            }
-             else 
-                return createResult(ErrorCodes.UNCLASSIFIED_ERROR, response.error);
         }
+        // Registration-specific: MORETHANONEENTITYEXISTSEXCEPTION means contact already exists
+        if (response.error && (response.error.error == "COM.CRM.EXCEPTIONS.MORETHANONEENTITYEXISTSEXCEPTION" || response.error.error == 'CRM.EXCEPTIONS.MORETHANONEENTITYEXISTSEXCEPTION')) {
+            return createResult(ErrorCodes.REGISTRATION_FAIL_CONTACT_EXISTS, response.error);
+        }
+        // Pass-specific: NOTFOUNDEXCEPTION means invalid pass in this context
+        if (response.error && response.error.error == "CRM.EXCEPTIONS.NOTFOUNDEXCEPTION") {
+            return createResult(ErrorCodes.REDEEM_PASS_INVALID, response.error);
+        }
+        return createCommonResult(response);
     } catch (e) {
         logger.error("Exception register:", e);
         return createResult(ErrorCodes.UNKNOWN, e);
@@ -421,28 +377,15 @@ async function addContactIdentity(body,contactId,accessToken) {
             accessToken: accessToken
         });
         logger.debug('Identity add response received')
-        if (response.code == "OK")
+        if (response.code == "OK") {
             return createResult(ErrorCodes.OK, response.data);
-        else {
-            logger.debug("Identity add error:", response.error)
-            if (response.error && (response.error.error == "COM.CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION")) {
-                return createResult(
-                    ErrorCodes.REGISTRATION_FAIL_CONTACT_EXISTS,
-                    response.error
-                );
-            } else if (response.error && (response.error.error == "COM.CRM.EXCEPTIONS.INVALIDPASSWORDEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.INVALIDPASSWORDEXCEPTION")) {
-                return createResult(
-                    ErrorCodes.INVALID_PASSWORD_EXCEPTION,
-                    response.error
-                );
-            } else if (response.error && (response.error.error == "COM.CRM.EXCEPTIONS.INVALIDCONTACTPASSWORDEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.INVALIDCONTACTPASSWORDEXCEPTION")) {
-                return createResult(
-                    "INVALID_CONTACTPASSWORD_EXCEPTION",
-                    response.error
-                );
-            }
-            else return createResult(ErrorCodes.UNCLASSIFIED_ERROR, response.error);
         }
+        logger.debug("Identity add error:", response.error)
+        // Identity-specific: ALREADYEXISTSEXCEPTION means contact already exists
+        if (response.error && (response.error.error == "COM.CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION")) {
+            return createResult(ErrorCodes.REGISTRATION_FAIL_CONTACT_EXISTS, response.error);
+        }
+        return createCommonResult(response);
     } catch (e) {
         logger.error("Exception register:", e);
         return createResult(ErrorCodes.UNKNOWN, e);
@@ -458,15 +401,14 @@ async function forgotPassword(email) {
             },
             logOutIfSessionInvalid: false
         });
-        if (response.code == "OK")
+        if (response.code == "OK") {
             return createResult(ErrorCodes.OK, response.data);
-        else {
-            if (response.error && response.error.error == "COM.CRM.EXCEPTIONS.INVALIDVALUEEXCEPTION") {
-                return createResult(ErrorCodes.FORGOT_EMAIL_NOT_FOUND_EXCEPTION, response.error);
-            } else if (response.code == '429') {
-                return createResult(ErrorCodes.TOO_MANY_REQUESTS, response.error);
-            } else return createResult(ErrorCodes.UNCLASSIFIED_ERROR, response.error);
         }
+        // Forgot password specific: INVALIDVALUEEXCEPTION means email not found
+        if (response.error && (response.error.error == "COM.CRM.EXCEPTIONS.INVALIDVALUEEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.INVALIDVALUEEXCEPTION")) {
+            return createResult(ErrorCodes.FORGOT_EMAIL_NOT_FOUND_EXCEPTION, response.error);
+        }
+        return createCommonResult(response);
     } catch (e) {
         logger.error("Exception update phone:", e);
         return createResult(ErrorCodes.UNKNOWN, e);

package/config.js

@@ -1,6 +1,5 @@
 import { httpUtil } from './httpUtil'
 import { ErrorCodes, createResult, createCommonResult } from './resultUtil'
-import { getData } from '../../utils/common';
 import { logger } from './logger';
 export const config = {
 	getAppCfg,
@@ -23,9 +22,6 @@ async function getAppCfg({
 	cname
 } = {}) {
 	try {
-		var appId = await getData("APP_ID");
-		if (!app_id) app_id = appId;
-
 		var queryParams = {}
 		if (use_cname) {
 			queryParams.cloud_name = cname;

package/connectx.js

@@ -1,7 +1,6 @@
 import { httpUtil } from './httpUtil'
 import { ErrorCodes, createResult, createCommonResult } from './resultUtil'
-import { getData } from '../../utils/common';
-import { logger } from './logger';
+import { logger } from './logger';
 export const connectx = {
     getBuckets,
     simConfirmation,

package/contacts.js

@@ -123,19 +123,14 @@ async function addContactAddress({
             },
             withAccessToken: true,
         });
-        if (response.code == "OK")
+        if (response.code == "OK") {
             return createResult(ErrorCodes.OK, response.data);
-        else {
-            if (
-                response.error && (
-                    response.error.error == "COM.CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION")
-            ) {
-                return createResult(
-                    ErrorCodes.ADD_ADDRESS_ALREADY_TYPE,
-                    response.error
-                );
-            } else return createResult(ErrorCodes.UNCLASSIFIED_ERROR, response.error);
         }
+        // Address-specific: ALREADYEXISTSEXCEPTION means address type already exists
+        if (response.error && (response.error.error == "COM.CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION")) {
+            return createResult(ErrorCodes.ADD_ADDRESS_ALREADY_TYPE, response.error);
+        }
+        return createCommonResult(response);
     } catch (e) {
         logger.error("Exception addContactAddress:", e);
         return createResult(ErrorCodes.UNKNOWN, e);
@@ -176,19 +171,14 @@ async function updateContactAddress({
             },
             withAccessToken: true,
         });
-        if (response.code == "OK")
+        if (response.code == "OK") {
             return createResult(ErrorCodes.OK, response.data);
-        else {
-            if (
-                response.error && (
-                    response.error.error == "COM.CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION")
-            ) {
-                return createResult(
-                    ErrorCodes.ADD_ADDRESS_ALREADY_TYPE,
-                    response.error
-                );
-            } else return createResult(ErrorCodes.UNCLASSIFIED_ERROR, response.error);
         }
+        // Address-specific: ALREADYEXISTSEXCEPTION means address type already exists
+        if (response.error && (response.error.error == "COM.CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION" || response.error.error == "CRM.EXCEPTIONS.ALREADYEXISTSEXCEPTION")) {
+            return createResult(ErrorCodes.ADD_ADDRESS_ALREADY_TYPE, response.error);
+        }
+        return createCommonResult(response);
     } catch (e) {
         logger.error("Exception updateContactAddress:", e);
         return createResult(ErrorCodes.UNKNOWN, e);
@@ -207,9 +197,7 @@ async function updateContactOnboardingCards({
             },
             withAccessToken: true,
         });
-        if (response.code == "OK")
-            return createResult(ErrorCodes.OK, response.data);
-        else return createResult(ErrorCodes.UNCLASSIFIED_ERROR, response.error);
+        return createCommonResult(response);
     } catch (e) {
         logger.error("Exception updateContactOnboardingCards:", e);
         return createResult(ErrorCodes.UNKNOWN, e);

package/eventListener.js

@@ -1,17 +1,17 @@
 import { logger } from './logger';
 let events = {};
 
-try {
-    // Dynamic import for Vite / ES modules
-    const customConfigModule = import("../../../custom.config");
-    events = customConfigModule.events || {};
-} catch (error) {
-    if (error.code === 'MODULE_NOT_FOUND') {
-        events = {};
-    } else {
-        throw error;
-    }
-}
+// try {
+//     // Dynamic import for Vite / ES modules
+//     const customConfigModule = import("../../../custom.config");
+//     events = customConfigModule.events || {};
+// } catch (error) {
+//     if (error.code === 'MODULE_NOT_FOUND') {
+//         events = {};
+//     } else {
+//         throw error;
+//     }
+// }
 
 export const eventListener = {
     handleEvent,
@@ -28,14 +28,14 @@ export async function handleEvent({
     object_type // object type, e.g., string or object
 }) {
     logger.debug("handleEvent type:", type);
-    logger.debug("handleEvent code:", code);
-    logger.debug("handleEvent object_type:", object_type);
-    logger.debug("handleEvent data:", data);
+    // logger.debug("handleEvent code:", code);
+    // logger.debug("handleEvent object_type:", object_type);
+    // logger.debug("handleEvent data:", data);
 
-    if (type === eventTypes.kochava) {
-        const kochava = events?.kochava ?? null;
-        if (kochava?.sendEvent) {
-            await kochava.sendEvent(object_type, code, data);
-        }
-    }
+    // if (type === eventTypes.kochava) {
+    //     const kochava = events?.kochava ?? null;
+    //     if (kochava?.sendEvent) {
+    //         await kochava.sendEvent(object_type, code, data);
+    //     }
+    // }
 }

package/httpBackOfficeUtil.js

@@ -3,12 +3,16 @@
  */
 
 //import querystring from 'querystring';
-import { initOptionHeader } from '../../utils/common';
 import {jwtDecode} from 'jwt-decode';
 import { logger } from './logger';
 
+let _initialized = false;
+
 export const httpBackOfficeUtil = {
-  setupChannel,
+  init,
+  /** @deprecated Use init() instead */
+  setupChannel: init,
+  isInitialized: () => _initialized,
   put,
   post,
   get,
@@ -21,9 +25,24 @@ export const httpBackOfficeUtil = {
   switchSession
 };
 
+const initOptionHeader = () => {
+    return {
+        'User-Agent': 'request',
+        'Content-Type': 'application/json; charset=utf-8'
+    }
+}
 
 /** local variables */
 
+function _assertInitialized() {
+    if (!_initialized) {
+        throw new Error(
+            'CRM.COM Back-Office SDK not initialized. Call initBackOffice() before using any back-office SDK methods. ' +
+            'Example: import { initBackOffice } from "@crmcom/self-service-sdk"; await initBackOffice({ apiKey, host, ... });'
+        );
+    }
+}
+
 let _storeKVFn;
 let _getKVFn;
 let _sessionInvalidCallback;
@@ -43,7 +62,7 @@ let _backofficePath = 'backoffice/v1/';
  * when no connection refresh token will not be available -> should not kick user out.
  */
 
-async function setupChannel({
+async function init({
   storeKVFn,  //function to store key value
   getKVFn,    //function to get value by key from the storage
   sessionInvalidCallback, //function to call when api_key or token key is invalid and refresh token if available was failed
@@ -75,7 +94,7 @@ async function setupChannel({
       _sessionData = undefined;
     }
   }
-  //TODO add silent refresh token here
+  _initialized = true;
 }
 
 async function refreshToken() {
@@ -179,6 +198,7 @@ async function post({
   logOutIfSessionInvalid=true,
   refreshToken
 }) {
+  _assertInitialized();
   // let serverConfig = getServerConfig();
   // let uri = getURI(isBackend, resourcePath);
   let uri = _host + 'backoffice/v1/' + resourcePath;
@@ -242,6 +262,7 @@ async function get({
   logOutIfSessionInvalid = true,
   returnText=false
 }) {
+  _assertInitialized();
   let uri = getURI(isBackend, resourcePath);
   // let uri = _host + 'backoffice/v1/' + resourcePath;
   var options = {};
@@ -291,6 +312,7 @@ async function sendDelete({
   isBackend = false,
   logOutIfSessionInvalid = true
 }) {
+  _assertInitialized();
   // let uri = getURI(isBackend, resourcePath);
   let uri = _host + 'backoffice/v1/' + resourcePath;
   var options = {};
@@ -339,6 +361,7 @@ async function put({
   isBackend = false, 
   logOutIfSessionInvalid = true
 }) {
+  _assertInitialized();
   // let uri = getURI(isBackend, resourcePath);
   let uri = _host + 'backoffice/v1/' + resourcePath;
   var options = {};