@sakeetech/viva-payments-core 0.2.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/LICENSE +21 -0
- package/README.md +413 -0
- package/dist/auth/http.d.ts +44 -0
- package/dist/auth/http.d.ts.map +1 -0
- package/dist/auth/http.js +80 -0
- package/dist/auth/http.js.map +1 -0
- package/dist/auth/index.d.ts +19 -0
- package/dist/auth/index.d.ts.map +1 -0
- package/dist/auth/index.js +18 -0
- package/dist/auth/index.js.map +1 -0
- package/dist/auth/oauth2-strategy.d.ts +117 -0
- package/dist/auth/oauth2-strategy.d.ts.map +1 -0
- package/dist/auth/oauth2-strategy.js +217 -0
- package/dist/auth/oauth2-strategy.js.map +1 -0
- package/dist/auth/reseller-strategy.d.ts +65 -0
- package/dist/auth/reseller-strategy.d.ts.map +1 -0
- package/dist/auth/reseller-strategy.js +68 -0
- package/dist/auth/reseller-strategy.js.map +1 -0
- package/dist/auth/single-flight.d.ts +81 -0
- package/dist/auth/single-flight.d.ts.map +1 -0
- package/dist/auth/single-flight.js +160 -0
- package/dist/auth/single-flight.js.map +1 -0
- package/dist/auth/token-cache.d.ts +50 -0
- package/dist/auth/token-cache.d.ts.map +1 -0
- package/dist/auth/token-cache.js +59 -0
- package/dist/auth/token-cache.js.map +1 -0
- package/dist/errors/api-error.d.ts +15 -0
- package/dist/errors/api-error.d.ts.map +1 -0
- package/dist/errors/api-error.js +18 -0
- package/dist/errors/api-error.js.map +1 -0
- package/dist/errors/auth-error.d.ts +14 -0
- package/dist/errors/auth-error.d.ts.map +1 -0
- package/dist/errors/auth-error.js +17 -0
- package/dist/errors/auth-error.js.map +1 -0
- package/dist/errors/base.d.ts +59 -0
- package/dist/errors/base.d.ts.map +1 -0
- package/dist/errors/base.js +51 -0
- package/dist/errors/base.js.map +1 -0
- package/dist/errors/index.d.ts +18 -0
- package/dist/errors/index.d.ts.map +1 -0
- package/dist/errors/index.js +16 -0
- package/dist/errors/index.js.map +1 -0
- package/dist/errors/mode-mismatch-error.d.ts +19 -0
- package/dist/errors/mode-mismatch-error.d.ts.map +1 -0
- package/dist/errors/mode-mismatch-error.js +22 -0
- package/dist/errors/mode-mismatch-error.js.map +1 -0
- package/dist/errors/rate-limit-error.d.ts +20 -0
- package/dist/errors/rate-limit-error.d.ts.map +1 -0
- package/dist/errors/rate-limit-error.js +20 -0
- package/dist/errors/rate-limit-error.js.map +1 -0
- package/dist/errors/validation-error.d.ts +14 -0
- package/dist/errors/validation-error.d.ts.map +1 -0
- package/dist/errors/validation-error.js +17 -0
- package/dist/errors/validation-error.js.map +1 -0
- package/dist/errors/webhook-error.d.ts +14 -0
- package/dist/errors/webhook-error.d.ts.map +1 -0
- package/dist/errors/webhook-error.js +17 -0
- package/dist/errors/webhook-error.js.map +1 -0
- package/dist/index.d.ts +15 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/dist/isv/accounts.d.ts +38 -0
- package/dist/isv/accounts.d.ts.map +1 -0
- package/dist/isv/accounts.js +60 -0
- package/dist/isv/accounts.js.map +1 -0
- package/dist/isv/client.d.ts +187 -0
- package/dist/isv/client.d.ts.map +1 -0
- package/dist/isv/client.js +465 -0
- package/dist/isv/client.js.map +1 -0
- package/dist/isv/index.d.ts +52 -0
- package/dist/isv/index.d.ts.map +1 -0
- package/dist/isv/index.js +53 -0
- package/dist/isv/index.js.map +1 -0
- package/dist/isv/legacy-basic-client.d.ts +122 -0
- package/dist/isv/legacy-basic-client.d.ts.map +1 -0
- package/dist/isv/legacy-basic-client.js +281 -0
- package/dist/isv/legacy-basic-client.js.map +1 -0
- package/dist/isv/payments.d.ts +199 -0
- package/dist/isv/payments.d.ts.map +1 -0
- package/dist/isv/payments.js +385 -0
- package/dist/isv/payments.js.map +1 -0
- package/dist/isv/sources.d.ts +80 -0
- package/dist/isv/sources.d.ts.map +1 -0
- package/dist/isv/sources.js +112 -0
- package/dist/isv/sources.js.map +1 -0
- package/dist/isv/webhooks-api.d.ts +48 -0
- package/dist/isv/webhooks-api.d.ts.map +1 -0
- package/dist/isv/webhooks-api.js +66 -0
- package/dist/isv/webhooks-api.js.map +1 -0
- package/dist/legacy/client.d.ts +199 -0
- package/dist/legacy/client.d.ts.map +1 -0
- package/dist/legacy/client.js +351 -0
- package/dist/legacy/client.js.map +1 -0
- package/dist/legacy/index.d.ts +15 -0
- package/dist/legacy/index.d.ts.map +1 -0
- package/dist/legacy/index.js +14 -0
- package/dist/legacy/index.js.map +1 -0
- package/dist/observability/context.d.ts +30 -0
- package/dist/observability/context.d.ts.map +1 -0
- package/dist/observability/context.js +40 -0
- package/dist/observability/context.js.map +1 -0
- package/dist/observability/index.d.ts +15 -0
- package/dist/observability/index.d.ts.map +1 -0
- package/dist/observability/index.js +11 -0
- package/dist/observability/index.js.map +1 -0
- package/dist/observability/logger.d.ts +81 -0
- package/dist/observability/logger.d.ts.map +1 -0
- package/dist/observability/logger.js +127 -0
- package/dist/observability/logger.js.map +1 -0
- package/dist/observability/metrics.d.ts +37 -0
- package/dist/observability/metrics.d.ts.map +1 -0
- package/dist/observability/metrics.js +40 -0
- package/dist/observability/metrics.js.map +1 -0
- package/dist/observability/redact.d.ts +21 -0
- package/dist/observability/redact.d.ts.map +1 -0
- package/dist/observability/redact.js +72 -0
- package/dist/observability/redact.js.map +1 -0
- package/dist/observability/tracer.d.ts +25 -0
- package/dist/observability/tracer.d.ts.map +1 -0
- package/dist/observability/tracer.js +18 -0
- package/dist/observability/tracer.js.map +1 -0
- package/dist/payments/client.d.ts +247 -0
- package/dist/payments/client.d.ts.map +1 -0
- package/dist/payments/client.js +488 -0
- package/dist/payments/client.js.map +1 -0
- package/dist/payments/index.d.ts +14 -0
- package/dist/payments/index.d.ts.map +1 -0
- package/dist/payments/index.js +13 -0
- package/dist/payments/index.js.map +1 -0
- package/dist/refunds/fast-refund-client.d.ts +128 -0
- package/dist/refunds/fast-refund-client.d.ts.map +1 -0
- package/dist/refunds/fast-refund-client.js +138 -0
- package/dist/refunds/fast-refund-client.js.map +1 -0
- package/dist/refunds/index.d.ts +19 -0
- package/dist/refunds/index.d.ts.map +1 -0
- package/dist/refunds/index.js +17 -0
- package/dist/refunds/index.js.map +1 -0
- package/dist/refunds/strategy.d.ts +78 -0
- package/dist/refunds/strategy.d.ts.map +1 -0
- package/dist/refunds/strategy.js +75 -0
- package/dist/refunds/strategy.js.map +1 -0
- package/dist/types/auth.d.ts +80 -0
- package/dist/types/auth.d.ts.map +1 -0
- package/dist/types/auth.js +12 -0
- package/dist/types/auth.js.map +1 -0
- package/dist/types/card-types.d.ts +48 -0
- package/dist/types/card-types.d.ts.map +1 -0
- package/dist/types/card-types.js +62 -0
- package/dist/types/card-types.js.map +1 -0
- package/dist/types/common.d.ts +160 -0
- package/dist/types/common.d.ts.map +1 -0
- package/dist/types/common.js +70 -0
- package/dist/types/common.js.map +1 -0
- package/dist/types/index.d.ts +21 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/types/index.js +21 -0
- package/dist/types/index.js.map +1 -0
- package/dist/types/isv-accounts.d.ts +109 -0
- package/dist/types/isv-accounts.d.ts.map +1 -0
- package/dist/types/isv-accounts.js +22 -0
- package/dist/types/isv-accounts.js.map +1 -0
- package/dist/types/isv-payments.d.ts +262 -0
- package/dist/types/isv-payments.d.ts.map +1 -0
- package/dist/types/isv-payments.js +19 -0
- package/dist/types/isv-payments.js.map +1 -0
- package/dist/types/status.d.ts +125 -0
- package/dist/types/status.d.ts.map +1 -0
- package/dist/types/status.js +19 -0
- package/dist/types/status.js.map +1 -0
- package/dist/types/webhook-events.d.ts +447 -0
- package/dist/types/webhook-events.d.ts.map +1 -0
- package/dist/types/webhook-events.js +76 -0
- package/dist/types/webhook-events.js.map +1 -0
- package/dist/webhooks/challenge-response.d.ts +28 -0
- package/dist/webhooks/challenge-response.d.ts.map +1 -0
- package/dist/webhooks/challenge-response.js +35 -0
- package/dist/webhooks/challenge-response.js.map +1 -0
- package/dist/webhooks/event-types.d.ts +44 -0
- package/dist/webhooks/event-types.d.ts.map +1 -0
- package/dist/webhooks/event-types.js +50 -0
- package/dist/webhooks/event-types.js.map +1 -0
- package/dist/webhooks/extract-client-ip.d.ts +40 -0
- package/dist/webhooks/extract-client-ip.d.ts.map +1 -0
- package/dist/webhooks/extract-client-ip.js +72 -0
- package/dist/webhooks/extract-client-ip.js.map +1 -0
- package/dist/webhooks/hmac-verify.d.ts +38 -0
- package/dist/webhooks/hmac-verify.d.ts.map +1 -0
- package/dist/webhooks/hmac-verify.js +92 -0
- package/dist/webhooks/hmac-verify.js.map +1 -0
- package/dist/webhooks/index.d.ts +19 -0
- package/dist/webhooks/index.d.ts.map +1 -0
- package/dist/webhooks/index.js +19 -0
- package/dist/webhooks/index.js.map +1 -0
- package/dist/webhooks/ip-allowlist.d.ts +59 -0
- package/dist/webhooks/ip-allowlist.d.ts.map +1 -0
- package/dist/webhooks/ip-allowlist.js +147 -0
- package/dist/webhooks/ip-allowlist.js.map +1 -0
- package/dist/webhooks/status-lattice.d.ts +72 -0
- package/dist/webhooks/status-lattice.d.ts.map +1 -0
- package/dist/webhooks/status-lattice.js +208 -0
- package/dist/webhooks/status-lattice.js.map +1 -0
- package/package.json +85 -0
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { VivaError, type VivaErrorOptions } from './base.js';
|
|
2
|
+
/**
|
|
3
|
+
* Thrown for local pre-flight validation failures.
|
|
4
|
+
*
|
|
5
|
+
* Examples: multi-tenant cart rejected at `initiatePayment` (plan P19),
|
|
6
|
+
* amount out of range, missing required field before the HTTP call is made.
|
|
7
|
+
*
|
|
8
|
+
* Maps to `MedusaError(Types.INVALID_DATA)` in the adapter layer.
|
|
9
|
+
*/
|
|
10
|
+
export declare class VivaValidationError extends VivaError {
|
|
11
|
+
readonly code: "VIVA_VALIDATION_ERROR";
|
|
12
|
+
constructor(opts: VivaErrorOptions);
|
|
13
|
+
}
|
|
14
|
+
//# sourceMappingURL=validation-error.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validation-error.d.ts","sourceRoot":"","sources":["../../src/errors/validation-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IAChD,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAU;gBAErC,IAAI,EAAE,gBAAgB;CAInC"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { VivaError } from './base.js';
|
|
2
|
+
/**
|
|
3
|
+
* Thrown for local pre-flight validation failures.
|
|
4
|
+
*
|
|
5
|
+
* Examples: multi-tenant cart rejected at `initiatePayment` (plan P19),
|
|
6
|
+
* amount out of range, missing required field before the HTTP call is made.
|
|
7
|
+
*
|
|
8
|
+
* Maps to `MedusaError(Types.INVALID_DATA)` in the adapter layer.
|
|
9
|
+
*/
|
|
10
|
+
export class VivaValidationError extends VivaError {
|
|
11
|
+
code = 'VIVA_VALIDATION_ERROR';
|
|
12
|
+
constructor(opts) {
|
|
13
|
+
super(opts);
|
|
14
|
+
this.name = 'VivaValidationError';
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
//# sourceMappingURL=validation-error.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validation-error.js","sourceRoot":"","sources":["../../src/errors/validation-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACvC,IAAI,GAAG,uBAAgC,CAAC;IAEjD,YAAY,IAAsB;QAChC,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { VivaError, type VivaErrorOptions } from './base.js';
|
|
2
|
+
/**
|
|
3
|
+
* Thrown when webhook verification or shape validation fails.
|
|
4
|
+
*
|
|
5
|
+
* Covers: HMAC signature mismatch, unknown event type, malformed payload,
|
|
6
|
+
* IP allowlist rejection (layer a), challenge-response failure (layer b).
|
|
7
|
+
*
|
|
8
|
+
* The webhook handler returns 401 (no payload processing) when this is thrown.
|
|
9
|
+
*/
|
|
10
|
+
export declare class VivaWebhookError extends VivaError {
|
|
11
|
+
readonly code: "VIVA_WEBHOOK_ERROR";
|
|
12
|
+
constructor(opts: VivaErrorOptions);
|
|
13
|
+
}
|
|
14
|
+
//# sourceMappingURL=webhook-error.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"webhook-error.d.ts","sourceRoot":"","sources":["../../src/errors/webhook-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAElC,IAAI,EAAE,gBAAgB;CAInC"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { VivaError } from './base.js';
|
|
2
|
+
/**
|
|
3
|
+
* Thrown when webhook verification or shape validation fails.
|
|
4
|
+
*
|
|
5
|
+
* Covers: HMAC signature mismatch, unknown event type, malformed payload,
|
|
6
|
+
* IP allowlist rejection (layer a), challenge-response failure (layer b).
|
|
7
|
+
*
|
|
8
|
+
* The webhook handler returns 401 (no payload processing) when this is thrown.
|
|
9
|
+
*/
|
|
10
|
+
export class VivaWebhookError extends VivaError {
|
|
11
|
+
code = 'VIVA_WEBHOOK_ERROR';
|
|
12
|
+
constructor(opts) {
|
|
13
|
+
super(opts);
|
|
14
|
+
this.name = 'VivaWebhookError';
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
//# sourceMappingURL=webhook-error.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"webhook-error.js","sourceRoot":"","sources":["../../src/errors/webhook-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IACpC,IAAI,GAAG,oBAA6B,CAAC;IAE9C,YAAY,IAAsB;QAChC,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* viva-payments-core
|
|
3
|
+
*
|
|
4
|
+
* Framework-agnostic Viva Wallet client for ISV (Independent Software Vendor)
|
|
5
|
+
* integrations. Zero Medusa or Vendure imports.
|
|
6
|
+
*
|
|
7
|
+
* Subpath exports:
|
|
8
|
+
* - viva-payments-core/auth OAuth2 + Reseller auth strategies
|
|
9
|
+
* - viva-payments-core/isv ISV payments, connected accounts, webhooks API
|
|
10
|
+
* - viva-payments-core/webhooks verification, event types, status lattice
|
|
11
|
+
* - viva-payments-core/types TypeScript types for the Viva API surface
|
|
12
|
+
* - viva-payments-core/errors VivaApiError, VivaAuthError, etc.
|
|
13
|
+
*/
|
|
14
|
+
export declare const VERSION = "0.0.0";
|
|
15
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,OAAO,UAAU,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* viva-payments-core
|
|
3
|
+
*
|
|
4
|
+
* Framework-agnostic Viva Wallet client for ISV (Independent Software Vendor)
|
|
5
|
+
* integrations. Zero Medusa or Vendure imports.
|
|
6
|
+
*
|
|
7
|
+
* Subpath exports:
|
|
8
|
+
* - viva-payments-core/auth OAuth2 + Reseller auth strategies
|
|
9
|
+
* - viva-payments-core/isv ISV payments, connected accounts, webhooks API
|
|
10
|
+
* - viva-payments-core/webhooks verification, event types, status lattice
|
|
11
|
+
* - viva-payments-core/types TypeScript types for the Viva API surface
|
|
12
|
+
* - viva-payments-core/errors VivaApiError, VivaAuthError, etc.
|
|
13
|
+
*/
|
|
14
|
+
export const VERSION = "0.0.0";
|
|
15
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IsvAccounts — ISV Connected Account API methods.
|
|
3
|
+
*
|
|
4
|
+
* Probe-verified 2026-05-11 against the live demo environment. Endpoints below
|
|
5
|
+
* match the canonical spec at `docs/payment-isv-api.yaml`.
|
|
6
|
+
*
|
|
7
|
+
* - createConnectedAccount → POST /isv/v1/accounts
|
|
8
|
+
* - retrieveConnectedAccount → GET /isv/v1/accounts/{accountId}
|
|
9
|
+
*
|
|
10
|
+
* Update is NOT implemented: the ISV spec exposes no update endpoint. The
|
|
11
|
+
* merchant edits their own account via the Viva self-care UI.
|
|
12
|
+
*
|
|
13
|
+
* Auth: OAuth2 Bearer with scopes
|
|
14
|
+
* `urn:viva:payments:core:api:isv urn:viva:payments:core:api:redirectcheckout`.
|
|
15
|
+
*/
|
|
16
|
+
import type { IsvHttpClient } from './client.js';
|
|
17
|
+
import type { CreateConnectedAccountRequest, CreateConnectedAccountResponse, GetConnectedAccountResponse, ConnectedAccountId } from '../types/index.js';
|
|
18
|
+
export declare class IsvAccounts {
|
|
19
|
+
private readonly client;
|
|
20
|
+
constructor(client: IsvHttpClient);
|
|
21
|
+
/**
|
|
22
|
+
* Create a connected merchant account.
|
|
23
|
+
*
|
|
24
|
+
* Returns `{accountId, invitation: {email, redirectUrl, created}}`. Share
|
|
25
|
+
* `invitation.redirectUrl` with the merchant to complete Viva-hosted KYC.
|
|
26
|
+
* The onboarding URL is only functional in production.
|
|
27
|
+
*/
|
|
28
|
+
createConnectedAccount(req: CreateConnectedAccountRequest): Promise<CreateConnectedAccountResponse>;
|
|
29
|
+
/**
|
|
30
|
+
* Retrieve a connected account.
|
|
31
|
+
*
|
|
32
|
+
* Returns the verification status (`verified`), the assigned `merchantId`
|
|
33
|
+
* (null until KYC is complete), and `acquiringEnabled` (true when the
|
|
34
|
+
* merchant can accept card payments).
|
|
35
|
+
*/
|
|
36
|
+
retrieveConnectedAccount(connectedAccountId: ConnectedAccountId): Promise<GetConnectedAccountResponse>;
|
|
37
|
+
}
|
|
38
|
+
//# sourceMappingURL=accounts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../../src/isv/accounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EACV,6BAA6B,EAC7B,8BAA8B,EAC9B,2BAA2B,EAC3B,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAElD;;;;;;OAMG;IACG,sBAAsB,CAC1B,GAAG,EAAE,6BAA6B,GACjC,OAAO,CAAC,8BAA8B,CAAC;IAkB1C;;;;;;OAMG;IACG,wBAAwB,CAC5B,kBAAkB,EAAE,kBAAkB,GACrC,OAAO,CAAC,2BAA2B,CAAC;CAQxC"}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IsvAccounts — ISV Connected Account API methods.
|
|
3
|
+
*
|
|
4
|
+
* Probe-verified 2026-05-11 against the live demo environment. Endpoints below
|
|
5
|
+
* match the canonical spec at `docs/payment-isv-api.yaml`.
|
|
6
|
+
*
|
|
7
|
+
* - createConnectedAccount → POST /isv/v1/accounts
|
|
8
|
+
* - retrieveConnectedAccount → GET /isv/v1/accounts/{accountId}
|
|
9
|
+
*
|
|
10
|
+
* Update is NOT implemented: the ISV spec exposes no update endpoint. The
|
|
11
|
+
* merchant edits their own account via the Viva self-care UI.
|
|
12
|
+
*
|
|
13
|
+
* Auth: OAuth2 Bearer with scopes
|
|
14
|
+
* `urn:viva:payments:core:api:isv urn:viva:payments:core:api:redirectcheckout`.
|
|
15
|
+
*/
|
|
16
|
+
export class IsvAccounts {
|
|
17
|
+
client;
|
|
18
|
+
constructor(client) {
|
|
19
|
+
this.client = client;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Create a connected merchant account.
|
|
23
|
+
*
|
|
24
|
+
* Returns `{accountId, invitation: {email, redirectUrl, created}}`. Share
|
|
25
|
+
* `invitation.redirectUrl` with the merchant to complete Viva-hosted KYC.
|
|
26
|
+
* The onboarding URL is only functional in production.
|
|
27
|
+
*/
|
|
28
|
+
async createConnectedAccount(req) {
|
|
29
|
+
const wireBody = {
|
|
30
|
+
email: req.email,
|
|
31
|
+
returnUrl: req.returnUrl,
|
|
32
|
+
};
|
|
33
|
+
if (req.branding !== undefined) {
|
|
34
|
+
wireBody['branding'] = req.branding;
|
|
35
|
+
}
|
|
36
|
+
return this.client.request({
|
|
37
|
+
method: 'POST',
|
|
38
|
+
path: '/isv/v1/accounts',
|
|
39
|
+
body: wireBody,
|
|
40
|
+
idempotent: true,
|
|
41
|
+
endpoint: 'POST /isv/v1/accounts',
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Retrieve a connected account.
|
|
46
|
+
*
|
|
47
|
+
* Returns the verification status (`verified`), the assigned `merchantId`
|
|
48
|
+
* (null until KYC is complete), and `acquiringEnabled` (true when the
|
|
49
|
+
* merchant can accept card payments).
|
|
50
|
+
*/
|
|
51
|
+
async retrieveConnectedAccount(connectedAccountId) {
|
|
52
|
+
return this.client.request({
|
|
53
|
+
method: 'GET',
|
|
54
|
+
path: `/isv/v1/accounts/${connectedAccountId}`,
|
|
55
|
+
idempotent: true,
|
|
56
|
+
endpoint: 'GET /isv/v1/accounts/{accountId}',
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
//# sourceMappingURL=accounts.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../src/isv/accounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAEtD;;;;;;OAMG;IACH,KAAK,CAAC,sBAAsB,CAC1B,GAAkC;QAElC,MAAM,QAAQ,GAA4B;YACxC,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB,CAAC;QACF,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC/B,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC;QACtC,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAiC;YACzD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,kBAAkB;YACxB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,IAAI;YAChB,QAAQ,EAAE,uBAAuB;SAClC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,wBAAwB,CAC5B,kBAAsC;QAEtC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAA8B;YACtD,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,oBAAoB,kBAAkB,EAAE;YAC9C,UAAU,EAAE,IAAI;YAChB,QAAQ,EAAE,kCAAkC;SAC7C,CAAC,CAAC;IACL,CAAC;CACF"}
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IsvHttpClient — shared HTTP wrapper for all ISV API calls.
|
|
3
|
+
*
|
|
4
|
+
* Responsibilities:
|
|
5
|
+
* - Resolve base URL from VivaEnvironment
|
|
6
|
+
* - Inject Authorization header from AuthStrategy.getBearerToken()
|
|
7
|
+
* - Bigint-safe JSON serialization (request body) and deserialization (response)
|
|
8
|
+
* - Per-request timeout via AbortController
|
|
9
|
+
* - Retry policy: idempotent requests retry 429 + 5xx up to 3 times with
|
|
10
|
+
* exponential backoff [500, 1500, 4500]ms ±20% jitter
|
|
11
|
+
* - Non-idempotent POST: only retry on connection-level errors (never on ack)
|
|
12
|
+
* - 401 handling: force-refresh token once, retry same request once
|
|
13
|
+
* - Error mapping to typed VivaError subclasses
|
|
14
|
+
*
|
|
15
|
+
* @see references/viva-docs/md/isv-credentials.txt:107 (auth credential types)
|
|
16
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104 (ISV API overview)
|
|
17
|
+
*/
|
|
18
|
+
import type { Dispatcher } from 'undici';
|
|
19
|
+
import type { AuthStrategy, VivaEnvironment } from '../types/index.js';
|
|
20
|
+
import type { MetricsHook } from '../observability/index.js';
|
|
21
|
+
export interface IsvHttpClientConfig {
|
|
22
|
+
environment: VivaEnvironment;
|
|
23
|
+
authStrategy: AuthStrategy;
|
|
24
|
+
/** Override undici dispatcher for tests (e.g. MockAgent). */
|
|
25
|
+
dispatcher?: Dispatcher;
|
|
26
|
+
/** Override global fetch. Defaults to undici fetch when dispatcher is provided, else global fetch. */
|
|
27
|
+
fetchImpl?: typeof fetch;
|
|
28
|
+
/** Clock override for tests. Defaults to Date.now. */
|
|
29
|
+
now?: () => number;
|
|
30
|
+
/**
|
|
31
|
+
* Exponential backoff schedule in milliseconds.
|
|
32
|
+
* Default: [500, 1500, 4500] per plan Auth Flow line 319.
|
|
33
|
+
*
|
|
34
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104
|
|
35
|
+
*/
|
|
36
|
+
retryBackoffsMs?: number[];
|
|
37
|
+
/**
|
|
38
|
+
* Jitter ratio applied to each backoff (±jitterRatio * backoff).
|
|
39
|
+
* Default: 0.2 (±20%).
|
|
40
|
+
*
|
|
41
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104
|
|
42
|
+
*/
|
|
43
|
+
jitterRatio?: number;
|
|
44
|
+
/** Default per-request timeout in milliseconds. Default: 30_000. */
|
|
45
|
+
defaultTimeoutMs?: number;
|
|
46
|
+
/** Optional metrics hook. Records viva_api_request_duration_seconds. */
|
|
47
|
+
metrics?: MetricsHook;
|
|
48
|
+
}
|
|
49
|
+
interface RequestOptions {
|
|
50
|
+
method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
|
|
51
|
+
path: string;
|
|
52
|
+
query?: Record<string, string | number | bigint | undefined>;
|
|
53
|
+
body?: unknown;
|
|
54
|
+
/**
|
|
55
|
+
* Sets the `Idempotency-Key` header on the request.
|
|
56
|
+
*
|
|
57
|
+
* TODO(impl): Viva's exact idempotency header name is unconfirmed from local docs.
|
|
58
|
+
* Using `Idempotency-Key` (standard RFC 8929 / common vendor practice).
|
|
59
|
+
* If Viva uses a different name, update this constant.
|
|
60
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104
|
|
61
|
+
*/
|
|
62
|
+
idempotencyKey?: string;
|
|
63
|
+
timeoutMs?: number;
|
|
64
|
+
/**
|
|
65
|
+
* When true: retries on 429 and 5xx per the backoff schedule.
|
|
66
|
+
* When false: only retries on connection-level errors (never on ack).
|
|
67
|
+
*
|
|
68
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104 (Auth Flow line 319)
|
|
69
|
+
*/
|
|
70
|
+
idempotent: boolean;
|
|
71
|
+
/**
|
|
72
|
+
* Endpoint label for metrics: `${METHOD} ${pathTemplate}` (no query string).
|
|
73
|
+
* Example: `'POST /checkout/v2/orders'`
|
|
74
|
+
* Callers must supply the template (not the concrete URL with query params).
|
|
75
|
+
*/
|
|
76
|
+
endpoint?: string;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Shared HTTP client for all ISV API endpoints.
|
|
80
|
+
*
|
|
81
|
+
* Constructed once per platform context (auth strategy + environment) and
|
|
82
|
+
* shared across IsvPayments, IsvAccounts, IsvWebhooks.
|
|
83
|
+
*
|
|
84
|
+
* @see references/viva-docs/md/isv-credentials.txt:107
|
|
85
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104
|
|
86
|
+
*/
|
|
87
|
+
export declare class IsvHttpClient {
|
|
88
|
+
private readonly apiBaseUrl;
|
|
89
|
+
private readonly authStrategy;
|
|
90
|
+
private readonly dispatcher;
|
|
91
|
+
private readonly fetchImpl;
|
|
92
|
+
private readonly now;
|
|
93
|
+
private readonly backoffsMs;
|
|
94
|
+
private readonly jitterRatio;
|
|
95
|
+
private readonly defaultTimeoutMs;
|
|
96
|
+
private readonly metrics;
|
|
97
|
+
/**
|
|
98
|
+
* Last observed `x-viva-correlationid` header value.
|
|
99
|
+
* Updated after every successful HTTP response. Used by `requestWithMeta`.
|
|
100
|
+
* Probe-verified 2026-04-25: Viva includes this on every response.
|
|
101
|
+
*/
|
|
102
|
+
private _vivaLastCorrelationId;
|
|
103
|
+
/**
|
|
104
|
+
* Last observed `x-viva-eventid` header value.
|
|
105
|
+
* Updated after every successful HTTP response. Used by `requestWithMeta`.
|
|
106
|
+
*/
|
|
107
|
+
private _vivaLastEventId;
|
|
108
|
+
constructor(config: IsvHttpClientConfig);
|
|
109
|
+
/**
|
|
110
|
+
* Execute an outbound request to the Viva ISV API.
|
|
111
|
+
*
|
|
112
|
+
* Auth flow per plan Auth Flow line 317:
|
|
113
|
+
* 1. Get bearer token from authStrategy.
|
|
114
|
+
* 2. Execute request.
|
|
115
|
+
* 3. On 401: force-refresh token once, retry once.
|
|
116
|
+
* 4. Second 401 → VivaAuthError.
|
|
117
|
+
*
|
|
118
|
+
* Retry policy per plan Auth Flow line 319:
|
|
119
|
+
* - Idempotent: retry 429 + 5xx up to MAX_RETRIES with backoff + jitter.
|
|
120
|
+
* - Non-idempotent: retry only on connection-level errors.
|
|
121
|
+
*
|
|
122
|
+
* @see references/viva-docs/md/isv-credentials.txt:107 (auth strategy)
|
|
123
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104 (retry policy)
|
|
124
|
+
*/
|
|
125
|
+
request<T>(opts: RequestOptions): Promise<T>;
|
|
126
|
+
/**
|
|
127
|
+
* Like `request<T>` but also returns Viva tracing headers.
|
|
128
|
+
*
|
|
129
|
+
* Returns `{ data: T, vivaCorrelationId, vivaEventId }` for observability.
|
|
130
|
+
* Use this when the caller needs the `x-viva-correlationid` / `x-viva-eventid`
|
|
131
|
+
* values (e.g. to log them or attach them to structured traces).
|
|
132
|
+
*
|
|
133
|
+
* Probe-verified 2026-04-25: both headers are present on every Viva response.
|
|
134
|
+
*
|
|
135
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104
|
|
136
|
+
*/
|
|
137
|
+
requestWithMeta<T>(opts: RequestOptions): Promise<{
|
|
138
|
+
data: T;
|
|
139
|
+
vivaCorrelationId: string | undefined;
|
|
140
|
+
vivaEventId: string | undefined;
|
|
141
|
+
}>;
|
|
142
|
+
/**
|
|
143
|
+
* Executes the request with a single auth-refresh-then-retry cycle.
|
|
144
|
+
*
|
|
145
|
+
* On first 401: forceRefresh token, retry the request once.
|
|
146
|
+
* On second 401: throw VivaAuthError.
|
|
147
|
+
*
|
|
148
|
+
* @see references/viva-docs/md/isv-credentials.txt:107
|
|
149
|
+
*/
|
|
150
|
+
private _withAuthRefresh;
|
|
151
|
+
/**
|
|
152
|
+
* Executes the request with the idempotent retry loop.
|
|
153
|
+
* Does NOT handle auth-refresh — that is the caller's responsibility.
|
|
154
|
+
*
|
|
155
|
+
* Viva tracing headers are extracted on every response:
|
|
156
|
+
* - `x-viva-correlationid` (e.g. "26-115-EDAA55BC") — probe-verified 2026-04-25.
|
|
157
|
+
* - `x-viva-eventid` (e.g. "0") — probe-verified 2026-04-25.
|
|
158
|
+
* On errors these are attached to the thrown VivaError. On success they are
|
|
159
|
+
* available via the `_vivaLastCorrelationId` / `_vivaLastEventId` fields for
|
|
160
|
+
* callers that need them (use `request<T>` for the raw value; use
|
|
161
|
+
* `requestWithMeta<T>` for explicit access to the tracing pair).
|
|
162
|
+
*
|
|
163
|
+
* @see references/viva-docs/md/isv-partner-program.txt:104 (Auth Flow line 319)
|
|
164
|
+
*/
|
|
165
|
+
private _executeWithRetry;
|
|
166
|
+
/**
|
|
167
|
+
* Makes a single HTTP attempt. On connection-level errors:
|
|
168
|
+
* - If idempotent: bubble up (outer loop handles retry).
|
|
169
|
+
* - If NOT idempotent: retry once on connection-level errors per plan
|
|
170
|
+
* Auth Flow line 319 (request never acked).
|
|
171
|
+
*/
|
|
172
|
+
private _attempt;
|
|
173
|
+
private _buildUrl;
|
|
174
|
+
private _backoffMs;
|
|
175
|
+
private _retryAfterMs;
|
|
176
|
+
private _parseErrorBody;
|
|
177
|
+
private _isConnectionError;
|
|
178
|
+
/**
|
|
179
|
+
* Heuristic: was the abort triggered before any byte was received?
|
|
180
|
+
* Since AbortError doesn't carry this info directly, we treat all AbortErrors
|
|
181
|
+
* from our own timeout as "possibly not acked" — safe for non-idempotent retry.
|
|
182
|
+
*/
|
|
183
|
+
private _isBeforeAck;
|
|
184
|
+
private _sleep;
|
|
185
|
+
}
|
|
186
|
+
export {};
|
|
187
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/isv/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAsE7D,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,eAAe,CAAC;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,sGAAsG;IACtG,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,UAAU,cAAc;IACtB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA2BD;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IAEtC;;;;OAIG;IACH,OAAO,CAAC,sBAAsB,CAAiC;IAE/D;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAiC;gBAE7C,MAAM,EAAE,mBAAmB;IAmBvC;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAWlD;;;;;;;;;;OAUG;IACG,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IAkB5I;;;;;;;OAOG;YACW,gBAAgB;IAc9B;;;;;;;;;;;;;OAaG;YACW,iBAAiB;IAyF/B;;;;;OAKG;YACW,QAAQ;IA4EtB,OAAO,CAAC,SAAS;IAiBjB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,eAAe;IA2BvB,OAAO,CAAC,kBAAkB;IAS1B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,MAAM;CAGf"}
|