epic-collection-gateway-sdk 1.0.3 → 1.0.5

package/README.md

@@ -1,15 +1,12 @@
 # Epic Collection Gateway SDK
 
-A lightweight TypeScript/JavaScript SDK for integrating **Epic Collections Web Checkout** into your web storefront. It handles authentication, redirect-flow initiation, and return-URL parsing — no backend proxy required on your end.
+A lightweight TypeScript/JavaScript SDK for integrating **Epic Collections Web Checkout** into your web storefront. It handles authentication and redirect-flow initiation.
 
 ---
 
 ## Features
 
 - **`startEpicCollectionPayment`** – Authenticate with the Epic Collections API and get the redirect URL to the hosted payment portal in one call.
-- **`redirectToPortal`** – Build a portal redirect URL manually (useful when you already have credentials configured via `initEpicPay`).
-- **`parsePaymentResponseFromUrl`** – Parse query-string / hash parameters on your return page after the user completes (or cancels) payment.
-- **`initEpicPay`** – Optional global config initializer (environment, APIbase, event callbacks, etc.).
 - Zero dependencies, ESM-only, full TypeScript types included.
 
 ---
@@ -41,166 +38,89 @@ const url = await startEpicCollectionPayment({
 window.location.assign(url);
 ```
 
-On your `redirectUrl` page, parse the response:
-
-```ts
-import { parsePaymentResponseFromUrl } from "epic-collection-gateway-sdk";
-
-const result = parsePaymentResponseFromUrl();
-// { status, paymentRef, sessionId, ... }
-console.log(result);
-```
-
 ---
 
-## API Reference
-
-### `startEpicCollectionPayment(options)` → `Promise<string>`
-
-Authenticates your session with the Epic Collections backend and returns the fully-qualified portal redirect URL. This is the **primary integration function** for most storefronts.
-
-| Option | Type | Required | Description |
-|---|---|---|---|
-| `environment` | `string` | ✅ | Environment (sandbox or production). |
-| `clientId` | `string` | ✅ | Issued from the Epic Collections Admin Portal (min 16 chars). |
-| `clientSecret` | `string` | ✅ | Issued from the Epic Collections Admin Portal (min 16 chars). |
-| `redirectUrl` | `string` | ✅ | Merchant callback URL — where the user lands after payment or cancellation. |
-| `amount` | `number` | ✅ | Checkout amount (e.g. `2500` for ₦2,500). |
-| `sessionId` | `string` | ✅ | Unique identifier for this checkout session / order (min 16 chars). |
-| `customerDetails` | `EpicCollectioncustomerDetails` | — | Optional customer info forwarded to the portal. |
-
-**`EpicCollectioncustomerDetails`**
-
-```ts
-interface EpicCollectioncustomerDetails {
-  name?: string;
-  email?: string;
-  phone?: string;
-}
-```
+## React Integration Example
 
-**Example — React checkout button**
+Here is a practical example of integrating the SDK within a React component (e.g., a Header or Checkout button).
 
 ```tsx
-import { startEpicCollectionPayment } from "epic-collection-gateway-sdk";
+import { useState } from 'react';
+import { startEpicCollectionPayment } from 'epic-collection-gateway-sdk';
 
-function CheckoutButton({ cartItems }: { cartItems: CartItem[] }) {
+const CheckoutButton = ({ cart, total }) => {
   const [paying, setPaying] = useState(false);
-  const total = cartItems.reduce((sum, i) => sum + i.price * i.quantity, 0);
 
   const handleCheckout = async () => {
-    if (!cartItems.length) return;
+    if (cart.length === 0) return;
     try {
       setPaying(true);
+      
+      // Generate a unique session ID
+      const sessionId = `${Date.now()}${Math.floor(Math.random() * 1e9)}`;
+      
       const url = await startEpicCollectionPayment({
-        environment: "sandbox",
-        clientId: "YOUR_CLIENT_ID",
-        clientSecret: "YOUR_CLIENT_SECRET",
-        redirectUrl: "https://your-site.com",
+        environment: 'production', // or 'sandbox'
+        clientId: 'YOUR_CLIENT_ID',
+        clientSecret: 'YOUR_CLIENT_SECRET',
+        redirectUrl: 'https://your-site.com/checkout-success',
         amount: total,
-        sessionId: crypto.randomUUID(), // unique per order
-        customerDetails: { email: "user@example.com" },
+        sessionId,
+        customerDetails: {
+          email: 'user@example.com',
+          name: 'John Doe'
+        },
       });
+
+      // Redirect the user to the portal
       window.location.assign(url);
-    } catch (err) {
-      console.error("Payment initiation failed:", err);
+    } catch (error) {
+      console.error("Payment failed", error);
     } finally {
       setPaying(false);
     }
   };
 
   return (
-    <button onClick={handleCheckout} disabled={!cartItems.length || paying}>
-      {paying ? "Processing…" : `Pay ₦${total.toFixed(2)}`}
+    <button 
+      onClick={handleCheckout} 
+      disabled={paying || cart.length === 0}
+      className="btn-primary"
+    >
+      {paying ? 'Processing…' : `Proceed to Pay (₦${total})`}
     </button>
   );
-}
-```
-
----
-
-### `redirectToPortal(params)` → `string`
-
-Builds and returns the portal URL without making an auth API call. Use this if credentials are already set via `initEpicPay` and you want manual control.
-
-| Param | Type | Required | Description |
-|---|---|---|---|
-| `amount` | `number` | ✅ | Checkout amount. |
-| `sessionId` | `string` | ✅ | Unique checkout session ID. |
-| `redirectUrl` | `string` | — | Overrides the `redirectUrl` set in `initEpicPay`. |
-| `customerDetails` | `EpicCollectioncustomerDetails` | — | Optional customer metadata. |
-| `additionalParams` | `Record<string, string \| number \| boolean>` | — | Any extra query params to append to the URL. |
-
-> **Note:** `initEpicPay({ redirectUrl: "..." })` must be called before `redirectToPortal`, or a `redirectUrl` must be passed directly in params.
-
-```ts
-import { initEpicPay, redirectToPortal } from "epic-collection-gateway-sdk";
-
-initEpicPay({
-  redirectUrl: "https://pay.your-portal.com/checkout",
-  clientId: "YOUR_CLIENT_ID",
-  clientSecret: "YOUR_CLIENT_SECRET",
-});
-
-const url = redirectToPortal({
-  amount: 2300,
-  sessionId: "sess_123456789",
-  redirectUrl: "https://your-site.com/order-result",
-  customerDetails: { email: "user@example.com" },
-});
+};
 
-window.location.assign(url);
+export default CheckoutButton;
 ```
 
 ---
 
-### `parsePaymentResponseFromUrl(raw?)` → `Record<string, string>`
-
-Parses query-string or hash parameters from the current page URL (or a custom string) and returns them as a plain object. Call this on your `redirectUrl` return page.
-
-```ts
-import { parsePaymentResponseFromUrl } from "epic-collection-gateway-sdk";
-
-// Automatically reads window.location.search or window.location.hash
-const result = parsePaymentResponseFromUrl();
-
-if (result.status === "success") {
-  console.log("Payment reference:", result.paymentRef);
-  console.log("Session ID:", result.sessionId);
-} else {
-  console.warn("Payment not completed:", result.status);
-}
-```
-
-You may also pass a raw query string:
-
-```ts
-const result = parsePaymentResponseFromUrl("?status=success&paymentRef=TXN_001");
-```
-
----
+## API Reference
 
-### `initEpicPay(options?)` → `void`
+### `startEpicCollectionPayment(options)` → `Promise<string>`
 
-Sets global SDK configuration. Call this once at app startup. All options are optional.
+Authenticates your session with the Epic Collections backend and returns the fully-qualified portal redirect URL. This is the **primary integration function** for most storefronts.
 
-| Option | Type | Default | Description |
+| Option | Type | Required | Description |
 |---|---|---|---|
-| `environment` | `'sandbox' \| 'production'` | `'sandbox'` | Target environment. |
-| `apiBase` | `string` | — | Base URL for the Epic Collections API. |
-| `redirectUrl` | `string` | — | Default portal redirect URL. |
-| `clientId` | `string` | — | Client ID (can be passed here or per-call). |
-| `clientSecret` | `string` | — | Client secret (can be passed here or per-call). |
-| `headers` | `Record<string, string>` | — | Custom headers appended to API requests. |
-| `onEvent` | `(event: PaymentEvent) => void` | — | Global event callback. |
+| `environment` | `string` | ✅ | Environment (sandbox or production). |
+| `clientId` | `string` | ✅ | Issued from the Epic Collections Admin Portal (min 16 chars). |
+| `clientSecret` | `string` | ✅ | Issued from the Epic Collections Admin Portal (min 16 chars). |
+| `redirectUrl` | `string` | ✅ | Merchant callback URL — where the user lands after payment or cancellation. |
+| `amount` | `number` | ✅ | Checkout amount (e.g. `2500` for ₦2,500). |
+| `sessionId` | `string` | ✅ | Unique identifier for this checkout session / order (min 16 chars). |
+| `customerDetails` | `EpicCollectioncustomerDetails` | — | Optional customer info forwarded to the portal. |
 
-```ts
-import { initEpicPay } from "epic-collection-gateway-sdk";
+**`EpicCollectioncustomerDetails`**
 
-initEpicPay({
-  environment: "production",
-  onEvent: (e) => console.log("[EpicPay event]", e.type, e.payload),
-});
+```ts
+interface EpicCollectioncustomerDetails {
+  name?: string;
+  email?: string;
+  phone?: string;
+}
 ```
 
 ---
@@ -211,11 +131,9 @@ All types are exported from the package root:
 
 ```ts
 import type {
-  EpicPayInitOptions,
   EpicPayEnvironment,
   StartEpicCollectionPaymentOptions,
   EpicCollectioncustomerDetails,
-  RedirectToPortalParams,
   EpicPayConfig,
   PaymentEvent,
   PaymentResult,
@@ -223,15 +141,6 @@ import type {
 } from "epic-collection-gateway-sdk";
 ```
 
-| Type | Description |
-|---|---|
-| `EpicPayInitOptions` | Options for `initEpicPay()`. |
-| `StartEpicCollectionPaymentOptions` | Options for `startEpicCollectionPayment()`. |
-| `RedirectToPortalParams` | Params for `redirectToPortal()`. |
-| `EpicCollectioncustomerDetails` | Optional customer fields forwarded to the portal. |
-| `PaymentEvent` | Event object emitted via `onEvent`. Shape: `{ type, payload, timestamp }`. |
-| `PaymentResult` | Result shape returned from the portal on the return URL. |
-
 ---
 
 ## Default Export
@@ -241,24 +150,11 @@ A convenience object is available as the default export:
 ```ts
 import EpicCollectionSdk from "epic-collection-gateway-sdk";
 
-const { startEpicCollectionPayment, redirectToPortal, parsePaymentResponseFromUrl, initEpicPay } = EpicCollectionSdk;
+const { startEpicCollectionPayment } = EpicCollectionSdk;
 ```
 
 ---
 
-## Environment Variables (SDK-internal)
-
-When bundling the SDK from source, the following `VITE_` environment variables are resolved at build time:
-
-| Variable | Purpose |
-|---|---|
-| `VITE_PORTAL_URL` | Overrides the default payment portal base URL. |
-| `VITE_EPIC_ENVIRONMENT` | Sets the default environment (`sandbox` / `production`). |
-
-> These are for SDK development only. Integrators do **not** need to set these — pass `apiBase` / `redirectUrl` via `initEpicPay` or `startEpicCollectionPayment` instead.
-
----
-
 ## License
 
 MIT

package/dist/core/api.d.ts

@@ -1,21 +1,6 @@
 export type EpicPayEnvironment = 'sandbox' | 'production';
-export interface EpicPayInitOptions {
-    merchantId?: string;
-    environment?: EpicPayEnvironment;
-    onEvent?: (event: {
-        type: string;
-        payload?: any;
-        timestamp: number;
-    }) => void;
-    apiBase?: string;
-    headers?: Record<string, string>;
-    paymentMethodsUrl?: string;
-    theme?: Record<string, string>;
-    redirectUrl?: string;
-    clientId?: string;
-    clientSecret?: string;
-}
 export interface RedirectToPortalParams {
+    environment?: EpicPayEnvironment;
     amount: number;
     sessionId: string;
     additionalParams?: Record<string, string | number | boolean>;
@@ -39,5 +24,3 @@ export interface StartEpicCollectionPaymentOptions {
 }
 export declare function redirectToPortal(params: RedirectToPortalParams): string;
 export declare function startEpicCollectionPayment(options: StartEpicCollectionPaymentOptions): Promise<string>;
-export declare function parsePaymentResponseFromUrl(raw?: string): Record<string, string>;
-export declare function initEpicPay(options?: EpicPayInitOptions): void;

package/dist/core/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const EPIC_PORTAL_URL = "https://checkout.epicpay.co";
+export declare const EPIC_API_BASE = "https://zppicbcegi.execute-api.af-south-1.amazonaws.com/prod/api/v1";
+export declare const EPIC_HEADERS: {
+    grabbersbeware: string;
+};

package/dist/core/epicConfig.d.ts

@@ -2,4 +2,3 @@ import { EpicPayConfig } from './types';
 
 export declare const epicConfig: EpicPayConfig;
 export declare function setConfig(config: Partial<EpicPayConfig>): void;
-export declare function emit(type: string, payload?: any): void;

package/dist/core/types.d.ts

@@ -10,52 +10,4 @@ export interface EpicPayConfig {
     clientSecret?: string;
     /** If true, do not actually redirect; only log what would happen. */
     dryRun?: boolean;
-    onEvent?: (event: PaymentEvent) => void;
-}
-export interface ThemeConfig {
-    colorPrimaryViolet?: string;
-    borderColor?: string;
-    fontColor?: string;
-    black?: string;
-    white?: string;
-    inputBackground?: string;
-    tabBackground?: string;
-}
-export interface PaymentMethod {
-    identityKey: string;
-    methodName: string;
-    icon?: string;
-}
-export interface PaymentSheetProps {
-    amount: number;
-    currency?: string;
-    customer?: CustomerInfo;
-    paymentMethods?: PaymentMethod[] | 'auto';
-    onSuccess?: (result: PaymentResult) => void;
-    onError?: (error: PaymentError) => void;
-    onClose?: () => void;
-}
-export interface CustomerInfo {
-    id?: string;
-    email?: string;
-    name?: string;
-    phone?: string;
-}
-export interface PaymentResult {
-    status: 'succeeded' | 'failed' | 'cancelled';
-    method?: string;
-    amount?: number;
-    currency?: string;
-    transactionId?: string;
-    error?: string;
-}
-export interface PaymentError {
-    status: 'failed';
-    method?: string;
-    error: string;
-}
-export interface PaymentEvent {
-    type: string;
-    payload: any;
-    timestamp: number;
 }

package/dist/index.d.ts

@@ -1,13 +1,11 @@
-import { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl, startEpicCollectionPayment } from './core/api';
+import { redirectToPortal, startEpicCollectionPayment } from './core/api';
 export { setConfig, epicConfig } from './core/epicConfig';
 export * from './core/types';
-export { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl, startEpicCollectionPayment } from './core/api';
-export type { EpicPayInitOptions, EpicPayEnvironment } from './core/api';
+export { redirectToPortal, startEpicCollectionPayment } from './core/api';
+export type { EpicPayEnvironment } from './core/api';
 export type { RedirectToPortalParams, StartEpicCollectionPaymentOptions, EpicCollectioncustomerDetails } from './core/api';
 declare const EpicCollectionSdk: {
-    initEpicPay: typeof initEpicPay;
     redirectToPortal: typeof redirectToPortal;
-    parsePaymentResponseFromUrl: typeof parsePaymentResponseFromUrl;
     startEpicCollectionPayment: typeof startEpicCollectionPayment;
 };
 export default EpicCollectionSdk;

package/dist/index.js

@@ -1,43 +1,44 @@
-const u = "https://checkout.epicpay.co", y = "https://zppicbcegi.execute-api.af-south-1.amazonaws.com/prod/api/v1", s = {
+const u = "https://checkout.epicpay.co", g = "https://zppicbcegi.execute-api.af-south-1.amazonaws.com/prod/api/v1", m = {
+  grabbersbeware: "getthehellout989898"
+}, c = {
   environment: "",
-  apiBase: y,
+  apiBase: g,
   headers: {},
   redirectUrl: u,
   clientId: "",
   clientSecret: "",
-  dryRun: !0,
-  onEvent: void 0
+  dryRun: !0
 };
-function p(e) {
-  Object.assign(s, e);
+function w(l) {
+  Object.assign(c, l);
 }
-function m(e) {
-  const { amount: r, sessionId: c, additionalParams: n, redirectUrl: i } = e, a = s.redirectUrl || s.apiBase;
-  if (!a)
+function p(l) {
+  const { environment: a, amount: r, sessionId: n, additionalParams: i, redirectUrl: d } = l, t = c.redirectUrl || c.apiBase;
+  if (!t)
     throw new Error('No redirectUrl configured. Call initEpicPay({ redirectUrl: "https://..." }).');
-  const t = {
+  const e = {
     amount: String(r),
-    sessionId: c
+    sessionId: n
   };
-  i && (t.redirectUrl = String(i)), s.clientId && (t.clientId = s.clientId), s.clientSecret && (t.clientSecret = s.clientSecret), n && Object.keys(n).forEach((d) => {
-    t[d] = String(n[d]);
+  d && (e.redirectUrl = String(d)), c.clientId && (e.clientId = c.clientId), c.clientSecret && (e.clientSecret = c.clientSecret), a && (e.environment = String(a)), i && Object.keys(i).forEach((o) => {
+    e[o] = String(i[o]);
   });
-  const o = Object.keys(t).map((d) => `${encodeURIComponent(d)}=${encodeURIComponent(t[d])}`).join("&"), l = a + (a.includes("?") ? "&" : "?") + o;
+  const s = Object.keys(e).map((o) => `${encodeURIComponent(o)}=${encodeURIComponent(e[o])}`).join("&"), f = t + (t.includes("?") ? "&" : "?") + s;
   try {
-    console.log("[EpicPay] redirectToPortal", { portal: a, amount: r, sessionId: c });
+    console.log("[EpicPay] redirectToPortal", { portal: t, amount: r, sessionId: n });
   } catch {
   }
   try {
-    console.log("[EpicPay] redirectToPortal URL:", l);
+    console.log("[EpicPay] redirectToPortal URL:", f);
   } catch {
   }
-  return l;
+  return f;
 }
-async function g(e) {
-  const { environment: r, clientId: c, clientSecret: n, redirectUrl: i, amount: a, sessionId: t, customerDetails: o } = e;
-  if (!r || typeof r != "string")
+async function E(l) {
+  const { environment: a, clientId: r, clientSecret: n, redirectUrl: i, amount: d, sessionId: t, customerDetails: e } = l;
+  if (!a || typeof a != "string")
     throw new Error("Invalid environment");
-  if (!c || typeof c != "string" || c.length < 16)
+  if (!r || typeof r != "string" || r.length < 16)
     throw new Error("Invalid clientId");
   if (!n || typeof n != "string" || n.length < 16)
     throw new Error("Invalid clientSecret");
@@ -45,73 +46,45 @@ async function g(e) {
     throw new Error("Invalid sessionId");
   if (!i || typeof i != "string")
     throw new Error("Invalid redirectUrl");
-  p({
-    environment: r,
-    clientId: c,
+  w({
+    environment: a,
+    clientId: r,
     clientSecret: n
   });
-  const l = s.apiBase;
-  if (!l)
+  const s = c.apiBase;
+  if (!s)
     throw new Error("No API base configured for authentication");
-  const d = (l.endsWith("/") ? l.slice(0, -1) : l) + "/web-checkout/auth", f = await fetch(d, {
+  const f = (s.endsWith("/") ? s.slice(0, -1) : s) + "/web-checkout/auth", o = await fetch(f, {
     method: "POST",
-    headers: { "Content-Type": "application/json", grabbersbeware: "getthehellout989898" },
+    headers: { "Content-Type": "application/json", ...m },
     body: JSON.stringify({
-      clientId: c,
+      clientId: r,
       clientSecret: n,
       sessionId: t,
-      amount: a,
+      amount: d,
       redirectUrl: i,
-      customerDetails: o
+      customerDetails: e
     })
   });
-  if (!f.ok)
+  if (!o.ok)
     throw new Error("Authentication request failed");
   try {
-    await f.json();
+    await o.json();
   } catch {
   }
   const h = {};
-  return h.clientSecret = n, o && (o.name && (h.clientName = String(o.name)), o.email && (h.clientEmail = String(o.email)), o.phone && (h.clientPhone = String(o.phone))), m({
-    amount: a,
+  return h.clientSecret = n, e && (e.name && (h.clientName = String(e.name)), e.email && (h.clientEmail = String(e.email)), e.phone && (h.clientPhone = String(e.phone))), p({
+    amount: d,
     sessionId: t,
     additionalParams: h,
     redirectUrl: i
   });
 }
-function w(e) {
-  const r = e ?? (typeof window < "u" ? window.location.search || window.location.hash : ""), c = r.startsWith("?") || r.startsWith("#") ? r.substring(1) : r, n = new URLSearchParams(c), i = {};
-  n.forEach((a, t) => {
-    i[t] = a;
-  });
-  try {
-    console.log("[EpicPay] parsePaymentResponseFromUrl", i);
-  } catch {
-  }
-  return i;
-}
-function E(e = {}) {
-  p({
-    environment: e.environment ?? "sandbox",
-    apiBase: e.apiBase,
-    headers: e.headers,
-    onEvent: e.onEvent,
-    redirectUrl: e.redirectUrl,
-    clientId: e.clientId,
-    clientSecret: e.clientSecret
-  });
-  try {
-    console.log("[EpicPay] initEpicPay", { environment: e.environment ?? "sandbox", redirectUrl: e.redirectUrl, clientId: e.clientId, clientSecret: e.clientSecret });
-  } catch {
-  }
-}
-const I = { initEpicPay: E, redirectToPortal: m, parsePaymentResponseFromUrl: w, startEpicCollectionPayment: g };
+const I = { redirectToPortal: p, startEpicCollectionPayment: E };
 export {
   I as default,
-  s as epicConfig,
-  E as initEpicPay,
-  w as parsePaymentResponseFromUrl,
-  m as redirectToPortal,
-  p as setConfig,
-  g as startEpicCollectionPayment
+  c as epicConfig,
+  p as redirectToPortal,
+  w as setConfig,
+  E as startEpicCollectionPayment
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epic-collection-gateway-sdk",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",