nucleus-core-ts 0.10.232 → 0.10.233

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.
@@ -1,6 +1,6 @@
1
- import type { NucleusEmail } from 'src/Services/Email/directSendTypes';
2
- import type { NucleusCaptcha } from 'src/Services/Captcha/runtimeCaptchaTypes';
3
1
  import type { CaptchaService } from 'src/Services/Captcha';
2
+ import type { NucleusCaptcha } from 'src/Services/Captcha/runtimeCaptchaTypes';
3
+ import type { NucleusEmail } from 'src/Services/Email/directSendTypes';
4
4
  import type { EmailPayload, EmailSendResult, EmailService } from 'src/Services/Email/types';
5
5
  import { type Logger } from 'src/Services/Logger';
6
6
  import type { NotificationDeliveryReport, NotificationService, SendNotificationOptions, SendNotificationParams } from 'src/Services/Notification';
@@ -0,0 +1,61 @@
1
+ import type { PaymentAddress, PaymentBasketItem, PaymentBuyer, PaymentItemTransaction } from './types';
2
+ /**
3
+ * A provider-hosted checkout form: the guest types the card on the provider's page, so card data never
4
+ * reaches this server (PCI-DSS SAQ-A). iyzico: Checkout Form `initialize/auth/ecom` + `auth/ecom/detail`.
5
+ */
6
+ export type InitializeCheckoutRequest = {
7
+ locale?: string;
8
+ conversationId: string;
9
+ price: string;
10
+ paidPrice: string;
11
+ currency: string;
12
+ basketId?: string;
13
+ paymentGroup?: string;
14
+ buyer: PaymentBuyer;
15
+ shippingAddress: PaymentAddress;
16
+ billingAddress: PaymentAddress;
17
+ basketItems: PaymentBasketItem[];
18
+ /** Absolute URL the provider POSTs `token` to when the guest is done. */
19
+ callbackUrl: string;
20
+ /** Installment counts the form offers; omitted means the provider's default. */
21
+ enabledInstallments?: number[];
22
+ };
23
+ export type InitializeCheckoutResult = {
24
+ success: boolean;
25
+ /** The id that names this checkout when the result is retrieved. */
26
+ token?: string;
27
+ /** A page to redirect the guest to. */
28
+ paymentPageUrl?: string;
29
+ /** The provider's script snippet that renders the form inside the host's own page. */
30
+ checkoutFormContent?: string;
31
+ /** Epoch milliseconds after which the token is dead. */
32
+ tokenExpireTime?: number;
33
+ errorCode?: string;
34
+ errorMessage?: string;
35
+ rawResponse?: object;
36
+ };
37
+ export type RetrieveCheckoutRequest = {
38
+ locale?: string;
39
+ conversationId: string;
40
+ token: string;
41
+ };
42
+ export type RetrieveCheckoutResult = {
43
+ /** True only when the provider answered and reports the payment itself as successful. */
44
+ success: boolean;
45
+ /** The provider's own payment state (iyzico: `SUCCESS`, `FAILURE`, `INIT_THREEDS` ...). */
46
+ paymentStatus?: string;
47
+ paymentId?: string;
48
+ conversationId?: string;
49
+ price?: number;
50
+ paidPrice?: number;
51
+ currency?: string;
52
+ installment?: number;
53
+ cardType?: string;
54
+ cardAssociation?: string;
55
+ lastFourDigits?: string;
56
+ basketId?: string;
57
+ itemTransactions?: PaymentItemTransaction[];
58
+ errorCode?: string;
59
+ errorMessage?: string;
60
+ rawResponse?: object;
61
+ };
@@ -0,0 +1,18 @@
1
+ import { type HostDeps } from './start';
2
+ import type { HostCheckoutInput, HostCheckoutStarted, HostCompletion, HostFailure } from './types';
3
+ /**
4
+ * Starts a payment on the provider's hosted checkout form. The guest types the card on the provider's
5
+ * page, so card data never reaches this server (PCI-DSS SAQ-A). The row is written first and its id is
6
+ * the provider's `conversationId`; the provider's `token` is kept on the row, and the callback names
7
+ * the payment by it.
8
+ */
9
+ export declare function startCheckout(deps: HostDeps, input: HostCheckoutInput): Promise<HostCheckoutStarted | HostFailure>;
10
+ /**
11
+ * Retrieves the result of a hosted checkout from the `token` the provider POSTed to the host's callback
12
+ * route, and settles the payment row. Returns the `scope` and `reference` it was started with.
13
+ *
14
+ * Safe to call any number of times for one token: once settled or failed a repeat answers `replay: true`
15
+ * and changes nothing (no provider call). A provider that cannot be reached leaves the row open and
16
+ * answers `ignored / provider_unavailable`, so the host can retry the same token.
17
+ */
18
+ export declare function completeCheckout(deps: HostDeps, token: string): Promise<HostCompletion>;
@@ -0,0 +1,5 @@
1
+ import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
2
+ import type { TableWith } from '../../../Nucleus/routes/payment/tables';
3
+ import type { HostStore, HostTransaction } from './types';
4
+ /** The hosted-checkout half of the Drizzle store: the token lives in `metadata.host.token`. */
5
+ export declare function createCheckoutStore(database: NodePgDatabase, tx: TableWith<'id' | 'status' | 'metadata'>, find: (id: string) => Promise<HostTransaction | null>): Pick<HostStore, 'startedCheckout' | 'findByToken'>;
@@ -1,19 +1,23 @@
1
- import type { CompletePaymentRequest, CompletePaymentResult, InitializePaymentRequest, RefundRequest, RegisterSubMerchantRequest, UpdateSubMerchantRequest } from '../types';
1
+ import type { CompletePaymentRequest, CompletePaymentResult, InitializeCheckoutRequest, InitializePaymentRequest, RefundRequest, RegisterSubMerchantRequest, RetrieveCheckoutRequest, RetrieveCheckoutResult, UpdateSubMerchantRequest } from '../types';
2
2
  import { type HostPayments } from '.';
3
- import type { HostProvider, HostStartInput } from './types';
3
+ import type { HostCheckoutInput, HostProvider, HostStartInput } from './types';
4
+ type FakeCalls = {
5
+ initialize: InitializePaymentRequest[];
6
+ complete: CompletePaymentRequest[];
7
+ refund: RefundRequest[];
8
+ register: RegisterSubMerchantRequest[];
9
+ update: UpdateSubMerchantRequest[];
10
+ checkout: InitializeCheckoutRequest[];
11
+ retrieve: RetrieveCheckoutRequest[];
12
+ };
4
13
  /** A provider double that records what the host API sent and answers from scripts. */
5
14
  export declare function fakeProvider(script?: {
6
15
  complete?: CompletePaymentResult;
16
+ retrieve?: RetrieveCheckoutResult;
7
17
  refundFails?: number[];
8
18
  }): {
9
19
  provider: HostProvider;
10
- calls: {
11
- initialize: InitializePaymentRequest[];
12
- complete: CompletePaymentRequest[];
13
- refund: RefundRequest[];
14
- register: RegisterSubMerchantRequest[];
15
- update: UpdateSubMerchantRequest[];
16
- };
20
+ calls: FakeCalls;
17
21
  };
18
22
  export declare const log: {
19
23
  info: () => void;
@@ -30,14 +34,11 @@ export declare function setup(script?: Parameters<typeof fakeProvider>[0]): {
30
34
  }>;
31
35
  callbacks: Set<string>;
32
36
  };
33
- calls: {
34
- initialize: InitializePaymentRequest[];
35
- complete: CompletePaymentRequest[];
36
- refund: RefundRequest[];
37
- register: RegisterSubMerchantRequest[];
38
- update: UpdateSubMerchantRequest[];
39
- };
37
+ calls: FakeCalls;
40
38
  };
41
39
  export declare const startInput: (overrides?: Partial<HostStartInput>) => HostStartInput;
42
40
  export declare function started(payments: HostPayments): Promise<import("./types").HostStarted>;
43
41
  export declare function settled(payments: HostPayments): Promise<string>;
42
+ /** The same basket as `startInput`, for the hosted checkout form (no card). */
43
+ export declare const checkoutInput: (overrides?: Partial<HostCheckoutInput>) => HostCheckoutInput;
44
+ export {};
@@ -1,5 +1,5 @@
1
1
  import { type HostLog } from './start';
2
- import type { HostCompletion, HostFailure, HostProvider, HostRefunded, HostRefundInput, HostStarted, HostStartInput, HostStore, HostSubMerchantInput, HostSubMerchantResult, HostSubMerchantUpdate, HostTransaction } from './types';
2
+ import type { HostCheckoutInput, HostCheckoutStarted, HostCompletion, HostFailure, HostProvider, HostRefunded, HostRefundInput, HostStarted, HostStartInput, HostStore, HostSubMerchantInput, HostSubMerchantResult, HostSubMerchantUpdate, HostTransaction } from './types';
3
3
  /**
4
4
  * The payment verbs a host application calls from its own routes and jobs (`nucleus.payments()`).
5
5
  * No session, no `x-user-id`, no HTTP hop: the host has already decided who may pay and for which
@@ -12,7 +12,17 @@ export interface HostPayments {
12
12
  updateSubMerchant(input: HostSubMerchantUpdate): Promise<{
13
13
  ok: true;
14
14
  } | HostFailure>;
15
- /** Start a 3-D Secure card payment split to sub-merchants; render `html` for the guest. */
15
+ /**
16
+ * Open the provider's hosted checkout form for a split payment: the guest types the card on the
17
+ * provider's page, so card data never reaches this server (SAQ-A). Use this for a browser guest.
18
+ */
19
+ startCheckout(input: HostCheckoutInput): Promise<HostCheckoutStarted | HostFailure>;
20
+ /** Feed the `token` the provider POSTed to the callback route; settles the payment (idempotent). */
21
+ completeCheckout(token: string): Promise<HostCompletion>;
22
+ /**
23
+ * Start a 3-D Secure payment from a card the host forwards. SERVER-TO-SERVER ONLY: the card touches
24
+ * this server (PCI scope), so never feed it a browser guest's card; use `startCheckout`.
25
+ */
16
26
  startSplitPayment(input: HostStartInput): Promise<HostStarted | HostFailure>;
17
27
  /** Feed the provider's POST to the host's callback route; get back the tenant `scope` and `reference`. */
18
28
  handleCallback(form: Record<string, string>): Promise<HostCompletion>;
@@ -5,6 +5,8 @@ type HostMeta = {
5
5
  scope: string;
6
6
  reference: string;
7
7
  items: HostItemRecord[];
8
+ /** Set once a hosted checkout form was opened for this payment. */
9
+ token?: string;
8
10
  };
9
11
  /** The host block of a metadata value, or null when the row was not written by the host API. */
10
12
  export declare function readHostMeta(metadata: JsonValue | undefined): HostMeta | null;
@@ -0,0 +1,22 @@
1
+ import type { PaymentItemTransaction } from '../types';
2
+ import type { HostDeps } from './start';
3
+ import type { HostCompletion, HostTransaction } from './types';
4
+ /** Statuses of a payment that is already settled (or refunded after it settled). */
5
+ export declare const FINAL_STATUSES: readonly string[];
6
+ /** What a provider reports for a payment it settled: the part both 3-D Secure and checkout form share. */
7
+ export type SettledPayment = {
8
+ price?: number;
9
+ lastFourDigits?: string;
10
+ cardType?: string;
11
+ cardAssociation?: string;
12
+ installment?: number;
13
+ itemTransactions?: PaymentItemTransaction[];
14
+ rawResponse?: object;
15
+ };
16
+ export declare function outcome(row: HostTransaction, kind: 'settled' | 'failed' | 'amount_mismatch', paidMinor: number, replay: boolean, message?: string): HostCompletion;
17
+ /**
18
+ * The provider settled something. If it is not exactly the price this row was started for, the money
19
+ * moved but the host must not mark the bill paid; the row keeps the response for review. Otherwise the
20
+ * row settles once (a lost race is a replay) with the provider's per-item ids stored for refunds.
21
+ */
22
+ export declare function settleRow(deps: HostDeps, row: HostTransaction, paymentId: string, payment: SettledPayment): Promise<HostCompletion>;
@@ -1,5 +1,5 @@
1
1
  import type { ScopedLogger } from '../../Logger';
2
- import type { HostFailure, HostProvider, HostStarted, HostStartInput, HostStore } from './types';
2
+ import type { HostFailure, HostProvider, HostSplitItem, HostStarted, HostStartInput, HostStore } from './types';
3
3
  export type HostLog = Pick<ScopedLogger, 'info' | 'warn' | 'error'>;
4
4
  export type HostDeps = {
5
5
  provider: HostProvider;
@@ -9,10 +9,28 @@ export type HostDeps = {
9
9
  defaultLocale: string;
10
10
  };
11
11
  export declare const refuse: (code: HostFailure["code"], message: string, extra?: Pick<HostFailure, "providerCode" | "refundedMinor">) => HostFailure;
12
+ /** What both ways of starting a payment (card forwarded, hosted form) share. */
13
+ export type OpenInput = {
14
+ scope: string;
15
+ reference: string;
16
+ callbackUrl: string;
17
+ currency?: string;
18
+ items: HostSplitItem[];
19
+ installment?: number;
20
+ ip?: string;
21
+ };
22
+ /**
23
+ * Validates the split and writes the payment row (status `pending`) before the provider is called, so a
24
+ * provider call that never answers still leaves a trace. The row id is the provider's `conversationId`,
25
+ * which is how a callback finds it again.
26
+ */
27
+ export declare function openPayment(deps: HostDeps, input: OpenInput): Promise<{
28
+ transactionId: string;
29
+ currency: string;
30
+ } | HostFailure>;
12
31
  /**
13
- * Starts a 3-D Secure payment for one tenant, split to its sub-merchants.
14
- *
15
- * The row is written first (status `pending`) so a provider call that never answers still leaves a
16
- * trace; its id is the provider's `conversationId`, which is how the callback finds it again.
32
+ * Starts a 3-D Secure payment for one tenant, split to its sub-merchants, from a card the host
33
+ * forwards. Server-to-server only: the card touches this server, so a browser guest uses
34
+ * `startCheckout` (the provider's hosted form) instead.
17
35
  */
18
36
  export declare function startSplitPayment(deps: HostDeps, input: HostStartInput): Promise<HostStarted | HostFailure>;
@@ -11,6 +11,8 @@ export type HostTransaction = {
11
11
  providerPaymentId: string | null;
12
12
  refundedMinor: number;
13
13
  items: HostItemRecord[];
14
+ /** The hosted checkout form's token, when the payment was started that way. */
15
+ checkoutToken?: string;
14
16
  };
15
17
  export type HostItemRecord = {
16
18
  itemId: string;
@@ -50,8 +52,11 @@ export interface HostStore {
50
52
  ip: string | null;
51
53
  }): Promise<HostTransaction>;
52
54
  started(id: string, paymentId: string, response: object): Promise<void>;
55
+ /** `pending -> processing` for a hosted checkout form: keeps the token the callback will name. */
56
+ startedCheckout(id: string, token: string, response: object): Promise<void>;
53
57
  failed(id: string, message: string, response: object): Promise<void>;
54
58
  find(id: string): Promise<HostTransaction | null>;
59
+ findByToken(token: string): Promise<HostTransaction | null>;
55
60
  /** Conditional `processing -> completed`; false when another callback already settled it. */
56
61
  settle(id: string, settlement: HostSettlement): Promise<boolean>;
57
62
  /** Records a provider callback once per `key`; false when the key was seen before. */
@@ -8,7 +8,7 @@ import type { PaymentAddress, PaymentBuyer, PaymentCard, PaymentProvider, SubMer
8
8
  * calls back, and required again on a refund, so a callback or a refund can never reach another tenant.
9
9
  */
10
10
  /** The provider verbs the host API uses; a test double implements exactly these. */
11
- export type HostProvider = Pick<PaymentProvider, 'name' | 'initialize3DS' | 'complete3DS' | 'parseCallback' | 'refund' | 'registerSubMerchant' | 'updateSubMerchant'>;
11
+ export type HostProvider = Pick<PaymentProvider, 'name' | 'initialize3DS' | 'complete3DS' | 'initializeCheckout' | 'retrieveCheckout' | 'parseCallback' | 'refund' | 'registerSubMerchant' | 'updateSubMerchant'>;
12
12
  /** One basket item: what the guest pays for, and which sub-merchant receives it. */
13
13
  export type HostSplitItem = {
14
14
  /** Unique within the payment; the provider echoes it per item. */
@@ -41,6 +41,38 @@ export type HostStartInput = {
41
41
  /** Client IP, kept on the row for the provider's fraud checks. */
42
42
  ip?: string;
43
43
  };
44
+ /**
45
+ * A payment on the provider's hosted checkout form: the guest types the card on the provider's page,
46
+ * so card data never reaches this server (PCI-DSS SAQ-A). This is the way for a browser guest.
47
+ */
48
+ export type HostCheckoutInput = {
49
+ scope: string;
50
+ reference: string;
51
+ currency?: string;
52
+ items: HostSplitItem[];
53
+ buyer: PaymentBuyer;
54
+ /** Used as both shipping and billing address. */
55
+ address: PaymentAddress;
56
+ /** Absolute URL of the host route the provider POSTs `token` to; give that body to `completeCheckout`. */
57
+ callbackUrl: string;
58
+ /** Installment counts the form offers; omitted means the provider's default. */
59
+ enabledInstallments?: number[];
60
+ locale?: string;
61
+ /** Client IP; also sent as the buyer's when the buyer has none. */
62
+ ip?: string;
63
+ };
64
+ export type HostCheckoutStarted = {
65
+ ok: true;
66
+ transactionId: string;
67
+ /** Keep it: the callback names the checkout by this token. */
68
+ token: string;
69
+ /** A provider page to redirect the guest to, when the provider gave one. */
70
+ paymentPageUrl?: string;
71
+ /** The provider's script snippet that renders the form in the host's own page, when given. */
72
+ checkoutFormContent?: string;
73
+ /** Epoch milliseconds after which the token is dead, when the provider says. */
74
+ expiresAt?: number;
75
+ };
44
76
  export type HostRefusal = 'invalid_input' | 'provider_refused' | 'not_found' | 'not_refundable' | 'amount_exceeds_refundable' | 'store_failed';
45
77
  export type HostFailure = {
46
78
  ok: false;
@@ -60,7 +92,7 @@ export type HostStarted = {
60
92
  export type HostCompletionOutcome = 'settled' | 'failed' | 'amount_mismatch';
61
93
  export type HostCompletion = {
62
94
  kind: 'ignored';
63
- reason: 'no_payment' | 'unknown_transaction' | 'payment_mismatch';
95
+ reason: 'no_payment' | 'unknown_transaction' | 'payment_mismatch' | 'provider_unavailable';
64
96
  } | {
65
97
  kind: HostCompletionOutcome;
66
98
  transactionId: string;
@@ -0,0 +1,3 @@
1
+ import type { PaymentProvider, PaymentProviderConfig } from './types';
2
+ /** iyzico's hosted Checkout Form: initialize returns a token and a page; the callback carries the token back. */
3
+ export declare const createIyzicoCheckout: (config: PaymentProviderConfig) => Pick<PaymentProvider, "initializeCheckout" | "retrieveCheckout">;
@@ -0,0 +1,45 @@
1
+ import { type JsonObject } from '../../Client/Proxy/jsonValue';
2
+ import type { PaymentItemTransaction, PaymentProviderConfig } from './types';
3
+ export declare const IYZICO_PATHS: {
4
+ INITIALIZE_3DS: string;
5
+ COMPLETE_3DS: string;
6
+ PAYMENT_AUTH: string;
7
+ PAYMENT_DETAIL: string;
8
+ BIN_CHECK: string;
9
+ CARD_SAVE: string;
10
+ CARD_LIST: string;
11
+ CARD_DELETE: string;
12
+ REFUND: string;
13
+ SUB_MERCHANT_CREATE: string;
14
+ SUB_MERCHANT_UPDATE: string;
15
+ SUB_MERCHANT_DETAIL: string;
16
+ CHECKOUT_INITIALIZE: string;
17
+ CHECKOUT_DETAIL: string;
18
+ APPROVAL: string;
19
+ DISAPPROVAL: string;
20
+ };
21
+ /** A request body: whatever JSON.stringify can write (the typed request records included). */
22
+ export type IyzicoPayload = {
23
+ [field: string]: string | number | boolean | object | null | undefined;
24
+ };
25
+ /** A parsed iyzico answer, read field by field: a field of the wrong kind reads as absent. */
26
+ export interface IyzicoBody {
27
+ text(field: string): string | undefined;
28
+ number(field: string): number | undefined;
29
+ list(field: string): IyzicoBody[];
30
+ /** An identifier that iyzico may write as a string or as a number. */
31
+ id(field: string): string | undefined;
32
+ }
33
+ export declare const iyzicoFetch: (config: PaymentProviderConfig, path: string, payload: IyzicoPayload, method?: "POST" | "PUT") => Promise<{
34
+ success: boolean;
35
+ data: IyzicoBody | null;
36
+ errorCode?: string;
37
+ errorMessage?: string;
38
+ rawResponse: JsonObject;
39
+ }>;
40
+ /**
41
+ * The per-basket-item rows of a completed payment. iyzico refunds and approves an ITEM
42
+ * (`paymentTransactionId`), never the payment, so a caller that wants to refund must keep these.
43
+ * An id may arrive as a string or a number; a row without both ids is dropped.
44
+ */
45
+ export declare const readItemTransactions: (data: IyzicoBody | null | undefined) => PaymentItemTransaction[];
@@ -2,6 +2,8 @@
2
2
  * Payment provider interface and shared types.
3
3
  * Designed to be provider-agnostic — iyzico is the first implementation.
4
4
  */
5
+ import type { InitializeCheckoutRequest, InitializeCheckoutResult, RetrieveCheckoutRequest, RetrieveCheckoutResult } from './CheckoutTypes';
6
+ export type * from './CheckoutTypes';
5
7
  export type PaymentProviderName = 'iyzico' | 'stripe';
6
8
  export type PaymentTransactionStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'refunded' | 'partially_refunded' | 'cancelled';
7
9
  export type PaymentMethodType = 'card' | 'bank_account' | 'wallet';
@@ -1043,6 +1045,9 @@ export type PaymentProvider = {
1043
1045
  deleteCard(request: DeleteCardRequest): Promise<DeleteCardResult>;
1044
1046
  refund(request: RefundRequest): Promise<RefundResult>;
1045
1047
  parseCallback(formData: Record<string, string>): ParsedCallback;
1048
+ /** A provider-hosted checkout form: card data never reaches this server. */
1049
+ initializeCheckout(request: InitializeCheckoutRequest): Promise<InitializeCheckoutResult>;
1050
+ retrieveCheckout(request: RetrieveCheckoutRequest): Promise<RetrieveCheckoutResult>;
1046
1051
  registerSubMerchant(request: RegisterSubMerchantRequest): Promise<RegisterSubMerchantResult>;
1047
1052
  updateSubMerchant(request: UpdateSubMerchantRequest): Promise<UpdateSubMerchantResult>;
1048
1053
  getSubMerchant(request: GetSubMerchantRequest): Promise<GetSubMerchantResult>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nucleus-core-ts",
3
- "version": "0.10.232",
3
+ "version": "0.10.233",
4
4
  "description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
5
5
  "author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
6
6
  "license": "SEE LICENSE IN LICENSE",