celitech-sdk 1.1.68 → 1.1.72

package/documentation/services/PurchasesService.md

@@ -0,0 +1,219 @@
+# PurchasesService
+
+A list of all methods in the `PurchasesService` service. Click on the method name to view detailed information about that method.
+
+| Methods                                           | Description                                                                                                                                                                                                                                                                                                            |
+| :------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [listPurchases](#listpurchases)                   | This endpoint can be used to list all the successful purchases made between a given interval.                                                                                                                                                                                                                          |
+| [createPurchase](#createpurchase)                 | This endpoint is used to purchase a new eSIM by providing the package details.                                                                                                                                                                                                                                         |
+| [topUpESIM](#topupesim)                           | This endpoint is used to top-up an eSIM with the previously associated destination by providing an existing ICCID and the package details. The top-up is not feasible for eSIMs in "DELETED" or "ERROR" state.                                                                                                         |
+| [editPurchase](#editpurchase)                     | This endpoint allows you to modify the dates of an existing package with a future activation start time. Editing can only be performed for packages that have not been activated, and it cannot change the package size. The modification must not change the package duration category to ensure pricing consistency. |
+| [getPurchaseConsumption](#getpurchaseconsumption) | This endpoint can be called for consumption notifications (e.g. every 1 hour or when the user clicks a button). It returns the data balance (consumption) of purchased packages.                                                                                                                                       |
+
+## listPurchases
+
+This endpoint can be used to list all the successful purchases made between a given interval.
+
+- HTTP Method: `GET`
+- Endpoint: `/purchases`
+
+**Parameters**
+
+| Name        | Type   | Required | Description                                                                                                                                                                                                         |
+| :---------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| iccid       | string | ❌       | ID of the eSIM                                                                                                                                                                                                      |
+| afterDate   | string | ❌       | Start date of the interval for filtering purchases in the format 'yyyy-MM-dd'                                                                                                                                       |
+| beforeDate  | string | ❌       | End date of the interval for filtering purchases in the format 'yyyy-MM-dd'                                                                                                                                         |
+| referenceId | string | ❌       | The referenceId that was provided by the partner during the purchase or topup flow.                                                                                                                                 |
+| afterCursor | string | ❌       | To get the next batch of results, use this parameter. It tells the API where to start fetching data after the last item you received. It helps you avoid repeats and efficiently browse through large sets of data. |
+| limit       | number | ❌       | Maximum number of purchases to be returned in the response. The value must be greater than 0 and less than or equal to 100. If not provided, the default value is 20                                                |
+| after       | number | ❌       | Epoch value representing the start of the time interval for filtering purchases                                                                                                                                     |
+| before      | number | ❌       | Epoch value representing the end of the time interval for filtering purchases                                                                                                                                       |
+
+**Return Type**
+
+`ListPurchasesOkResponse`
+
+**Example Usage Code Snippet**
+
+```typescript
+import { Celitech } from 'celitech-sdk';
+
+(async () => {
+  const celitech = new Celitech({
+    clientId: 'client-id',
+    clientSecret: 'client-secret',
+  });
+
+  const { data } = await celitech.purchases.listPurchases({});
+
+  console.log(data);
+})();
+```
+
+## createPurchase
+
+This endpoint is used to purchase a new eSIM by providing the package details.
+
+- HTTP Method: `POST`
+- Endpoint: `/purchases`
+
+**Parameters**
+
+| Name | Type                                                        | Required | Description       |
+| :--- | :---------------------------------------------------------- | :------- | :---------------- |
+| body | [CreatePurchaseRequest](../models/CreatePurchaseRequest.md) | ✅       | The request body. |
+
+**Return Type**
+
+`CreatePurchaseOkResponse`
+
+**Example Usage Code Snippet**
+
+```typescript
+import { Celitech, CreatePurchaseRequest } from 'celitech-sdk';
+
+(async () => {
+  const celitech = new Celitech({
+    clientId: 'client-id',
+    clientSecret: 'client-secret',
+  });
+
+  const input: CreatePurchaseRequest = {
+    destination: 'FRA',
+    dataLimitInGb: 1,
+    startDate: '2023-11-01',
+    endDate: '2023-11-20',
+    email: 'example@domain.com',
+    referenceId: 'abc111222333444',
+    networkBrand: 'CELITECH',
+    startTime: 8.94,
+    endTime: 5.28,
+  };
+
+  const { data } = await celitech.purchases.createPurchase(input);
+
+  console.log(data);
+})();
+```
+
+## topUpESIM
+
+This endpoint is used to top-up an eSIM with the previously associated destination by providing an existing ICCID and the package details. The top-up is not feasible for eSIMs in "DELETED" or "ERROR" state.
+
+- HTTP Method: `POST`
+- Endpoint: `/purchases/topup`
+
+**Parameters**
+
+| Name | Type                                              | Required | Description       |
+| :--- | :------------------------------------------------ | :------- | :---------------- |
+| body | [TopUpEsimRequest](../models/TopUpEsimRequest.md) | ✅       | The request body. |
+
+**Return Type**
+
+`TopUpEsimOkResponse`
+
+**Example Usage Code Snippet**
+
+```typescript
+import { Celitech, TopUpEsimRequest } from 'celitech-sdk';
+
+(async () => {
+  const celitech = new Celitech({
+    clientId: 'client-id',
+    clientSecret: 'client-secret',
+  });
+
+  const input: TopUpEsimRequest = {
+    iccid: '1111222233334444555',
+    dataLimitInGb: 1,
+    startDate: '2023-11-01',
+    endDate: '2023-11-20',
+    email: 'example@domain.com',
+    referenceId: 'abc111222333444',
+    startTime: 5.74,
+    endTime: 9.23,
+  };
+
+  const { data } = await celitech.purchases.topUpEsim(input);
+
+  console.log(data);
+})();
+```
+
+## editPurchase
+
+This endpoint allows you to modify the dates of an existing package with a future activation start time. Editing can only be performed for packages that have not been activated, and it cannot change the package size. The modification must not change the package duration category to ensure pricing consistency.
+
+- HTTP Method: `POST`
+- Endpoint: `/purchases/edit`
+
+**Parameters**
+
+| Name | Type                                                    | Required | Description       |
+| :--- | :------------------------------------------------------ | :------- | :---------------- |
+| body | [EditPurchaseRequest](../models/EditPurchaseRequest.md) | ✅       | The request body. |
+
+**Return Type**
+
+`EditPurchaseOkResponse`
+
+**Example Usage Code Snippet**
+
+```typescript
+import { Celitech, EditPurchaseRequest } from 'celitech-sdk';
+
+(async () => {
+  const celitech = new Celitech({
+    clientId: 'client-id',
+    clientSecret: 'client-secret',
+  });
+
+  const input: EditPurchaseRequest = {
+    purchaseId: 'ae471106-c8b4-42cf-b83a-b061291f2922',
+    startDate: '2023-11-01',
+    endDate: '2023-11-20',
+    startTime: 1.27,
+    endTime: 5.18,
+  };
+
+  const { data } = await celitech.purchases.editPurchase(input);
+
+  console.log(data);
+})();
+```
+
+## getPurchaseConsumption
+
+This endpoint can be called for consumption notifications (e.g. every 1 hour or when the user clicks a button). It returns the data balance (consumption) of purchased packages.
+
+- HTTP Method: `GET`
+- Endpoint: `/purchases/{purchaseId}/consumption`
+
+**Parameters**
+
+| Name       | Type   | Required | Description        |
+| :--------- | :----- | :------- | :----------------- |
+| purchaseId | string | ✅       | ID of the purchase |
+
+**Return Type**
+
+`GetPurchaseConsumptionOkResponse`
+
+**Example Usage Code Snippet**
+
+```typescript
+import { Celitech } from 'celitech-sdk';
+
+(async () => {
+  const celitech = new Celitech({
+    clientId: 'client-id',
+    clientSecret: 'client-secret',
+  });
+
+  const { data } = await celitech.purchases.getPurchaseConsumption('4973fa15-6979-4daa-9cf3-672620df819c');
+
+  console.log(data);
+})();
+```

package/examples/README.md

@@ -0,0 +1,27 @@
+# celitech-sdk
+
+A basic example of how to use the celitech-sdk package.
+
+## Installation
+
+In the event `celitech-sdk` is not published to npm, you can install it locally by running the following command in the examples folder:
+
+```sh
+npm run setup
+```
+
+This will rebuild the parent package and install it locally.
+
+Otherwise you can install it from npm:
+
+```sh
+npm install celitech-sdk
+```
+
+## Usage
+
+To run the example, run the following command in the examples folder:
+
+```sh
+npm run start
+```

package/examples/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "Celitech",
+  "version": "1.1.72",
+  "private": true,
+  "dependencies": {
+    "celitech-sdk": "file:../",
+    "zod": "3.22.0"
+  },
+  "scripts": {
+    "setup": "npm --prefix ../ install && npm --prefix ../ run build && npm install",
+    "start": "tsc && node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.1",
+    "typescript": "5.3.3"
+  }
+}

package/examples/src/index.ts

@@ -0,0 +1,12 @@
+import { Celitech } from 'celitech-sdk';
+
+(async () => {
+  const celitech = new Celitech({
+    clientId: 'client-id',
+    clientSecret: 'client-secret',
+  });
+
+  const { data } = await celitech.destinations.listDestinations();
+
+  console.log(data);
+})();

package/examples/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noImplicitAny": true,
+    "baseUrl": "./",
+    "declaration": true,
+    "moduleResolution": "node",
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true,
+    "declarationMap": true,
+    "lib": ["es2017", "dom"],
+    "sourceMap": true
+  },
+  "include": ["src/"]
+}

package/package.json

@@ -1,57 +1,24 @@
 {
-  "source": "./src/index.ts",
-  "exports": {
-    "require": "./dist/commonjs/index.js",
-    "types": "./dist/commonjs/index.d.ts",
-    "default": "./dist/esm/index.js"
+  "name": "celitech-sdk",
+  "version": "1.1.72",
+  "description": "Welcome to the CELITECH API documentation!  Useful links: [Homepage](https://www.celitech.com) | [Support email](mailto:support@celitech.com) | [Blog](https://www.celitech.com/blog/) ",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
   },
-  "main": "./dist/commonjs/index.js",
-  "module": "./dist/esm/index.js",
-  "browser": "./dist/index.umd.js",
-  "unpkg": "./dist/index.umd.js",
-  "types": "./dist/commonjs/index.d.ts",
-  "files": [
-    "dist",
-    "README.md"
+  "keywords": [
+    "typescript",
+    "sdk",
+    "api",
+    "client"
   ],
+  "author": "CELITECH",
+  "license": "MIT",
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^5.43.0",
-    "@typescript-eslint/parser": "^5.43.0",
-    "@types/node": "^17.0.23",
-    "@types/jest": "^29.5.6",
-    "eslint": "^8.20.0",
-    "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-config-airbnb-typescript": "^17.0.0",
-    "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "jest": "^29.7.0",
-    "nock": "^13.2.4",
-    "prettier": "^2.6.2",
-    "ts-jest": "^29.1.1",
-    "typescript": "^4.6.0"
-  },
-  "scripts": {
-    "build": "npm run build:all",
-    "build:cjs": "tsc --module commonjs --outDir dist/commonjs",
-    "build:esm": "tsc --module esnext --outDir dist/esm",
-    "build:umd": "tsc --module umd --outDir dist/umd",
-    "build:all": "npm run build:cjs && npm run build:esm && npm run build:umd",
-    "lint": "eslint --ext .ts,.js ./src/ --resolve-plugins-relative-to .",
-    "lint:ci": "eslint --ext .ts,.js ./src/ --resolve-plugins-relative-to . --cache --quiet",
-    "lint:fix": "eslint --ext .ts,.js ./src/ --resolve-plugins-relative-to . --cache --fix",
-    "rebuild": "rm -rf dist/ && tsc",
-    "test": "jest --detectOpenHandles",
-    "watch": "rm -rf dist/ && tsc -w",
-    "version": "tsc --version",
-    "prepublishOnly": "npm run build"
+    "typescript": "5.3.3"
   },
-  "name": "celitech-sdk",
-  "description": "Celitech - Welcome to the CELITECH API documentation!  Useful links: [Homepage](https://www.celitech.com) | [Support email](mailto:support@celitech.com) | [Blog](https://www.celitech.com/blog/) ",
-  "version": "1.1.68",
-  "author": "Celitech",
   "dependencies": {
-    "axios": "^1.0.0"
-  },
-  "license": "MIT"
+    "zod": "3.22.0"
+  }
 }

package/src/http/client.ts

@@ -0,0 +1,46 @@
+import { SerializationStyle, serializePath, serializeQuery } from './serializer';
+import { HttpMethod, HttpResponse, Options, RetryOptions, SdkConfig } from './types';
+import { RequestHandlerChain } from './handlers/handler-chain';
+import { HookHandler } from './handlers/hook-handler';
+import { ResponseValidationHandler } from './handlers/response-validation-handler';
+import { RequestValidationHandler } from './handlers/request-validation-handler';
+import { CustomHook } from './hooks/custom-hook';
+import { TerminatingHandler } from './handlers/terminating-handler';
+import { RetryHandler } from './handlers/retry-handler';
+import { Request } from './transport/request';
+
+export class HttpClient {
+  private readonly requestHandlerChain = new RequestHandlerChain();
+
+  constructor(
+    private config: SdkConfig,
+    hook = new CustomHook(),
+  ) {
+    this.requestHandlerChain.addHandler(new ResponseValidationHandler());
+    this.requestHandlerChain.addHandler(new RequestValidationHandler());
+    this.requestHandlerChain.addHandler(new RetryHandler());
+    this.requestHandlerChain.addHandler(new HookHandler(hook));
+    this.requestHandlerChain.addHandler(new TerminatingHandler());
+  }
+
+  call<T>(request: Request<T>): Promise<HttpResponse<T>> {
+    return this.requestHandlerChain.callChain(request);
+  }
+
+  buildPath(
+    pathPattern: string,
+    pathArguments: Record<string, unknown>,
+    style = SerializationStyle.SIMPLE,
+    explode = false,
+  ): string {
+    return serializePath(pathPattern, pathArguments, style, explode);
+  }
+
+  setBaseUrl(url: string): void {
+    this.config.baseUrl = url;
+  }
+
+  setConfig(config: SdkConfig): void {
+    this.config = config;
+  }
+}

package/src/http/environment.ts

@@ -0,0 +1,3 @@
+export enum Environment {
+  DEFAULT = 'https://api.celitech.net/v1',
+}

package/src/http/error.ts

@@ -0,0 +1,12 @@
+import { HttpMetadata } from './types';
+
+export class HttpError extends Error {
+  public readonly error: string;
+  public readonly metadata: HttpMetadata;
+
+  constructor(metadata: HttpMetadata, error?: string) {
+    super(error);
+    this.error = metadata.statusText;
+    this.metadata = metadata;
+  }
+}

package/src/http/handlers/handler-chain.ts

@@ -0,0 +1,22 @@
+import { Request } from '../transport/request';
+import { HttpResponse, RequestHandler } from '../types';
+
+export class RequestHandlerChain {
+  private readonly handlers: RequestHandler[] = [];
+
+  addHandler(handler: RequestHandler): void {
+    if (this.handlers.length > 0) {
+      const previousHandler = this.handlers[this.handlers.length - 1];
+      previousHandler.next = handler;
+    }
+    this.handlers.push(handler);
+  }
+
+  async callChain<T>(request: Request<T>): Promise<HttpResponse<T>> {
+    if (!this.handlers.length) {
+      throw new Error('No handlers added to the chain');
+    }
+
+    return this.handlers[0].handle(request);
+  }
+}

package/src/http/handlers/hook-handler.ts

@@ -0,0 +1,47 @@
+import { Request } from '../transport/request';
+import { HttpResponse, RequestHandler } from '../types';
+import { HttpError } from '../error';
+import { Hook } from '../hooks/hook';
+
+export class HookHandler implements RequestHandler {
+  next?: RequestHandler;
+
+  constructor(private readonly hook: Hook) {}
+
+  async handle<T>(request: Request<T>): Promise<HttpResponse<T>> {
+    if (!this.next) {
+      throw new Error('No next handler set in hook handler.');
+    }
+
+    const hookParams = this.getHookParams<T>(request);
+
+    const nextRequest = await this.beforeRequest(request, hookParams);
+
+    const response = await this.next.handle(nextRequest);
+
+    if (response.metadata.status < 400) {
+      return await this.hook.afterResponse(request.toHookRequest(), response, hookParams);
+    }
+
+    const error = await this.hook.onError(request.toHookRequest(), response, hookParams);
+
+    throw new HttpError(error.metadata, error.error);
+  }
+
+  private async beforeRequest<T>(request: Request<T>, hookParams: Map<string, string>): Promise<Request<T>> {
+    const hookRequest = request.toHookRequest();
+
+    const newRequest = await this.hook.beforeRequest(hookRequest, hookParams);
+
+    request.updateFromHookRequest(newRequest);
+
+    return request;
+  }
+
+  getHookParams<T>(request: Request<T>): Map<string, string> {
+    const hookParams: Map<string, string> = new Map();
+    hookParams.set('clientId', request.config.clientId || '');
+    hookParams.set('clientSecret', request.config.clientSecret || '');
+    return hookParams;
+  }
+}

package/src/http/handlers/request-validation-handler.ts

@@ -0,0 +1,72 @@
+import { Request } from '../transport/request';
+import { ContentType, HttpResponse, RequestHandler } from '../types';
+import { HttpError } from '../error';
+
+export class RequestValidationHandler implements RequestHandler {
+  next?: RequestHandler;
+
+  async handle<T>(request: Request<T>): Promise<HttpResponse<T>> {
+    if (!this.next) {
+      throw new Error('No next handler set in ContentTypeHandler.');
+    }
+
+    if (request.requestContentType === ContentType.Json) {
+      request.body = JSON.stringify(request.requestSchema?.parse(request.body));
+    } else if (
+      request.requestContentType === ContentType.Xml ||
+      request.requestContentType === ContentType.Binary ||
+      request.requestContentType === ContentType.Text
+    ) {
+      request.body = request.body;
+    } else if (request.requestContentType === ContentType.FormUrlEncoded) {
+      request.body = this.toFormUrlEncoded(request.body);
+    } else if (request.requestContentType === ContentType.MultipartFormData) {
+      request.body = this.toFormData(request.body);
+    } else {
+      request.body = JSON.stringify(request.requestSchema?.parse(request.body));
+    }
+
+    return await this.next.handle(request);
+  }
+
+  toFormUrlEncoded(body: BodyInit | undefined): string {
+    if (body === undefined) {
+      return '';
+    }
+
+    if (typeof body === 'string') {
+      return body;
+    }
+
+    if (body instanceof URLSearchParams) {
+      return body.toString();
+    }
+
+    if (body instanceof FormData) {
+      const params = new URLSearchParams();
+      body.forEach((value, key) => {
+        params.append(key, value.toString());
+      });
+      return params.toString();
+    }
+
+    return '';
+  }
+
+  toFormData(body: Record<string, any>): FormData | undefined {
+    const formData = new FormData();
+
+    Object.keys(body).forEach((key: any) => {
+      const value: any = body[key];
+      if (Array.isArray(value)) {
+        value.forEach((v, i) => formData.append(`${key}[${i}]`, v));
+      } else if (value instanceof ArrayBuffer) {
+        formData.append(key, new Blob([value]));
+      } else {
+        formData.append(key, value);
+      }
+    });
+
+    return formData;
+  }
+}