@crmcom/self-service-sdk 3.0.0-build.8 → 3.0.0-build.9

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/httpBackOfficeUtil.js

@@ -6,8 +6,13 @@
 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,
@@ -29,6 +34,15 @@ const initOptionHeader = () => {
 
 /** 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;
@@ -48,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
@@ -80,7 +94,7 @@ async function setupChannel({
       _sessionData = undefined;
     }
   }
-  //TODO add silent refresh token here
+  _initialized = true;
 }
 
 async function refreshToken() {
@@ -184,6 +198,7 @@ async function post({
   logOutIfSessionInvalid=true,
   refreshToken
 }) {
+  _assertInitialized();
   // let serverConfig = getServerConfig();
   // let uri = getURI(isBackend, resourcePath);
   let uri = _host + 'backoffice/v1/' + resourcePath;
@@ -247,6 +262,7 @@ async function get({
   logOutIfSessionInvalid = true,
   returnText=false
 }) {
+  _assertInitialized();
   let uri = getURI(isBackend, resourcePath);
   // let uri = _host + 'backoffice/v1/' + resourcePath;
   var options = {};
@@ -296,6 +312,7 @@ async function sendDelete({
   isBackend = false,
   logOutIfSessionInvalid = true
 }) {
+  _assertInitialized();
   // let uri = getURI(isBackend, resourcePath);
   let uri = _host + 'backoffice/v1/' + resourcePath;
   var options = {};
@@ -344,6 +361,7 @@ async function put({
   isBackend = false, 
   logOutIfSessionInvalid = true
 }) {
+  _assertInitialized();
   // let uri = getURI(isBackend, resourcePath);
   let uri = _host + 'backoffice/v1/' + resourcePath;
   var options = {};

package/httpUtil.js

@@ -17,8 +17,13 @@ const initOptionHeader = () => {
 }
 
 // import { showMessageError } from '../../utils/util';
+let _initialized = false;
+
 export const httpUtil = {
-    setupChannel,
+    init,
+    /** @deprecated Use init() instead */
+    setupChannel: init,
+    isInitialized: () => _initialized,
     put,
     post,
     get,
@@ -43,6 +48,15 @@ export const httpUtil = {
 
 /** local variables */
 
+function _assertInitialized() {
+    if (!_initialized) {
+        throw new Error(
+            'CRM.COM SDK not initialized. Call init() before using any SDK methods. ' +
+            'Example: import { init } from "@crmcom/self-service-sdk"; await init({ apiKey, host, ... });'
+        );
+    }
+}
+
 let _storeKVFn;
 let _getKVFn;
 let _sessionInvalidCallback;
@@ -65,7 +79,7 @@ let _mwNodejs_host;
 let _mwNodejs_apiKey;
 
 
-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
@@ -114,7 +128,7 @@ async function setupChannel({
             _sessionData = undefined;
         }
     }
-    //TODO add silent refresh token here
+    _initialized = true;
 }
 
 async function setupApiKey(apikey){
@@ -282,6 +296,7 @@ async function post({
     isMwNodejs = false,
     plugin,
 }) {
+    _assertInitialized();
     try {
         //let logoutStatus = await getData('LOGOUT_STATUS');
         //if(logoutStatus == 'PROCESSING') return;
@@ -421,6 +436,7 @@ async function get({
     isMwNodejs = false,
     plugin,
 }) {
+    _assertInitialized();
     try {
        // let logoutStatus = await getData('LOGOUT_STATUS');
         //if(logoutStatus == 'PROCESSING') return;
@@ -525,6 +541,7 @@ async function sendDelete({
     isMiddleware = false,
     isMwNodejs = false,
 }) {
+    _assertInitialized();
     try {
         let uri = getURI(isBackend, resourcePath, isMiddleware, isMwNodejs);
         var options = {};
@@ -604,6 +621,7 @@ async function put({
     isMwNodejs = false,
     accessToken,
 }) {
+    _assertInitialized();
     try {
         let uri = getURI(isBackend, resourcePath, isMiddleware, isMwNodejs);
         var options = {};
@@ -736,6 +754,7 @@ async function uploadFile({
     keyParam = 'file',
     disalbedContentType = false,
 }) {
+    _assertInitialized();
     try {
         let uri = getURI(isBackend, resourcePath, isMiddleware);
         var options = {};
@@ -823,6 +842,7 @@ async function uploadFileNew({
     accessToken,
     isMiddleware = false
 }) {
+    _assertInitialized();
     try {
         let uri = getURI(isBackend, resourcePath, isMiddleware);
 

package/index.d.ts

@@ -69,7 +69,7 @@ export declare const logger: {
 // HTTP Utilities
 // ============================================================================
 
-interface SetupChannelOptions {
+export interface InitOptions {
     storeKVFn: (key: string, value: any) => void | Promise<void>;
     getKVFn: (key: string) => any | Promise<any>;
     sessionInvalidCallback: (shouldLogout: boolean) => void | Promise<void>;
@@ -129,7 +129,10 @@ interface UploadFileOptions {
 }
 
 export declare const httpUtil: {
-    setupChannel(options: SetupChannelOptions): Promise<void>;
+    init(options: InitOptions): Promise<void>;
+    /** @deprecated Use init() instead */
+    setupChannel(options: InitOptions): Promise<void>;
+    isInitialized(): boolean;
     setupApiKey(apiKey: string): Promise<void>;
     post(options: HttpRequestOptions): Promise<SDKResult>;
     get(options: HttpRequestOptions): Promise<SDKResult>;
@@ -152,7 +155,10 @@ export declare const httpUtil: {
 };
 
 export declare const httpBackOfficeUtil: {
-    setupChannel(options: Pick<SetupChannelOptions, 'storeKVFn' | 'getKVFn' | 'sessionInvalidCallback' | 'apiKey' | 'host' | 'fetchFn'>): Promise<void>;
+    init(options: Pick<InitOptions, 'storeKVFn' | 'getKVFn' | 'sessionInvalidCallback' | 'apiKey' | 'host' | 'fetchFn'>): Promise<void>;
+    /** @deprecated Use init() instead */
+    setupChannel(options: Pick<InitOptions, 'storeKVFn' | 'getKVFn' | 'sessionInvalidCallback' | 'apiKey' | 'host' | 'fetchFn'>): Promise<void>;
+    isInitialized(): boolean;
     post(options: HttpRequestOptions): Promise<SDKResult>;
     get(options: HttpRequestOptions): Promise<SDKResult>;
     put(options: HttpRequestOptions): Promise<SDKResult>;
@@ -519,9 +525,18 @@ export declare const eventListener: {
 };
 
 // ============================================================================
-// Data Utilities
+// Top-level SDK Initialization
 // ============================================================================
 
-export declare const dataUtil: {
-    [key: string]: (...args: any[]) => any;
-};
+/**
+ * Initialize the Self-Service SDK. Must be called before using any other SDK module.
+ * Alias for httpUtil.init().
+ */
+export declare function init(options: InitOptions): Promise<void>;
+
+/**
+ * Initialize the Back-Office SDK. Must be called before using any back-office module.
+ * Alias for httpBackOfficeUtil.init().
+ */
+export declare function initBackOffice(options: Pick<InitOptions, 'storeKVFn' | 'getKVFn' | 'sessionInvalidCallback' | 'apiKey' | 'host' | 'fetchFn'>): Promise<void>;
+

package/index.js

@@ -1,5 +1,22 @@
 export { httpUtil } from './httpUtil.js';
 export { httpBackOfficeUtil } from './httpBackOfficeUtil.js';
+
+// Top-level convenience aliases for SDK initialization
+import { httpUtil as _httpUtil } from './httpUtil.js';
+import { httpBackOfficeUtil as _httpBackOfficeUtil } from './httpBackOfficeUtil.js';
+
+/**
+ * Initialize the Self-Service SDK. Must be called before using any other SDK module.
+ * @see httpUtil.init
+ */
+export const init = _httpUtil.init;
+
+/**
+ * Initialize the Back-Office SDK. Must be called before using any back-office module.
+ * @see httpBackOfficeUtil.init
+ */
+export const initBackOffice = _httpBackOfficeUtil.init;
+
 export { authentication } from './authentication.js';
 export { contacts } from './contacts.js';
 export { orders } from './orders.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crmcom/self-service-sdk",
-  "version": "3.0.0-build.8",
+  "version": "3.0.0-build.9",
   "description": "Official CRM.COM Self-Service JavaScript SDK for consumer-facing API integration",
   "type": "module",
   "main": "index.js",