liqpay-nestjs 0.3.5 → 0.3.7

package/README.md

@@ -1,15 +1,15 @@
 # liqpay-nestjs
 
-NestJS module for LiqPay payments with typed request builders, signed checkout payload generation, webhook callback parsing, and payment status lookups.
+NestJS module for LiqPay payments with typed request models, signed checkout payload generation, webhook callback parsing, and payment status lookups.
 
 ## Features
 
 - NestJS module with `forRoot` and `forRootAsync`
 - `LiqpayService` with `payments` and `webhooks` helpers
-- Signed builders for `pay`, `hold`, and `subscribe` checkout flows
-- HTML pay button generation with LiqPay SDK markup
-- Zod schemas and TypeScript types exported from the package root
-- Callback signature verification and camelCase response parsing
+- Signed checkout builders for standard payment, hold, and subscription flows
+- HTML checkout button generation with LiqPay SDK markup
+- Typed payment status requests and normalized responses
+- TypeScript types exported from the package root
 
 ## Requirements
 
@@ -71,11 +71,16 @@ import { LiqPayModule } from 'liqpay-nestjs'
 export class AppModule {}
 ```
 
-### Use `LiqpayService`
+### Inject and use `LiqpayService`
 
 ```ts
-import { Body, Controller, Get, Param, Post } from '@nestjs/common'
-import { CheckoutInput, LiqPayEnvelope, LiqpayService } from 'liqpay-nestjs'
+import { Body, Controller, Get, Post, Query } from '@nestjs/common'
+import { LiqpayService } from 'liqpay-nestjs'
+import type {
+	CheckoutInput,
+	LiqPayEnvelope,
+	PaymentStatusInput,
+} from 'liqpay-nestjs'
 
 @Controller('payments')
 export class PaymentsController {
@@ -90,7 +95,7 @@ export class PaymentsController {
 			orderId: 'order-123',
 		}
 
-		const checkout = this.liqpay.payments.pay(payload)
+		const checkout = this.liqpay.payments.getCheckoutUrl(payload)
 
 		return {
 			url: checkout.url,
@@ -99,9 +104,10 @@ export class PaymentsController {
 		}
 	}
 
-	@Get(':orderId/status')
-	getStatus(@Param('orderId') orderId: string) {
-		return this.liqpay.payments.getPaymentStatus(orderId)
+	@Get('status')
+	getStatus(@Query('orderId') orderId: string) {
+		const payload: PaymentStatusInput = { orderId }
+		return this.liqpay.payments.getStatus(payload)
 	}
 
 	@Post('webhook')
@@ -113,12 +119,12 @@ export class PaymentsController {
 
 ## Typical Flow
 
-1. Register `LiqPayModule` with your keys and optional default callback URLs.
-2. Build a checkout payload with `liqpay.payments.pay(...)`, `hold(...)`, or `subscribe(...)`.
-3. Redirect the user to the returned `url`, or render your own form using `data` and `signature`.
+1. Register `LiqPayModule` with your public and private keys.
+2. Build a checkout payload with `liqpay.payments.getCheckoutUrl(...)`, `hold(...)`, or `subscribe(...)`.
+3. Redirect the customer to `result.url` or render the returned button HTML.
 4. Receive the LiqPay callback envelope at your `serverUrl` endpoint.
 5. Parse the callback with `liqpay.webhooks.parseCheckoutCallback(...)`.
-6. Confirm the final state later with `liqpay.payments.getPaymentStatus(orderId)` if needed.
+6. Query the current state later with `liqpay.payments.getStatus({ orderId })` when needed.
 
 ## Configuration
 
@@ -138,20 +144,20 @@ The async registration provider validates the resolved options and throws if `pu
 
 `LiqpayService.payments` exposes five methods.
 
-| Method                                             | Purpose                                                  | Return type                                                          |
-| -------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
-| `pay(payload)`                                     | Builds a signed checkout payload for a standard payment. | `CheckoutRequest & { url: string; data: string; signature: string }` |
-| `hold(payload)`                                    | Builds a signed checkout payload for a hold operation.   | `CheckoutRequest & { url: string; data: string; signature: string }` |
-| `subscribe(payload)`                               | Builds a signed checkout payload for recurring payments. | `CheckoutRequest & { url: string; data: string; signature: string }` |
-| `getPayButton(payload, buttonText?, buttonColor?)` | Returns HTML for a LiqPay pay button.                    | `string`                                                             |
-| `getPaymentStatus(orderId)`                        | Calls the LiqPay status API.                             | `Promise<Result<PaymentStatusResponse>>`                             |
+| Method                                                  | Purpose                                                     | Notes                                           |
+| ------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------- |
+| `getCheckoutUrl(payload)`                               | Builds a signed standard checkout payload.                  | Returns a full result object, not only the URL. |
+| `hold(payload)`                                         | Builds a signed checkout payload with action `hold`.        | Local builder, no HTTP call.                    |
+| `subscribe(payload)`                                    | Builds a signed checkout payload with action `subscribe`.   | Local builder, no HTTP call.                    |
+| `getCheckoutButton(payload, buttonText?, buttonColor?)` | Returns LiqPay checkout HTML for the standard payment flow. | Uses action `pay`.                              |
+| `getStatus(payload)`                                    | Calls LiqPay status API.                                    | Expects `PaymentStatusInput`.                   |
 
-### `payments.pay(payload)`
+### `payments.getCheckoutUrl(payload)`
 
-Use `pay(...)` for a normal payment flow.
+Use this for a normal checkout flow.
 
 ```ts
-import { CheckoutInput } from 'liqpay-nestjs'
+import type { CheckoutInput } from 'liqpay-nestjs'
 
 const payload: CheckoutInput = {
 	amount: 100,
@@ -160,23 +166,23 @@ const payload: CheckoutInput = {
 	orderId: 'order-123',
 }
 
-const checkout = liqpay.payments.pay(payload)
+const checkout = liqpay.payments.getCheckoutUrl(payload)
 
 console.log(checkout.url)
 console.log(checkout.data)
 console.log(checkout.signature)
 ```
 
-Returned fields:
+Despite the method name, the return value is a signed checkout object containing:
 
-- `url`: ready-to-use LiqPay checkout URL
+- `url`: ready-to-use LiqPay redirect URL
 - `data`: Base64-encoded request payload
-- `signature`: request signature generated from your private key
-- all resolved request fields including `action`, `version`, `publicKey`, and inherited `resultUrl` / `serverUrl`
+- `signature`: signature generated from your private key
+- the resolved checkout fields such as `action`, `version`, `publicKey`, and inherited `resultUrl` / `serverUrl`
 
 ### `payments.hold(payload)`
 
-`hold(...)` has the same return shape as `pay(...)`, but the generated request uses action `hold`.
+Builds the same signed result shape as `getCheckoutUrl(...)`, but with action `hold`.
 
 ```ts
 const holdCheckout = liqpay.payments.hold({
@@ -189,7 +195,7 @@ const holdCheckout = liqpay.payments.hold({
 
 ### `payments.subscribe(payload)`
 
-`subscribe(...)` has the same return shape as `pay(...)`, but builds a subscription request. Subscription-related fields still come from your `CheckoutInput`.
+Builds the same signed result shape as `getCheckoutUrl(...)`, but with action `subscribe`.
 
 ```ts
 const subscriptionCheckout = liqpay.payments.subscribe({
@@ -203,12 +209,12 @@ const subscriptionCheckout = liqpay.payments.subscribe({
 })
 ```
 
-### `payments.getPayButton(payload, buttonText?, buttonColor?)`
+### `payments.getCheckoutButton(payload, buttonText?, buttonColor?)`
 
-Returns an HTML string containing a form and LiqPay `sdk-button` markup for the `pay` action.
+Returns an HTML string containing a form and LiqPay `sdk-button` markup for the standard payment flow.
 
 ```ts
-const html = liqpay.payments.getPayButton(
+const html = liqpay.payments.getCheckoutButton(
 	{
 		amount: 100,
 		currency: 'UAH',
@@ -225,12 +231,15 @@ Defaults:
 - `buttonText`: `Pay`
 - `buttonColor`: `#77CC5D`
 
-### `payments.getPaymentStatus(orderId)`
+### `payments.getStatus(payload)`
 
 Calls LiqPay's status API and returns `Promise<Result<PaymentStatusResponse>>`.
 
 ```ts
-const result = await liqpay.payments.getPaymentStatus('order-123')
+import type { PaymentStatusInput } from 'liqpay-nestjs'
+
+const payload: PaymentStatusInput = { orderId: 'order-123' }
+const result = await liqpay.payments.getStatus(payload)
 
 if (result.error) {
 	console.error(result.error.code, result.error.description)
@@ -241,7 +250,7 @@ if (result.error) {
 }
 ```
 
-This is the only payments helper that performs an HTTP request.
+This is the only payments helper that performs an HTTP request. The library fills `action: 'status'`, `version: 7`, and your configured `publicKey` automatically.
 
 ## Webhooks API
 
@@ -249,7 +258,8 @@ This is the only payments helper that performs an HTTP request.
 
 ```ts
 import { Body, Controller, Post } from '@nestjs/common'
-import { LiqPayEnvelope, LiqpayService } from 'liqpay-nestjs'
+import { LiqpayService } from 'liqpay-nestjs'
+import type { LiqPayEnvelope } from 'liqpay-nestjs'
 
 @Controller('payments')
 export class WebhookController {
@@ -268,7 +278,7 @@ export class WebhookController {
 }
 ```
 
-The envelope shape is:
+`LiqPayEnvelope` is the callback wrapper sent by LiqPay:
 
 ```ts
 type LiqPayEnvelope = {
@@ -279,20 +289,10 @@ type LiqPayEnvelope = {
 
 ## Checkout Types
 
-The checkout flow exposes three related types.
-
-| Type                 | Purpose                                                                                            |
-| -------------------- | -------------------------------------------------------------------------------------------------- |
-| `CheckoutInput`      | The consumer-facing payload you pass into `pay`, `hold`, `subscribe`, or `getPayButton`.           |
-| `CheckoutRequest`    | The enriched request after the library injects `action`, `version`, `publicKey`, and default URLs. |
-| `RawCheckoutRequest` | The final wire-format payload sent to LiqPay after snake_case and value transformations.           |
-
-In most applications you should create `CheckoutInput` values and let the library build the rest.
-
-### Minimal `CheckoutInput`
+For library consumers, the main checkout type is `CheckoutInput`.
 
 ```ts
-import { CheckoutInput } from 'liqpay-nestjs'
+import type { CheckoutInput } from 'liqpay-nestjs'
 
 const payload: CheckoutInput = {
 	amount: 100,
@@ -302,64 +302,43 @@ const payload: CheckoutInput = {
 }
 ```
 
-### Advanced `CheckoutInput` fields
-
-The public checkout input supports many LiqPay options, including:
+Useful optional fields include:
 
 - `resultUrl`, `serverUrl`
 - `paytypes`, `language`, `expiredDate`
-- `cardToken`, `customer`, `customerUserId`, `recurringByToken`
+- `verifyCode`
+- `fiscalData`, `splitRules`, `detailAddenda`
+- `customer`, `customerUserId`, `recurringByToken`
 - `subscribe`, `subscribeDateStart`, `subscribePeriodicity`
-- `fiscalData`, `detailAddenda`, `splitRules`
 - sender metadata such as `senderFirstName`, `senderLastName`, `senderAddress`, and `senderCountryCode`
 - product metadata such as `productName`, `productDescription`, `productCategory`, and `productUrl`
 
-## Request and Response Normalization
+The source repository keeps the full request and response models under `src/core/types` if you need exact field-level reference.
 
-The library keeps the application-facing API mostly in camelCase and handles LiqPay's transport format internally.
+## Type Exports
 
-- Top-level request fields use names like `orderId`, `resultUrl`, `serverUrl`, `verifyCode`, `fiscalData`, and `detailAddenda`.
-- Outgoing requests are serialized into LiqPay's expected field format.
-- Checkout callbacks and payment status responses are transformed back into camelCase.
-- Several values such as dates, booleans, and enum-backed fields are normalized during parsing.
-- Some nested helper objects still use provider-specific field names defined by their exported schemas.
-
-## Schemas and Types
-
-All public schemas and types are exported from the package root.
+The package root exports TypeScript types for request and response modeling, for example:
 
 ```ts
-import {
+import type {
 	CheckoutCallback,
-	CheckoutCallbackSchema,
 	CheckoutInput,
-	CheckoutInputSchema,
 	LiqPayEnvelope,
-	LiqPayEnvelopeSchema,
+	LiqPayError,
+	PaymentStatusInput,
 	PaymentStatusResponse,
-	PaymentStatusResponseSchema,
 	Result,
 } from 'liqpay-nestjs'
 ```
 
-Main export groups:
-
-- base: `LiqPayEnvelope`, `LiqPayEnvelopeSchema`, `Result<T>`, request and response unions
-- checkout: `CheckoutInput`, `CheckoutInputSchema`, `CheckoutRequest`, `CheckoutCallback`, and raw request helpers
-- payment status: `PaymentStatusRequest`, `PaymentStatusRequestSchema`, `PaymentStatusResponse`, `PaymentStatusResponseSchema`
-- common: fiscal, split, and addenda schemas and their types
-- enums: action, currency, language, paytype, version, payment status, and related schema exports
-- error: LiqPay error response and error code schemas and types
-- nest: `LiqPayModule`, `LiqpayService`, `LiqPayOptions`, `LiqPayAsyncOptions`, `LIQPAY_OPTIONS`
-
-### Validate controller input with the exported schemas
+It also exports these runtime values:
 
-```ts
-import { CheckoutInputSchema } from 'liqpay-nestjs'
+- `LiqPayModule`
+- `LiqpayService`
+- `LIQPAY_OPTIONS`
+- `UnitEnum`
 
-const payload = CheckoutInputSchema.parse(input)
-const checkout = liqpay.payments.pay(payload)
-```
+Note: the package root currently exports types, not Zod schema values. The schema implementations live in the source under `src/core/types`.
 
 ## Result Contract and Error Handling
 
@@ -373,29 +352,29 @@ type Result<T> =
 
 This applies to:
 
-- `liqpay.payments.getPaymentStatus(...)`
+- `liqpay.payments.getStatus(...)`
 - `liqpay.webhooks.parseCheckoutCallback(...)`
 
-Possible error sources include:
+Errors can come from:
 
-- LiqPay provider errors parsed from `err_code` and `err_description`
+- LiqPay API error responses
 - invalid callback signatures
 - Base64 decode failures
 - invalid JSON responses
-- schema validation failures
+- response validation failures
 - HTTP transport failures
 
 Always check `result.error` before using `result.data`.
 
-## Advanced Nest Exports
+## Nest Exports
 
-The package root also exports:
+The package root exports:
 
+- `LiqPayModule`
+- `LiqpayService`
 - `LIQPAY_OPTIONS`
-- `createLiqpayOptionsProvider(...)`
-- `createLiqpayAsyncOptionsProvider(...)`
-
-These are useful if you want to build custom providers around the package token instead of using `LiqPayModule` directly.
+- `LiqPayOptions`
+- `LiqPayAsyncOptions`
 
 ## Build
 

package/dist/core/clients/index.d.ts

@@ -1,4 +1 @@
 export * from './liqpay.client';
-export * from './payments.client';
-export * from './utils.client';
-export * from './webhooks.client';

package/dist/core/clients/index.js

@@ -15,6 +15,3 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./liqpay.client"), exports);
-__exportStar(require("./payments.client"), exports);
-__exportStar(require("./utils.client"), exports);
-__exportStar(require("./webhooks.client"), exports);

package/dist/core/clients/liqpay.client.d.ts

@@ -1,8 +1,10 @@
 import { PaymentsClient } from './payments.client';
+import { RefundsClient } from './refunds.client';
 import { WebhooksClient } from './webhooks.client';
 export declare class LiqPayClient {
     payments: PaymentsClient;
     webhooks: WebhooksClient;
+    refunds: RefundsClient;
     constructor(options: {
         publicKey: string;
         privateKey: string;

package/dist/core/clients/liqpay.client.js

@@ -2,16 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LiqPayClient = void 0;
 const payments_client_1 = require("./payments.client");
+const refunds_client_1 = require("./refunds.client");
 const utils_client_1 = require("./utils.client");
 const webhooks_client_1 = require("./webhooks.client");
 class LiqPayClient {
     payments;
     webhooks;
+    refunds;
     constructor(options) {
         const { publicKey, privateKey, resultUrl, serverUrl } = options;
         const utils = new utils_client_1.UtilsClient(publicKey, privateKey, resultUrl ?? '', serverUrl ?? '');
         this.payments = new payments_client_1.PaymentsClient(utils);
         this.webhooks = new webhooks_client_1.WebhooksClient(utils);
+        this.refunds = new refunds_client_1.RefundsClient(utils);
     }
 }
 exports.LiqPayClient = LiqPayClient;

package/dist/core/clients/payments.client.js

@@ -82,7 +82,7 @@ class PaymentsClient {
             version: 7,
             publicKey: this.utils.publicKey,
         };
-        return await this.utils.call(request, payment_status_1.RawPaymentStatusRequestSchema, payment_status_1.PaymentStatusResponseSchema, common_1.REQUEST_URL);
+        return await this.utils.call(request, payment_status_1.RawPaymentStatusRequestSchema, payment_status_1.PaymentStatusResponseSchema);
     }
 }
 exports.PaymentsClient = PaymentsClient;

package/dist/core/clients/refunds.client.d.ts

@@ -0,0 +1,7 @@
+import { RefundInput } from '../types/refund';
+import { UtilsClient } from './utils.client';
+export declare class RefundsClient {
+    private readonly utils;
+    constructor(utils: UtilsClient);
+    refund(payload: RefundInput): void;
+}

package/dist/core/clients/refunds.client.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RefundsClient = void 0;
+const refund_1 = require("../types/refund");
+class RefundsClient {
+    utils;
+    constructor(utils) {
+        this.utils = utils;
+    }
+    refund(payload) {
+        const request = {
+            ...payload,
+            version: 7,
+            publicKey: this.utils.publicKey,
+            action: 'refund',
+        };
+        this.utils.call(request, refund_1.RawRefundRequestSchema, refund_1.RefundResponseSchema);
+    }
+}
+exports.RefundsClient = RefundsClient;

package/dist/core/clients/utils.client.d.ts

@@ -16,5 +16,5 @@ export declare class UtilsClient {
     parseData<T>(schema: z.ZodType<T>, data: unknown): Result<T>;
     parseError(data: unknown): Result<never> | null;
     parseEnvelope<TResponse extends LiqPayResponse>(envelope: LiqPayEnvelope, schema: z.ZodType<TResponse>): Result<TResponse>;
-    call<TRequest extends LiqPayRequest, TRawRequest extends LiqPayRawRequest, TResponse extends LiqPayResponse>(payload: TRequest, rawSchema: z.ZodType<TRawRequest>, responseSchema: z.ZodType<TResponse>, url: string): Promise<Result<TResponse>>;
+    call<TRequest extends LiqPayRequest, TRawRequest extends LiqPayRawRequest, TResponse extends LiqPayResponse>(payload: TRequest, rawSchema: z.ZodType<TRawRequest>, responseSchema: z.ZodType<TResponse>, url?: string): Promise<Result<TResponse>>;
 }

package/dist/core/clients/utils.client.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UtilsClient = void 0;
 const node_crypto_1 = require("node:crypto");
+const common_1 = require("../types/common");
 const error_1 = require("../types/error");
 class UtilsClient {
     publicKey;
@@ -70,7 +71,7 @@ class UtilsClient {
         }
         return this.parseData(schema, rawData);
     }
-    async call(payload, rawSchema, responseSchema, url) {
+    async call(payload, rawSchema, responseSchema, url = common_1.REQUEST_URL) {
         const raw = rawSchema.parse(payload);
         const envelope = this.toEnvelope(raw);
         const response = await fetch(url, {

package/dist/core/types/base/request.type.d.ts

@@ -1,4 +1,5 @@
 import { CheckoutRequest, RawCheckoutRequest } from '../checkout';
 import { PaymentStatusRequest, RawPaymentStatusRequest } from '../payment-status';
-export type LiqPayRequest = CheckoutRequest | PaymentStatusRequest;
-export type LiqPayRawRequest = RawCheckoutRequest | RawPaymentStatusRequest;
+import { RawRefundRequest, RefundRequest } from '../refund';
+export type LiqPayRequest = CheckoutRequest | PaymentStatusRequest | RefundRequest;
+export type LiqPayRawRequest = RawCheckoutRequest | RawPaymentStatusRequest | RawRefundRequest;

package/dist/core/types/base/response.type.d.ts

@@ -1,8 +1,9 @@
 import { CheckoutCallback, RawCheckoutCallback } from '../checkout';
 import { LiqPayErrorResponse } from '../error';
 import { PaymentStatusResponse, RawPaymentStatusResponse } from '../payment-status';
-export type LiqPayResponse = CheckoutCallback | PaymentStatusResponse;
-export type LiqPayRawResponse = RawCheckoutCallback | RawPaymentStatusResponse | LiqPayErrorResponse;
+import { RawRefundResponse, RefundResponse } from '../refund';
+export type LiqPayResponse = CheckoutCallback | PaymentStatusResponse | RefundResponse;
+export type LiqPayRawResponse = RawCheckoutCallback | RawPaymentStatusResponse | RawRefundResponse | LiqPayErrorResponse;
 export type Result<T> = {
     data: T;
     error?: null;

package/dist/core/types/refund/index.d.ts

@@ -0,0 +1,2 @@
+export * from './refund.request';
+export * from './refund.response';

package/dist/core/types/refund/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./refund.request"), exports);
+__exportStar(require("./refund.response"), exports);

package/dist/nest/services/refunds.service.d.ts

@@ -0,0 +1,7 @@
+import { LiqPayClient } from '../../core/clients';
+import { RefundInput } from '../../core/types/refund';
+export declare class RefundsService {
+    private readonly client;
+    constructor(client: LiqPayClient);
+    refund(payload: RefundInput): Promise<void>;
+}

package/dist/nest/services/refunds.service.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RefundsService = void 0;
+class RefundsService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async refund(payload) {
+        return this.client.refunds.refund(payload);
+    }
+}
+exports.RefundsService = RefundsService;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "liqpay-nestjs",
 	"description": "LiqPay integration module for NestJS with support for payments, callbacks, and configuration via DI.",
-	"version": "0.3.5",
+	"version": "0.3.7",
 	"type": "commonjs",
 	"module": "dist/index.js",
 	"main": "dist/index.js",
@@ -15,7 +15,8 @@
 		"nestjs-module"
 	],
 	"files": [
-		"dist"
+		"dist",
+		"README.md"
 	],
 	"exports": {
 		".": {