@isroilov_an/paylov 0.0.1
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.
- package/CHANGELOG.md +35 -0
- package/LICENSE +21 -0
- package/README.md +81 -0
- package/dist/client-DOu4B-bL.js +2576 -0
- package/dist/client-DOu4B-bL.js.map +1 -0
- package/dist/index.d.ts +393 -0
- package/dist/index.js +458 -0
- package/dist/index.js.map +1 -0
- package/dist/testing.d.ts +198 -0
- package/dist/testing.js +1079 -0
- package/dist/testing.js.map +1 -0
- package/dist/types-Bj9umT2M.d.ts +1620 -0
- package/docs/usage/INDEX.md +30 -0
- package/docs/usage/cards.md +69 -0
- package/docs/usage/checkout.md +30 -0
- package/docs/usage/errors.md +107 -0
- package/docs/usage/fiscalization.md +62 -0
- package/docs/usage/holds.md +82 -0
- package/docs/usage/money-and-time.md +45 -0
- package/docs/usage/onboarding.md +28 -0
- package/docs/usage/payments.md +57 -0
- package/docs/usage/setup.md +85 -0
- package/docs/usage/splits.md +46 -0
- package/docs/usage/testing.md +132 -0
- package/docs/usage/transactions.md +43 -0
- package/docs/usage/webhooks.md +168 -0
- package/package.json +86 -0
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `@isroilov_an/paylov/testing` entry point: an in-memory gateway and webhook requests for
|
|
3
|
+
* application tests. Never import it from production code.
|
|
4
|
+
*/
|
|
5
|
+
import { $t as PaylovErrorCode, L as SplitsResource, N as SubMerchantsResource, T as TransactionsResource, U as PaymentsResource, Wt as FetchLike, Z as HoldsResource, a as PaylovWebhookReceiverConfig, at as GatewayResource, b as PaylovOnboardingConfig, d as WebhookEvent, f as WebhookInput, g as PaylovOnboarding, st as FiscalizationResource, w as PaylovClientConfig, wt as CardsResource } from "./types-Bj9umT2M.js";
|
|
6
|
+
/** How a scripted failure reads once the SDK decodes it as a `PaylovApiError`. */
|
|
7
|
+
interface PaylovFakeFailure {
|
|
8
|
+
/** Default 400. Any status from 400 to 599. */
|
|
9
|
+
readonly httpStatus?: number;
|
|
10
|
+
/** `validation_error`, `field_not_valid` (one field) and `field_required` (one field) only. */
|
|
11
|
+
readonly fields?: readonly string[];
|
|
12
|
+
/** `rate_limit_exceeded` and `card_is_blocked` only, from 1 to 3600. */
|
|
13
|
+
readonly retryAfterSeconds?: number;
|
|
14
|
+
}
|
|
15
|
+
/** How long a scripted answer lasts. */
|
|
16
|
+
interface PaylovFakeSchedule {
|
|
17
|
+
/**
|
|
18
|
+
* Serve this answer to every request of its method that no one-time answer matches, instead of
|
|
19
|
+
* to one attempt; `assertDone()` then requires only that it served at least one. Default
|
|
20
|
+
* `false`.
|
|
21
|
+
*/
|
|
22
|
+
readonly persist?: boolean;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* The script of one SDK method. Each answer serves one HTTP attempt, unless `{ persist: true }`
|
|
26
|
+
* keeps it for every attempt; the fake serves one-time answers in order. A GET that fails
|
|
27
|
+
* transiently is retried, so script one answer per attempt or a persistent one.
|
|
28
|
+
*/
|
|
29
|
+
interface PaylovFakeMethod<T, P> {
|
|
30
|
+
/**
|
|
31
|
+
* Answers with `result` encoded as the gateway sends it, so the SDK's own decoding runs. Throws
|
|
32
|
+
* `TypeError` for a value the wire cannot carry, such as a fractional SUM or sub-second time.
|
|
33
|
+
*
|
|
34
|
+
* @example
|
|
35
|
+
* fake.payments.create.reply({ transactionId: '00000000-0000-4000-8000-000000000001' });
|
|
36
|
+
*/
|
|
37
|
+
reply(result: T, schedule?: PaylovFakeSchedule): void;
|
|
38
|
+
/**
|
|
39
|
+
* Answers with a gateway error; the call rejects with `PaylovApiError` `code`. Throws
|
|
40
|
+
* `TypeError` for a failure the gateway cannot report, such as `fields` on a code without them.
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* fake.payments.pay.fail('insufficient_funds');
|
|
44
|
+
* fake.transactions.get.fail('server_error', { httpStatus: 500 }, { persist: true });
|
|
45
|
+
*/
|
|
46
|
+
fail(code: PaylovErrorCode, failure?: PaylovFakeFailure, schedule?: PaylovFakeSchedule): void;
|
|
47
|
+
/**
|
|
48
|
+
* Fails the attempt before any response: the call rejects with `PaylovConnectionError`
|
|
49
|
+
* `sdk_network_error`, and the outcome of a POST is unknown.
|
|
50
|
+
*
|
|
51
|
+
* @example
|
|
52
|
+
* fake.payments.pay.disconnect();
|
|
53
|
+
*/
|
|
54
|
+
disconnect(schedule?: PaylovFakeSchedule): void;
|
|
55
|
+
/**
|
|
56
|
+
* Never answers the attempt: the call rejects with `sdk_timeout` after `timeoutMs`, or with
|
|
57
|
+
* `sdk_aborted` when its signal aborts.
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* fake.payments.pay.hang();
|
|
61
|
+
*/
|
|
62
|
+
hang(schedule?: PaylovFakeSchedule): void;
|
|
63
|
+
/**
|
|
64
|
+
* The params of each attempt this method's answers served, in order, decoded from the request
|
|
65
|
+
* the SDK sent: wire names and units read back as the method's own params, so a retried GET
|
|
66
|
+
* appears once per attempt. It holds a full card number where the method's params do, which is
|
|
67
|
+
* your own test input; it never holds a password. A method that takes no params records
|
|
68
|
+
* `undefined`.
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* expect(fake.holds.capture.requests).toEqual([{ transactionId, amountTiyin: 150_000 }]);
|
|
72
|
+
*/
|
|
73
|
+
readonly requests: readonly P[];
|
|
74
|
+
}
|
|
75
|
+
/** The result type of an SDK method. */
|
|
76
|
+
type ResultOf<M> = M extends ((...args: never[]) => Promise<infer T>) ? T : never;
|
|
77
|
+
/** Never a password: the fake must not retain a credential. */
|
|
78
|
+
type RecordedParams<P> = P extends {
|
|
79
|
+
readonly password: unknown;
|
|
80
|
+
} ? Omit<P, "password"> : P;
|
|
81
|
+
/**
|
|
82
|
+
* What the fake records of a request. Every I/O method takes its call options last, so a method
|
|
83
|
+
* of at most one parameter takes only options and sends no params.
|
|
84
|
+
*/
|
|
85
|
+
type RequestOf<M> = M extends ((...args: infer A) => Promise<unknown>) ? [A["length"]] extends [0 | 1] ? undefined : RecordedParams<NonNullable<A[0]>> : never;
|
|
86
|
+
/** The I/O methods of surface `R`. */
|
|
87
|
+
type IoMethodOf<R> = { [K in keyof R]: R[K] extends ((...args: never[]) => Promise<unknown>) ? K : never; }[keyof R];
|
|
88
|
+
/** One script per I/O method of surface `R`, mirroring how the client exposes it. */
|
|
89
|
+
type PaylovFakeSurface<R> = { readonly [K in IoMethodOf<R>]: PaylovFakeMethod<ResultOf<R[K]>, RequestOf<R[K]>>; };
|
|
90
|
+
/** `'<namespace>.<method>'` for each I/O method of surface `R`, exposed as `namespace`. */
|
|
91
|
+
type MethodNameOf<Namespace extends string, R> = `${Namespace}.${IoMethodOf<R> & string}`;
|
|
92
|
+
/** The client surface behind each scripted namespace. */
|
|
93
|
+
interface ScriptedSurfaces {
|
|
94
|
+
readonly gateway: GatewayResource;
|
|
95
|
+
readonly cards: CardsResource;
|
|
96
|
+
readonly payments: PaymentsResource;
|
|
97
|
+
readonly transactions: TransactionsResource;
|
|
98
|
+
readonly holds: HoldsResource;
|
|
99
|
+
readonly splits: SplitsResource;
|
|
100
|
+
readonly fiscalization: FiscalizationResource;
|
|
101
|
+
readonly subMerchants: SubMerchantsResource;
|
|
102
|
+
readonly onboarding: PaylovOnboarding;
|
|
103
|
+
}
|
|
104
|
+
/** `'<namespace>.<method>'` of every scripted SDK method, such as `'payments.pay'`. */
|
|
105
|
+
type ScriptedMethod = { [K in keyof ScriptedSurfaces]: MethodNameOf<K, ScriptedSurfaces[K]>; }[keyof ScriptedSurfaces];
|
|
106
|
+
/** One request the fake received. */
|
|
107
|
+
interface PaylovFakeCall {
|
|
108
|
+
/**
|
|
109
|
+
* The SDK method whose scripted answer served the request, such as `'payments.pay'`; `null`
|
|
110
|
+
* for the token and revoke requests the fake answers itself and for requests no scripted
|
|
111
|
+
* answer served.
|
|
112
|
+
*/
|
|
113
|
+
readonly method: ScriptedMethod | null;
|
|
114
|
+
/** The route as logger events name it, such as `'GET /merchant/userCard/getCard/{cardId}/'`. */
|
|
115
|
+
readonly endpoint: string;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* An in-memory Paylov gateway for application tests. Pass `clientConfig` (or `onboardingConfig`)
|
|
119
|
+
* to the SDK, script each expected call through the namespace that
|
|
120
|
+
* mirrors the client, then call `assertDone()`. Answers run through the SDK's real transport and
|
|
121
|
+
* decoders, so retries, the token lifecycle, errors and result types behave as against the
|
|
122
|
+
* gateway. Token and revoke requests are answered automatically. Each method's `requests` holds
|
|
123
|
+
* the params its served requests carried; requests never reach logs or errors.
|
|
124
|
+
*
|
|
125
|
+
* One-time answers are served in the order they were scripted, each to the first request of its
|
|
126
|
+
* method; a persistent answer (`{ persist: true }`) serves every request of its method that no
|
|
127
|
+
* one-time answer takes. Methods that send to the same gateway endpoint are told apart by their
|
|
128
|
+
* request, so each answer reaches only its own method. An unscripted request fails with
|
|
129
|
+
* `PaylovApiError` `fake_unscripted`, and a request the fake cannot read back into its method's
|
|
130
|
+
* params with `fake_unreadable_request`, both at HTTP 501 and reported by `assertDone()`.
|
|
131
|
+
*
|
|
132
|
+
* @example
|
|
133
|
+
* import { PaylovClient } from '@isroilov_an/paylov';
|
|
134
|
+
* import { PaylovFakeGateway } from '@isroilov_an/paylov/testing';
|
|
135
|
+
*
|
|
136
|
+
* const fake = new PaylovFakeGateway();
|
|
137
|
+
* const paylov = new PaylovClient(fake.clientConfig);
|
|
138
|
+
* fake.payments.create.reply({ transactionId: '00000000-0000-4000-8000-000000000001' });
|
|
139
|
+
* fake.payments.pay.fail('insufficient_funds');
|
|
140
|
+
*
|
|
141
|
+
* await expect(checkout(paylov, order)).rejects.toMatchObject({ code: 'insufficient_funds' });
|
|
142
|
+
* fake.assertDone();
|
|
143
|
+
*/
|
|
144
|
+
export declare class PaylovFakeGateway {
|
|
145
|
+
#private;
|
|
146
|
+
readonly gateway: PaylovFakeSurface<GatewayResource>;
|
|
147
|
+
readonly cards: PaylovFakeSurface<CardsResource>;
|
|
148
|
+
readonly payments: PaylovFakeSurface<PaymentsResource>;
|
|
149
|
+
readonly transactions: PaylovFakeSurface<TransactionsResource>;
|
|
150
|
+
readonly holds: PaylovFakeSurface<HoldsResource>;
|
|
151
|
+
readonly splits: PaylovFakeSurface<SplitsResource>;
|
|
152
|
+
readonly fiscalization: PaylovFakeSurface<FiscalizationResource>;
|
|
153
|
+
readonly subMerchants: PaylovFakeSurface<SubMerchantsResource>;
|
|
154
|
+
readonly onboarding: PaylovFakeSurface<PaylovOnboarding>;
|
|
155
|
+
/** The `fetch` that answers from the script; the configurations below already carry it. */
|
|
156
|
+
readonly fetch: FetchLike;
|
|
157
|
+
/** A complete `PaylovClient` configuration with canary credentials; spread it to add options. */
|
|
158
|
+
readonly clientConfig: PaylovClientConfig;
|
|
159
|
+
/** A complete `PaylovOnboarding` configuration. */
|
|
160
|
+
readonly onboardingConfig: PaylovOnboardingConfig;
|
|
161
|
+
constructor();
|
|
162
|
+
/**
|
|
163
|
+
* Every request received so far, in order, token and revoke requests included. Each method's
|
|
164
|
+
* `requests` holds the params of its own requests.
|
|
165
|
+
*
|
|
166
|
+
* @example
|
|
167
|
+
* expect(fake.calls.map((call) => call.method)).toEqual([null, 'payments.create', 'payments.pay']);
|
|
168
|
+
*/
|
|
169
|
+
get calls(): readonly PaylovFakeCall[];
|
|
170
|
+
/**
|
|
171
|
+
* Throws when a request arrived unscripted or unreadable, or a scripted answer was never served.
|
|
172
|
+
*
|
|
173
|
+
* @example
|
|
174
|
+
* afterEach(() => fake.assertDone());
|
|
175
|
+
*/
|
|
176
|
+
assertDone(): void;
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* The request Paylov would send for `event`, authenticated with the receiver's credentials, so
|
|
180
|
+
* `receiver.receive(request)` returns `event`. Change the result to cover the `invalid`
|
|
181
|
+
* outcomes. Throws `TypeError` for a time the wire cannot carry (sub-second or before 1970).
|
|
182
|
+
*
|
|
183
|
+
* @example
|
|
184
|
+
* import { createWebhookRequest } from '@isroilov_an/paylov/testing';
|
|
185
|
+
*
|
|
186
|
+
* const request = createWebhookRequest(
|
|
187
|
+
* {
|
|
188
|
+
* kind: 'transaction.check',
|
|
189
|
+
* id: 1,
|
|
190
|
+
* account: { order_id: 'A-1024' },
|
|
191
|
+
* amount: { currency: 860, amountTiyin: 50_000 },
|
|
192
|
+
* },
|
|
193
|
+
* { login: webhookLogin, password: webhookPassword },
|
|
194
|
+
* );
|
|
195
|
+
* const response = await handleWebhook(request); // your handler around receiver.receive
|
|
196
|
+
*/
|
|
197
|
+
export declare function createWebhookRequest(event: WebhookEvent, credentials: PaylovWebhookReceiverConfig): WebhookInput;
|
|
198
|
+
export type { PaylovFakeCall, PaylovFakeFailure, PaylovFakeMethod, PaylovFakeSchedule, PaylovFakeSurface };
|