@ngandu-dev/flexpay 2.0.4 → 3.0.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.
Files changed (7) hide show
  1. package/README.md +175 -125
  2. package/UPGRADE_3.0.0.md +345 -0
  3. package/dist/index.d.mts +186 -118
  4. package/dist/index.d.ts +186 -118
  5. package/dist/index.js +1 -1
  6. package/dist/index.mjs +1 -1
  7. package/package.json +11 -6
package/dist/index.d.mts CHANGED
@@ -1,163 +1,231 @@
1
- import * as z from 'zod';
1
+ import { z } from 'zod';
2
2
 
3
- type EnvironmentType = "prod" | "dev";
4
- /** Versioned endpoint prefixes, without the service path (for example, /pay). */
5
- interface BaseUrls {
6
- apiBaseUrl?: string;
7
- cardBaseUrl?: string;
8
- }
9
- declare class Environment {
10
- readonly value: EnvironmentType;
11
- private readonly apiBaseUrl;
12
- private readonly cardBaseUrl;
13
- constructor(value: EnvironmentType, baseUrls?: BaseUrls);
14
- getMobilePaymentUrl(): string;
15
- getPayoutUrl(): string;
16
- getCheckStatusUrl(orderNumber: string): string;
17
- getCardPaymentUrl(): string;
18
- private getBaseUrl;
19
- }
3
+ declare const BaseUrlSchema: z.ZodReadonly<z.ZodObject<{
4
+ payment: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
5
+ check: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
6
+ payout: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
7
+ }, z.core.$strict>>;
8
+ /** Three explicit versioned endpoint prefixes, without the service path. */
9
+ type BaseUrl = z.infer<typeof BaseUrlSchema>;
10
+ declare const productionBaseUrl: BaseUrl;
11
+ declare const CredentialSchema: z.ZodReadonly<z.ZodObject<{
12
+ merchant: z.ZodString;
13
+ token: z.ZodString;
14
+ }, z.core.$strict>>;
15
+ type Credential = z.infer<typeof CredentialSchema>;
20
16
 
21
- declare enum Status {
22
- SUCCESS = 0,// When the request is successfully processed
23
- FAILURE = 1
24
- }
25
17
  declare const CurrencySchema: z.ZodEnum<{
26
18
  USD: "USD";
27
19
  CDF: "CDF";
28
20
  }>;
29
21
  type Currency = z.infer<typeof CurrencySchema>;
30
- declare const StatusSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
31
- declare const MobileResponseSchema: z.ZodPipe<z.ZodObject<{
32
- code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
22
+ declare const MobileRequestSchema: z.ZodReadonly<z.ZodObject<{
23
+ amount: z.ZodNumber;
24
+ currency: z.ZodEnum<{
25
+ USD: "USD";
26
+ CDF: "CDF";
27
+ }>;
28
+ reference: z.ZodString;
29
+ callbackUrl: z.ZodString;
30
+ phone: z.ZodString;
31
+ }, z.core.$strict>>;
32
+ declare const CardRequestSchema: z.ZodReadonly<z.ZodObject<{
33
+ amount: z.ZodNumber;
34
+ currency: z.ZodEnum<{
35
+ USD: "USD";
36
+ CDF: "CDF";
37
+ }>;
38
+ reference: z.ZodString;
39
+ callbackUrl: z.ZodString;
40
+ approveUrl: z.ZodString;
41
+ cancelUrl: z.ZodString;
42
+ declineUrl: z.ZodString;
43
+ }, z.core.$strict>>;
44
+ declare const PayoutRequestSchema: z.ZodReadonly<z.ZodObject<{
45
+ amount: z.ZodNumber;
46
+ currency: z.ZodEnum<{
47
+ USD: "USD";
48
+ CDF: "CDF";
49
+ }>;
50
+ reference: z.ZodString;
51
+ callbackUrl: z.ZodString;
52
+ phone: z.ZodString;
53
+ }, z.core.$strict>>;
54
+ type MobileRequest = z.infer<typeof MobileRequestSchema>;
55
+ type CardRequest = z.infer<typeof CardRequestSchema>;
56
+ type PayoutRequest = z.infer<typeof PayoutRequestSchema>;
57
+
58
+ /** A provider result code. Unknown integer codes retain their value without an inferred state. */
59
+ declare class Status {
60
+ readonly value: number;
61
+ constructor(value: number);
62
+ isSuccessful(): boolean;
63
+ isFailure(): boolean;
64
+ }
65
+ declare const StatusSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodInt>]>, z.ZodTransform<Status, number>>;
66
+
67
+ declare const MobileResponseSchema: z.ZodReadonly<z.ZodPipe<z.ZodObject<{
68
+ code: z.ZodPipe<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodInt>]>, z.ZodTransform<Status, number>>;
33
69
  message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
34
- orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
35
- provider_reference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
36
- providerReference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
37
- reference: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
38
- url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
70
+ orderNumber: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
39
71
  }, z.core.$strip>, z.ZodTransform<{
72
+ accepted: boolean;
73
+ code: Status;
74
+ message: string;
75
+ orderNumber: string | null;
76
+ }, {
77
+ code: Status;
78
+ message: string;
79
+ orderNumber: string | null;
80
+ }>>>;
81
+ declare const CardResponseSchema: z.ZodReadonly<z.ZodPipe<z.ZodObject<{
82
+ code: z.ZodPipe<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodInt>]>, z.ZodTransform<Status, number>>;
83
+ message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
84
+ orderNumber: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
85
+ url: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
86
+ }, z.core.$strip>, z.ZodTransform<{
87
+ accepted: boolean;
40
88
  code: Status;
41
89
  message: string;
42
90
  orderNumber: string | null;
43
- providerReference: string | null;
44
- reference: string | null;
45
91
  url: string | null;
46
92
  }, {
47
93
  code: Status;
48
94
  message: string;
49
- orderNumber?: string | null | undefined;
50
- provider_reference?: string | null | undefined;
51
- providerReference?: string | null | undefined;
52
- reference?: string | null | undefined;
53
- url?: string | null | undefined;
54
- }>>;
55
- declare const CardResponseSchema: z.ZodObject<{
56
- code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
95
+ orderNumber: string | null;
96
+ url: string | null;
97
+ }>>>;
98
+ declare const PayoutResponseSchema: z.ZodReadonly<z.ZodPipe<z.ZodObject<{
99
+ code: z.ZodPipe<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodInt>]>, z.ZodTransform<Status, number>>;
100
+ message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
101
+ orderNumber: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
102
+ }, z.core.$strip>, z.ZodTransform<{
103
+ accepted: boolean;
104
+ code: Status;
105
+ message: string;
106
+ orderNumber: string | null;
107
+ }, {
108
+ code: Status;
109
+ message: string;
110
+ orderNumber: string | null;
111
+ }>>>;
112
+ declare const CallbackResponseSchema: z.ZodReadonly<z.ZodPipe<z.ZodObject<{
113
+ code: z.ZodPipe<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodInt>]>, z.ZodTransform<Status, number>>;
57
114
  message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
58
- orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
59
- url: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
60
- }, z.core.$strip>;
61
- declare const TransactionSchema: z.ZodObject<{
115
+ orderNumber: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
116
+ reference: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
117
+ provider_reference: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
118
+ amount: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>>>>;
119
+ amountCustomer: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>>>>;
120
+ phone: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
121
+ currency: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodEnum<{
122
+ USD: "USD";
123
+ CDF: "CDF";
124
+ }>>>>;
125
+ createdAt: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
126
+ channel: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
127
+ }, z.core.$strip>, z.ZodTransform<{
128
+ code: Status;
129
+ successful: boolean;
130
+ message: string;
131
+ orderNumber: string | null;
132
+ reference: string | null;
133
+ providerReference: string | null;
134
+ amount: number | null;
135
+ amountCustomer: number | null;
136
+ phone: string | null;
137
+ currency: "USD" | "CDF" | null;
138
+ createdAt: string | null;
139
+ channel: string | null;
140
+ }, {
141
+ code: Status;
142
+ message: string;
143
+ orderNumber: string | null;
144
+ reference: string | null;
145
+ provider_reference: string | null;
146
+ amount: number | null;
147
+ amountCustomer: number | null;
148
+ phone: string | null;
149
+ currency: "USD" | "CDF" | null;
150
+ createdAt: string | null;
151
+ channel: string | null;
152
+ }>>>;
153
+ declare const TransactionSchema: z.ZodReadonly<z.ZodObject<{
62
154
  amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
63
155
  amountCustomer: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
64
- channel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
156
+ channel: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
65
157
  createdAt: z.ZodString;
66
158
  currency: z.ZodEnum<{
67
159
  USD: "USD";
68
160
  CDF: "CDF";
69
161
  }>;
70
- orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
162
+ orderNumber: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
71
163
  reference: z.ZodString;
72
- status: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
73
- }, z.core.$strip>;
74
- declare const CheckResponseSchema: z.ZodObject<{
75
- code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
164
+ status: z.ZodPipe<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodInt>]>, z.ZodTransform<Status, number>>;
165
+ }, z.core.$strip>>;
166
+ declare const CheckResponseSchema: z.ZodReadonly<z.ZodPipe<z.ZodObject<{
167
+ code: z.ZodPipe<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodInt>]>, z.ZodTransform<Status, number>>;
76
168
  message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
77
- transaction: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
169
+ transaction: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodReadonly<z.ZodObject<{
78
170
  amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
79
171
  amountCustomer: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>]>;
80
- channel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
172
+ channel: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
81
173
  createdAt: z.ZodString;
82
174
  currency: z.ZodEnum<{
83
175
  USD: "USD";
84
176
  CDF: "CDF";
85
177
  }>;
86
- orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
178
+ orderNumber: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
87
179
  reference: z.ZodString;
88
- status: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
89
- }, z.core.$strip>, z.ZodNull]>>>;
90
- }, z.core.$strip>;
91
- declare const PayoutResponseSchema: z.ZodObject<{
92
- code: z.ZodPipe<z.ZodUnion<readonly [z.ZodLiteral<Status.SUCCESS>, z.ZodLiteral<Status.FAILURE>, z.ZodLiteral<"0">, z.ZodLiteral<"1">]>, z.ZodTransform<Status, "0" | "1" | Status>>;
93
- message: z.ZodDefault<z.ZodOptional<z.ZodString>>;
94
- orderNumber: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
95
- }, z.core.$strip>;
96
- declare const MobileRequestSchema: z.ZodObject<{
97
- amount: z.ZodNumber;
98
- approveUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
99
- callbackUrl: z.ZodString;
100
- cancelUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
101
- currency: z.ZodEnum<{
102
- USD: "USD";
103
- CDF: "CDF";
104
- }>;
105
- declineUrl: z.ZodNullable<z.ZodOptional<z.ZodString>>;
106
- description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
107
- reference: z.ZodString;
108
- phone: z.ZodString;
109
- }, z.core.$strip>;
110
- declare const CardRequestSchema: z.ZodObject<{
111
- amount: z.ZodNumber;
112
- approveUrl: z.ZodString;
113
- callbackUrl: z.ZodString;
114
- cancelUrl: z.ZodString;
115
- currency: z.ZodEnum<{
116
- USD: "USD";
117
- CDF: "CDF";
118
- }>;
119
- declineUrl: z.ZodString;
120
- description: z.ZodString;
121
- homeUrl: z.ZodString;
122
- reference: z.ZodString;
123
- }, z.core.$strip>;
124
- declare const PayoutRequestSchema: z.ZodObject<{
125
- amount: z.ZodNumber;
126
- callbackUrl: z.ZodString;
127
- currency: z.ZodEnum<{
128
- USD: "USD";
129
- CDF: "CDF";
130
- }>;
131
- phone: z.ZodString;
132
- reference: z.ZodString;
133
- }, z.core.$strip>;
180
+ status: z.ZodPipe<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodInt>]>, z.ZodTransform<Status, number>>;
181
+ }, z.core.$strip>>>>>;
182
+ }, z.core.$strip>, z.ZodTransform<{
183
+ successful: boolean;
184
+ code: Status;
185
+ message: string;
186
+ transaction: Readonly<{
187
+ amount: number;
188
+ amountCustomer: number;
189
+ channel: string | null;
190
+ createdAt: string;
191
+ currency: "USD" | "CDF";
192
+ orderNumber: string | null;
193
+ reference: string;
194
+ status: Status;
195
+ }> | null;
196
+ }, {
197
+ code: Status;
198
+ message: string;
199
+ transaction: Readonly<{
200
+ amount: number;
201
+ amountCustomer: number;
202
+ channel: string | null;
203
+ createdAt: string;
204
+ currency: "USD" | "CDF";
205
+ orderNumber: string | null;
206
+ reference: string;
207
+ status: Status;
208
+ }> | null;
209
+ }>>>;
134
210
  type MobileResponse = z.infer<typeof MobileResponseSchema>;
135
211
  type CardResponse = z.infer<typeof CardResponseSchema>;
212
+ type PayoutResponse = z.infer<typeof PayoutResponseSchema>;
213
+ type CallbackResponse = z.infer<typeof CallbackResponseSchema>;
136
214
  type Transaction = z.infer<typeof TransactionSchema>;
137
215
  type CheckResponse = z.infer<typeof CheckResponseSchema>;
138
- type PayoutResponse = z.infer<typeof PayoutResponseSchema>;
139
- type MobileRequest = z.infer<typeof MobileRequestSchema>;
140
- type CardRequest = z.infer<typeof CardRequestSchema>;
141
- type PayoutRequest = z.infer<typeof PayoutRequestSchema>;
216
+ /** Parses a provider callback; it does not authenticate its sender. */
217
+ declare function parseCallback(data: unknown): CallbackResponse;
142
218
 
219
+ /** Coordinates explicit payment operations using validated configuration and the HTTP transport. */
143
220
  declare class Client {
144
- private readonly credential;
145
- private readonly env;
146
- constructor(merchant: string, token: string, env?: EnvironmentType, baseUrls?: BaseUrls);
221
+ private readonly merchant;
222
+ private readonly baseUrl;
223
+ private readonly transport;
224
+ constructor(credential: Credential, baseUrl: BaseUrl, fetch?: typeof globalThis.fetch);
147
225
  mobile(request: MobileRequest): Promise<MobileResponse>;
148
226
  card(request: CardRequest): Promise<CardResponse>;
149
- pay(request: MobileRequest): Promise<MobileResponse>;
150
- pay(request: CardRequest): Promise<CardResponse>;
151
- check(orderNumber: string): Promise<CheckResponse>;
152
227
  payout(request: PayoutRequest): Promise<PayoutResponse>;
153
- handleCallback(data: unknown): MobileResponse;
154
- isSuccessful<T extends {
155
- code: Status;
156
- }>(response: T): response is T & {
157
- code: Status.SUCCESS;
158
- };
159
- private requestJson;
160
- private parseWith;
228
+ check(orderNumber: string): Promise<CheckResponse>;
161
229
  }
162
230
 
163
231
  declare class NetworkException extends Error {
@@ -173,4 +241,4 @@ declare class ClientException extends NetworkException {
173
241
  declare class ServerException extends NetworkException {
174
242
  }
175
243
 
176
- export { AccountException, type BaseUrls, type CardRequest, CardRequestSchema, type CardResponse, CardResponseSchema, type CheckResponse, CheckResponseSchema, Client, ClientException, type Currency, CurrencySchema, Environment, type EnvironmentType, type MobileRequest, MobileRequestSchema, type MobileResponse, MobileResponseSchema, NetworkException, type PayoutRequest, PayoutRequestSchema, type PayoutResponse, PayoutResponseSchema, ServerException, Status, StatusSchema, type Transaction, TransactionSchema };
244
+ export { AccountException, type BaseUrl, BaseUrlSchema, type CallbackResponse, CallbackResponseSchema, type CardRequest, CardRequestSchema, type CardResponse, CardResponseSchema, type CheckResponse, CheckResponseSchema, Client, ClientException, type Credential, CredentialSchema, type Currency, CurrencySchema, type MobileRequest, MobileRequestSchema, type MobileResponse, MobileResponseSchema, NetworkException, type PayoutRequest, PayoutRequestSchema, type PayoutResponse, PayoutResponseSchema, ServerException, Status, StatusSchema, type Transaction, TransactionSchema, parseCallback, productionBaseUrl };