@oapiex/sdk-kit 0.1.1

package/dist/index.js

@@ -0,0 +1,756 @@
+import "dotenv/config";
+import axios from "axios";
+import path from "path";
+import crypto from "crypto";
+
+//#region src/utilities/global.ts
+String.prototype.toKebabCase = function() {
+	return this.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+};
+String.prototype.toCamelCase = function() {
+	return this.replace(/[-_ ]+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase()).replace(/^[A-Z]/, (c) => c.toLowerCase());
+};
+String.prototype.toPascalCase = function() {
+	return this.replace(/(^\w|[-_ ]+\w)/g, (match) => match.replace(/[-_ ]+/, "").toUpperCase());
+};
+String.prototype.toSnakeCase = function() {
+	return this.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[\s-]+/g, "_").toLowerCase();
+};
+String.prototype.toSlug = function(separator = "-") {
+	return this.toSnakeCase().replace(/[/__:]+/g, "_").replace(/_/g, separator);
+};
+String.prototype.toTitleCase = function() {
+	return this.toLowerCase().replace(/(^|\s)\w/g, (match) => match.toUpperCase());
+};
+String.prototype.toCleanCase = function() {
+	return this.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").replace(/\s+/g, " ").split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ").trim().replace(/\b\w{1,3}\b/g, (match) => match.toUpperCase());
+};
+String.prototype.truncate = function(n, suffix = "…") {
+	return this.length > n ? this.slice(0, n - 1) + suffix : this.toString();
+};
+
+//#endregion
+//#region src/utilities/helpers.ts
+/**
+* Takes a value like the one prodvided in a destructuring assignment where for instance
+* a single value might have been provided as opposed to an array of values and 
+* normalizes it.
+* 
+* Examples:
+* Definition:
+* (...value: string[]) => normalizeValue(value)
+* 
+* Usage:
+* normalizeValue('singleValue') // returns ['singleValue']
+* normalizeValue('value1', 'value2') // returns ['value1', 'value2']
+* normalizeValue(['value1', 'value2']) // returns ['value1', 'value2']
+* 
+* @param value 
+* @returns 
+*/
+const normalizeValue = (value) => {
+	if (Array.isArray(value)) return value;
+	return [value];
+};
+/**
+* Builds a full url based on endpoint provided
+* 
+* @param baseUrl 
+* @param endpoint 
+* 
+* @returns 
+*/
+const buildUrl = (baseUrl, ...endpoint) => {
+	return (baseUrl + path.normalize(path.join(...normalizeValue(endpoint)))).replace(/([^:]\/)\/+/g, "$1");
+};
+
+//#endregion
+//#region src/Builder.ts
+var Builder = class {
+	static baseUrls = {
+		live: "https://api.flutterwave.com/v4/",
+		sandbox: "https://developersandbox-api.flutterwave.com/"
+	};
+	/**
+	* Flutterwave Environment
+	*/
+	static environment;
+	constructor() {}
+	/**
+	* Sets the environment for the builder
+	* 
+	* @param env
+	*/
+	static setEnvironment(env) {
+		this.environment = env;
+	}
+	/**
+	* Gets the base url based on environment
+	* 
+	* @returns 
+	*/
+	static baseUrl() {
+		if ((process.env.ENVIRONMENT || this.environment || "sandbox") === "live") return this.baseUrls.live;
+		return this.baseUrls.sandbox;
+	}
+	/**
+	* Builds a full url based on endpoint provided
+	* 
+	* @param endpoint 
+	* @returns 
+	*/
+	static buildUrl(...endpoint) {
+		return buildUrl(this.baseUrl(), ...endpoint);
+	}
+	/**
+	* Builds parameters for query or path
+	* 
+	* @param params 
+	* @param type 
+	* @returns 
+	*/
+	static buildParams(params, type = "path") {
+		let built = "";
+		if (type === "path") built = Object.values(params).join("/");
+		else {
+			const queryParams = [];
+			for (const [key, value] of Object.entries(params)) queryParams.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+			built = queryParams.join("&");
+		}
+		return built;
+	}
+	/**
+	* Assigns parameters to url {placeholders} based on type
+	* 
+	* @param url 
+	* @param params 
+	* @param type 
+	* 
+	* @returns 
+	*/
+	static assignParamsToUrl(url, params, type = "path") {
+		let builtUrl = url;
+		if (type === "path") for (const [key, value] of Object.entries(params)) {
+			builtUrl = builtUrl.replace(`{${key}}`, encodeURIComponent(String(value)));
+			builtUrl = builtUrl.replace(`:${key}`, encodeURIComponent(String(value)));
+		}
+		else {
+			if (Object.keys(params).length === 0) return builtUrl;
+			const queryString = this.buildParams(params, "query");
+			const separator = builtUrl.includes("?") ? "&" : "?";
+			builtUrl += `${separator}${queryString}`;
+		}
+		return builtUrl;
+	}
+	/**
+	* Builds the target url by assigning both path and query parameters
+	* 
+	* @param path 
+	* @param params 
+	* @param queryParams 
+	* @returns 
+	*/
+	static buildTargetUrl(path$1, params = {}, queryParams = {}) {
+		const url = this.buildUrl(path$1);
+		let builtUrl = this.assignParamsToUrl(url, params, "path");
+		builtUrl = this.assignParamsToUrl(builtUrl, queryParams, "query");
+		return builtUrl;
+	}
+	/**
+	* Encrypts specified keys in the input object and returns a new object with 
+	* encrypted values.
+	* 
+	* @param input             The input object containing the data to be encrypted.
+	* @param keysToEncrypt     The keys in the input object that should be encrypted.
+	* @param outputMapping     A mapping of input keys to output keys for the encrypted values.
+	* @returns                 A new object with the specified keys encrypted.
+	*/
+	static async encryptDetails(input, keysToEncrypt = [], outputMapping = {}) {
+		const nonce = crypto.randomBytes(12).toString("base64").slice(0, 12);
+		const encryptableKeys = keysToEncrypt.length > 0 ? keysToEncrypt : Object.keys(input);
+		const encrypted = Object.fromEntries(Object.entries(input).map(([key, value]) => {
+			if (encryptableKeys.includes(key) && typeof value === "string") return [outputMapping?.[key] || key, this.encryptAES(value, process.env.ENCRYPTION_KEY, nonce)];
+			return [key, value];
+		}));
+		for (const key of encryptableKeys) delete input[key];
+		return encrypted;
+	}
+	/**
+	* Encrypts data using AES-GCM encryption
+	* @param data 
+	* @param token 
+	* @param nonce 
+	* @returns 
+	*/
+	static async encryptAES(data, token, nonce) {
+		if (nonce.length !== 12) throw new Error("Nonce must be exactly 12 characters long");
+		const cryptoSubtle = globalThis.crypto?.subtle || crypto.webcrypto?.subtle;
+		if (!cryptoSubtle) throw new Error("Crypto API is not available in this environment.");
+		const decodedKeyBytes = Uint8Array.from(atob(token), (c) => c.charCodeAt(0));
+		const key = await cryptoSubtle.importKey("raw", decodedKeyBytes, { name: "AES-GCM" }, false, ["encrypt"]);
+		const iv = new TextEncoder().encode(nonce);
+		const encryptedData = await cryptoSubtle.encrypt({
+			name: "AES-GCM",
+			iv
+		}, key, new TextEncoder().encode(data));
+		return btoa(String.fromCharCode(...new Uint8Array(encryptedData)));
+	}
+};
+
+//#endregion
+//#region src/Exceptions/BadRequestException.ts
+var BadRequestException = class extends Error {
+	statusCode = 400;
+	type = "INVALID_REQUEST";
+	code = "400";
+	data;
+	constructor(data) {
+		super(data?.error.message ?? data?.message ?? "Bad request. The server could not understand the request due to invalid syntax.");
+		if (data?.error.code) this.type = data.error.type;
+		if (data?.error.code) this.code = data.error.code;
+		this.data = data ?? {
+			status: "failed",
+			error: {
+				type: this.type,
+				code: this.code,
+				message: this.message,
+				validation_errors: []
+			}
+		};
+		this.name = "BadRequestException";
+	}
+};
+
+//#endregion
+//#region src/Exceptions/ForbiddenRequestException.ts
+var ForbiddenRequestException = class extends Error {
+	statusCode = 403;
+	type = "FORBIDDEN";
+	code = "403";
+	data;
+	constructor(data) {
+		super(data?.error.message ?? data?.message ?? "Forbidden request. You do not have permission to access this resource.");
+		if (data?.error.code) this.type = data.error.type;
+		if (data?.error.code) this.code = data.error.code;
+		this.data = data ?? {
+			status: "failed",
+			error: {
+				type: this.type,
+				code: this.code,
+				message: this.message
+			}
+		};
+		this.name = "ForbiddenRequestException";
+	}
+};
+
+//#endregion
+//#region src/Exceptions/UnauthorizedRequestException.ts
+var UnauthorizedRequestException = class extends Error {
+	statusCode = 401;
+	type = "UNAUTHORIZED";
+	code = "401";
+	data;
+	constructor(data) {
+		super(data?.error.message ?? data?.message ?? "Forbidden request. You do not have permission to access this resource.");
+		if (data?.error.code) this.type = data.error.type;
+		if (data?.error.code) this.code = data.error.code;
+		this.data = data ?? {
+			status: "failed",
+			error: {
+				type: this.type,
+				code: this.code,
+				message: this.message
+			}
+		};
+		this.name = "UnauthorizedRequestException";
+	}
+};
+
+//#endregion
+//#region src/Exceptions/HttpException.ts
+var HttpException = class HttpException extends Error {
+	statusCode = 500;
+	parent;
+	constructor(data, statusCode, parent) {
+		super(data.message);
+		this.data = data;
+		this.name = "HttpException";
+		this.parent = parent;
+		if (statusCode) this.statusCode = statusCode;
+	}
+	/**
+	* Create an exception from status code
+	* 
+	* @param code 
+	* @param data 
+	*/
+	static fromCode(code, data, parent) {
+		switch (code) {
+			case 400: return new BadRequestException(data);
+			case 401: return new UnauthorizedRequestException(data);
+			case 403: return new ForbiddenRequestException(data);
+			default: return new HttpException(data, code, parent);
+		}
+	}
+};
+
+//#endregion
+//#region src/Http.ts
+var Http = class Http {
+	/**
+	* Bearer token
+	*/
+	static bearerToken;
+	/**
+	* Debug level
+	*/
+	static debugLevel = 0;
+	static apiInstance;
+	/**
+	* Creates an instance of Http.
+	* 
+	* @param method 
+	* @param url 
+	* @param headers 
+	* @param body 
+	*/
+	constructor(headers = {}, body) {
+		this.headers = headers;
+		this.body = body;
+	}
+	/**
+	* Set the debug level
+	* 
+	* @param debug 
+	*/
+	static setDebugLevel(level = 0) {
+		this.debugLevel = level ?? 0;
+	}
+	/**
+	* Set the API instance
+	* 
+	* @param api 
+	*/
+	static setApiInstance(api) {
+		this.apiInstance = api;
+	}
+	/**
+	* Set the bearer token
+	* 
+	* @param token 
+	*/
+	static setBearerToken(token) {
+		this.bearerToken = token;
+	}
+	setDefaultHeaders(defaults) {
+		this.headers = {
+			...defaults,
+			...this.headers
+		};
+		if (Http.bearerToken) this.headers.Authorization = `Bearer ${Http.bearerToken}`;
+	}
+	getHeaders() {
+		return this.headers;
+	}
+	getBody() {
+		return this.body;
+	}
+	axiosApi() {
+		this.setDefaultHeaders({
+			"Accept": "application/json",
+			"Content-Type": "application/json"
+		});
+		const instance = axios.create({
+			baseURL: Builder.baseUrl(),
+			headers: this.getHeaders()
+		});
+		if (Http.debugLevel > 0) {
+			instance.interceptors.request.use((request) => {
+				console.log("Starting Request", JSON.stringify({
+					url: request.url,
+					method: request.method,
+					headers: Http.debugLevel < 3 ? Object.fromEntries(Object.entries(request.headers || {}).filter(([key]) => key.toLowerCase() !== "authorization")) : request.headers,
+					params: request.params,
+					data: request.data
+				}, null, 2));
+				return request;
+			}, (error) => {
+				console.log("Request Error:", JSON.stringify(error, null, 2));
+				return Promise.reject(error);
+			});
+			instance.interceptors.response.use((response) => {
+				console.log("Response:", JSON.stringify({
+					status: response.status,
+					data: Http.debugLevel < 3 ? Object.fromEntries(Object.entries(response.data || {}).filter(([key]) => key.toLowerCase() !== "access_token")) : response.data
+				}, null, 2));
+				return response;
+			}, (error) => {
+				console.log("Response Error:", JSON.stringify({
+					status: error.response?.status,
+					data: Object.fromEntries(Object.entries(error.response?.data || {}).filter(([key]) => key.toLowerCase() !== "access_token"))
+				}, null, 2));
+				return Promise.reject(error);
+			});
+		}
+		return instance;
+	}
+	/**
+	* Makes a GET request
+	* 
+	* @param url 
+	* @param headers 
+	* @param params 
+	* @returns 
+	*/
+	static async get(url, params, headers = {}) {
+		return this.send(url, "GET", void 0, headers, params);
+	}
+	/**
+	* 
+	* 
+	* @param url 
+	* @param headers 
+	* @param params 
+	* @returns 
+	*/
+	static async send(url, method, body, headers = {}, params) {
+		try {
+			const { data } = await new Http(headers).axiosApi()({
+				url,
+				method,
+				data: body,
+				params
+			});
+			return {
+				success: true,
+				message: data.message || "Request successful",
+				data: data.data ?? data,
+				meta: data.meta
+			};
+		} catch (e) {
+			const error = e.response?.data ?? {};
+			throw this.exception(e.response?.status ?? 500, error || e, e);
+		}
+	}
+	/**
+	* Create an HttpException from status and error
+	* 
+	* @param status 
+	* @param error 
+	* @returns 
+	*/
+	static exception(status, error, originalError) {
+		const exception = HttpException.fromCode(status, {
+			success: false,
+			message: `Request failed: ${error.error?.message || "An error occurred"}`,
+			status: "failed",
+			data: void 0,
+			meta: {},
+			error: {
+				type: ((typeof error.error === "string" ? error.error : error.error?.type) ?? "UNKNOWN_ERROR").toUpperCase(),
+				code: error.error?.code ?? "000000",
+				message: error.error?.message ?? error.error_description ?? error.message,
+				validation_errors: error.error?.validation_errors ?? []
+			}
+		}, originalError);
+		if (this.apiInstance) this.apiInstance.setLastException(exception);
+		return exception;
+	}
+};
+
+//#endregion
+//#region src/Apis/BaseApi.ts
+var BaseApi = class {
+	/**
+	* Flutterwave instance
+	*/
+	#core;
+	lastException;
+	/**
+	* Create a BaseApi instance
+	* 
+	* @param coreInstance Core instance
+	*/
+	constructor(coreInstance) {
+		this.#core = coreInstance;
+	}
+	/**
+	* Get the owning core instance for SDK-specific API bootstrapping.
+	*/
+	get core() {
+		return this.#core;
+	}
+	/**
+	* Hook for SDK-specific API registration.
+	*/
+	boot() {}
+	/**
+	* Set access validator function
+	* 
+	* @param validator 
+	*/
+	setAccessValidator(validator) {
+		this.#core.setAccessValidator(validator);
+	}
+	/**
+	* Get the last exception
+	* 
+	* @returns 
+	*/
+	getLastException() {
+		return this.lastException;
+	}
+	/**
+	* Set the last exception
+	* 
+	* @param exception 
+	*/
+	setLastException(exception) {
+		this.lastException = exception;
+	}
+	/**
+	* Initialize BaseApi and its sub-APIs
+	* 
+	* @param coreInstance Core instance
+	* @returns 
+	*/
+	static initialize(coreInstance) {
+		Http.setDebugLevel(coreInstance.debugLevel);
+		const baseApi = new this(coreInstance);
+		Http.setApiInstance(baseApi);
+		baseApi.boot();
+		return baseApi;
+	}
+};
+
+//#endregion
+//#region src/RuntimeSdk.ts
+const createRuntimeApi = (core, bundle) => {
+	const api = BaseApi.initialize(core);
+	for (const group of bundle.manifest.groups) {
+		const namespace = {};
+		for (const operation of group.operations) namespace[operation.methodName] = async (...args) => {
+			await core.validateAccess();
+			const [pathParams, queryParams, body, headers] = normalizeRuntimeArguments(operation, args);
+			validateRequiredArguments(operation.pathParams, pathParams, "path");
+			validateRequiredArguments(operation.queryParams, queryParams, "query");
+			validateRequiredArguments(operation.headerParams, headers, "header");
+			if (operation.hasBody && operation.bodyRequired && body == null) throw new Error(`Missing required request body for ${operation.method} ${operation.path}`);
+			const { data } = await Http.send(core.builder.buildTargetUrl(operation.path, pathParams, queryParams), operation.method, body ?? {}, headers);
+			return data;
+		};
+		api[group.propertyName] = namespace;
+	}
+	return api;
+};
+const createSdk = (bundle, options) => {
+	return new Core(options).useDocument(bundle);
+};
+const normalizeRuntimeArguments = (operation, args) => {
+	let cursor = 0;
+	return [
+		operation.pathParams.length > 0 ? toRecord(args[cursor++]) : {},
+		operation.queryParams.length > 0 ? toRecord(args[cursor++]) : {},
+		operation.hasBody ? args[cursor++] : void 0,
+		operation.headerParams.length > 0 ? toRecord(args[cursor++]) : {}
+	];
+};
+const validateRequiredArguments = (parameters, values, location) => {
+	for (const parameter of parameters) {
+		if (!parameter.required) continue;
+		if (values[parameter.name] === void 0 && values[parameter.accessor] === void 0) throw new Error(`Missing required ${location} parameter: ${parameter.name}`);
+	}
+};
+const toRecord = (value) => {
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) return value;
+	return {};
+};
+
+//#endregion
+//#region src/Core.ts
+var Core = class {
+	static apiClass = BaseApi;
+	debugLevel = 0;
+	/**
+	* Client ID
+	*/
+	clientId;
+	/**
+	* Client Secret
+	*/
+	clientSecret;
+	/**
+	* Flutterwave Environment
+	*/
+	environment = "live";
+	accessValidator;
+	/**
+	* API Instance
+	*/
+	api;
+	/**
+	* Builder Instance
+	*/
+	builder = Builder;
+	constructor(clientId, clientSecret, encryptionKey, env) {
+		if (typeof clientId === "object") {
+			this.clientId = clientId.clientId;
+			this.clientSecret = clientId.clientSecret;
+			this.environment = clientId.environment ?? "live";
+		} else {
+			this.clientId = clientId ?? process.env.CLIENT_ID ?? "";
+			this.clientSecret = clientSecret ?? process.env.CLIENT_SECRET ?? "";
+			this.environment = env ?? process.env.ENVIRONMENT ?? "live";
+		}
+		if (!this.clientId || !this.clientSecret) throw new Error("Client ID and Client Secret are required to initialize Flutterwave instance");
+		this.builder.setEnvironment(this.environment);
+		this.api = this.createApi();
+	}
+	createApi() {
+		return (this.constructor.apiClass ?? BaseApi).initialize(this);
+	}
+	init(clientId, clientSecret, encryptionKey, env) {
+		return new this.constructor(clientId, clientSecret, encryptionKey, env);
+	}
+	/**
+	* Set the debug level
+	* 
+	* @param level 
+	* @returns 
+	*/
+	debug(level = 0) {
+		this.debugLevel = level;
+		Http.setDebugLevel(level);
+		return this;
+	}
+	/**
+	* Get the current environment
+	* 
+	* @returns 
+	*/
+	getEnvironment() {
+		return this.environment;
+	}
+	/**
+	* Set access validator function
+	* 
+	* @param validator Function to validate access
+	*/
+	setAccessValidator(validator) {
+		this.accessValidator = validator;
+	}
+	/**
+	* Validates access using the provided access validator function
+	* 
+	* @throws Error if validation fails
+	*/
+	async validateAccess() {
+		const check = this.accessValidator ? await this.accessValidator(this) : true;
+		if (check !== true) throw new Error(typeof check === "string" ? check : "Access validation failed");
+	}
+	/**
+	* Use a manifest bundle to create the API instance
+	* 
+	* @param bundle 
+	* @returns 
+	*/
+	useDocument(bundle) {
+		this.api = createRuntimeApi(this, bundle);
+		return this;
+	}
+	/**
+	* Use a manifest bundle to create the API instance (alias for useDocument).
+	* 
+	* @param bundle 
+	* @returns 
+	*/
+	useSdk(bundle) {
+		return this.useDocument(bundle);
+	}
+};
+
+//#endregion
+//#region src/utilities/Manager.ts
+const defaultConfig = {
+	environment: "sandbox",
+	urls: {
+		live: "",
+		sandbox: ""
+	}
+};
+let globalConfig = defaultConfig;
+const defineConfig = (config) => {
+	const userConfig = {
+		...defaultConfig,
+		...config,
+		urls: {
+			...defaultConfig.urls,
+			...config.urls
+		}
+	};
+	globalConfig = userConfig;
+	return userConfig;
+};
+
+//#endregion
+//#region src/utilities/WebhookValidator.ts
+var WebhookValidator = class {
+	algorithm = "sha256";
+	encoding = "base64";
+	/**
+	* @param secretHash 
+	* @param options 
+	*/
+	constructor(secretHash, options) {
+		this.secretHash = secretHash;
+		this.algorithm = options?.hashAlgorithm || "sha256";
+		this.encoding = options?.encoding || "base64";
+		if (!this.secretHash || this.secretHash.length === 0) this.secretHash = process.env.SECRET_HASH;
+	}
+	/**
+	* Validate webhook signature
+	* @param rawBody - Raw request body as string
+	* @param signature - Signature from request header
+	* @returns {boolean} - True if signature is valid
+	*/
+	validate(rawBody, signature) {
+		if (!this.secretHash) throw new Error("Secret hash is required for validation");
+		return crypto.createHmac(this.algorithm, this.secretHash).update(rawBody).digest(this.encoding) === signature;
+	}
+	/**
+	* Generate signature for testing/verification
+	* @param rawBody - Raw request body as string
+	* @returns {string} - Generated signature
+	*/
+	generateSignature(rawBody) {
+		if (!this.secretHash) throw new Error("Secret hash is required to generate signature");
+		return crypto.createHmac(this.algorithm, this.secretHash).update(rawBody).digest(this.encoding);
+	}
+	/**
+	* Async version of validate (for large payloads)
+	* 
+	* @param rawBody 
+	* @param signature 
+	* @returns {Promise<boolean>}
+	*/
+	validateAsync(rawBody, signature) {
+		if (!this.secretHash) throw new Error("Secret hash is required for validation");
+		const hmac = crypto.createHmac(this.algorithm, this.secretHash);
+		hmac.update(rawBody);
+		return hmac.digest(this.encoding) === signature;
+	}
+	/**
+	* Get current configuration
+	*/
+	getConfig() {
+		return {
+			algorithm: this.algorithm,
+			encoding: this.encoding,
+			secretHashLength: this.secretHash?.length
+		};
+	}
+};
+
+//#endregion
+export { BadRequestException, BaseApi, Builder, Core, ForbiddenRequestException, Http, HttpException, UnauthorizedRequestException, WebhookValidator, buildUrl, createRuntimeApi, createSdk, defaultConfig, defineConfig, globalConfig, normalizeValue };