@keytd/manat 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Manat for TypeScript / JavaScript
 
-One API for Azerbaijani online payment providers: Kapital Bank, Azericard, Payriff, Epoint and GoldenPay.
+One API for Azerbaijani online payment providers: Kapital Bank, Azericard, Payriff, Epoint, GoldenPay and Yığım.
 Node.js 18+, ESM and CommonJS, no runtime dependencies.
 
 ```bash
@@ -27,13 +27,14 @@ Store `paymentId` with the order. It is what `getStatus`, `refund`, `capture` an
 ## Providers
 
 ```ts
-import {azericard, epoint, goldenPay, kapitalBank, payriff} from '@keytd/manat';
+import {azericard, epoint, goldenPay, kapitalBank, payriff, yigim} from '@keytd/manat';
 
 kapitalBank({username, password, environment: 'test'});
 azericard({terminal, privateKey, gatewayPublicKey, merchantName, merchantUrl, environment: 'test'});
 payriff({secretKey});
 epoint({publicKey, privateKey});
 goldenPay({authKey, merchantName, environment: 'test'});
+yigim({merchant, apiKey, biller, environment: 'test'});
 ```
 
 | Provider     | createPayment | verifyCallback | getStatus | refund | capture | cancel |
@@ -43,10 +44,9 @@ goldenPay({authKey, merchantName, environment: 'test'});
 | Payriff      | ✓ | ✓ | ✓ | ✓ | ✓ | — |
 | Epoint       | ✓ | ✓ | ✓ | ✓ | — | — |
 | GoldenPay    | ✓ | ✓ | ✓ | ✓ | — | — |
+| Yığım        | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
 
 `pay.supports('capture')` tells you at runtime; an unsupported call throws `unsupported_operation`.
-Provider details (what was checked live, quirks, why some operations are missing) are in the
-[main README](https://github.com/KeyTechAndDesign/manat#providers).
 
 ## Callbacks
 

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   Manat: () => Manat,
   ManatError: () => ManatError,
   PayriffProvider: () => PayriffProvider,
+  YigimProvider: () => YigimProvider,
   azericard: () => azericard,
   azn: () => azn,
   epoint: () => epoint,
@@ -36,7 +37,8 @@ __export(index_exports, {
   isManatError: () => isManatError,
   kapitalBank: () => kapitalBank,
   payriff: () => payriff,
-  toDecimalString: () => toDecimalString
+  toDecimalString: () => toDecimalString,
+  yigim: () => yigim
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -47,18 +49,18 @@ var ManatError = class extends Error {
   providerCode;
   providerMessage;
   raw;
-  constructor(code, message, details = {}) {
+  constructor(code2, message, details = {}) {
     super(message, details.cause === void 0 ? void 0 : { cause: details.cause });
     this.name = "ManatError";
-    this.code = code;
+    this.code = code2;
     this.provider = details.provider;
     this.providerCode = details.providerCode;
     this.providerMessage = details.providerMessage;
     this.raw = details.raw;
   }
 };
-function isManatError(error, code) {
-  return error instanceof ManatError && (code === void 0 || error.code === code);
+function isManatError(error, code2) {
+  return error instanceof ManatError && (code2 === void 0 || error.code === code2);
 }
 
 // src/money.ts
@@ -87,8 +89,11 @@ function fromDecimal(value, currency) {
   const fraction = (match[2] ?? "").padEnd(digits, "0");
   return { amount: Number(`${match[1]}${fraction}`), currency };
 }
-function currencyFromNumeric(code) {
-  return Object.keys(NUMERIC_CODES).find((c) => NUMERIC_CODES[c] === code);
+function currencyNumericCode(currency) {
+  return NUMERIC_CODES[currency];
+}
+function currencyFromNumeric(code2) {
+  return Object.keys(NUMERIC_CODES).find((c) => NUMERIC_CODES[c] === code2);
 }
 function azn(value) {
   return fromDecimal(value, "AZN");
@@ -365,9 +370,9 @@ function kapitalBank(config, options) {
 function assertOrderId(paymentId) {
   if (!/^\d+$/.test(paymentId)) throw new ManatError("invalid_request", `kapitalbank: paymentId must be the numeric order id, got "${paymentId}"`);
 }
-function toCurrency(code, paymentId) {
-  if (code === "AZN" || code === "USD" || code === "EUR" || code === "RUB" || code === "TRY" || code === "GBP") return code;
-  throw new ManatError("provider_error", `kapitalbank: unexpected currency "${code}" on order ${paymentId}`, { provider: "kapitalbank" });
+function toCurrency(code2, paymentId) {
+  if (code2 === "AZN" || code2 === "USD" || code2 === "EUR" || code2 === "RUB" || code2 === "TRY" || code2 === "GBP") return code2;
+  throw new ManatError("provider_error", `kapitalbank: unexpected currency "${code2}" on order ${paymentId}`, { provider: "kapitalbank" });
 }
 function missingAmount(paymentId) {
   throw new ManatError("provider_error", `kapitalbank: order ${paymentId} has no amount to capture`, { provider: "kapitalbank" });
@@ -387,7 +392,6 @@ function pickBody(body, key) {
 var import_node_crypto = require("crypto");
 var GATEWAY_URLS = {
   test: "https://testmpi.3dsecure.az/cgi-bin/cgi_link",
-  // Not in the public docs (they only publish the test URL); used by existing integrations.
   production: "https://mpi.3dsecure.az/cgi-bin/cgi_link"
 };
 var AZERICARD_MAC_FIELDS = {
@@ -500,13 +504,7 @@ var AzericardProvider = class {
     }
     return event;
   }
-  /**
-   * TRTYPE 90. Works for 24 hours after the payment. The original TRTYPE is not known from the
-   * paymentId alone, so a purchase (1) is asked for first and a pre-auth (0) on "context mismatch".
-   * The answer only describes the transaction type asked about, so completion (21) and the
-   * reversals (22 online, 24 offline) are queried too. Only the latest offline reversal is
-   * visible this way, so refundedAmount can be lower than the truth after several 24s.
-   */
+  /** TRTYPE 90 answers for one transaction type, so the purchase (or pre-auth), completion and reversals are each queried. */
   async getStatus({ paymentId }) {
     if (!/^\d{6,32}$/.test(paymentId)) throw new ManatError("invalid_request", `azericard: paymentId must be the numeric ORDER, got "${paymentId}"`);
     let trtype = "1";
@@ -666,9 +664,9 @@ function parseAmount(amount, currency) {
   const alpha = /^\d{3}$/.test(currency) ? currencyFromNumeric(currency) : currency;
   return alpha ? fromDecimal(amount, toCurrency2(alpha)) : void 0;
 }
-function toCurrency2(code) {
-  if (code === "AZN" || code === "USD" || code === "EUR" || code === "RUB" || code === "TRY" || code === "GBP") return code;
-  throw new ManatError("provider_error", `azericard: unsupported currency "${code}"`, { provider: "azericard" });
+function toCurrency2(code2) {
+  if (code2 === "AZN" || code2 === "USD" || code2 === "EUR" || code2 === "RUB" || code2 === "TRY" || code2 === "GBP") return code2;
+  throw new ManatError("provider_error", `azericard: unsupported currency "${code2}"`, { provider: "azericard" });
 }
 function parseTimestamp(value) {
   const m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(value);
@@ -853,9 +851,9 @@ function encodeId(paymentId) {
   if (!/^[A-Za-z0-9-]{1,64}$/.test(paymentId)) throw new ManatError("invalid_request", `payriff: invalid paymentId "${paymentId}"`);
   return paymentId;
 }
-function toCurrency3(code) {
-  if (code === "AZN" || code === "USD" || code === "EUR" || code === "RUB" || code === "TRY" || code === "GBP") return code;
-  throw new ManatError("provider_error", `payriff: unsupported currency "${code}"`, { provider: "payriff" });
+function toCurrency3(code2) {
+  if (code2 === "AZN" || code2 === "USD" || code2 === "EUR" || code2 === "RUB" || code2 === "TRY" || code2 === "GBP") return code2;
+  throw new ManatError("provider_error", `payriff: unsupported currency "${code2}"`, { provider: "payriff" });
 }
 
 // src/crypto.ts
@@ -996,8 +994,8 @@ function epoint(config, options) {
 function formFields(body) {
   if (typeof body === "string") return Object.fromEntries(new URLSearchParams(body));
   if (!body || typeof body !== "object") return {};
-  const pick3 = (key) => typeof body[key] === "string" ? body[key] : void 0;
-  return { data: pick3("data"), signature: pick3("signature") };
+  const pick4 = (key) => typeof body[key] === "string" ? body[key] : void 0;
+  return { data: pick4("data"), signature: pick4("signature") };
 }
 function decodeData(data) {
   if (!/^[A-Za-z0-9+/]+={0,2}$/.test(data)) throw new ManatError("provider_error", "epoint: callback data is not base64", { provider: "epoint", raw: data });
@@ -1022,8 +1020,8 @@ var CAPABILITIES5 = /* @__PURE__ */ new Set(["createPayment", "verifyCallback",
 var SUCCESS2 = 1;
 var REVERSED = 817;
 var MAX_DESCRIPTION_BYTES = 500;
-function mapGoldenPayStatus(code) {
-  switch (code) {
+function mapGoldenPayStatus(code2) {
+  switch (code2) {
     case SUCCESS2:
       return "paid";
     case 813:
@@ -1041,7 +1039,7 @@ function mapGoldenPayStatus(code) {
     case REVERSED:
       return "refunded";
     default:
-      throw new ManatError("provider_error", `goldenpay: status code ${code} does not describe a payment`, { provider: "goldenpay" });
+      throw new ManatError("provider_error", `goldenpay: status code ${code2} does not describe a payment`, { provider: "goldenpay" });
   }
 }
 var PAYMENT_CODES = /* @__PURE__ */ new Set([SUCCESS2, 813, 814, 815, 816, REVERSED, 818, 819]);
@@ -1092,10 +1090,10 @@ var GoldenPayProvider = class {
     assertPaymentKey(paymentId);
     const query = new URLSearchParams({ payment_key: paymentId, hash_code: md5(this.config.authKey + paymentId) });
     const response = await this.call("GET", `getPaymentResult?${query}`);
-    const code = response.status?.code;
-    if (code === void 0 || !PAYMENT_CODES.has(code)) throw this.error("status is not available", response);
+    const code2 = response.status?.code;
+    if (code2 === void 0 || !PAYMENT_CODES.has(code2)) throw this.error("status is not available", response);
     if (response.paymentKey && response.paymentKey !== paymentId) throw this.error(`result is for payment ${response.paymentKey}, not ${paymentId}`, response);
-    const state = { paymentId, status: mapGoldenPayStatus(code), raw: response };
+    const state = { paymentId, status: mapGoldenPayStatus(code2), raw: response };
     if (typeof response.amount === "number" && response.amount > 0) state.amount = { amount: response.amount, currency: "AZN" };
     return state;
   }
@@ -1111,8 +1109,8 @@ var GoldenPayProvider = class {
       amount: amount.amount,
       secretKey: md5(hashCode + amount.amount)
     });
-    const code = response.status?.code;
-    if (code !== REVERSED && code !== SUCCESS2) throw this.error("refund failed", response);
+    const code2 = response.status?.code;
+    if (code2 !== REVERSED && code2 !== SUCCESS2) throw this.error("refund failed", response);
     const partial = payment.amount !== void 0 && amount.amount < payment.amount.amount;
     return { paymentId: request.paymentId, status: partial ? "partially_refunded" : "refunded", raw: { refund: response, payment: payment.raw } };
   }
@@ -1123,11 +1121,11 @@ var GoldenPayProvider = class {
     return data;
   }
   error(what, response) {
-    const { code, message } = response.status ?? {};
-    const fromProvider = code !== void 0 && code !== SUCCESS2;
+    const { code: code2, message } = response.status ?? {};
+    const fromProvider = code2 !== void 0 && code2 !== SUCCESS2;
     return new ManatError("provider_error", `goldenpay: ${fromProvider && message ? message : what}`, {
       provider: this.name,
-      ...fromProvider ? { providerCode: String(code) } : {},
+      ...fromProvider ? { providerCode: String(code2) } : {},
       ...fromProvider && message ? { providerMessage: message } : {},
       raw: response
     });
@@ -1165,6 +1163,177 @@ function pickBody2(body, key) {
   const value = body[key];
   return typeof value === "string" ? value : void 0;
 }
+
+// src/providers/yigim.ts
+var BASE_URLS3 = {
+  test: "https://sandbox.api.pay.yigim.az",
+  production: "https://api.pay.yigim.az"
+};
+var CAPABILITIES6 = /* @__PURE__ */ new Set(["createPayment", "verifyCallback", "getStatus", "refund", "capture", "cancel"]);
+var OK = 0;
+var DEFAULT_TEMPLATE = "TPL0001";
+var REFERENCE = /^[^\s\u0000-\u001f]{1,255}$/;
+function mapYigimStatus(status) {
+  switch (status) {
+    case "S0":
+    // created, waiting for card data
+    case "S2":
+    // in progress
+    case "S7":
+    // system malfunction
+    case "09":
+      return "pending";
+    case "S1":
+      return "authorized";
+    case "00":
+      return "paid";
+    case "S4":
+      return "cancelled";
+    case "S3":
+    // unknown error
+    case "01":
+    // refer to issuer
+    case "02":
+    // expired card
+    case "03":
+    // invalid amount
+    case "04":
+    // inactive card
+    case "05":
+    // insufficient funds
+    case "06":
+    // suspected fraud
+    case "07":
+    // exceeds withdrawal limit
+    case "08":
+      return "failed";
+    default:
+      throw new ManatError("provider_error", `yigim: unknown payment status "${status}"`, { provider: "yigim" });
+  }
+}
+var YigimProvider = class {
+  constructor(config, options = {}) {
+    this.config = config;
+    if (!config?.merchant) throw new ManatError("invalid_request", "yigim: merchant is required");
+    if (!config.apiKey) throw new ManatError("invalid_request", "yigim: apiKey is required");
+    if (!config.biller) throw new ManatError("invalid_request", "yigim: biller is required");
+    this.baseUrl = (config.baseUrl ?? BASE_URLS3[config.environment ?? "production"]).replace(/\/+$/, "");
+    this.http = new HttpClient(this.name, options);
+  }
+  config;
+  name = "yigim";
+  capabilities = CAPABILITIES6;
+  http;
+  baseUrl;
+  async createPayment(request) {
+    assertReference(request.orderId);
+    if (/[&;]/.test(request.returnUrl)) {
+      throw new ManatError("invalid_request", 'yigim: returnUrl may carry at most one query parameter and no ";"');
+    }
+    const params = {
+      reference: request.orderId,
+      type: request.intent === "authorize" ? "DMS" : "SMS",
+      amount: String(request.amount.amount),
+      currency: currencyNumericCode(request.amount.currency),
+      biller: this.config.biller
+    };
+    if (request.description) params.description = request.description;
+    params.template = this.config.template ?? DEFAULT_TEMPLATE;
+    params.language = request.language ?? "az";
+    if (request.callbackUrl) params.callback = request.callbackUrl.includes("?") ? request.callbackUrl : `${request.callbackUrl}?`;
+    params.extra = `back-url=${request.returnUrl};fail-url=${request.returnUrl}`;
+    const reply = await this.call("payment/create", params);
+    if (!reply.url) throw this.error("payment page URL is missing", reply);
+    return { paymentId: request.orderId, status: "pending", next: { type: "redirect", url: reply.url }, raw: reply };
+  }
+  async verifyCallback(callback) {
+    const reference = pick3(callback.query, "reference") ?? pickBody3(callback.body, "reference");
+    if (!reference || !REFERENCE.test(reference)) {
+      throw new ManatError("invalid_signature", "yigim: callback has no reference", { provider: this.name, raw: callback });
+    }
+    const state = await this.getStatus({ paymentId: reference });
+    const event = { paymentId: state.paymentId, orderId: state.paymentId, status: state.status, raw: state.raw };
+    if (state.amount) event.amount = state.amount;
+    return event;
+  }
+  async getStatus({ paymentId }) {
+    assertReference(paymentId);
+    const reply = await this.call("payment/status", { reference: paymentId });
+    if (reply.reference && reply.reference !== paymentId) throw this.error(`status is for payment ${reply.reference}, not ${paymentId}`, reply);
+    const state = { paymentId, status: mapYigimStatus(reply.status), raw: reply };
+    const currency = typeof reply.currency === "string" ? currencyFromNumeric(reply.currency) : void 0;
+    if (reply.amount !== void 0 && reply.amount !== "" && currency) state.amount = fromDecimal(String(reply.amount), currency);
+    return state;
+  }
+  async refund(request) {
+    const reply = await this.call("payment/refund", withAmount(request.paymentId, request.amount));
+    const state = await this.getStatus({ paymentId: request.paymentId });
+    return { paymentId: request.paymentId, status: refundStatus(state, request.amount), raw: { refund: reply, payment: state.raw } };
+  }
+  async capture({ paymentId, amount }) {
+    await this.call("payment/charge", withAmount(paymentId, amount));
+    return this.getStatus({ paymentId });
+  }
+  async cancel({ paymentId }) {
+    await this.call("payment/cancel", { reference: paymentId });
+    return this.getStatus({ paymentId });
+  }
+  async call(command, params) {
+    assertReference(params.reference ?? "");
+    const { status, data } = await this.http.json({
+      method: "GET",
+      url: `${this.baseUrl}/${command}?${new URLSearchParams(params)}`,
+      headers: { "x-merchant": this.config.merchant, "x-api-key": this.config.apiKey, "x-type": "JSON" }
+    });
+    const reply = unwrap(data);
+    if (!reply || code(reply) === void 0) {
+      throw new ManatError("provider_error", `yigim: unexpected response (HTTP ${status})`, { provider: this.name, raw: data });
+    }
+    if (status >= 400 || code(reply) !== OK) throw this.error(`HTTP ${status}`, reply);
+    return reply;
+  }
+  error(what, reply) {
+    const fromProvider = code(reply) !== void 0 && code(reply) !== OK;
+    return new ManatError("provider_error", `yigim: ${fromProvider && reply.message ? reply.message : what}`, {
+      provider: this.name,
+      ...fromProvider ? { providerCode: String(reply.code) } : {},
+      ...fromProvider && reply.message ? { providerMessage: reply.message } : {},
+      raw: reply
+    });
+  }
+};
+function yigim(config, options) {
+  return new YigimProvider(config, options);
+}
+function code(reply) {
+  if (typeof reply.code === "number") return reply.code;
+  return typeof reply.code === "string" && /^-?\d+$/.test(reply.code) ? Number(reply.code) : void 0;
+}
+function unwrap(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const inner = data.response;
+  return inner && typeof inner === "object" ? inner : data;
+}
+function withAmount(reference, amount) {
+  return amount ? { reference, amount: String(amount.amount) } : { reference };
+}
+function refundStatus(state, amount) {
+  if (state.status !== "paid") return state.status;
+  return amount && state.amount && amount.amount < state.amount.amount ? "partially_refunded" : "refunded";
+}
+function assertReference(reference) {
+  if (!REFERENCE.test(reference)) throw new ManatError("invalid_request", `yigim: invalid reference "${reference}"`);
+}
+function pick3(source, key) {
+  const value = source?.[key];
+  return Array.isArray(value) ? value[0] : value;
+}
+function pickBody3(body, key) {
+  if (!body) return void 0;
+  if (typeof body === "string") return new URLSearchParams(body).get(key) ?? void 0;
+  const value = body[key];
+  return typeof value === "string" ? value : void 0;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AZERICARD_MAC_FIELDS,
@@ -1175,6 +1344,7 @@ function pickBody2(body, key) {
   Manat,
   ManatError,
   PayriffProvider,
+  YigimProvider,
   azericard,
   azn,
   epoint,
@@ -1183,5 +1353,6 @@ function pickBody2(body, key) {
   isManatError,
   kapitalBank,
   payriff,
-  toDecimalString
+  toDecimalString,
+  yigim
 });

package/dist/index.d.cts

@@ -207,7 +207,7 @@ interface AzericardConfig {
     clock?: () => Date;
     nonce?: () => string;
 }
-/** MAC field orders from the docs (sections 2.2.1–2.2.4 and 4.3). */
+/** MAC field orders per message type. */
 declare const AZERICARD_MAC_FIELDS: Readonly<Record<AzericardMessage, readonly string[]>>;
 declare class AzericardProvider implements PaymentProvider {
     private readonly config;
@@ -223,13 +223,7 @@ declare class AzericardProvider implements PaymentProvider {
     constructor(config: AzericardConfig, options?: HttpOptions);
     createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
     verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
-    /**
-     * TRTYPE 90. Works for 24 hours after the payment. The original TRTYPE is not known from the
-     * paymentId alone, so a purchase (1) is asked for first and a pre-auth (0) on "context mismatch".
-     * The answer only describes the transaction type asked about, so completion (21) and the
-     * reversals (22 online, 24 offline) are queried too. Only the latest offline reversal is
-     * visible this way, so refundedAmount can be lower than the truth after several 24s.
-     */
+    /** TRTYPE 90 answers for one transaction type, so the purchase (or pre-auth), completion and reversals are each queried. */
     getStatus({ paymentId }: {
         paymentId: string;
     }): Promise<PaymentState>;
@@ -321,4 +315,37 @@ declare class GoldenPayProvider implements PaymentProvider {
 }
 declare function goldenPay(config: GoldenPayConfig, options?: HttpOptions): GoldenPayProvider;
 
-export { AZERICARD_MAC_FIELDS, type AzericardConfig, type AzericardMessage, AzericardProvider, type Capability, type CreatePaymentRequest, type CreatePaymentResult, type Currency, type EpointConfig, EpointProvider, type FetchLike, type GoldenPayConfig, GoldenPayProvider, type HttpOptions, type IncomingCallback, type KapitalBankConfig, KapitalBankProvider, type Language, Manat, ManatError, type ManatErrorCode, type Money, type NextAction, type PaymentAction, type PaymentEvent, type PaymentProvider, type PaymentState, type PaymentStatus, type PayriffConfig, PayriffProvider, type RefundRequest, type RefundResult, azericard, azn, epoint, fromDecimal, goldenPay, isManatError, kapitalBank, payriff, toDecimalString };
+interface YigimConfig {
+    /** Merchant name issued by Yığım (`X-Merchant`). */
+    merchant: string;
+    /** API key issued by Yığım (`X-API-Key`). */
+    apiKey: string;
+    /** Biller name provided by the acquirer. */
+    biller: string;
+    /** Payment page template; default `TPL0001`. */
+    template?: string;
+    environment?: 'test' | 'production';
+    /** Override the API host. */
+    baseUrl?: string;
+}
+declare class YigimProvider implements PaymentProvider {
+    private readonly config;
+    readonly name = "yigim";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    private readonly baseUrl;
+    constructor(config: YigimConfig, options?: HttpOptions);
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus({ paymentId }: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    capture({ paymentId, amount }: PaymentAction): Promise<PaymentState>;
+    cancel({ paymentId }: PaymentAction): Promise<PaymentState>;
+    private call;
+    private error;
+}
+declare function yigim(config: YigimConfig, options?: HttpOptions): YigimProvider;
+
+export { AZERICARD_MAC_FIELDS, type AzericardConfig, type AzericardMessage, AzericardProvider, type Capability, type CreatePaymentRequest, type CreatePaymentResult, type Currency, type EpointConfig, EpointProvider, type FetchLike, type GoldenPayConfig, GoldenPayProvider, type HttpOptions, type IncomingCallback, type KapitalBankConfig, KapitalBankProvider, type Language, Manat, ManatError, type ManatErrorCode, type Money, type NextAction, type PaymentAction, type PaymentEvent, type PaymentProvider, type PaymentState, type PaymentStatus, type PayriffConfig, PayriffProvider, type RefundRequest, type RefundResult, type YigimConfig, YigimProvider, azericard, azn, epoint, fromDecimal, goldenPay, isManatError, kapitalBank, payriff, toDecimalString, yigim };

package/dist/index.d.ts

@@ -207,7 +207,7 @@ interface AzericardConfig {
     clock?: () => Date;
     nonce?: () => string;
 }
-/** MAC field orders from the docs (sections 2.2.1–2.2.4 and 4.3). */
+/** MAC field orders per message type. */
 declare const AZERICARD_MAC_FIELDS: Readonly<Record<AzericardMessage, readonly string[]>>;
 declare class AzericardProvider implements PaymentProvider {
     private readonly config;
@@ -223,13 +223,7 @@ declare class AzericardProvider implements PaymentProvider {
     constructor(config: AzericardConfig, options?: HttpOptions);
     createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
     verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
-    /**
-     * TRTYPE 90. Works for 24 hours after the payment. The original TRTYPE is not known from the
-     * paymentId alone, so a purchase (1) is asked for first and a pre-auth (0) on "context mismatch".
-     * The answer only describes the transaction type asked about, so completion (21) and the
-     * reversals (22 online, 24 offline) are queried too. Only the latest offline reversal is
-     * visible this way, so refundedAmount can be lower than the truth after several 24s.
-     */
+    /** TRTYPE 90 answers for one transaction type, so the purchase (or pre-auth), completion and reversals are each queried. */
     getStatus({ paymentId }: {
         paymentId: string;
     }): Promise<PaymentState>;
@@ -321,4 +315,37 @@ declare class GoldenPayProvider implements PaymentProvider {
 }
 declare function goldenPay(config: GoldenPayConfig, options?: HttpOptions): GoldenPayProvider;
 
-export { AZERICARD_MAC_FIELDS, type AzericardConfig, type AzericardMessage, AzericardProvider, type Capability, type CreatePaymentRequest, type CreatePaymentResult, type Currency, type EpointConfig, EpointProvider, type FetchLike, type GoldenPayConfig, GoldenPayProvider, type HttpOptions, type IncomingCallback, type KapitalBankConfig, KapitalBankProvider, type Language, Manat, ManatError, type ManatErrorCode, type Money, type NextAction, type PaymentAction, type PaymentEvent, type PaymentProvider, type PaymentState, type PaymentStatus, type PayriffConfig, PayriffProvider, type RefundRequest, type RefundResult, azericard, azn, epoint, fromDecimal, goldenPay, isManatError, kapitalBank, payriff, toDecimalString };
+interface YigimConfig {
+    /** Merchant name issued by Yığım (`X-Merchant`). */
+    merchant: string;
+    /** API key issued by Yığım (`X-API-Key`). */
+    apiKey: string;
+    /** Biller name provided by the acquirer. */
+    biller: string;
+    /** Payment page template; default `TPL0001`. */
+    template?: string;
+    environment?: 'test' | 'production';
+    /** Override the API host. */
+    baseUrl?: string;
+}
+declare class YigimProvider implements PaymentProvider {
+    private readonly config;
+    readonly name = "yigim";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    private readonly baseUrl;
+    constructor(config: YigimConfig, options?: HttpOptions);
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus({ paymentId }: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    capture({ paymentId, amount }: PaymentAction): Promise<PaymentState>;
+    cancel({ paymentId }: PaymentAction): Promise<PaymentState>;
+    private call;
+    private error;
+}
+declare function yigim(config: YigimConfig, options?: HttpOptions): YigimProvider;
+
+export { AZERICARD_MAC_FIELDS, type AzericardConfig, type AzericardMessage, AzericardProvider, type Capability, type CreatePaymentRequest, type CreatePaymentResult, type Currency, type EpointConfig, EpointProvider, type FetchLike, type GoldenPayConfig, GoldenPayProvider, type HttpOptions, type IncomingCallback, type KapitalBankConfig, KapitalBankProvider, type Language, Manat, ManatError, type ManatErrorCode, type Money, type NextAction, type PaymentAction, type PaymentEvent, type PaymentProvider, type PaymentState, type PaymentStatus, type PayriffConfig, PayriffProvider, type RefundRequest, type RefundResult, type YigimConfig, YigimProvider, azericard, azn, epoint, fromDecimal, goldenPay, isManatError, kapitalBank, payriff, toDecimalString, yigim };

package/dist/index.js

@@ -5,18 +5,18 @@ var ManatError = class extends Error {
   providerCode;
   providerMessage;
   raw;
-  constructor(code, message, details = {}) {
+  constructor(code2, message, details = {}) {
     super(message, details.cause === void 0 ? void 0 : { cause: details.cause });
     this.name = "ManatError";
-    this.code = code;
+    this.code = code2;
     this.provider = details.provider;
     this.providerCode = details.providerCode;
     this.providerMessage = details.providerMessage;
     this.raw = details.raw;
   }
 };
-function isManatError(error, code) {
-  return error instanceof ManatError && (code === void 0 || error.code === code);
+function isManatError(error, code2) {
+  return error instanceof ManatError && (code2 === void 0 || error.code === code2);
 }
 
 // src/money.ts
@@ -45,8 +45,11 @@ function fromDecimal(value, currency) {
   const fraction = (match[2] ?? "").padEnd(digits, "0");
   return { amount: Number(`${match[1]}${fraction}`), currency };
 }
-function currencyFromNumeric(code) {
-  return Object.keys(NUMERIC_CODES).find((c) => NUMERIC_CODES[c] === code);
+function currencyNumericCode(currency) {
+  return NUMERIC_CODES[currency];
+}
+function currencyFromNumeric(code2) {
+  return Object.keys(NUMERIC_CODES).find((c) => NUMERIC_CODES[c] === code2);
 }
 function azn(value) {
   return fromDecimal(value, "AZN");
@@ -323,9 +326,9 @@ function kapitalBank(config, options) {
 function assertOrderId(paymentId) {
   if (!/^\d+$/.test(paymentId)) throw new ManatError("invalid_request", `kapitalbank: paymentId must be the numeric order id, got "${paymentId}"`);
 }
-function toCurrency(code, paymentId) {
-  if (code === "AZN" || code === "USD" || code === "EUR" || code === "RUB" || code === "TRY" || code === "GBP") return code;
-  throw new ManatError("provider_error", `kapitalbank: unexpected currency "${code}" on order ${paymentId}`, { provider: "kapitalbank" });
+function toCurrency(code2, paymentId) {
+  if (code2 === "AZN" || code2 === "USD" || code2 === "EUR" || code2 === "RUB" || code2 === "TRY" || code2 === "GBP") return code2;
+  throw new ManatError("provider_error", `kapitalbank: unexpected currency "${code2}" on order ${paymentId}`, { provider: "kapitalbank" });
 }
 function missingAmount(paymentId) {
   throw new ManatError("provider_error", `kapitalbank: order ${paymentId} has no amount to capture`, { provider: "kapitalbank" });
@@ -345,7 +348,6 @@ function pickBody(body, key) {
 import { createPrivateKey, createPublicKey, randomBytes, sign, verify } from "crypto";
 var GATEWAY_URLS = {
   test: "https://testmpi.3dsecure.az/cgi-bin/cgi_link",
-  // Not in the public docs (they only publish the test URL); used by existing integrations.
   production: "https://mpi.3dsecure.az/cgi-bin/cgi_link"
 };
 var AZERICARD_MAC_FIELDS = {
@@ -458,13 +460,7 @@ var AzericardProvider = class {
     }
     return event;
   }
-  /**
-   * TRTYPE 90. Works for 24 hours after the payment. The original TRTYPE is not known from the
-   * paymentId alone, so a purchase (1) is asked for first and a pre-auth (0) on "context mismatch".
-   * The answer only describes the transaction type asked about, so completion (21) and the
-   * reversals (22 online, 24 offline) are queried too. Only the latest offline reversal is
-   * visible this way, so refundedAmount can be lower than the truth after several 24s.
-   */
+  /** TRTYPE 90 answers for one transaction type, so the purchase (or pre-auth), completion and reversals are each queried. */
   async getStatus({ paymentId }) {
     if (!/^\d{6,32}$/.test(paymentId)) throw new ManatError("invalid_request", `azericard: paymentId must be the numeric ORDER, got "${paymentId}"`);
     let trtype = "1";
@@ -624,9 +620,9 @@ function parseAmount(amount, currency) {
   const alpha = /^\d{3}$/.test(currency) ? currencyFromNumeric(currency) : currency;
   return alpha ? fromDecimal(amount, toCurrency2(alpha)) : void 0;
 }
-function toCurrency2(code) {
-  if (code === "AZN" || code === "USD" || code === "EUR" || code === "RUB" || code === "TRY" || code === "GBP") return code;
-  throw new ManatError("provider_error", `azericard: unsupported currency "${code}"`, { provider: "azericard" });
+function toCurrency2(code2) {
+  if (code2 === "AZN" || code2 === "USD" || code2 === "EUR" || code2 === "RUB" || code2 === "TRY" || code2 === "GBP") return code2;
+  throw new ManatError("provider_error", `azericard: unsupported currency "${code2}"`, { provider: "azericard" });
 }
 function parseTimestamp(value) {
   const m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(value);
@@ -811,9 +807,9 @@ function encodeId(paymentId) {
   if (!/^[A-Za-z0-9-]{1,64}$/.test(paymentId)) throw new ManatError("invalid_request", `payriff: invalid paymentId "${paymentId}"`);
   return paymentId;
 }
-function toCurrency3(code) {
-  if (code === "AZN" || code === "USD" || code === "EUR" || code === "RUB" || code === "TRY" || code === "GBP") return code;
-  throw new ManatError("provider_error", `payriff: unsupported currency "${code}"`, { provider: "payriff" });
+function toCurrency3(code2) {
+  if (code2 === "AZN" || code2 === "USD" || code2 === "EUR" || code2 === "RUB" || code2 === "TRY" || code2 === "GBP") return code2;
+  throw new ManatError("provider_error", `payriff: unsupported currency "${code2}"`, { provider: "payriff" });
 }
 
 // src/crypto.ts
@@ -954,8 +950,8 @@ function epoint(config, options) {
 function formFields(body) {
   if (typeof body === "string") return Object.fromEntries(new URLSearchParams(body));
   if (!body || typeof body !== "object") return {};
-  const pick3 = (key) => typeof body[key] === "string" ? body[key] : void 0;
-  return { data: pick3("data"), signature: pick3("signature") };
+  const pick4 = (key) => typeof body[key] === "string" ? body[key] : void 0;
+  return { data: pick4("data"), signature: pick4("signature") };
 }
 function decodeData(data) {
   if (!/^[A-Za-z0-9+/]+={0,2}$/.test(data)) throw new ManatError("provider_error", "epoint: callback data is not base64", { provider: "epoint", raw: data });
@@ -980,8 +976,8 @@ var CAPABILITIES5 = /* @__PURE__ */ new Set(["createPayment", "verifyCallback",
 var SUCCESS2 = 1;
 var REVERSED = 817;
 var MAX_DESCRIPTION_BYTES = 500;
-function mapGoldenPayStatus(code) {
-  switch (code) {
+function mapGoldenPayStatus(code2) {
+  switch (code2) {
     case SUCCESS2:
       return "paid";
     case 813:
@@ -999,7 +995,7 @@ function mapGoldenPayStatus(code) {
     case REVERSED:
       return "refunded";
     default:
-      throw new ManatError("provider_error", `goldenpay: status code ${code} does not describe a payment`, { provider: "goldenpay" });
+      throw new ManatError("provider_error", `goldenpay: status code ${code2} does not describe a payment`, { provider: "goldenpay" });
   }
 }
 var PAYMENT_CODES = /* @__PURE__ */ new Set([SUCCESS2, 813, 814, 815, 816, REVERSED, 818, 819]);
@@ -1050,10 +1046,10 @@ var GoldenPayProvider = class {
     assertPaymentKey(paymentId);
     const query = new URLSearchParams({ payment_key: paymentId, hash_code: md5(this.config.authKey + paymentId) });
     const response = await this.call("GET", `getPaymentResult?${query}`);
-    const code = response.status?.code;
-    if (code === void 0 || !PAYMENT_CODES.has(code)) throw this.error("status is not available", response);
+    const code2 = response.status?.code;
+    if (code2 === void 0 || !PAYMENT_CODES.has(code2)) throw this.error("status is not available", response);
     if (response.paymentKey && response.paymentKey !== paymentId) throw this.error(`result is for payment ${response.paymentKey}, not ${paymentId}`, response);
-    const state = { paymentId, status: mapGoldenPayStatus(code), raw: response };
+    const state = { paymentId, status: mapGoldenPayStatus(code2), raw: response };
     if (typeof response.amount === "number" && response.amount > 0) state.amount = { amount: response.amount, currency: "AZN" };
     return state;
   }
@@ -1069,8 +1065,8 @@ var GoldenPayProvider = class {
       amount: amount.amount,
       secretKey: md5(hashCode + amount.amount)
     });
-    const code = response.status?.code;
-    if (code !== REVERSED && code !== SUCCESS2) throw this.error("refund failed", response);
+    const code2 = response.status?.code;
+    if (code2 !== REVERSED && code2 !== SUCCESS2) throw this.error("refund failed", response);
     const partial = payment.amount !== void 0 && amount.amount < payment.amount.amount;
     return { paymentId: request.paymentId, status: partial ? "partially_refunded" : "refunded", raw: { refund: response, payment: payment.raw } };
   }
@@ -1081,11 +1077,11 @@ var GoldenPayProvider = class {
     return data;
   }
   error(what, response) {
-    const { code, message } = response.status ?? {};
-    const fromProvider = code !== void 0 && code !== SUCCESS2;
+    const { code: code2, message } = response.status ?? {};
+    const fromProvider = code2 !== void 0 && code2 !== SUCCESS2;
     return new ManatError("provider_error", `goldenpay: ${fromProvider && message ? message : what}`, {
       provider: this.name,
-      ...fromProvider ? { providerCode: String(code) } : {},
+      ...fromProvider ? { providerCode: String(code2) } : {},
       ...fromProvider && message ? { providerMessage: message } : {},
       raw: response
     });
@@ -1123,6 +1119,177 @@ function pickBody2(body, key) {
   const value = body[key];
   return typeof value === "string" ? value : void 0;
 }
+
+// src/providers/yigim.ts
+var BASE_URLS3 = {
+  test: "https://sandbox.api.pay.yigim.az",
+  production: "https://api.pay.yigim.az"
+};
+var CAPABILITIES6 = /* @__PURE__ */ new Set(["createPayment", "verifyCallback", "getStatus", "refund", "capture", "cancel"]);
+var OK = 0;
+var DEFAULT_TEMPLATE = "TPL0001";
+var REFERENCE = /^[^\s\u0000-\u001f]{1,255}$/;
+function mapYigimStatus(status) {
+  switch (status) {
+    case "S0":
+    // created, waiting for card data
+    case "S2":
+    // in progress
+    case "S7":
+    // system malfunction
+    case "09":
+      return "pending";
+    case "S1":
+      return "authorized";
+    case "00":
+      return "paid";
+    case "S4":
+      return "cancelled";
+    case "S3":
+    // unknown error
+    case "01":
+    // refer to issuer
+    case "02":
+    // expired card
+    case "03":
+    // invalid amount
+    case "04":
+    // inactive card
+    case "05":
+    // insufficient funds
+    case "06":
+    // suspected fraud
+    case "07":
+    // exceeds withdrawal limit
+    case "08":
+      return "failed";
+    default:
+      throw new ManatError("provider_error", `yigim: unknown payment status "${status}"`, { provider: "yigim" });
+  }
+}
+var YigimProvider = class {
+  constructor(config, options = {}) {
+    this.config = config;
+    if (!config?.merchant) throw new ManatError("invalid_request", "yigim: merchant is required");
+    if (!config.apiKey) throw new ManatError("invalid_request", "yigim: apiKey is required");
+    if (!config.biller) throw new ManatError("invalid_request", "yigim: biller is required");
+    this.baseUrl = (config.baseUrl ?? BASE_URLS3[config.environment ?? "production"]).replace(/\/+$/, "");
+    this.http = new HttpClient(this.name, options);
+  }
+  config;
+  name = "yigim";
+  capabilities = CAPABILITIES6;
+  http;
+  baseUrl;
+  async createPayment(request) {
+    assertReference(request.orderId);
+    if (/[&;]/.test(request.returnUrl)) {
+      throw new ManatError("invalid_request", 'yigim: returnUrl may carry at most one query parameter and no ";"');
+    }
+    const params = {
+      reference: request.orderId,
+      type: request.intent === "authorize" ? "DMS" : "SMS",
+      amount: String(request.amount.amount),
+      currency: currencyNumericCode(request.amount.currency),
+      biller: this.config.biller
+    };
+    if (request.description) params.description = request.description;
+    params.template = this.config.template ?? DEFAULT_TEMPLATE;
+    params.language = request.language ?? "az";
+    if (request.callbackUrl) params.callback = request.callbackUrl.includes("?") ? request.callbackUrl : `${request.callbackUrl}?`;
+    params.extra = `back-url=${request.returnUrl};fail-url=${request.returnUrl}`;
+    const reply = await this.call("payment/create", params);
+    if (!reply.url) throw this.error("payment page URL is missing", reply);
+    return { paymentId: request.orderId, status: "pending", next: { type: "redirect", url: reply.url }, raw: reply };
+  }
+  async verifyCallback(callback) {
+    const reference = pick3(callback.query, "reference") ?? pickBody3(callback.body, "reference");
+    if (!reference || !REFERENCE.test(reference)) {
+      throw new ManatError("invalid_signature", "yigim: callback has no reference", { provider: this.name, raw: callback });
+    }
+    const state = await this.getStatus({ paymentId: reference });
+    const event = { paymentId: state.paymentId, orderId: state.paymentId, status: state.status, raw: state.raw };
+    if (state.amount) event.amount = state.amount;
+    return event;
+  }
+  async getStatus({ paymentId }) {
+    assertReference(paymentId);
+    const reply = await this.call("payment/status", { reference: paymentId });
+    if (reply.reference && reply.reference !== paymentId) throw this.error(`status is for payment ${reply.reference}, not ${paymentId}`, reply);
+    const state = { paymentId, status: mapYigimStatus(reply.status), raw: reply };
+    const currency = typeof reply.currency === "string" ? currencyFromNumeric(reply.currency) : void 0;
+    if (reply.amount !== void 0 && reply.amount !== "" && currency) state.amount = fromDecimal(String(reply.amount), currency);
+    return state;
+  }
+  async refund(request) {
+    const reply = await this.call("payment/refund", withAmount(request.paymentId, request.amount));
+    const state = await this.getStatus({ paymentId: request.paymentId });
+    return { paymentId: request.paymentId, status: refundStatus(state, request.amount), raw: { refund: reply, payment: state.raw } };
+  }
+  async capture({ paymentId, amount }) {
+    await this.call("payment/charge", withAmount(paymentId, amount));
+    return this.getStatus({ paymentId });
+  }
+  async cancel({ paymentId }) {
+    await this.call("payment/cancel", { reference: paymentId });
+    return this.getStatus({ paymentId });
+  }
+  async call(command, params) {
+    assertReference(params.reference ?? "");
+    const { status, data } = await this.http.json({
+      method: "GET",
+      url: `${this.baseUrl}/${command}?${new URLSearchParams(params)}`,
+      headers: { "x-merchant": this.config.merchant, "x-api-key": this.config.apiKey, "x-type": "JSON" }
+    });
+    const reply = unwrap(data);
+    if (!reply || code(reply) === void 0) {
+      throw new ManatError("provider_error", `yigim: unexpected response (HTTP ${status})`, { provider: this.name, raw: data });
+    }
+    if (status >= 400 || code(reply) !== OK) throw this.error(`HTTP ${status}`, reply);
+    return reply;
+  }
+  error(what, reply) {
+    const fromProvider = code(reply) !== void 0 && code(reply) !== OK;
+    return new ManatError("provider_error", `yigim: ${fromProvider && reply.message ? reply.message : what}`, {
+      provider: this.name,
+      ...fromProvider ? { providerCode: String(reply.code) } : {},
+      ...fromProvider && reply.message ? { providerMessage: reply.message } : {},
+      raw: reply
+    });
+  }
+};
+function yigim(config, options) {
+  return new YigimProvider(config, options);
+}
+function code(reply) {
+  if (typeof reply.code === "number") return reply.code;
+  return typeof reply.code === "string" && /^-?\d+$/.test(reply.code) ? Number(reply.code) : void 0;
+}
+function unwrap(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const inner = data.response;
+  return inner && typeof inner === "object" ? inner : data;
+}
+function withAmount(reference, amount) {
+  return amount ? { reference, amount: String(amount.amount) } : { reference };
+}
+function refundStatus(state, amount) {
+  if (state.status !== "paid") return state.status;
+  return amount && state.amount && amount.amount < state.amount.amount ? "partially_refunded" : "refunded";
+}
+function assertReference(reference) {
+  if (!REFERENCE.test(reference)) throw new ManatError("invalid_request", `yigim: invalid reference "${reference}"`);
+}
+function pick3(source, key) {
+  const value = source?.[key];
+  return Array.isArray(value) ? value[0] : value;
+}
+function pickBody3(body, key) {
+  if (!body) return void 0;
+  if (typeof body === "string") return new URLSearchParams(body).get(key) ?? void 0;
+  const value = body[key];
+  return typeof value === "string" ? value : void 0;
+}
 export {
   AZERICARD_MAC_FIELDS,
   AzericardProvider,
@@ -1132,6 +1299,7 @@ export {
   Manat,
   ManatError,
   PayriffProvider,
+  YigimProvider,
   azericard,
   azn,
   epoint,
@@ -1140,5 +1308,6 @@ export {
   isManatError,
   kapitalBank,
   payriff,
-  toDecimalString
+  toDecimalString,
+  yigim
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keytd/manat",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One API for Azerbaijani online payment providers.",
   "license": "MIT",
   "author": "KeyTD <info@keytd.com>",
@@ -23,7 +23,9 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -36,7 +38,19 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
-  "keywords": ["azerbaijan", "payments", "azn", "manat", "payment-gateway", "kapital-bank", "azericard", "payriff", "epoint", "goldenpay"],
+  "keywords": [
+    "azerbaijan",
+    "payments",
+    "azn",
+    "manat",
+    "payment-gateway",
+    "kapital-bank",
+    "azericard",
+    "payriff",
+    "epoint",
+    "goldenpay",
+    "yigim"
+  ],
   "devDependencies": {
     "@types/node": "^20.14.0",
     "tsup": "^8.3.0",