@instincthub/react-ui 0.3.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,6 @@
1
- import { PaystackConfigObjectType, PaystackConfigType, PaystackResponseType, PaymentContextType } from "@/types";
1
+ import { PaystackConfigObjectType, PaystackConfigType, PaystackResponseType, PaymentContextType, SavedCardChargeOptionsType } from "@/types";
2
+ /** Paystack inline v2 script, needed for server-initialised transactions. */
3
+ export declare const PAYSTACK_INLINE_V2_URL = "https://js.paystack.co/v2/inline.js";
2
4
  /**
3
5
  * Context for processing payments
4
6
  * @property {Event | null} [e] - The event object that triggered the payment
@@ -17,17 +19,50 @@ import { PaystackConfigObjectType, PaystackConfigType, PaystackResponseType, Pay
17
19
  * @property {number} [gatwayCharges] - Payment gateway charges percentage
18
20
  */
19
21
  /**
20
- * Configures the Paystack payment data for processing
22
+ * Configures the Paystack popup data.
23
+ *
24
+ * Only the PUBLIC key (`NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY`) is ever read here.
25
+ * The secret key must never reach the browser: anything a `NEXT_PUBLIC_*`
26
+ * variable holds is inlined into the shipped JavaScript.
21
27
  * @param obj - Object containing payment details
22
28
  * @returns PaystackConfig - Configured payment data
23
29
  */
24
30
  export declare const paystackDataConfig: (obj: PaystackConfigObjectType) => PaystackConfigType;
25
31
  /**
26
- * Charges a customer using an existing authorization
27
- * @param data - Payment configuration data
28
- * @returns Promise with transaction data
32
+ * Charges the logged-in user's saved card THROUGH THE APP'S SERVER.
33
+ *
34
+ * The browser never calls Paystack's charge_authorization API and never sends
35
+ * an authorization code or an amount the server trusts. It POSTs only what
36
+ * identifies the purchase (`body`, e.g. the saved payment method id, the item
37
+ * and a coupon code) to `chargeUrl`; the server looks the card up by the
38
+ * logged-in user, prices the item itself and charges it with its own secret
39
+ * key. The server is expected to answer with the Paystack transaction object
40
+ * (`status`, `reference`, `amount`, ...), optionally wrapped in `data`.
41
+ *
42
+ * @example
43
+ * ```ts
44
+ * const res = await chargeAuthorization({
45
+ * chargeUrl: `${API_HOST_URL}payments/${channel}/paystack/charge-saved-card/`,
46
+ * token,
47
+ * body: { payment_method_id: card.id, item_type: "course", item_id: course.id },
48
+ * });
49
+ * if (res.status === "success") recordPayment(res);
50
+ * ```
51
+ * @param options - Server endpoint, auth token and purchase identifiers
52
+ * @returns Promise with the transaction data (status "failed" on error)
53
+ */
54
+ export declare const chargeAuthorization: (options: SavedCardChargeOptionsType) => Promise<any>;
55
+ /**
56
+ * Opens the Paystack popup for a transaction the app's SERVER initialised
57
+ * (POST /transaction/initialize with the secret key), so amount, email and
58
+ * metadata are fixed server-side and cannot be changed in the browser.
59
+ *
60
+ * Uses Paystack inline v2 (`resumeTransaction`). The v2 script is loaded on
61
+ * demand when it is not already on the page.
62
+ * @param accessCode - `access_code` returned by the server's initialize call
63
+ * @returns Promise with the payment response (`status: "canceled"` on close)
29
64
  */
30
- export declare const chargeAuthorization: (data: PaystackConfigType) => Promise<any>;
65
+ export declare const payWithAccessCode: (accessCode: string) => Promise<PaystackResponseType>;
31
66
  /**
32
67
  * Initiates payment with Paystack popup
33
68
  * @param config - Payment configuration
@@ -51,18 +86,19 @@ export declare const payWithPaystack: (config: PaystackConfigType) => Promise<Pa
51
86
  * email: "user@example.com",
52
87
  * amount: 1000,
53
88
  * currency: "NGN",
54
- * authorization_code: "1234567890",
55
89
  * first_name: "John",
56
90
  * last_name: "Doe",
57
91
  * email: "user@example.com",
58
92
  * },
59
93
  * coupon: "1234567890",
60
94
  * gatwayCharges: 10,
61
- * paymentMethod: {
62
- * authorization: {
63
- * card_type: "MasterCard",
64
- * last4: "1234",
65
- * },
95
+ * paymentMethod: savedCard, // from user-payment-method-list
96
+ * // Saved cards are charged by YOUR server, never from the browser.
97
+ * // Without savedCardCharge the user always gets the Paystack popup.
98
+ * savedCardCharge: {
99
+ * chargeUrl: `${API_HOST_URL}payments/${channel}/paystack/charge-saved-card/`,
100
+ * token,
101
+ * body: { item_type: "course", item_id: "123" },
66
102
  * },
67
103
  * handleDBAction: (data: any) => {
68
104
  * console.log(data);
@@ -586,6 +586,11 @@ export interface PaystackMetadataType {
586
586
  [key: string]: any;
587
587
  }
588
588
  export interface PaystackConfigObjectType {
589
+ /**
590
+ * @deprecated Ignored since 0.4.0. Saved cards are charged by the app's
591
+ * server (see `PaymentContextType.savedCardCharge`), which looks the card up
592
+ * itself; the browser no longer handles authorization codes.
593
+ */
589
594
  authorization_code?: string;
590
595
  email: string;
591
596
  first_name: string;
@@ -605,8 +610,7 @@ export interface PaystackConfigType {
605
610
  currency: string;
606
611
  amount: number;
607
612
  reference?: string;
608
- authorization_code?: string;
609
- publicKey?: string | undefined;
613
+ /** Paystack PUBLIC key (pk_...). Never put a secret key in browser code. */
610
614
  key?: string | undefined;
611
615
  callback_url?: string;
612
616
  metadata?: PaystackMetadataType;
@@ -661,6 +665,26 @@ export interface PaymentContextType {
661
665
  defaultMsg?: string;
662
666
  gatwayCharges?: number;
663
667
  openConfirm?: boolean;
668
+ /**
669
+ * Server endpoint that charges `paymentMethod`. When omitted, saved cards
670
+ * are not offered and the Paystack popup is used.
671
+ */
672
+ savedCardCharge?: SavedCardChargeOptionsType;
673
+ }
674
+ /**
675
+ * Options for charging a saved card through the app's own server.
676
+ * The server looks the card up by the logged-in user and prices the item;
677
+ * the browser sends identifiers only.
678
+ */
679
+ export interface SavedCardChargeOptionsType {
680
+ /** Absolute URL of the server endpoint that performs the charge. */
681
+ chargeUrl: string;
682
+ /** Bearer token of the logged-in user. */
683
+ token?: string | null;
684
+ /** Optional channel header passed to `reqOptions`. */
685
+ channel?: string | null;
686
+ /** Purchase identifiers, e.g. payment_method_id, item_type, item_id, coupon. */
687
+ body?: Record<string, any>;
664
688
  }
665
689
  export interface PaymentReferenceType {
666
690
  reference: string;