@cashela/payin 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @cashela/payin
+
+Zero-runtime-dependency Node.js SDK for the Cashela Pay-In API. Uses global
+`fetch` and `node:crypto`. Requires Node >= 18.
+
+**Server-only.** This package is meant to run on your backend. `api_secret`
+and your webhook signing secret must never be sent to, embedded in, or
+otherwise reach the browser. Nothing exported here is safe for client-side
+use.
+
+## Install
+
+```bash
+npm install @cashela/payin
+```
+
+## Usage: `CashelaPayIn`
+
+```ts
+import { CashelaPayIn } from "@cashela/payin";
+
+const payin = new CashelaPayIn({
+  environment: "sandbox", // "dev" | "staging" | "sandbox" | "production"
+  apiKey: process.env.CASHELA_API_KEY!,
+  apiSecret: process.env.CASHELA_API_SECRET!,
+});
+
+const deposit = await payin.createDeposit(
+  {
+    payment_type: "bank_transfer",
+    payment_method: "pse",
+    amount: 50000,
+    country: "COL",
+    external_identifier: "order-1234",
+    invoice_description: "Order #1234",
+    notification_url: "https://example.com/webhooks/cashela",
+    redirect_url: "https://example.com/checkout/return",
+    logo: "https://example.com/logo.png",
+    mobile: false,
+    language: "es",
+    fee_on_payer: true,
+    client_ip: "203.0.113.10",
+  },
+  { idempotencyKey: "order-1234" },
+);
+
+const transaction = await payin.getTransaction(deposit.data.reference);
+```
+
+`createDeposit` is never retried automatically by the SDK — retrying a
+deposit-creation POST can move money twice. If a request times out or the
+network fails, check `getTransaction` before deciding whether to resend.
+
+## Usage: `verifyWebhookSignature` in a handler
+
+```ts
+import { verifyWebhookSignature, WebhookSignatureError } from "@cashela/payin";
+
+// Example: a plain Node http handler receiving the raw request body.
+app.post("/webhooks/cashela", async (req, res) => {
+  const rawBody = await readRawBody(req); // read bytes BEFORE any JSON parsing
+
+  try {
+    const payload = verifyWebhookSignature({
+      rawBody,
+      signature: req.headers["x-cashela-signature"] as string,
+      timestamp: req.headers["x-cashela-timestamp"] as string,
+      nonce: req.headers["x-cashela-nonce"] as string,
+      secret: process.env.CASHELA_WEBHOOK_SECRET!,
+    });
+
+    // payload.status is one of COMPLETED | EXPIRED | CANCELLED | VOID | REFUND
+    await handleTransactionUpdate(payload);
+    res.sendStatus(200);
+  } catch (err) {
+    if (err instanceof WebhookSignatureError) {
+      res.sendStatus(400); // missing-header | bad-signature | stale-timestamp
+      return;
+    }
+    throw err;
+  }
+});
+```
+
+Verify against the **raw, unparsed** request body — re-serializing JSON
+before verifying will break the signature check.

package/dist/index.cjs

@@ -0,0 +1,139 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CashelaApiError: () => CashelaApiError,
+  CashelaPayIn: () => CashelaPayIn,
+  WebhookSignatureError: () => WebhookSignatureError,
+  resolveBaseUrl: () => resolveBaseUrl,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/environment.ts
+var ENVS = ["dev", "staging", "sandbox", "production"];
+function resolveBaseUrl(env, override) {
+  if (override) return override;
+  if (!ENVS.includes(env)) throw new Error(`unknown environment: ${env}`);
+  return `https://${env}-api.cashela.com/api/v1/pay-in`;
+}
+
+// src/errors.ts
+var CashelaApiError = class extends Error {
+  constructor(message, status, raw) {
+    super(message);
+    this.status = status;
+    this.raw = raw;
+    this.name = "CashelaApiError";
+  }
+  status;
+  raw;
+};
+var WebhookSignatureError = class extends Error {
+  constructor(reason) {
+    super(`webhook signature invalid: ${reason}`);
+    this.reason = reason;
+    this.name = "WebhookSignatureError";
+  }
+  reason;
+};
+
+// src/client.ts
+var CashelaPayIn = class {
+  baseUrl;
+  auth;
+  fetch;
+  timeoutMs;
+  constructor(opts) {
+    this.baseUrl = resolveBaseUrl(opts.environment, opts.baseUrl);
+    this.auth = "Basic " + Buffer.from(`${opts.apiKey}:${opts.apiSecret}`).toString("base64");
+    this.fetch = opts.fetch ?? globalThis.fetch;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  async request(method, path, body, extraHeaders) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: { Authorization: this.auth, "Content-Type": "application/json", Accept: "application/json", ...extraHeaders },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok || json?.success === false) {
+        throw new CashelaApiError(json?.message ?? `HTTP ${res.status}`, res.status, json);
+      }
+      return json;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  listCountries(params) {
+    const q = new URLSearchParams();
+    params?.payment_types?.forEach((t) => q.append("payment_types", t));
+    params?.countries?.forEach((c) => q.append("countries", c));
+    const qs = q.toString();
+    return this.request("GET", `/deposit-creation/countries${qs ? `?${qs}` : ""}`);
+  }
+  listPaymentMethods(body) {
+    return this.request("POST", "/deposit-creation/available-payment-methods", body);
+  }
+  getExchangeRates(body) {
+    return this.request("POST", "/deposit-creation/exchange-rates", body);
+  }
+  createDeposit(request, opts) {
+    return this.request("POST", "/deposit-creation", request, opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0);
+  }
+  getTransaction(reference) {
+    return this.request("GET", `/transactions/${encodeURIComponent(reference)}`);
+  }
+  resendCallback(reference) {
+    return this.request("POST", `/transactions/${encodeURIComponent(reference)}/callback`);
+  }
+};
+
+// src/webhook.ts
+var import_node_crypto = require("crypto");
+function verifyWebhookSignature(input) {
+  const { rawBody, signature, timestamp, nonce, secret } = input;
+  if (!signature || !timestamp || !nonce || rawBody == null || secret == null) {
+    throw new WebhookSignatureError("missing-header");
+  }
+  const tolerance = input.toleranceSeconds ?? 300;
+  const now = input.now ?? Math.floor(Date.now() / 1e3);
+  const ts = Number(timestamp);
+  if (!Number.isFinite(ts) || Math.abs(now - ts) > tolerance) throw new WebhookSignatureError("stale-timestamp");
+  const body = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestamp}.${nonce}.${body}`).digest("hex");
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(signature, "utf8");
+  if (a.length !== b.length || !(0, import_node_crypto.timingSafeEqual)(a, b)) throw new WebhookSignatureError("bad-signature");
+  return JSON.parse(body);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CashelaApiError,
+  CashelaPayIn,
+  WebhookSignatureError,
+  resolveBaseUrl,
+  verifyWebhookSignature
+});

package/dist/index.d.cts

@@ -0,0 +1,416 @@
+type CashelaEnvironment = "dev" | "staging" | "sandbox" | "production";
+declare function resolveBaseUrl(env: CashelaEnvironment, override?: string): string;
+
+interface WebhookPayload {
+    ref: string;
+    external_identifier: string;
+    status: "COMPLETED" | "EXPIRED" | "CANCELLED" | "VOID" | "REFUND";
+    date: string;
+    amount: number;
+    currency: string;
+    settlement_currency?: string;
+    net_amount?: number;
+    processing_fee_amount?: number;
+    fx_spread_amount?: number;
+    tax_amount?: number;
+}
+interface VerifyInput {
+    rawBody: string | Buffer;
+    signature: string;
+    timestamp: string;
+    nonce: string;
+    secret: string;
+    toleranceSeconds?: number;
+    now?: number;
+}
+declare function verifyWebhookSignature(input: VerifyInput): WebhookPayload;
+
+type FetchLike = (url: string, init?: any) => Promise<any>;
+interface CashelaPayInOptions {
+    environment: CashelaEnvironment;
+    apiKey: string;
+    apiSecret: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetch?: FetchLike;
+}
+interface CreateDepositOptions {
+    idempotencyKey?: string;
+}
+declare class CashelaPayIn {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly fetch;
+    private readonly timeoutMs;
+    constructor(opts: CashelaPayInOptions);
+    private request;
+    listCountries(params?: {
+        payment_types?: string[];
+        countries?: string[];
+    }): Promise<any>;
+    listPaymentMethods(body: {
+        country: string;
+        amount: number;
+        fee_on_payer?: boolean;
+        currency?: string;
+    }): Promise<any>;
+    getExchangeRates(body: {
+        country: string;
+        payment_type: string;
+        amount: number;
+    }): Promise<any>;
+    createDeposit(request: Record<string, unknown>, opts?: CreateDepositOptions): Promise<any>;
+    getTransaction(reference: string): Promise<any>;
+    resendCallback(reference: string): Promise<any>;
+}
+
+declare class CashelaApiError extends Error {
+    readonly status: number;
+    readonly raw: unknown;
+    constructor(message: string, status: number, raw: unknown);
+}
+type WebhookSignatureReason = "missing-header" | "bad-signature" | "stale-timestamp";
+declare class WebhookSignatureError extends Error {
+    readonly reason: WebhookSignatureReason;
+    constructor(reason: WebhookSignatureReason);
+}
+
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+interface paths {
+    "/deposit-creation/countries": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Lista países disponibles */
+        get: operations["listCountries"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/deposit-creation/available-payment-methods": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Métodos cotizables para país + monto */
+        post: operations["listPaymentMethods"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/deposit-creation/exchange-rates": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Tasa de cambio de un corredor */
+        post: operations["getExchangeRates"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/deposit-creation": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Crear depósito (mueve dinero) */
+        post: operations["createDeposit"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/transactions/{reference}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Leer un depósito (ref, external_identifier o id interno) */
+        get: operations["getTransaction"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/transactions/{reference}/callback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reenviar la notificación de resultado (solo si terminal) */
+        post: operations["resendCallback"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        Envelope: {
+            success: boolean;
+            message: string;
+            data?: unknown;
+        };
+        DepositCreationRequest: {
+            payment_type: string;
+            payment_method: string;
+            amount: number;
+            country: string;
+            external_identifier: string;
+            invoice_description: string;
+            /** Format: uri */
+            notification_url: string;
+            /** Format: uri */
+            redirect_url: string;
+            /** Format: uri */
+            logo: string;
+            mobile: boolean;
+            /** @enum {string} */
+            language: "en" | "es";
+            fee_on_payer: boolean;
+            client_ip: string;
+            first_name?: string;
+            last_name?: string;
+            /** Format: email */
+            email?: string;
+            phone?: string;
+            /** @description Clave (no etiqueta). Ej: CHL=RUT, COL=CC|CE|NIT. */
+            document_key?: string;
+            document_number?: string;
+            address?: string;
+            zip?: string;
+            city_id?: string;
+        };
+        WebhookPayload: {
+            ref: string;
+            external_identifier: string;
+            /** @enum {string} */
+            status: "COMPLETED" | "EXPIRED" | "CANCELLED" | "VOID" | "REFUND";
+            date: string;
+            amount: number;
+            currency: string;
+            settlement_currency?: string;
+            net_amount?: number;
+            processing_fee_amount?: number;
+            fx_spread_amount?: number;
+            tax_amount?: number;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+interface operations {
+    listCountries: {
+        parameters: {
+            query?: {
+                payment_types?: string[];
+                countries?: string[];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    listPaymentMethods: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    country: string;
+                    amount: number;
+                    fee_on_payer?: boolean;
+                    currency?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    getExchangeRates: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    country: string;
+                    payment_type: string;
+                    amount: number;
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    createDeposit: {
+        parameters: {
+            query?: never;
+            header?: {
+                "Idempotency-Key"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["DepositCreationRequest"];
+            };
+        };
+        responses: {
+            /** @description Creado */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+            /** @description Validación */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    getTransaction: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                reference: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+            /** @description No encontrado */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    resendCallback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                reference: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Reencolado */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+}
+
+export { CashelaApiError, type CashelaEnvironment, CashelaPayIn, type CashelaPayInOptions, type CreateDepositOptions, type VerifyInput, type WebhookPayload, WebhookSignatureError, type WebhookSignatureReason, type components, type paths, resolveBaseUrl, verifyWebhookSignature };

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+type CashelaEnvironment = "dev" | "staging" | "sandbox" | "production";
+declare function resolveBaseUrl(env: CashelaEnvironment, override?: string): string;
+
+interface WebhookPayload {
+    ref: string;
+    external_identifier: string;
+    status: "COMPLETED" | "EXPIRED" | "CANCELLED" | "VOID" | "REFUND";
+    date: string;
+    amount: number;
+    currency: string;
+    settlement_currency?: string;
+    net_amount?: number;
+    processing_fee_amount?: number;
+    fx_spread_amount?: number;
+    tax_amount?: number;
+}
+interface VerifyInput {
+    rawBody: string | Buffer;
+    signature: string;
+    timestamp: string;
+    nonce: string;
+    secret: string;
+    toleranceSeconds?: number;
+    now?: number;
+}
+declare function verifyWebhookSignature(input: VerifyInput): WebhookPayload;
+
+type FetchLike = (url: string, init?: any) => Promise<any>;
+interface CashelaPayInOptions {
+    environment: CashelaEnvironment;
+    apiKey: string;
+    apiSecret: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetch?: FetchLike;
+}
+interface CreateDepositOptions {
+    idempotencyKey?: string;
+}
+declare class CashelaPayIn {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly fetch;
+    private readonly timeoutMs;
+    constructor(opts: CashelaPayInOptions);
+    private request;
+    listCountries(params?: {
+        payment_types?: string[];
+        countries?: string[];
+    }): Promise<any>;
+    listPaymentMethods(body: {
+        country: string;
+        amount: number;
+        fee_on_payer?: boolean;
+        currency?: string;
+    }): Promise<any>;
+    getExchangeRates(body: {
+        country: string;
+        payment_type: string;
+        amount: number;
+    }): Promise<any>;
+    createDeposit(request: Record<string, unknown>, opts?: CreateDepositOptions): Promise<any>;
+    getTransaction(reference: string): Promise<any>;
+    resendCallback(reference: string): Promise<any>;
+}
+
+declare class CashelaApiError extends Error {
+    readonly status: number;
+    readonly raw: unknown;
+    constructor(message: string, status: number, raw: unknown);
+}
+type WebhookSignatureReason = "missing-header" | "bad-signature" | "stale-timestamp";
+declare class WebhookSignatureError extends Error {
+    readonly reason: WebhookSignatureReason;
+    constructor(reason: WebhookSignatureReason);
+}
+
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+interface paths {
+    "/deposit-creation/countries": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Lista países disponibles */
+        get: operations["listCountries"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/deposit-creation/available-payment-methods": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Métodos cotizables para país + monto */
+        post: operations["listPaymentMethods"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/deposit-creation/exchange-rates": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Tasa de cambio de un corredor */
+        post: operations["getExchangeRates"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/deposit-creation": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Crear depósito (mueve dinero) */
+        post: operations["createDeposit"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/transactions/{reference}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Leer un depósito (ref, external_identifier o id interno) */
+        get: operations["getTransaction"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/transactions/{reference}/callback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reenviar la notificación de resultado (solo si terminal) */
+        post: operations["resendCallback"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        Envelope: {
+            success: boolean;
+            message: string;
+            data?: unknown;
+        };
+        DepositCreationRequest: {
+            payment_type: string;
+            payment_method: string;
+            amount: number;
+            country: string;
+            external_identifier: string;
+            invoice_description: string;
+            /** Format: uri */
+            notification_url: string;
+            /** Format: uri */
+            redirect_url: string;
+            /** Format: uri */
+            logo: string;
+            mobile: boolean;
+            /** @enum {string} */
+            language: "en" | "es";
+            fee_on_payer: boolean;
+            client_ip: string;
+            first_name?: string;
+            last_name?: string;
+            /** Format: email */
+            email?: string;
+            phone?: string;
+            /** @description Clave (no etiqueta). Ej: CHL=RUT, COL=CC|CE|NIT. */
+            document_key?: string;
+            document_number?: string;
+            address?: string;
+            zip?: string;
+            city_id?: string;
+        };
+        WebhookPayload: {
+            ref: string;
+            external_identifier: string;
+            /** @enum {string} */
+            status: "COMPLETED" | "EXPIRED" | "CANCELLED" | "VOID" | "REFUND";
+            date: string;
+            amount: number;
+            currency: string;
+            settlement_currency?: string;
+            net_amount?: number;
+            processing_fee_amount?: number;
+            fx_spread_amount?: number;
+            tax_amount?: number;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+interface operations {
+    listCountries: {
+        parameters: {
+            query?: {
+                payment_types?: string[];
+                countries?: string[];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    listPaymentMethods: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    country: string;
+                    amount: number;
+                    fee_on_payer?: boolean;
+                    currency?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    getExchangeRates: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    country: string;
+                    payment_type: string;
+                    amount: number;
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    createDeposit: {
+        parameters: {
+            query?: never;
+            header?: {
+                "Idempotency-Key"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["DepositCreationRequest"];
+            };
+        };
+        responses: {
+            /** @description Creado */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+            /** @description Validación */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    getTransaction: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                reference: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+            /** @description No encontrado */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+    resendCallback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                reference: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Reencolado */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Envelope"];
+                };
+            };
+        };
+    };
+}
+
+export { CashelaApiError, type CashelaEnvironment, CashelaPayIn, type CashelaPayInOptions, type CreateDepositOptions, type VerifyInput, type WebhookPayload, WebhookSignatureError, type WebhookSignatureReason, type components, type paths, resolveBaseUrl, verifyWebhookSignature };

package/dist/index.js

@@ -0,0 +1,108 @@
+// src/environment.ts
+var ENVS = ["dev", "staging", "sandbox", "production"];
+function resolveBaseUrl(env, override) {
+  if (override) return override;
+  if (!ENVS.includes(env)) throw new Error(`unknown environment: ${env}`);
+  return `https://${env}-api.cashela.com/api/v1/pay-in`;
+}
+
+// src/errors.ts
+var CashelaApiError = class extends Error {
+  constructor(message, status, raw) {
+    super(message);
+    this.status = status;
+    this.raw = raw;
+    this.name = "CashelaApiError";
+  }
+  status;
+  raw;
+};
+var WebhookSignatureError = class extends Error {
+  constructor(reason) {
+    super(`webhook signature invalid: ${reason}`);
+    this.reason = reason;
+    this.name = "WebhookSignatureError";
+  }
+  reason;
+};
+
+// src/client.ts
+var CashelaPayIn = class {
+  baseUrl;
+  auth;
+  fetch;
+  timeoutMs;
+  constructor(opts) {
+    this.baseUrl = resolveBaseUrl(opts.environment, opts.baseUrl);
+    this.auth = "Basic " + Buffer.from(`${opts.apiKey}:${opts.apiSecret}`).toString("base64");
+    this.fetch = opts.fetch ?? globalThis.fetch;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  async request(method, path, body, extraHeaders) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: { Authorization: this.auth, "Content-Type": "application/json", Accept: "application/json", ...extraHeaders },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok || json?.success === false) {
+        throw new CashelaApiError(json?.message ?? `HTTP ${res.status}`, res.status, json);
+      }
+      return json;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  listCountries(params) {
+    const q = new URLSearchParams();
+    params?.payment_types?.forEach((t) => q.append("payment_types", t));
+    params?.countries?.forEach((c) => q.append("countries", c));
+    const qs = q.toString();
+    return this.request("GET", `/deposit-creation/countries${qs ? `?${qs}` : ""}`);
+  }
+  listPaymentMethods(body) {
+    return this.request("POST", "/deposit-creation/available-payment-methods", body);
+  }
+  getExchangeRates(body) {
+    return this.request("POST", "/deposit-creation/exchange-rates", body);
+  }
+  createDeposit(request, opts) {
+    return this.request("POST", "/deposit-creation", request, opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0);
+  }
+  getTransaction(reference) {
+    return this.request("GET", `/transactions/${encodeURIComponent(reference)}`);
+  }
+  resendCallback(reference) {
+    return this.request("POST", `/transactions/${encodeURIComponent(reference)}/callback`);
+  }
+};
+
+// src/webhook.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(input) {
+  const { rawBody, signature, timestamp, nonce, secret } = input;
+  if (!signature || !timestamp || !nonce || rawBody == null || secret == null) {
+    throw new WebhookSignatureError("missing-header");
+  }
+  const tolerance = input.toleranceSeconds ?? 300;
+  const now = input.now ?? Math.floor(Date.now() / 1e3);
+  const ts = Number(timestamp);
+  if (!Number.isFinite(ts) || Math.abs(now - ts) > tolerance) throw new WebhookSignatureError("stale-timestamp");
+  const body = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+  const expected = createHmac("sha256", secret).update(`${timestamp}.${nonce}.${body}`).digest("hex");
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(signature, "utf8");
+  if (a.length !== b.length || !timingSafeEqual(a, b)) throw new WebhookSignatureError("bad-signature");
+  return JSON.parse(body);
+}
+export {
+  CashelaApiError,
+  CashelaPayIn,
+  WebhookSignatureError,
+  resolveBaseUrl,
+  verifyWebhookSignature
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@cashela/payin",
+  "version": "0.1.0",
+  "type": "module",
+  "engines": { "node": ">=18" },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" } },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "gen:types": "node scripts/gen-types.mjs",
+    "sync:vectors": "node scripts/sync-vectors.mjs"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "openapi-typescript": "^7.4.0",
+    "@types/node": "^20.14.0"
+  }
+}