@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.
@@ -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 };