@paykit-sdk/chapa 1.0.1

package/dist/schema.d.mts

@@ -0,0 +1,194 @@
+/**
+ * Chapa wraps every response in this envelope, e.g.
+ * `{ message: "Refund verified successfully", status: "success", data: {...} }`
+ */
+interface ChapaResponse<T = unknown> {
+    /**
+     * A human readable message describing the result
+     */
+    message: string;
+    /**
+     * Whether the request was successful
+     */
+    status: 'success' | 'failed';
+    /**
+     * The data of the response
+     */
+    data: T;
+}
+interface ChapaCustomization {
+    /**
+     * The title shown on the Chapa checkout page
+     */
+    title: string | null;
+    /**
+     * The description shown on the Chapa checkout page
+     */
+    description: string | null;
+    /**
+     * A logo shown on the Chapa checkout page
+     */
+    logo?: string | null;
+}
+/**
+ * The shape returned by `GET /transaction/verify/:tx_ref`, and the shape
+ * of the `charge.*` webhook payload (minus the `event` key).
+ */
+interface ChapaTransaction {
+    /**
+     * The customer's first name
+     */
+    first_name: string | null;
+    /**
+     * The customer's last name
+     */
+    last_name: string | null;
+    /**
+     * The customer's email
+     */
+    email: string | null;
+    /**
+     * The customer's mobile number
+     */
+    mobile: string | null;
+    /**
+     * The currency of the transaction e.g `ETB`
+     */
+    currency: string;
+    /**
+     * The amount of the transaction, as a decimal string e.g `"400.00"`
+     */
+    amount: string;
+    /**
+     * The fee charged by Chapa, as a decimal string
+     */
+    charge: string;
+    /**
+     * The status of the transaction
+     */
+    status: 'success' | 'failed' | 'pending' | string;
+    /**
+     * Whether the transaction happened in `test` or `live` mode
+     */
+    mode: 'test' | 'live';
+    /**
+     * Chapa's internal reference for the transaction
+     */
+    reference: string;
+    /**
+     * The created at timestamp of the transaction
+     */
+    created_at: string;
+    /**
+     * The updated at timestamp of the transaction
+     */
+    updated_at: string;
+    /**
+     * The channel the transaction was initiated through e.g `API`
+     */
+    type: string;
+    /**
+     * The merchant-supplied transaction reference
+     */
+    tx_ref: string;
+    /**
+     * The payment channel used e.g `telebirr`, `mpesa`, `card`
+     */
+    payment_method: string | null;
+    /**
+     * The checkout customization used for the transaction
+     */
+    customization: ChapaCustomization | null;
+    /**
+     * Free-form metadata echoed back from what was sent at initialization
+     */
+    meta: Record<string, unknown> | null;
+}
+interface ChapaInitializeResponse {
+    /**
+     * The URL to redirect the customer to in order to complete payment
+     */
+    checkout_url: string;
+}
+/**
+ * The shape returned by `GET /refund/:ref_id/verify`. The create-refund
+ * response is assumed to follow the same envelope/shape; fields that
+ * aren't confirmed there are backfilled from request-time context in
+ * the mapper rather than assumed present.
+ */
+interface ChapaRefund {
+    /**
+     * The refunded amount
+     */
+    amount: number;
+    /**
+     * The currency of the refund
+     */
+    currency: string;
+    /**
+     * Chapa's internal reference for the refund
+     */
+    ref_id: string;
+    /**
+     * The reference of the original payment being refunded
+     */
+    payment_reference: string;
+    /**
+     * An optional merchant-supplied reference for the refund
+     */
+    merchant_reference: string | null;
+    /**
+     * The status of the refund
+     */
+    status: 'initiated' | 'processing' | 'refunded' | 'reversed' | string;
+    /**
+     * The created at timestamp of the refund
+     */
+    created_at: string;
+    /**
+     * The updated at timestamp of the refund
+     */
+    updated_at: string;
+}
+interface ChapaWebhookTransactionEvent extends ChapaTransaction {
+    /**
+     * e.g `charge.success`. Chapa's docs also show `charge.refunded`,
+     * `charge.reversed` and `charge.failed/cancelled`, but only
+     * `charge.success` is unambiguously documented as a literal value -
+     * the others are handled defensively off the `status` field instead
+     * of an exact string match.
+     */
+    event: string;
+}
+interface ChapaWebhookPayoutEvent {
+    /**
+     * e.g `payout.success`
+     */
+    event: string;
+    type: 'Payout';
+    account_name: string;
+    account_number: string;
+    bank_id: number;
+    bank_name: string;
+    amount: string;
+    charge: string;
+    currency: string;
+    status: string;
+    reference: string;
+    chapa_reference: string;
+    bank_reference: string;
+    created_at: string;
+    updated_at: string;
+}
+type ChapaWebhookEvent = ChapaWebhookTransactionEvent | ChapaWebhookPayoutEvent;
+declare const isChapaTransactionEvent: (event: ChapaWebhookEvent) => event is ChapaWebhookTransactionEvent;
+type ChapaRawEvents = {
+    'chapa.charge.success': ChapaWebhookTransactionEvent;
+    'chapa.charge.failure': ChapaWebhookTransactionEvent;
+    'chapa.charge.refunded': ChapaWebhookTransactionEvent;
+    'chapa.charge.reversed': ChapaWebhookTransactionEvent;
+    'chapa.payout.success': ChapaWebhookPayoutEvent;
+    'chapa.payout.failure': ChapaWebhookPayoutEvent;
+};
+
+export { type ChapaCustomization, type ChapaInitializeResponse, type ChapaRawEvents, type ChapaRefund, type ChapaResponse, type ChapaTransaction, type ChapaWebhookEvent, type ChapaWebhookPayoutEvent, type ChapaWebhookTransactionEvent, isChapaTransactionEvent };

package/dist/schema.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Chapa wraps every response in this envelope, e.g.
+ * `{ message: "Refund verified successfully", status: "success", data: {...} }`
+ */
+interface ChapaResponse<T = unknown> {
+    /**
+     * A human readable message describing the result
+     */
+    message: string;
+    /**
+     * Whether the request was successful
+     */
+    status: 'success' | 'failed';
+    /**
+     * The data of the response
+     */
+    data: T;
+}
+interface ChapaCustomization {
+    /**
+     * The title shown on the Chapa checkout page
+     */
+    title: string | null;
+    /**
+     * The description shown on the Chapa checkout page
+     */
+    description: string | null;
+    /**
+     * A logo shown on the Chapa checkout page
+     */
+    logo?: string | null;
+}
+/**
+ * The shape returned by `GET /transaction/verify/:tx_ref`, and the shape
+ * of the `charge.*` webhook payload (minus the `event` key).
+ */
+interface ChapaTransaction {
+    /**
+     * The customer's first name
+     */
+    first_name: string | null;
+    /**
+     * The customer's last name
+     */
+    last_name: string | null;
+    /**
+     * The customer's email
+     */
+    email: string | null;
+    /**
+     * The customer's mobile number
+     */
+    mobile: string | null;
+    /**
+     * The currency of the transaction e.g `ETB`
+     */
+    currency: string;
+    /**
+     * The amount of the transaction, as a decimal string e.g `"400.00"`
+     */
+    amount: string;
+    /**
+     * The fee charged by Chapa, as a decimal string
+     */
+    charge: string;
+    /**
+     * The status of the transaction
+     */
+    status: 'success' | 'failed' | 'pending' | string;
+    /**
+     * Whether the transaction happened in `test` or `live` mode
+     */
+    mode: 'test' | 'live';
+    /**
+     * Chapa's internal reference for the transaction
+     */
+    reference: string;
+    /**
+     * The created at timestamp of the transaction
+     */
+    created_at: string;
+    /**
+     * The updated at timestamp of the transaction
+     */
+    updated_at: string;
+    /**
+     * The channel the transaction was initiated through e.g `API`
+     */
+    type: string;
+    /**
+     * The merchant-supplied transaction reference
+     */
+    tx_ref: string;
+    /**
+     * The payment channel used e.g `telebirr`, `mpesa`, `card`
+     */
+    payment_method: string | null;
+    /**
+     * The checkout customization used for the transaction
+     */
+    customization: ChapaCustomization | null;
+    /**
+     * Free-form metadata echoed back from what was sent at initialization
+     */
+    meta: Record<string, unknown> | null;
+}
+interface ChapaInitializeResponse {
+    /**
+     * The URL to redirect the customer to in order to complete payment
+     */
+    checkout_url: string;
+}
+/**
+ * The shape returned by `GET /refund/:ref_id/verify`. The create-refund
+ * response is assumed to follow the same envelope/shape; fields that
+ * aren't confirmed there are backfilled from request-time context in
+ * the mapper rather than assumed present.
+ */
+interface ChapaRefund {
+    /**
+     * The refunded amount
+     */
+    amount: number;
+    /**
+     * The currency of the refund
+     */
+    currency: string;
+    /**
+     * Chapa's internal reference for the refund
+     */
+    ref_id: string;
+    /**
+     * The reference of the original payment being refunded
+     */
+    payment_reference: string;
+    /**
+     * An optional merchant-supplied reference for the refund
+     */
+    merchant_reference: string | null;
+    /**
+     * The status of the refund
+     */
+    status: 'initiated' | 'processing' | 'refunded' | 'reversed' | string;
+    /**
+     * The created at timestamp of the refund
+     */
+    created_at: string;
+    /**
+     * The updated at timestamp of the refund
+     */
+    updated_at: string;
+}
+interface ChapaWebhookTransactionEvent extends ChapaTransaction {
+    /**
+     * e.g `charge.success`. Chapa's docs also show `charge.refunded`,
+     * `charge.reversed` and `charge.failed/cancelled`, but only
+     * `charge.success` is unambiguously documented as a literal value -
+     * the others are handled defensively off the `status` field instead
+     * of an exact string match.
+     */
+    event: string;
+}
+interface ChapaWebhookPayoutEvent {
+    /**
+     * e.g `payout.success`
+     */
+    event: string;
+    type: 'Payout';
+    account_name: string;
+    account_number: string;
+    bank_id: number;
+    bank_name: string;
+    amount: string;
+    charge: string;
+    currency: string;
+    status: string;
+    reference: string;
+    chapa_reference: string;
+    bank_reference: string;
+    created_at: string;
+    updated_at: string;
+}
+type ChapaWebhookEvent = ChapaWebhookTransactionEvent | ChapaWebhookPayoutEvent;
+declare const isChapaTransactionEvent: (event: ChapaWebhookEvent) => event is ChapaWebhookTransactionEvent;
+type ChapaRawEvents = {
+    'chapa.charge.success': ChapaWebhookTransactionEvent;
+    'chapa.charge.failure': ChapaWebhookTransactionEvent;
+    'chapa.charge.refunded': ChapaWebhookTransactionEvent;
+    'chapa.charge.reversed': ChapaWebhookTransactionEvent;
+    'chapa.payout.success': ChapaWebhookPayoutEvent;
+    'chapa.payout.failure': ChapaWebhookPayoutEvent;
+};
+
+export { type ChapaCustomization, type ChapaInitializeResponse, type ChapaRawEvents, type ChapaRefund, type ChapaResponse, type ChapaTransaction, type ChapaWebhookEvent, type ChapaWebhookPayoutEvent, type ChapaWebhookTransactionEvent, isChapaTransactionEvent };

package/dist/schema.js

@@ -0,0 +1,6 @@
+'use strict';
+
+// src/schema.ts
+var isChapaTransactionEvent = (event) => event.event.startsWith("charge.");
+
+exports.isChapaTransactionEvent = isChapaTransactionEvent;

package/dist/schema.mjs

@@ -0,0 +1,4 @@
+// src/schema.ts
+var isChapaTransactionEvent = (event) => event.event.startsWith("charge.");
+
+export { isChapaTransactionEvent };

package/dist/utils/mapper.d.mts

@@ -0,0 +1,41 @@
+import { Payment, Checkout, Invoice, Refund } from '@paykit-sdk/core';
+import { ChapaTransaction, ChapaRefund } from '../schema.mjs';
+
+/**
+ * @internal
+ */
+declare const Payment$inboundSchema: (data: ChapaTransaction, overridePaymentUrl?: string | null) => Payment;
+/**
+ * @internal
+ */
+declare const Checkout$inboundSchema: (init: {
+    checkout_url: string | null;
+    tx_ref: string;
+}, transaction: Omit<Partial<ChapaTransaction>, "amount" | "currency"> & {
+    amount?: number | string;
+    currency?: string;
+}) => Checkout;
+/**
+ * @internal
+ */
+declare const Invoice$inboundSchema: (data: ChapaTransaction) => Invoice;
+/**
+ * Builds a `Refund` from a `charge.refunded`/`charge.reversed` webhook
+ * payload, which is a transaction snapshot rather than a dedicated refund
+ * resource - Chapa doesn't send a refund id on these events, so `tx_ref`
+ * is used as the id.
+ *
+ * @internal
+ */
+declare const RefundFromTransaction$inboundSchema: (data: ChapaTransaction) => Refund;
+/**
+ * @internal
+ */
+declare const Refund$inboundSchema: (data: Partial<ChapaRefund>, context: {
+    paymentId: string;
+    amount: number;
+    currency: string;
+    reason: string | null;
+}) => Refund;
+
+export { Checkout$inboundSchema, Invoice$inboundSchema, Payment$inboundSchema, Refund$inboundSchema, RefundFromTransaction$inboundSchema };

package/dist/utils/mapper.d.ts

@@ -0,0 +1,41 @@
+import { Payment, Checkout, Invoice, Refund } from '@paykit-sdk/core';
+import { ChapaTransaction, ChapaRefund } from '../schema.js';
+
+/**
+ * @internal
+ */
+declare const Payment$inboundSchema: (data: ChapaTransaction, overridePaymentUrl?: string | null) => Payment;
+/**
+ * @internal
+ */
+declare const Checkout$inboundSchema: (init: {
+    checkout_url: string | null;
+    tx_ref: string;
+}, transaction: Omit<Partial<ChapaTransaction>, "amount" | "currency"> & {
+    amount?: number | string;
+    currency?: string;
+}) => Checkout;
+/**
+ * @internal
+ */
+declare const Invoice$inboundSchema: (data: ChapaTransaction) => Invoice;
+/**
+ * Builds a `Refund` from a `charge.refunded`/`charge.reversed` webhook
+ * payload, which is a transaction snapshot rather than a dedicated refund
+ * resource - Chapa doesn't send a refund id on these events, so `tx_ref`
+ * is used as the id.
+ *
+ * @internal
+ */
+declare const RefundFromTransaction$inboundSchema: (data: ChapaTransaction) => Refund;
+/**
+ * @internal
+ */
+declare const Refund$inboundSchema: (data: Partial<ChapaRefund>, context: {
+    paymentId: string;
+    amount: number;
+    currency: string;
+    reason: string | null;
+}) => Refund;
+
+export { Checkout$inboundSchema, Invoice$inboundSchema, Payment$inboundSchema, Refund$inboundSchema, RefundFromTransaction$inboundSchema };

package/dist/utils/mapper.js

@@ -0,0 +1,105 @@
+'use strict';
+
+var core = require('@paykit-sdk/core');
+
+// src/utils/mapper.ts
+var chapaStatusMap = {
+  success: "succeeded",
+  failed: "failed",
+  pending: "pending"
+};
+var resolveCustomer = (data) => data.email ? { email: data.email } : null;
+var Payment$inboundSchema = (data, overridePaymentUrl) => {
+  const rawMeta = data.meta ?? {};
+  const metadata = core.omitInternalMetadata(rawMeta);
+  let itemId = null;
+  const paykitMeta = core.parseJSON(
+    rawMeta[core.PAYKIT_METADATA_KEY],
+    core.Schema.object({ item_id: core.Schema.string().optional() })
+  );
+  if (paykitMeta) itemId = paykitMeta.item_id ?? null;
+  const status = chapaStatusMap[data.status] ?? "pending";
+  return {
+    id: data.tx_ref,
+    amount: parseFloat(data.amount),
+    currency: data.currency,
+    customer: resolveCustomer(data),
+    status,
+    metadata,
+    item_id: itemId,
+    requires_action: status === "pending",
+    payment_url: overridePaymentUrl ?? null
+  };
+};
+var Checkout$inboundSchema = (init, transaction) => {
+  const rawMeta = transaction.meta ?? {};
+  const metadata = core.omitInternalMetadata(rawMeta);
+  let itemId = "";
+  let quantity = 1;
+  let type = null;
+  const paykitMeta = core.parseJSON(
+    rawMeta[core.PAYKIT_METADATA_KEY],
+    core.Schema.object({
+      item_id: core.Schema.string().optional(),
+      quantity: core.Schema.number().optional(),
+      type: core.billingModeSchema.optional()
+    })
+  );
+  if (paykitMeta) {
+    itemId = paykitMeta.item_id ?? "";
+    quantity = paykitMeta.quantity ?? 1;
+    type = paykitMeta.type ?? null;
+  }
+  const amount = typeof transaction.amount === "string" ? parseFloat(transaction.amount) : transaction.amount ?? 0;
+  return {
+    id: init.tx_ref,
+    customer: resolveCustomer({ email: transaction.email ?? null }),
+    payment_url: init.checkout_url ?? "",
+    metadata: Object.keys(metadata).length > 0 ? metadata : null,
+    session_type: type ?? "one_time",
+    products: [{ id: itemId, quantity }],
+    currency: transaction.currency ?? "ETB",
+    amount
+  };
+};
+var Invoice$inboundSchema = (data) => {
+  const rawMeta = data.meta ?? {};
+  const metadata = core.omitInternalMetadata(rawMeta);
+  return {
+    id: data.reference,
+    customer: resolveCustomer(data),
+    subscription_id: null,
+    billing_mode: "one_time",
+    amount_paid: parseFloat(data.amount),
+    currency: data.currency,
+    status: "paid",
+    paid_at: data.updated_at,
+    line_items: null,
+    metadata: Object.keys(metadata).length > 0 ? metadata : null,
+    custom_fields: null
+  };
+};
+var RefundFromTransaction$inboundSchema = (data) => {
+  const rawMeta = data.meta ?? {};
+  const metadata = core.omitInternalMetadata(rawMeta);
+  return {
+    id: data.tx_ref,
+    amount: parseFloat(data.amount),
+    currency: data.currency,
+    reason: null,
+    metadata: Object.keys(metadata).length > 0 ? metadata : null
+  };
+};
+var Refund$inboundSchema = (data, context) => ({
+  id: data.ref_id ?? context.paymentId,
+  amount: data.amount ?? context.amount,
+  currency: data.currency ?? context.currency,
+  reason: context.reason,
+  metadata: null
+});
+
+exports.Checkout$inboundSchema = Checkout$inboundSchema;
+exports.Invoice$inboundSchema = Invoice$inboundSchema;
+exports.Payment$inboundSchema = Payment$inboundSchema;
+exports.Refund$inboundSchema = Refund$inboundSchema;
+exports.RefundFromTransaction$inboundSchema = RefundFromTransaction$inboundSchema;

package/dist/utils/mapper.mjs

@@ -0,0 +1,99 @@
+import { omitInternalMetadata, parseJSON, PAYKIT_METADATA_KEY, Schema, billingModeSchema } from '@paykit-sdk/core';
+
+// src/utils/mapper.ts
+var chapaStatusMap = {
+  success: "succeeded",
+  failed: "failed",
+  pending: "pending"
+};
+var resolveCustomer = (data) => data.email ? { email: data.email } : null;
+var Payment$inboundSchema = (data, overridePaymentUrl) => {
+  const rawMeta = data.meta ?? {};
+  const metadata = omitInternalMetadata(rawMeta);
+  let itemId = null;
+  const paykitMeta = parseJSON(
+    rawMeta[PAYKIT_METADATA_KEY],
+    Schema.object({ item_id: Schema.string().optional() })
+  );
+  if (paykitMeta) itemId = paykitMeta.item_id ?? null;
+  const status = chapaStatusMap[data.status] ?? "pending";
+  return {
+    id: data.tx_ref,
+    amount: parseFloat(data.amount),
+    currency: data.currency,
+    customer: resolveCustomer(data),
+    status,
+    metadata,
+    item_id: itemId,
+    requires_action: status === "pending",
+    payment_url: overridePaymentUrl ?? null
+  };
+};
+var Checkout$inboundSchema = (init, transaction) => {
+  const rawMeta = transaction.meta ?? {};
+  const metadata = omitInternalMetadata(rawMeta);
+  let itemId = "";
+  let quantity = 1;
+  let type = null;
+  const paykitMeta = parseJSON(
+    rawMeta[PAYKIT_METADATA_KEY],
+    Schema.object({
+      item_id: Schema.string().optional(),
+      quantity: Schema.number().optional(),
+      type: billingModeSchema.optional()
+    })
+  );
+  if (paykitMeta) {
+    itemId = paykitMeta.item_id ?? "";
+    quantity = paykitMeta.quantity ?? 1;
+    type = paykitMeta.type ?? null;
+  }
+  const amount = typeof transaction.amount === "string" ? parseFloat(transaction.amount) : transaction.amount ?? 0;
+  return {
+    id: init.tx_ref,
+    customer: resolveCustomer({ email: transaction.email ?? null }),
+    payment_url: init.checkout_url ?? "",
+    metadata: Object.keys(metadata).length > 0 ? metadata : null,
+    session_type: type ?? "one_time",
+    products: [{ id: itemId, quantity }],
+    currency: transaction.currency ?? "ETB",
+    amount
+  };
+};
+var Invoice$inboundSchema = (data) => {
+  const rawMeta = data.meta ?? {};
+  const metadata = omitInternalMetadata(rawMeta);
+  return {
+    id: data.reference,
+    customer: resolveCustomer(data),
+    subscription_id: null,
+    billing_mode: "one_time",
+    amount_paid: parseFloat(data.amount),
+    currency: data.currency,
+    status: "paid",
+    paid_at: data.updated_at,
+    line_items: null,
+    metadata: Object.keys(metadata).length > 0 ? metadata : null,
+    custom_fields: null
+  };
+};
+var RefundFromTransaction$inboundSchema = (data) => {
+  const rawMeta = data.meta ?? {};
+  const metadata = omitInternalMetadata(rawMeta);
+  return {
+    id: data.tx_ref,
+    amount: parseFloat(data.amount),
+    currency: data.currency,
+    reason: null,
+    metadata: Object.keys(metadata).length > 0 ? metadata : null
+  };
+};
+var Refund$inboundSchema = (data, context) => ({
+  id: data.ref_id ?? context.paymentId,
+  amount: data.amount ?? context.amount,
+  currency: data.currency ?? context.currency,
+  reason: context.reason,
+  metadata: null
+});
+
+export { Checkout$inboundSchema, Invoice$inboundSchema, Payment$inboundSchema, Refund$inboundSchema, RefundFromTransaction$inboundSchema };