nomkit 0.0.0

package/dist/client/index.d.ts

@@ -0,0 +1,13 @@
+//#region client/index.d.ts
+interface NomKitClientOptions {
+  baseURL?: string;
+}
+declare function createNomKitClient<TServer extends Record<string, any>>(options?: NomKitClientOptions): InferClientAPI<ExtractAPI<TServer>>;
+type AnyFn = (...args: any[]) => any;
+type AwaitedReturn<T extends AnyFn> = Awaited<ReturnType<T>>;
+type ExtractAPI<T> = T extends {
+  api: infer TApi;
+} ? TApi : never;
+type InferClientAPI<T> = { [K in keyof T]: T[K] extends AnyFn ? (...args: Parameters<T[K]>) => Promise<AwaitedReturn<T[K]>> : T[K] extends object ? InferClientAPI<T[K]> : never };
+//#endregion
+export { NomKitClientOptions, createNomKitClient };

package/dist/client/index.js

@@ -0,0 +1,34 @@
+import { createFetch } from "../node_modules/.pnpm/@better-fetch_fetch@1.3.1/node_modules/@better-fetch/fetch/dist/index.js";
+//#region client/index.ts
+function createNomKitClient(options) {
+	const baseUrl = (options?.baseURL ?? "/nomkit").replace(/\/+$/, "");
+	let apiUrl;
+	if (baseUrl === "") apiUrl = "/nomkit";
+	else if (baseUrl.endsWith("/nomkit")) apiUrl = baseUrl;
+	else apiUrl = `${baseUrl}/nomkit`;
+	const supportsCredentials = typeof globalThis.Request !== "undefined" && "credentials" in Request.prototype;
+	const $fetch = createFetch({
+		baseURL: apiUrl,
+		throw: true,
+		...supportsCredentials ? { credentials: "include" } : {}
+	});
+	const createProxy = (path = []) => new Proxy(() => {}, {
+		get(_, prop) {
+			if (typeof prop !== "string") return;
+			if (prop === "then" || prop === "catch" || prop === "finally") return;
+			return createProxy([...path, prop]);
+		},
+		async apply(_, __, args) {
+			const routePath = "/" + path.map((segment) => segment.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)).join("/");
+			const body = args[0] ?? {};
+			console.log("Nomkit client: ", routePath);
+			return $fetch(routePath, {
+				method: "POST",
+				body
+			});
+		}
+	});
+	return createProxy();
+}
+//#endregion
+export { createNomKitClient };

package/dist/core/nomba_api/banks.d.ts

@@ -0,0 +1,14 @@
+//#region core/nomba_api/banks.d.ts
+interface GetBanksResponse {
+  code: string;
+  description: string;
+  data: {
+    results: Result[];
+  };
+}
+type Result = {
+  code: string;
+  name: string;
+};
+//#endregion
+export { GetBanksResponse, Result };

package/dist/core/nomba_api/charge-tokenized-card.d.ts

@@ -0,0 +1,33 @@
+//#region core/nomba_api/charge-tokenized-card.d.ts
+interface TokenizedCardChargeRequest {
+  tokenKey: string;
+  order?: TokenizedCardOrder;
+}
+interface TokenizedCardOrder {
+  orderReference?: string;
+  customerId?: string;
+  callbackUrl?: string;
+  customerEmail?: string;
+  amount?: string;
+  currency?: string;
+  accountId?: string;
+  splitRequest?: SplitRequest;
+}
+interface SplitRequest {
+  splitType: "PERCENTAGE" | "AMOUNT";
+  splitList: SplitRecipient[];
+}
+interface SplitRecipient {
+  accountId: string;
+  value: string;
+}
+interface TokenizedCardChargeResponse {
+  "code": "00";
+  "description": string;
+  "data": {
+    "status": string;
+    "message": string;
+  };
+}
+//#endregion
+export { SplitRecipient, SplitRequest, TokenizedCardChargeRequest, TokenizedCardChargeResponse, TokenizedCardOrder };

package/dist/core/nomba_api/checkout.d.ts

@@ -0,0 +1,44 @@
+//#region core/nomba_api/checkout.d.ts
+interface CreateCheckoutRequest {
+  order: Checkout;
+  /**
+   * Note: we require this for subscriptions to be able to headlessly
+   * charge their card without triggering another checkout flow
+   * @default true
+   */
+  tokenizeCard: boolean;
+}
+type Metadata = "nomkit.order_reference" | "nomkit.subscription.id" | "nomkit.subscription.customer_id" | "nomkit.subscription.customer_email" | "nomkit.subscription.internalPlanId";
+type NonRequiredMetadata = "nomkit.subscription.kind" | "nomkit.subscription.previous_subscription_id" | "nomkit.subscription.previous_internalPlanId" | "nomkit.subscription.prorated_credit_applied";
+type CheckoutMetadata = Record<Metadata, string> & Partial<Record<NonRequiredMetadata, string>>;
+interface Checkout {
+  amount: string;
+  currency: string;
+  orderReference?: string;
+  callbackUrl?: string;
+  customerEmail?: string;
+  customerId?: string;
+  accountId?: string;
+  allowedPaymentMethods?: PaymentMethod[];
+  splitRequest?: SplitRequest;
+  orderMetaData?: Record<string, string>;
+}
+interface SplitRequest {
+  splitType: "PERCENTAGE" | "AMOUNT";
+  splitList: SplitRecipient[];
+}
+interface SplitRecipient {
+  accountId: string;
+  value: string;
+}
+type PaymentMethod = "Card" | "Transfer" | "Nomba QR" | "USSD" | "Buy Now Pay Later" | "MOMO" | "Intl Card" | "Apple Pay";
+interface CreateCheckoutResponse {
+  code: string;
+  description: string;
+  data: {
+    checkoutLink: string;
+    orderReference: string;
+  };
+}
+//#endregion
+export { Checkout, CheckoutMetadata, CreateCheckoutRequest, CreateCheckoutResponse, Metadata, NonRequiredMetadata, PaymentMethod, SplitRecipient, SplitRequest };

package/dist/core/nomba_api/get_checkout.d.ts

@@ -0,0 +1,57 @@
+import { CheckoutMetadata } from "./checkout.js";
+
+//#region core/nomba_api/get_checkout.d.ts
+interface FetchCheckoutResponse {
+  code: string;
+  description: string;
+  data: {
+    success: boolean;
+    message: string;
+    order: CheckoutOrder;
+    transactionDetails: TransactionDetails;
+    transferDetails: TransferDetails;
+    /**
+     * Will be null if the user paid by Bank Transfer
+     */
+    cardDetails: CardDetails | null;
+  };
+}
+interface CheckoutOrder {
+  orderId: string;
+  orderReference: string;
+  customerId: string;
+  accountId: string;
+  callbackUrl: string;
+  customerEmail: string;
+  amount: string;
+  currency: string;
+  orderMetaData: CheckoutMetadata;
+}
+interface TransactionDetails {
+  transactionDate: string;
+  paymentReference: string;
+  paymentVendorReference: string;
+  /**
+   * Will be false if the user paid by transfer
+   */
+  tokenizedCardPayment: boolean;
+  statusCode: string;
+}
+interface TransferDetails {
+  sessionId: string;
+  beneficiaryAccountName: string;
+  beneficiaryAccountNumber: string;
+  originatorAccountName: string;
+  originatorAccountNumber: string;
+  narration: string;
+  destinationInstitutionCode: string;
+  paymentReference: string;
+}
+interface CardDetails {
+  cardPan: string;
+  cardType: string;
+  cardCurrency: string;
+  cardBank: string;
+}
+//#endregion
+export { CardDetails, CheckoutOrder, FetchCheckoutResponse, TransactionDetails, TransferDetails };

package/dist/core/nomba_api/index.d.ts

@@ -0,0 +1,313 @@
+import { CheckoutMetadata } from "./checkout.js";
+import { CardDetails, CheckoutOrder, TransactionDetails, TransferDetails } from "./get_checkout.js";
+import { CardDataList } from "./list-tokenized-cards.js";
+
+//#region core/nomba_api/index.d.ts
+type Environment = "production" | "sandbox";
+declare class NombaAPI {
+  private environment;
+  private accountId;
+  private clientId;
+  private clientSecret;
+  private endpoint;
+  private webhookSecret;
+  private tokenManager;
+  constructor(args: {
+    accountId: string;
+    clientId: string;
+    clientSecret: string;
+    webhookSecret: string;
+    environment?: Environment;
+  });
+  init(): Promise<void>;
+  checkOut(args: {
+    successURL: string;
+    customerEmail: string;
+    amount: string;
+    reference: string;
+    metadata: CheckoutMetadata;
+  }): Promise<{
+    checkoutLink: string;
+    orderReference: string;
+  }>;
+  getCheckOut(args: {
+    reference?: string;
+    orderId?: string;
+  }): Promise<{
+    success: boolean;
+    message: string;
+    order: CheckoutOrder;
+    transactionDetails: TransactionDetails;
+    transferDetails: TransferDetails;
+    cardDetails: CardDetails | null;
+  }>;
+  chargeCard(args: {
+    orderReference: string;
+    amount: string;
+    tokenKey: string;
+    customerEmail: string;
+    successURL: string;
+  }): Promise<{
+    status: string;
+    message: string;
+  }>;
+  listCards(args: {
+    customerEmail: string;
+  }): Promise<{
+    nextPage: number;
+    tokenizedCardDataList: CardDataList[];
+  }>;
+  getBanks(): Promise<readonly [{
+    readonly name: "Access Bank";
+    readonly code: "044";
+  }, {
+    readonly name: "Addosser Microfinance Bank";
+    readonly code: "090160";
+  }, {
+    readonly name: "AB Microfinance Bank";
+    readonly code: "090270";
+  }, {
+    readonly name: "Citibank Nigeria Limited";
+    readonly code: "023";
+  }, {
+    readonly name: "Diamond Bank";
+    readonly code: "063";
+  }, {
+    readonly name: "Ecobank Nigeria";
+    readonly code: "050";
+  }, {
+    readonly name: "Enterprise Bank";
+    readonly code: "084";
+  }, {
+    readonly name: "eTranzact";
+    readonly code: "306";
+  }, {
+    readonly name: "Fidelity Bank";
+    readonly code: "070";
+  }, {
+    readonly name: "First Bank of Nigeria";
+    readonly code: "011";
+  }, {
+    readonly name: "First City Monument Bank";
+    readonly code: "214";
+  }, {
+    readonly name: "First Monnie Wallet";
+    readonly code: "309";
+  }, {
+    readonly name: "Globus Bank";
+    readonly code: "000027";
+  }, {
+    readonly name: "Guaranty Trust Bank";
+    readonly code: "058";
+  }, {
+    readonly name: "Heritage Bank";
+    readonly code: "030";
+  }, {
+    readonly name: "Hackman Microfinance Bank";
+    readonly code: "090147";
+  }, {
+    readonly name: "Ibile Microfinance Bank";
+    readonly code: "090118";
+  }, {
+    readonly name: "Jaiz Bank";
+    readonly code: "301";
+  }, {
+    readonly name: "Key Stone Bank";
+    readonly code: "082";
+  }, {
+    readonly name: "Kuda Microfinance Bank";
+    readonly code: "090267";
+  }, {
+    readonly name: "Paycom (Opay)";
+    readonly code: "305";
+  }, {
+    readonly name: "Paga";
+    readonly code: "327";
+  }, {
+    readonly name: "PayAttitude Online";
+    readonly code: "329";
+  }, {
+    readonly name: "Providus Bank";
+    readonly code: "101";
+  }, {
+    readonly name: "RenMoney Microfinance Bank";
+    readonly code: "090198";
+  }, {
+    readonly name: "Royal Exchange Microfinance Bank";
+    readonly code: "090138";
+  }, {
+    readonly name: "Polaris Bank";
+    readonly code: "076";
+  }, {
+    readonly name: "Stanbic IBTC Bank";
+    readonly code: "039";
+  }, {
+    readonly name: "Standard Chartered Bank Nigeria";
+    readonly code: "068";
+  }, {
+    readonly name: "Sterling Bank Plc";
+    readonly code: "232";
+  }, {
+    readonly name: "SunTrust Bank Nigeria Limited";
+    readonly code: "100";
+  }, {
+    readonly name: "Taj Bank";
+    readonly code: "000026";
+  }, {
+    readonly name: "Titan Trust Bank";
+    readonly code: "000025";
+  }, {
+    readonly name: "Union Bank of Nigeria";
+    readonly code: "032";
+  }, {
+    readonly name: "United Bank for Africa";
+    readonly code: "033";
+  }, {
+    readonly name: "Unity Bank";
+    readonly code: "215";
+  }, {
+    readonly name: "Wema Bank";
+    readonly code: "035";
+  }, {
+    readonly name: "Zenith Bank";
+    readonly code: "057";
+  }, {
+    readonly name: "Parallex MF Bank";
+    readonly code: "526";
+  }, {
+    readonly name: "Nirsal MFB";
+    readonly code: "090194";
+  }, {
+    readonly name: "Moniepoint Microfinance Bank";
+    readonly code: "090405";
+  }, {
+    readonly name: "VFD Microfinance Bank Limited";
+    readonly code: "566";
+  }, {
+    readonly name: "Palmpay";
+    readonly code: "100033";
+  }, {
+    readonly name: "Good News Microfinance Bank";
+    readonly code: "090495";
+  }, {
+    readonly name: "Lapo Microfinance Bank";
+    readonly code: "090177";
+  }, {
+    readonly name: "Accion Microfinance Bank";
+    readonly code: "090134";
+  }, {
+    readonly name: "Hala Credit Microfinance Bank";
+    readonly code: "090291";
+  }, {
+    readonly name: "Page Financials";
+    readonly code: "070008";
+  }, {
+    readonly name: "Pristine Divitis Microfinance Bank";
+    readonly code: "090499";
+  }, {
+    readonly name: "Mainstreet Microfinance Bank";
+    readonly code: "090171";
+  }, {
+    readonly name: "Shalom Microfinance Bank";
+    readonly code: "090502";
+  }, {
+    readonly name: "Projetcs Microfinance Bank";
+    readonly code: "090503";
+  }, {
+    readonly name: "Zikora Microfinance Bank";
+    readonly code: "090504";
+  }, {
+    readonly name: "Enrich Microfinance Bank";
+    readonly code: "090539";
+  }, {
+    readonly name: "Ampersand Microfinance Bank";
+    readonly code: "090529";
+  }, {
+    readonly name: "Randalpha Microfinance Bank";
+    readonly code: "090496";
+  }, {
+    readonly name: "OAU Microfinance Bank";
+    readonly code: "090345";
+  }, {
+    readonly name: "Hope Payment Service Bank";
+    readonly code: "120002";
+  }, {
+    readonly name: "Fairmoney Microfinance Bank";
+    readonly code: "090551";
+  }, {
+    readonly name: "Access Yellow";
+    readonly code: "100052";
+  }, {
+    readonly name: "Contec Global Infotech Limited";
+    readonly code: "100032";
+  }, {
+    readonly name: "Lotus Bank";
+    readonly code: "000029";
+  }, {
+    readonly name: "Mkobo Microfinance Bank";
+    readonly code: "090455";
+  }, {
+    readonly name: "Momo Payment Service Bank";
+    readonly code: "120003";
+  }, {
+    readonly name: "Letshego Microfinance Bank";
+    readonly code: "090420";
+  }, {
+    readonly name: "Carbon";
+    readonly code: "100026";
+  }, {
+    readonly name: "Sparkle";
+    readonly code: "090325";
+  }, {
+    readonly name: "Kredi Microfinance Bank";
+    readonly code: "090380";
+  }, {
+    readonly name: "Renmoney Microfinance Bank";
+    readonly code: "090198";
+  }, {
+    readonly name: "Ekondo Microfinance Bank";
+    readonly code: "090097";
+  }, {
+    readonly name: "Premium Trust Bank";
+    readonly code: "000031";
+  }, {
+    readonly name: "Auchi Microfinance Bank";
+    readonly code: "090264";
+  }, {
+    readonly name: "AMJU Microfinance Bank";
+    readonly code: "090180";
+  }, {
+    readonly name: "Kenechukwu Microfinance Bank";
+    readonly code: "090602";
+  }, {
+    readonly name: "UNN Microfinance Bank";
+    readonly code: "090251";
+  }, {
+    readonly name: "AMUCHA Microfinance Bank";
+    readonly code: "090645";
+  }, {
+    readonly name: "9PSB";
+    readonly code: "120001";
+  }]>;
+  getClientSecret(): string;
+  getWebhookSecret(): string;
+  private getHeaders;
+}
+declare class BillingError extends Error {
+  private response;
+  constructor(message: string, args?: {
+    response: any;
+  });
+  getResponse<T>(): T;
+}
+declare function hashPayload({
+  payload,
+  secretKey,
+  timestamp
+}: {
+  payload: any;
+  secretKey: string;
+  timestamp: string | number;
+}): Promise<string>;
+//#endregion
+export { BillingError, NombaAPI, hashPayload };

package/dist/core/nomba_api/index.js

@@ -0,0 +1,179 @@
+import { banks } from "./lib/utils.js";
+import { TokenManager } from "./token-manager/index.js";
+//#region core/nomba_api/index.ts
+const BASEURL = {
+	production: "https://api.nomba.com",
+	sandbox: "https://sandbox.nomba.com"
+};
+var NombaAPI = class {
+	environment = "production";
+	accountId;
+	clientId;
+	clientSecret;
+	endpoint;
+	webhookSecret;
+	tokenManager;
+	constructor(args) {
+		this.accountId = args.accountId;
+		this.clientId = args.clientId;
+		this.clientSecret = args.clientSecret;
+		this.webhookSecret = args.webhookSecret;
+		this.environment = args.environment ?? "production";
+		const baseUrl = BASEURL?.[this.environment] ?? BASEURL.production;
+		this.endpoint = baseUrl;
+		if (!this.clientId) throw new Error("Nomba clientId is required");
+		if (!this.clientSecret) throw new Error("Nomba clientSecret is required");
+		this.tokenManager = new TokenManager({
+			baseUrl,
+			accountId: args.accountId,
+			clientId: args.clientId,
+			clientSecret: args.clientSecret
+		});
+	}
+	async init() {
+		await this.tokenManager.initialize();
+	}
+	async checkOut(args) {
+		const request = {
+			order: {
+				amount: args.amount,
+				currency: "NGN",
+				callbackUrl: args.successURL,
+				customerEmail: args.customerEmail,
+				orderReference: args.reference,
+				allowedPaymentMethods: ["Card", "Transfer"],
+				orderMetaData: args.metadata
+			},
+			tokenizeCard: true
+		};
+		const req = await fetch(`${this.endpoint}/v1/checkout/order`, {
+			method: "POST",
+			body: JSON.stringify(request),
+			headers: await this.getHeaders()
+		});
+		if (!req.ok) throw new Error("Failed to initialize checkout");
+		if (req.status !== 200) throw new Error("Failed to initialize checkout, bad request");
+		const response = await req.json();
+		if (isInvalid(response)) throw new BillingError("Checkout error: unable to checkout", { response });
+		return response.data;
+	}
+	async getCheckOut(args) {
+		if (!args.reference && !args.orderId) throw new Error("Either reference or orderId must be provided");
+		const url = new URL(`${this.endpoint}/v1/checkout/transaction`);
+		if (args.orderId) {
+			url.searchParams.set("id", args.orderId);
+			url.searchParams.set("idType", "ORDER_ID");
+		} else if (args.reference) {
+			url.searchParams.set("id", args.reference);
+			url.searchParams.set("idType", "ORDER_REFERENCE");
+		}
+		const req = await fetch(url, {
+			method: "GET",
+			headers: await this.getHeaders()
+		});
+		if (!req.ok) throw new Error("Failed to fetch checkout transaction");
+		if (req.status !== 200) throw new Error(`Failed to fetch checkout transaction, status ${req.status}`);
+		const response = await req.json();
+		if (isInvalid(response)) throw new BillingError("Checkout error: unable to fetch transaction", { response });
+		return response.data;
+	}
+	async chargeCard(args) {
+		const request = {
+			tokenKey: args.tokenKey,
+			order: {
+				orderReference: args.orderReference,
+				amount: args.amount,
+				currency: "NGN",
+				customerEmail: args.customerEmail,
+				callbackUrl: args.successURL
+			}
+		};
+		const req = await fetch(`${this.endpoint}/v1/checkout/tokenized-card-payment`, {
+			method: "POST",
+			body: JSON.stringify(request),
+			headers: await this.getHeaders()
+		});
+		if (!req.ok) throw new BillingError("API error: unable to charge card bad request");
+		if (req.status !== 200) throw new BillingError("API error: unable to charge card response error");
+		const response = await req.json();
+		if (isInvalid(response)) throw new BillingError("Charge error: unable to charge card", { response });
+		return response.data;
+	}
+	async listCards(args) {
+		const request = {
+			customerEmail: args.customerEmail,
+			page: 0
+		};
+		const req = await fetch(`${this.endpoint}/v1/checkout/tokenized-card-data`, {
+			method: "GET",
+			body: JSON.stringify(request),
+			headers: await this.getHeaders()
+		});
+		if (!req.ok) throw new Error("Failed to charge card");
+		if (req.status !== 200) throw new Error("Failed to charge card, bad request");
+		const response = await req.json();
+		if (isInvalid(response)) throw new BillingError("Card error: unable to list cards", { response });
+		return response.data;
+	}
+	async getBanks() {
+		return banks;
+	}
+	getClientSecret() {
+		return this.clientSecret;
+	}
+	getWebhookSecret() {
+		return this.webhookSecret;
+	}
+	async getHeaders() {
+		const token = await this.tokenManager.getAccessToken();
+		return new Headers({
+			"Content-Type": "application/json",
+			accountId: this.accountId,
+			Authorization: `Bearer ${token}`
+		});
+	}
+};
+const errors = {
+	SUCCESS: "00",
+	GENERIC_ERROR: "01",
+	VALIDATION_ERROR: "02",
+	TRANSACTION_DENIED: "05",
+	ERROR_NO_RETRY: "06"
+};
+const isInvalid = (response) => {
+	return !("data" in response) || "code" in response && response.code !== errors.SUCCESS;
+};
+var BillingError = class extends Error {
+	response;
+	constructor(message, args) {
+		super(message);
+		this.response = args?.response;
+	}
+	getResponse() {
+		return this.response;
+	}
+};
+async function hashPayload({ payload, secretKey, timestamp }) {
+	const data = payload.data || {};
+	const merchant = data.merchant || {};
+	const transaction = data.transaction || {};
+	const eventType = payload.event_type || "";
+	const requestId = payload.requestId || "";
+	const userId = merchant.userId || "";
+	const walletId = merchant.walletId || "";
+	const transactionId = transaction.transactionId || "";
+	const transactionType = transaction.type || "";
+	const transactionTime = transaction.time || "";
+	let transactionResponseCode = transaction.responseCode || "";
+	if (transactionResponseCode === "null") transactionResponseCode = "";
+	const hashingPayload = `${eventType}:${requestId}:${userId}:${walletId}:${transactionId}:${transactionType}:${transactionTime}:${transactionResponseCode}:${timestamp}`;
+	const encoder = new TextEncoder();
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secretKey), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(hashingPayload));
+	return Buffer.from(signature).toString("base64");
+}
+//#endregion
+export { BillingError, NombaAPI, hashPayload };