@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
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
/** The package's only public entry point; every other module is internal. */
|
|
2
|
+
import { $ as CreateHoldParams, $t as PaylovErrorCode, A as Transaction, At as CardProcessing, B as SplitRecipient, Bt as PanBindingStarted, C as PaylovClient, Ct as FiscalReceiptItemBase, D as GetRrnParams, Dt as CardBindLinkCreated, E as FiscalReceiptSummary, Et as Card, F as SubMerchantCreated, Ft as CreateBindLinkParams, G as CreatePaymentParams, Gt as PaylovCallOptions, H as SplitShare, Ht as StartPanBindingParams, I as SubMerchantOrganization, It as DeleteCardParams, J as PaymentRefunded, Jt as PaylovJsonValue, K as PanPaymentStarted, Kt as PaylovHttpMethod, L as SplitsResource, Lt as GetBindSessionParams, M as TransactionStatus, Mt as CardVendor, N as SubMerchantsResource, Nt as CheckCardPhoneParams, O as GetTransactionParams, Ot as CardBindSession, P as CreateSubMerchantParams, Pt as ConfirmPanBindingParams, Q as CaptureHoldParams, Qt as PaylovTransportConfig, R as CreateSplitParams, Rt as GetCardParams, S as CheckoutCurrency, St as FiscalReceiptItem, T as TransactionsResource, Tt as BoundCardBindSession, U as PaymentsResource, Ut as OtpSmsSettings, V as SplitRecipientStatus, Vt as PendingCardBindSession, W as ConfirmPanPaymentParams, Wt as FetchLike, X as StartPanPaymentParams, Xt as PaylovLoggerRequestEvent, Y as RefundPaymentParams, Yt as PaylovLogger, Z as HoldsResource, Zt as PaylovLoggerResponseEvent, _ as CheckOnboardingTokenParams, _t as RegisterCardFiscalReceiptParams, a as PaylovWebhookReceiverConfig, at as GatewayResource, b as PaylovOnboardingConfig, bt as TransactionLookup, c as TransactionPerformEvent, ct as ActivityTypeCheck, d as WebhookEvent, dt as FiscalActivityType, en as PaylovKnownErrorCode, et as GetHoldParams, f as WebhookInput, ft as FiscalReceipt, g as PaylovOnboarding, gt as RefundFiscalReceiptParams, h as WebhookResponseStatus, ht as GetFiscalReceiptParams, i as MerchantDepositEvent, it as ReleaseHoldParams, j as TransactionPage, jt as CardProcessingStatus, k as ListTransactionsParams, kt as CardBindStatus, l as WebhookCallbackId, lt as AttachFiscalReceiptParams, m as WebhookResponseBody, mt as FiscalReceiptRegistered, n as InvalidWebhook, nt as HoldCaptured, o as TransactionCancelEvent, ot as Bank, p as WebhookOutcome, pt as FiscalReceiptRefunded, q as PayPaymentParams, qt as PaylovJsonObject, r as InvalidWebhookReason, rt as HoldStatus, s as TransactionCheckEvent, st as FiscalizationResource, t as CardBindEvent, tt as Hold, u as WebhookDecision, ut as CheckActivityTypeParams, v as CompleteOnboardingParams, vt as RegisterCashFiscalReceiptParams, w as PaylovClientConfig, wt as CardsResource, x as CheckoutAmount, xt as TransactionReference, y as OnboardingCompleted, yt as RegisterFiscalReceiptParams, z as GetSplitParams, zt as ListCardsParams } from "./types-Bj9umT2M.js";
|
|
3
|
+
/** Parameters for {@link createCheckoutUrl}. */
|
|
4
|
+
interface CreateCheckoutUrlParams {
|
|
5
|
+
/** Public merchant id (UUID). */
|
|
6
|
+
readonly merchantId: string;
|
|
7
|
+
/** Amount in the minor unit of its currency, sent with `amount_in_tiyin=True`. */
|
|
8
|
+
readonly amount: CheckoutAmount;
|
|
9
|
+
/**
|
|
10
|
+
* Merchant order fields, sent as `account.<key>=<value>`. Paylov documents them in the
|
|
11
|
+
* `transaction.check` / `transaction.perform` callbacks, where the check handler matches its
|
|
12
|
+
* order by them, but its test environment stores none of them for a checkout: keep your own
|
|
13
|
+
* mapping from order to link too. Keys and values are limited to `A-Z a-z 0-9 . _ -`.
|
|
14
|
+
*/
|
|
15
|
+
readonly account: Readonly<Record<string, string>>;
|
|
16
|
+
/** Absolute `http(s)` URL the customer returns to. Paylov appends no payment outcome. */
|
|
17
|
+
readonly returnUrl: string;
|
|
18
|
+
/**
|
|
19
|
+
* `convert_to`: the currency the page converts the amount into, at the Central Bank rate, when
|
|
20
|
+
* the check is created. Each webhook states its own currency; the SDK expects the check and
|
|
21
|
+
* perform webhooks in the converted currency and amount, which Paylov does not state outright.
|
|
22
|
+
*/
|
|
23
|
+
readonly convertTo?: CheckoutCurrency;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Builds a hosted-checkout URL the customer opens in a browser. Pure: Paylov creates the check
|
|
27
|
+
* only when the page loads, so an unknown merchant or an out-of-range amount surfaces there.
|
|
28
|
+
* Moves no money; the customer pays on Paylov's page.
|
|
29
|
+
*
|
|
30
|
+
* The link is **not signed**: anyone who sees it can alter the amount, the currency or the
|
|
31
|
+
* account. Your `transaction.check` handler must re-validate all three against your own order
|
|
32
|
+
* record. The return redirect carries no outcome; rely on `transaction.perform`.
|
|
33
|
+
*
|
|
34
|
+
* @example
|
|
35
|
+
* const url = createCheckoutUrl({
|
|
36
|
+
* merchantId: paylovMerchantId,
|
|
37
|
+
* amount: { currency: 860, amountTiyin: 50_000 }, // 500.00 SUM
|
|
38
|
+
* account: { order_id: 'A-1001' },
|
|
39
|
+
* returnUrl: 'https://shop.example/checkout/return',
|
|
40
|
+
* });
|
|
41
|
+
*
|
|
42
|
+
* @throws {@link PaylovInputError} `sdk_invalid_amount` for the amount, `sdk_invalid_input` for
|
|
43
|
+
* any other field. Every failure is local; messages name the field, never a value.
|
|
44
|
+
*/
|
|
45
|
+
export declare function createCheckoutUrl(params: CreateCheckoutUrlParams): string;
|
|
46
|
+
/**
|
|
47
|
+
* Authenticates and decodes Paylov webhooks: checkout `transaction.check` and
|
|
48
|
+
* `transaction.perform`, the `transaction.cancel` and `merchant.deposit` notifications, and the
|
|
49
|
+
* Card Bind notification. Moves no money and keeps no state.
|
|
50
|
+
*
|
|
51
|
+
* `receive` never throws for anything a request carries. It checks `POST` and HTTP Basic
|
|
52
|
+
* credentials in constant time, then returns a decoded event or `{ kind: 'invalid', reason }`.
|
|
53
|
+
* The caller owns everything after:
|
|
54
|
+
* - answer check and perform with HTTP 200 and `createWebhookResponse(event, decision)`;
|
|
55
|
+
* - acknowledge `transaction.cancel`, `merchant.deposit` and `card.bind` with any 2xx once
|
|
56
|
+
* handled;
|
|
57
|
+
* - deduplicate: `transaction.perform` and `transaction.cancel` on `transactionId`,
|
|
58
|
+
* `merchant.deposit` on `depositId`, `card.bind` on `token`. Paylov retries cancel and deposit
|
|
59
|
+
* up to 3 times at 60 s intervals. It documents no retry of check and perform, and the SDK
|
|
60
|
+
* assumes none and that only an `accept` answer to perform completes the payment;
|
|
61
|
+
* - choose the HTTP response for invalid input; Paylov documents none.
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* const receiver = new PaylovWebhookReceiver({
|
|
65
|
+
* login: webhookLoginFromSecretManager,
|
|
66
|
+
* password: webhookPasswordFromSecretManager,
|
|
67
|
+
* });
|
|
68
|
+
* const event = receiver.receive({ method: req.method, headers: req.headers, body: rawBody });
|
|
69
|
+
* switch (event.kind) {
|
|
70
|
+
* case 'transaction.check':
|
|
71
|
+
* return reply(200, createWebhookResponse(event, await decideCheck(event)));
|
|
72
|
+
* case 'merchant.deposit':
|
|
73
|
+
* await recordDepositOnce(event.depositId, event.amountTiyin);
|
|
74
|
+
* return reply(200);
|
|
75
|
+
* case 'invalid':
|
|
76
|
+
* return reply(event.reason === 'unauthorized' ? 401 : 400);
|
|
77
|
+
* }
|
|
78
|
+
*
|
|
79
|
+
* @throws {@link PaylovInputError} `sdk_config_error` for a missing login or password, or a login
|
|
80
|
+
* containing a colon.
|
|
81
|
+
*/
|
|
82
|
+
export declare class PaylovWebhookReceiver {
|
|
83
|
+
#private;
|
|
84
|
+
constructor(config: PaylovWebhookReceiverConfig);
|
|
85
|
+
/**
|
|
86
|
+
* Authenticates and decodes one inbound webhook. Never throws for anything the request
|
|
87
|
+
* carries. Pass the body already read, as text, bytes or parsed JSON: an unread stream such as
|
|
88
|
+
* a Fetch `Request`'s `body` is answered `malformed_body`.
|
|
89
|
+
*
|
|
90
|
+
* @example
|
|
91
|
+
* const event = receiver.receive({
|
|
92
|
+
* method: request.method,
|
|
93
|
+
* headers: request.headers,
|
|
94
|
+
* body: new Uint8Array(await request.arrayBuffer()),
|
|
95
|
+
* });
|
|
96
|
+
* if (event.kind === 'transaction.cancel') await markCancelledOnce(event.transactionId);
|
|
97
|
+
*/
|
|
98
|
+
receive(input: WebhookInput): WebhookOutcome;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Builds the documented JSON-RPC answer to a `transaction.check` or `transaction.perform`
|
|
102
|
+
* event, with the status {@link WebhookDecision} maps `decision` to. Send it as the JSON body of
|
|
103
|
+
* an HTTP 200. Moves no money; for perform, answer `accept` only after the payment is applied to
|
|
104
|
+
* the order.
|
|
105
|
+
*
|
|
106
|
+
* @throws {@link PaylovInputError} `sdk_invalid_input` for an event that is not a check or
|
|
107
|
+
* perform event with a JSON-RPC id, or an unknown decision or a blank custom text.
|
|
108
|
+
*
|
|
109
|
+
* @example
|
|
110
|
+
* const order = await orders.find(event.account);
|
|
111
|
+
* const decision = order === undefined ? 'order_not_found' : 'accept';
|
|
112
|
+
* reply(200, createWebhookResponse(event, decision));
|
|
113
|
+
*/
|
|
114
|
+
export declare function createWebhookResponse(event: TransactionCheckEvent | TransactionPerformEvent, decision: WebhookDecision): WebhookResponseBody;
|
|
115
|
+
/** Where a failure came from. */
|
|
116
|
+
type PaylovErrorKind = "input" | "closed" | "api" | "protocol" | "connection";
|
|
117
|
+
/**
|
|
118
|
+
* Rejected locally, before any I/O:
|
|
119
|
+
* - `sdk_invalid_input`: a method parameter broke a rule.
|
|
120
|
+
* - `sdk_invalid_amount`: an amount is not a valid integer amount for that call.
|
|
121
|
+
* - `sdk_config_error`: constructor configuration broke a rule.
|
|
122
|
+
*/
|
|
123
|
+
type PaylovInputErrorCode = "sdk_invalid_input" | "sdk_invalid_amount" | "sdk_config_error";
|
|
124
|
+
/** The rule a rejected input broke. */
|
|
125
|
+
type PaylovInputRule = "required" | "type" | "format" | "range" | "exclusive";
|
|
126
|
+
/**
|
|
127
|
+
* - `sdk_malformed_response`: a 2xx body did not match the endpoint's documented shape.
|
|
128
|
+
* - `sdk_unexpected_status`: a non-2xx without a usable error body, for example a proxy page or
|
|
129
|
+
* a bare 401/403.
|
|
130
|
+
*/
|
|
131
|
+
type PaylovProtocolErrorCode = "sdk_malformed_response" | "sdk_unexpected_status";
|
|
132
|
+
/** `sdk_aborted`: the caller's `signal` fired; `isSent` tells whether a request had left. */
|
|
133
|
+
type PaylovConnectionErrorCode = "sdk_timeout" | "sdk_network_error" | "sdk_aborted";
|
|
134
|
+
/** The metadata `toJSON()` returns; safe to log. Details an error lacks are `undefined`. */
|
|
135
|
+
interface PaylovErrorDiagnostic {
|
|
136
|
+
readonly name: string;
|
|
137
|
+
readonly kind: PaylovErrorKind;
|
|
138
|
+
readonly code: PaylovErrorCode;
|
|
139
|
+
readonly message: string;
|
|
140
|
+
readonly httpStatus?: number;
|
|
141
|
+
readonly endpoint?: string;
|
|
142
|
+
readonly field?: string | undefined;
|
|
143
|
+
readonly rule?: PaylovInputRule | undefined;
|
|
144
|
+
readonly fields?: readonly string[] | undefined;
|
|
145
|
+
readonly retryAfterSeconds?: number | undefined;
|
|
146
|
+
readonly path?: string | undefined;
|
|
147
|
+
readonly timeoutMs?: number | undefined;
|
|
148
|
+
readonly isSent?: boolean;
|
|
149
|
+
}
|
|
150
|
+
type DiagnosticDetails = Omit<PaylovErrorDiagnostic, "name" | "kind" | "code" | "message">;
|
|
151
|
+
/** The shared base of the five error classes; consumers use the {@link PaylovError} union. */
|
|
152
|
+
declare abstract class PaylovBaseError extends Error {
|
|
153
|
+
abstract override readonly name: string;
|
|
154
|
+
abstract readonly kind: PaylovErrorKind;
|
|
155
|
+
abstract readonly code: string;
|
|
156
|
+
constructor(message: string);
|
|
157
|
+
/**
|
|
158
|
+
* Returns SDK diagnostic metadata only.
|
|
159
|
+
*
|
|
160
|
+
* @example
|
|
161
|
+
* logger.error('paylov call failed', error.toJSON());
|
|
162
|
+
*/
|
|
163
|
+
toJSON(): PaylovErrorDiagnostic;
|
|
164
|
+
protected abstract diagnosticDetails(): DiagnosticDetails;
|
|
165
|
+
}
|
|
166
|
+
interface PaylovInputErrorInit {
|
|
167
|
+
readonly code: PaylovInputErrorCode;
|
|
168
|
+
readonly message: string;
|
|
169
|
+
readonly field: string | undefined;
|
|
170
|
+
readonly rule: PaylovInputRule;
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* The SDK rejected a call locally, before any I/O: a parameter, an amount or the configuration
|
|
174
|
+
* broke a rule. This is an integration bug, never a gateway answer. Messages name the field,
|
|
175
|
+
* never its value.
|
|
176
|
+
*
|
|
177
|
+
* @example
|
|
178
|
+
* catch (error) {
|
|
179
|
+
* if (error instanceof PaylovInputError) logger.error('invalid paylov call', error.toJSON());
|
|
180
|
+
* throw error;
|
|
181
|
+
* }
|
|
182
|
+
*/
|
|
183
|
+
export declare class PaylovInputError extends PaylovBaseError {
|
|
184
|
+
override readonly name: "PaylovInputError";
|
|
185
|
+
readonly kind: "input";
|
|
186
|
+
readonly code: PaylovInputErrorCode;
|
|
187
|
+
/**
|
|
188
|
+
* SDK parameter path such as `items[0].priceTiyin`; `undefined` when the params or
|
|
189
|
+
* configuration object itself, or a choice between its top-level keys, broke the rule.
|
|
190
|
+
*/
|
|
191
|
+
readonly field: string | undefined;
|
|
192
|
+
readonly rule: PaylovInputRule;
|
|
193
|
+
constructor(init: PaylovInputErrorInit);
|
|
194
|
+
protected diagnosticDetails(): DiagnosticDetails;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* The client was closed with `close()`. Nothing was sent, or the gateway rejected the request
|
|
198
|
+
* before running it; a new client, on this process or another, can make the call.
|
|
199
|
+
*
|
|
200
|
+
* @example
|
|
201
|
+
* catch (error) {
|
|
202
|
+
* if (error instanceof PaylovClientClosedError) return serviceUnavailable();
|
|
203
|
+
* throw error;
|
|
204
|
+
* }
|
|
205
|
+
*/
|
|
206
|
+
export declare class PaylovClientClosedError extends PaylovBaseError {
|
|
207
|
+
override readonly name: "PaylovClientClosedError";
|
|
208
|
+
readonly kind: "closed";
|
|
209
|
+
readonly code: "sdk_client_closed";
|
|
210
|
+
constructor();
|
|
211
|
+
protected diagnosticDetails(): DiagnosticDetails;
|
|
212
|
+
}
|
|
213
|
+
interface PaylovApiErrorInit {
|
|
214
|
+
readonly code: PaylovErrorCode;
|
|
215
|
+
readonly httpStatus: number;
|
|
216
|
+
readonly endpoint: string;
|
|
217
|
+
readonly fields?: readonly string[] | undefined;
|
|
218
|
+
readonly retryAfterSeconds?: number | undefined;
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* The gateway answered with an error code. Unknown codes keep this class; narrow with
|
|
222
|
+
* {@link isPaylovApiError}.
|
|
223
|
+
*
|
|
224
|
+
* @example
|
|
225
|
+
* catch (error) {
|
|
226
|
+
* if (isPaylovApiError(error, 'rate_limit_exceeded')) await wait(error.retryAfterSeconds ?? 60);
|
|
227
|
+
* else throw error;
|
|
228
|
+
* }
|
|
229
|
+
*/
|
|
230
|
+
export declare class PaylovApiError extends PaylovBaseError {
|
|
231
|
+
override readonly name: "PaylovApiError";
|
|
232
|
+
readonly kind: "api";
|
|
233
|
+
readonly code: PaylovErrorCode;
|
|
234
|
+
readonly httpStatus: number;
|
|
235
|
+
/** Static endpoint identity, e.g. `"POST /merchant/receipts/pay/"`. */
|
|
236
|
+
readonly endpoint: string;
|
|
237
|
+
/**
|
|
238
|
+
* Wire field paths such as `items.0.title`, for `validation_error`, `field_not_valid` and
|
|
239
|
+
* `field_required` only. Names, never messages or values; not translated to SDK names.
|
|
240
|
+
*/
|
|
241
|
+
readonly fields: readonly string[] | undefined;
|
|
242
|
+
/**
|
|
243
|
+
* Seconds until a retry can succeed, from 1 to 3600: for `rate_limit_exceeded`, from the
|
|
244
|
+
* `Retry-After` header (nothing retries a 429); for `card_is_blocked`,
|
|
245
|
+
* the rest of the card's block after repeated wrong one-time codes.
|
|
246
|
+
*/
|
|
247
|
+
readonly retryAfterSeconds: number | undefined;
|
|
248
|
+
constructor(init: PaylovApiErrorInit);
|
|
249
|
+
protected diagnosticDetails(): DiagnosticDetails;
|
|
250
|
+
}
|
|
251
|
+
interface PaylovProtocolErrorInit {
|
|
252
|
+
readonly code: PaylovProtocolErrorCode;
|
|
253
|
+
readonly httpStatus: number;
|
|
254
|
+
readonly endpoint: string;
|
|
255
|
+
readonly path?: string | undefined;
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* The response did not match the endpoint's declared contract. After a POST the operation may
|
|
259
|
+
* have executed: reconcile through the method's documented status read.
|
|
260
|
+
*
|
|
261
|
+
* @example
|
|
262
|
+
* catch (error) {
|
|
263
|
+
* if (error instanceof PaylovProtocolError) metrics.increment('paylov.protocol', error.toJSON());
|
|
264
|
+
* throw error;
|
|
265
|
+
* }
|
|
266
|
+
*/
|
|
267
|
+
export declare class PaylovProtocolError extends PaylovBaseError {
|
|
268
|
+
override readonly name: "PaylovProtocolError";
|
|
269
|
+
readonly kind: "protocol";
|
|
270
|
+
readonly code: PaylovProtocolErrorCode;
|
|
271
|
+
readonly httpStatus: number;
|
|
272
|
+
readonly endpoint: string;
|
|
273
|
+
/** The decoded location that failed, e.g. `result.card.status`; never its value. */
|
|
274
|
+
readonly path: string | undefined;
|
|
275
|
+
constructor(init: PaylovProtocolErrorInit);
|
|
276
|
+
protected diagnosticDetails(): DiagnosticDetails;
|
|
277
|
+
}
|
|
278
|
+
interface PaylovConnectionErrorInit {
|
|
279
|
+
readonly code: PaylovConnectionErrorCode;
|
|
280
|
+
readonly endpoint: string;
|
|
281
|
+
readonly isSent: boolean;
|
|
282
|
+
readonly timeoutMs?: number | undefined;
|
|
283
|
+
}
|
|
284
|
+
/**
|
|
285
|
+
* No usable response: DNS, TCP or TLS failure, a reset, the SDK timeout, or the caller's abort.
|
|
286
|
+
* The underlying error is discarded: an injected transport can embed URLs, headers, bodies and
|
|
287
|
+
* credentials anywhere in it. Once `isSent`, the operation of a POST may have executed.
|
|
288
|
+
*
|
|
289
|
+
* @example
|
|
290
|
+
* catch (error) {
|
|
291
|
+
* if (error instanceof PaylovConnectionError && error.code === 'sdk_timeout') {
|
|
292
|
+
* metrics.increment('paylov.timeout', { endpoint: error.endpoint });
|
|
293
|
+
* }
|
|
294
|
+
* throw error;
|
|
295
|
+
* }
|
|
296
|
+
*/
|
|
297
|
+
export declare class PaylovConnectionError extends PaylovBaseError {
|
|
298
|
+
override readonly name: "PaylovConnectionError";
|
|
299
|
+
readonly kind: "connection";
|
|
300
|
+
readonly code: PaylovConnectionErrorCode;
|
|
301
|
+
readonly endpoint: string;
|
|
302
|
+
/**
|
|
303
|
+
* Whether an attempt of the call reached the transport. `false` only for an `sdk_aborted` that
|
|
304
|
+
* fired before anything was sent, so nothing can have executed.
|
|
305
|
+
*/
|
|
306
|
+
readonly isSent: boolean;
|
|
307
|
+
/** For `sdk_timeout` only: the per-attempt deadline that expired. */
|
|
308
|
+
readonly timeoutMs: number | undefined;
|
|
309
|
+
constructor(init: PaylovConnectionErrorInit);
|
|
310
|
+
protected diagnosticDetails(): DiagnosticDetails;
|
|
311
|
+
}
|
|
312
|
+
/**
|
|
313
|
+
* Anything this SDK throws. Narrow with {@link isPaylovError}, check
|
|
314
|
+
* {@link isPaylovOutcomeUnknown} (a gateway 5xx counts too), then switch on `kind` and `code`.
|
|
315
|
+
*
|
|
316
|
+
* @example
|
|
317
|
+
* catch (error) {
|
|
318
|
+
* if (!isPaylovError(error)) throw error;
|
|
319
|
+
* if (isPaylovOutcomeUnknown(error)) return reconcileLater();
|
|
320
|
+
* switch (error.kind) {
|
|
321
|
+
* case 'closed':
|
|
322
|
+
* return serviceUnavailable();
|
|
323
|
+
* case 'api':
|
|
324
|
+
* if (error.code === 'insufficient_funds') return declined();
|
|
325
|
+
* break;
|
|
326
|
+
* }
|
|
327
|
+
* throw error;
|
|
328
|
+
* }
|
|
329
|
+
*/
|
|
330
|
+
type PaylovError = PaylovInputError | PaylovClientClosedError | PaylovApiError | PaylovProtocolError | PaylovConnectionError;
|
|
331
|
+
/**
|
|
332
|
+
* True for anything this SDK throws; narrows to the {@link PaylovError} union.
|
|
333
|
+
*
|
|
334
|
+
* @example
|
|
335
|
+
* catch (error) {
|
|
336
|
+
* if (!isPaylovError(error)) throw error;
|
|
337
|
+
* metrics.increment('paylov.failure', { kind: error.kind, code: error.code });
|
|
338
|
+
* }
|
|
339
|
+
*/
|
|
340
|
+
export declare function isPaylovError(error: unknown): error is PaylovError;
|
|
341
|
+
/**
|
|
342
|
+
* True when the operation may have executed although the call failed: a protocol error, a
|
|
343
|
+
* connection error once a request was sent, or a gateway error with HTTP status 500 or above.
|
|
344
|
+
* Reconcile such a call through the method's documented status read before repeating it. False
|
|
345
|
+
* for input and closed-client errors, for an abort before anything was sent, for other gateway
|
|
346
|
+
* errors, and for anything the SDK did not throw.
|
|
347
|
+
*
|
|
348
|
+
* @example
|
|
349
|
+
* catch (error) {
|
|
350
|
+
* if (isPaylovOutcomeUnknown(error)) return queueReconciliation(transactionId);
|
|
351
|
+
* throw error;
|
|
352
|
+
* }
|
|
353
|
+
*/
|
|
354
|
+
export declare function isPaylovOutcomeUnknown(error: unknown): boolean;
|
|
355
|
+
/**
|
|
356
|
+
* True for a gateway error code; with codes, only for one of those codes.
|
|
357
|
+
*
|
|
358
|
+
* @example
|
|
359
|
+
* catch (error) {
|
|
360
|
+
* if (isPaylovApiError(error, 'transaction_already_payed')) return markPaid(transactionId);
|
|
361
|
+
* throw error;
|
|
362
|
+
* }
|
|
363
|
+
*/
|
|
364
|
+
export declare function isPaylovApiError(error: unknown): error is PaylovApiError;
|
|
365
|
+
export declare function isPaylovApiError<C extends PaylovKnownErrorCode>(error: unknown, ...codes: [C, ...C[]]): error is PaylovApiError & {
|
|
366
|
+
readonly code: C;
|
|
367
|
+
};
|
|
368
|
+
/**
|
|
369
|
+
* Converts SUM to tiyin exactly: a whole-SUM safe integer, or a decimal string with at most two
|
|
370
|
+
* fraction digits. Pass a string for fractional SUM; a fractional number is rejected.
|
|
371
|
+
*
|
|
372
|
+
* @throws {@link PaylovInputError} `sdk_invalid_amount` for a negative, fractional or unsafe
|
|
373
|
+
* number, a malformed string, or a result too large to express in tiyin.
|
|
374
|
+
*
|
|
375
|
+
* @example
|
|
376
|
+
* sumToTiyin(1000); // 100000
|
|
377
|
+
* sumToTiyin('12.5'); // 1250
|
|
378
|
+
* sumToTiyin(10.5); // throws PaylovInputError sdk_invalid_amount
|
|
379
|
+
*/
|
|
380
|
+
export declare function sumToTiyin(sum: number | string): number;
|
|
381
|
+
/**
|
|
382
|
+
* Formats a tiyin amount for display: ASCII-space thousands, `.` decimals, always two decimals.
|
|
383
|
+
* Locale-independent, so output is identical on every Node ICU build. Never send it on the wire.
|
|
384
|
+
*
|
|
385
|
+
* @throws {@link PaylovInputError} `sdk_invalid_amount` when `amountTiyin` is not a non-negative
|
|
386
|
+
* safe integer, so validate computed values such as balance deltas before display.
|
|
387
|
+
*
|
|
388
|
+
* @example
|
|
389
|
+
* formatSum(2_500_000); // '25 000.00'
|
|
390
|
+
* formatSum(5); // '0.05'
|
|
391
|
+
*/
|
|
392
|
+
export declare function formatSum(amountTiyin: number): string;
|
|
393
|
+
export { type ActivityTypeCheck, type AttachFiscalReceiptParams, type Bank, type BoundCardBindSession, type CaptureHoldParams, type Card, type CardBindEvent, type CardBindLinkCreated, type CardBindSession, type CardBindStatus, type CardProcessing, type CardProcessingStatus, type CardVendor, type CardsResource, type CheckActivityTypeParams, type CheckCardPhoneParams, type CheckOnboardingTokenParams, type CheckoutAmount, type CheckoutCurrency, type CompleteOnboardingParams, type ConfirmPanBindingParams, type ConfirmPanPaymentParams, type CreateBindLinkParams, type CreateCheckoutUrlParams, type CreateHoldParams, type CreatePaymentParams, type CreateSplitParams, type CreateSubMerchantParams, type DeleteCardParams, type FetchLike, type FiscalActivityType, type FiscalReceipt, type FiscalReceiptItem, type FiscalReceiptItemBase, type FiscalReceiptRefunded, type FiscalReceiptRegistered, type FiscalReceiptSummary, type FiscalizationResource, type GatewayResource, type GetBindSessionParams, type GetCardParams, type GetFiscalReceiptParams, type GetHoldParams, type GetRrnParams, type GetSplitParams, type GetTransactionParams, type Hold, type HoldCaptured, type HoldStatus, type HoldsResource, type InvalidWebhook, type InvalidWebhookReason, type ListCardsParams, type ListTransactionsParams, type MerchantDepositEvent, type OnboardingCompleted, type OtpSmsSettings, type PanBindingStarted, type PanPaymentStarted, type PayPaymentParams, type PaylovCallOptions, PaylovClient, type PaylovClientConfig, type PaylovConnectionErrorCode, type PaylovError, type PaylovErrorCode, type PaylovErrorDiagnostic, type PaylovErrorKind, type PaylovHttpMethod, type PaylovInputErrorCode, type PaylovInputRule, type PaylovJsonObject, type PaylovJsonValue, type PaylovKnownErrorCode, type PaylovLogger, type PaylovLoggerRequestEvent, type PaylovLoggerResponseEvent, PaylovOnboarding, type PaylovOnboardingConfig, type PaylovProtocolErrorCode, type PaylovTransportConfig, type PaylovWebhookReceiverConfig, type PaymentRefunded, type PaymentsResource, type PendingCardBindSession, type RefundFiscalReceiptParams, type RefundPaymentParams, type RegisterCardFiscalReceiptParams, type RegisterCashFiscalReceiptParams, type RegisterFiscalReceiptParams, type ReleaseHoldParams, type SplitRecipient, type SplitRecipientStatus, type SplitShare, type SplitsResource, type StartPanBindingParams, type StartPanPaymentParams, type SubMerchantCreated, type SubMerchantOrganization, type SubMerchantsResource, type Transaction, type TransactionCancelEvent, type TransactionCheckEvent, type TransactionLookup, type TransactionPage, type TransactionPerformEvent, type TransactionReference, type TransactionStatus, type TransactionsResource, type WebhookCallbackId, type WebhookDecision, type WebhookEvent, type WebhookInput, type WebhookOutcome, type WebhookResponseBody, type WebhookResponseStatus };
|