@paykit-sdk/xendit 1.0.0

package/dist/schema.d.mts

@@ -0,0 +1,192 @@
+/**
+ * Xendit's error envelope, returned on any non-2xx response, e.g.
+ * `{ error_code: "INVALID_REQUEST", message: "..." }`
+ */
+interface XenditErrorResponse {
+    error_code: string;
+    message: string;
+}
+interface XenditInvoiceItem {
+    name: string;
+    quantity: number;
+    price: number;
+    category?: string;
+}
+interface XenditInvoiceCustomer {
+    given_names?: string;
+    surname?: string;
+    email?: string;
+    mobile_number?: string;
+}
+/**
+ * The shape returned by `POST /v2/invoices/` and `GET /v2/invoices/:id`
+ * (Xendit's hosted checkout page).
+ */
+interface XenditInvoice {
+    id: string;
+    external_id: string;
+    user_id: string;
+    status: 'PENDING' | 'PAID' | 'SETTLED' | 'EXPIRED';
+    merchant_name?: string;
+    amount: number;
+    payer_email?: string;
+    description?: string;
+    paid_amount?: number;
+    created: string;
+    updated: string;
+    currency: string;
+    expiry_date: string;
+    invoice_url: string;
+    paid_at?: string;
+    payment_method?: string;
+    payment_channel?: string;
+    payment_id?: string;
+    success_redirect_url?: string;
+    failure_redirect_url?: string;
+    items?: XenditInvoiceItem[];
+    customer?: XenditInvoiceCustomer;
+    metadata?: Record<string, unknown> | null;
+    recurring_payment_id?: string;
+}
+/**
+ * The shape returned by `POST /customers`, `GET /customers/:id`, and
+ * `PATCH /customers/:id`.
+ */
+interface XenditCustomer {
+    id: string;
+    reference_id: string;
+    type?: 'INDIVIDUAL' | 'BUSINESS';
+    individual_detail?: {
+        given_names?: string;
+        surname?: string | null;
+    } | null;
+    email: string | null;
+    mobile_number: string | null;
+    phone_number?: string | null;
+    description?: string | null;
+    metadata: Record<string, unknown> | null;
+    created: string;
+    updated: string;
+}
+/**
+ * Interval unit accepted by the Recurring Plans API - `YEAR` is not
+ * supported natively and is translated to `MONTH` with `interval_count: 12`.
+ */
+type XenditRecurringInterval = 'DAY' | 'WEEK' | 'MONTH';
+interface XenditRecurringSchedule {
+    interval: XenditRecurringInterval;
+    interval_count: number;
+    total_recurrence?: number | null;
+    anchor_date?: string;
+    retry_interval?: string;
+    retry_interval_count?: number;
+    total_retry?: number;
+    created?: string;
+    updated?: string;
+}
+interface XenditPaymentToken {
+    payment_token_id: string;
+    rank: number;
+}
+/**
+ * The shape returned by `POST /recurring/plans`, `GET /recurring/plans/:id`,
+ * and `POST /recurring/plans/:id/deactivate`.
+ */
+interface XenditRecurringPlan {
+    id: string;
+    reference_id: string;
+    customer_id: string;
+    currency: string;
+    amount: number;
+    status: 'ACTIVE' | 'INACTIVE' | 'PENDING' | 'REQUIRES_ACTION';
+    country?: string;
+    recurring_cycle_count?: number;
+    schedule: XenditRecurringSchedule;
+    payment_tokens: XenditPaymentToken[];
+    immediate_payment?: boolean;
+    failed_cycle_action?: 'RESUME' | 'STOP';
+    metadata?: Record<string, unknown> | null;
+    description?: string | null;
+    created: string;
+    updated: string;
+    actions?: Array<{
+        action: string;
+        url_type: string;
+        url: string;
+        method: string;
+    }>;
+}
+/**
+ * The shape returned by `POST /refunds` and `GET /refunds/:id`.
+ */
+interface XenditRefund {
+    id: string;
+    payment_id?: string;
+    payment_request_id?: string;
+    invoice_id?: string;
+    amount: number;
+    currency: string;
+    channel_code?: string;
+    status: 'PENDING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
+    reason?: string;
+    reference_id?: string | null;
+    failure_code?: string | null;
+    metadata?: Record<string, unknown> | null;
+    created: string;
+    updated: string;
+}
+/**
+ * The Invoice Callback body is the invoice resource itself, sent
+ * unwrapped at the top level - there is no separate `event`/`data`
+ * envelope for invoice webhooks (unlike Recurring webhooks below).
+ */
+type XenditInvoiceCallback = XenditInvoice;
+/**
+ * Recurring webhooks (unlike invoice callbacks) use a wrapping
+ * `{ event, business_id, created, data }` envelope, reflecting a newer
+ * generation of Xendit's API.
+ */
+interface XenditRecurringCycle {
+    id: string;
+    reference_id?: string;
+    plan_id?: string;
+    customer_id?: string;
+    cycle_number?: number;
+    attempt_count?: number;
+    status: 'SCHEDULED' | 'SUCCEEDED' | 'RETRYING' | 'FAILED';
+    scheduled_timestamp?: string;
+    currency: string;
+    amount: number;
+    created?: string;
+    updated?: string;
+    metadata?: Record<string, unknown> | null;
+}
+interface XenditRecurringPlanWebhookEvent {
+    event: 'recurring.plan.activated' | 'recurring.plan.inactivated';
+    business_id: string;
+    created: string;
+    data: XenditRecurringPlan;
+}
+interface XenditRecurringCycleWebhookEvent {
+    event: 'recurring.cycle.created' | 'recurring.cycle.succeeded' | 'recurring.cycle.retrying' | 'recurring.cycle.failed';
+    business_id: string;
+    created: string;
+    data: XenditRecurringCycle;
+}
+type XenditRecurringWebhookEvent = XenditRecurringPlanWebhookEvent | XenditRecurringCycleWebhookEvent;
+type XenditWebhookEvent = XenditInvoiceCallback | XenditRecurringWebhookEvent;
+declare const isXenditRecurringWebhookEvent: (event: XenditWebhookEvent) => event is XenditRecurringWebhookEvent;
+type XenditRawEvents = {
+    'xendit.invoice.pending': XenditInvoiceCallback;
+    'xendit.invoice.paid': XenditInvoiceCallback;
+    'xendit.invoice.settled': XenditInvoiceCallback;
+    'xendit.invoice.expired': XenditInvoiceCallback;
+    'xendit.recurring.plan.activated': XenditRecurringPlanWebhookEvent;
+    'xendit.recurring.plan.inactivated': XenditRecurringPlanWebhookEvent;
+    'xendit.recurring.cycle.created': XenditRecurringCycleWebhookEvent;
+    'xendit.recurring.cycle.succeeded': XenditRecurringCycleWebhookEvent;
+    'xendit.recurring.cycle.retrying': XenditRecurringCycleWebhookEvent;
+    'xendit.recurring.cycle.failed': XenditRecurringCycleWebhookEvent;
+};
+
+export { type XenditCustomer, type XenditErrorResponse, type XenditInvoice, type XenditInvoiceCallback, type XenditInvoiceCustomer, type XenditInvoiceItem, type XenditPaymentToken, type XenditRawEvents, type XenditRecurringCycle, type XenditRecurringCycleWebhookEvent, type XenditRecurringInterval, type XenditRecurringPlan, type XenditRecurringPlanWebhookEvent, type XenditRecurringSchedule, type XenditRecurringWebhookEvent, type XenditRefund, type XenditWebhookEvent, isXenditRecurringWebhookEvent };

package/dist/schema.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Xendit's error envelope, returned on any non-2xx response, e.g.
+ * `{ error_code: "INVALID_REQUEST", message: "..." }`
+ */
+interface XenditErrorResponse {
+    error_code: string;
+    message: string;
+}
+interface XenditInvoiceItem {
+    name: string;
+    quantity: number;
+    price: number;
+    category?: string;
+}
+interface XenditInvoiceCustomer {
+    given_names?: string;
+    surname?: string;
+    email?: string;
+    mobile_number?: string;
+}
+/**
+ * The shape returned by `POST /v2/invoices/` and `GET /v2/invoices/:id`
+ * (Xendit's hosted checkout page).
+ */
+interface XenditInvoice {
+    id: string;
+    external_id: string;
+    user_id: string;
+    status: 'PENDING' | 'PAID' | 'SETTLED' | 'EXPIRED';
+    merchant_name?: string;
+    amount: number;
+    payer_email?: string;
+    description?: string;
+    paid_amount?: number;
+    created: string;
+    updated: string;
+    currency: string;
+    expiry_date: string;
+    invoice_url: string;
+    paid_at?: string;
+    payment_method?: string;
+    payment_channel?: string;
+    payment_id?: string;
+    success_redirect_url?: string;
+    failure_redirect_url?: string;
+    items?: XenditInvoiceItem[];
+    customer?: XenditInvoiceCustomer;
+    metadata?: Record<string, unknown> | null;
+    recurring_payment_id?: string;
+}
+/**
+ * The shape returned by `POST /customers`, `GET /customers/:id`, and
+ * `PATCH /customers/:id`.
+ */
+interface XenditCustomer {
+    id: string;
+    reference_id: string;
+    type?: 'INDIVIDUAL' | 'BUSINESS';
+    individual_detail?: {
+        given_names?: string;
+        surname?: string | null;
+    } | null;
+    email: string | null;
+    mobile_number: string | null;
+    phone_number?: string | null;
+    description?: string | null;
+    metadata: Record<string, unknown> | null;
+    created: string;
+    updated: string;
+}
+/**
+ * Interval unit accepted by the Recurring Plans API - `YEAR` is not
+ * supported natively and is translated to `MONTH` with `interval_count: 12`.
+ */
+type XenditRecurringInterval = 'DAY' | 'WEEK' | 'MONTH';
+interface XenditRecurringSchedule {
+    interval: XenditRecurringInterval;
+    interval_count: number;
+    total_recurrence?: number | null;
+    anchor_date?: string;
+    retry_interval?: string;
+    retry_interval_count?: number;
+    total_retry?: number;
+    created?: string;
+    updated?: string;
+}
+interface XenditPaymentToken {
+    payment_token_id: string;
+    rank: number;
+}
+/**
+ * The shape returned by `POST /recurring/plans`, `GET /recurring/plans/:id`,
+ * and `POST /recurring/plans/:id/deactivate`.
+ */
+interface XenditRecurringPlan {
+    id: string;
+    reference_id: string;
+    customer_id: string;
+    currency: string;
+    amount: number;
+    status: 'ACTIVE' | 'INACTIVE' | 'PENDING' | 'REQUIRES_ACTION';
+    country?: string;
+    recurring_cycle_count?: number;
+    schedule: XenditRecurringSchedule;
+    payment_tokens: XenditPaymentToken[];
+    immediate_payment?: boolean;
+    failed_cycle_action?: 'RESUME' | 'STOP';
+    metadata?: Record<string, unknown> | null;
+    description?: string | null;
+    created: string;
+    updated: string;
+    actions?: Array<{
+        action: string;
+        url_type: string;
+        url: string;
+        method: string;
+    }>;
+}
+/**
+ * The shape returned by `POST /refunds` and `GET /refunds/:id`.
+ */
+interface XenditRefund {
+    id: string;
+    payment_id?: string;
+    payment_request_id?: string;
+    invoice_id?: string;
+    amount: number;
+    currency: string;
+    channel_code?: string;
+    status: 'PENDING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
+    reason?: string;
+    reference_id?: string | null;
+    failure_code?: string | null;
+    metadata?: Record<string, unknown> | null;
+    created: string;
+    updated: string;
+}
+/**
+ * The Invoice Callback body is the invoice resource itself, sent
+ * unwrapped at the top level - there is no separate `event`/`data`
+ * envelope for invoice webhooks (unlike Recurring webhooks below).
+ */
+type XenditInvoiceCallback = XenditInvoice;
+/**
+ * Recurring webhooks (unlike invoice callbacks) use a wrapping
+ * `{ event, business_id, created, data }` envelope, reflecting a newer
+ * generation of Xendit's API.
+ */
+interface XenditRecurringCycle {
+    id: string;
+    reference_id?: string;
+    plan_id?: string;
+    customer_id?: string;
+    cycle_number?: number;
+    attempt_count?: number;
+    status: 'SCHEDULED' | 'SUCCEEDED' | 'RETRYING' | 'FAILED';
+    scheduled_timestamp?: string;
+    currency: string;
+    amount: number;
+    created?: string;
+    updated?: string;
+    metadata?: Record<string, unknown> | null;
+}
+interface XenditRecurringPlanWebhookEvent {
+    event: 'recurring.plan.activated' | 'recurring.plan.inactivated';
+    business_id: string;
+    created: string;
+    data: XenditRecurringPlan;
+}
+interface XenditRecurringCycleWebhookEvent {
+    event: 'recurring.cycle.created' | 'recurring.cycle.succeeded' | 'recurring.cycle.retrying' | 'recurring.cycle.failed';
+    business_id: string;
+    created: string;
+    data: XenditRecurringCycle;
+}
+type XenditRecurringWebhookEvent = XenditRecurringPlanWebhookEvent | XenditRecurringCycleWebhookEvent;
+type XenditWebhookEvent = XenditInvoiceCallback | XenditRecurringWebhookEvent;
+declare const isXenditRecurringWebhookEvent: (event: XenditWebhookEvent) => event is XenditRecurringWebhookEvent;
+type XenditRawEvents = {
+    'xendit.invoice.pending': XenditInvoiceCallback;
+    'xendit.invoice.paid': XenditInvoiceCallback;
+    'xendit.invoice.settled': XenditInvoiceCallback;
+    'xendit.invoice.expired': XenditInvoiceCallback;
+    'xendit.recurring.plan.activated': XenditRecurringPlanWebhookEvent;
+    'xendit.recurring.plan.inactivated': XenditRecurringPlanWebhookEvent;
+    'xendit.recurring.cycle.created': XenditRecurringCycleWebhookEvent;
+    'xendit.recurring.cycle.succeeded': XenditRecurringCycleWebhookEvent;
+    'xendit.recurring.cycle.retrying': XenditRecurringCycleWebhookEvent;
+    'xendit.recurring.cycle.failed': XenditRecurringCycleWebhookEvent;
+};
+
+export { type XenditCustomer, type XenditErrorResponse, type XenditInvoice, type XenditInvoiceCallback, type XenditInvoiceCustomer, type XenditInvoiceItem, type XenditPaymentToken, type XenditRawEvents, type XenditRecurringCycle, type XenditRecurringCycleWebhookEvent, type XenditRecurringInterval, type XenditRecurringPlan, type XenditRecurringPlanWebhookEvent, type XenditRecurringSchedule, type XenditRecurringWebhookEvent, type XenditRefund, type XenditWebhookEvent, isXenditRecurringWebhookEvent };

package/dist/schema.js

@@ -0,0 +1,8 @@
+'use strict';
+
+// src/schema.ts
+var isXenditRecurringWebhookEvent = (event) => typeof event.event === "string" && event.event.startsWith(
+  "recurring."
+);
+
+exports.isXenditRecurringWebhookEvent = isXenditRecurringWebhookEvent;

package/dist/schema.mjs

@@ -0,0 +1,6 @@
+// src/schema.ts
+var isXenditRecurringWebhookEvent = (event) => typeof event.event === "string" && event.event.startsWith(
+  "recurring."
+);
+
+export { isXenditRecurringWebhookEvent };

package/dist/utils/mapper.d.mts

@@ -0,0 +1,34 @@
+import { Payment, Checkout, Customer, Subscription, Refund, Invoice } from '@paykit-sdk/core';
+import { XenditInvoice, XenditCustomer, XenditRecurringPlan, XenditRefund } from '../schema.mjs';
+
+/**
+ * @internal
+ */
+declare const Payment$inboundSchema: (data: XenditInvoice, overridePaymentUrl?: string | null) => Payment;
+/**
+ * @internal
+ */
+declare const Checkout$inboundSchema: (data: XenditInvoice) => Checkout;
+/**
+ * @internal
+ */
+declare const Customer$inboundSchema: (data: XenditCustomer) => Customer;
+/**
+ * Xendit's Recurring Plans API has no separate reusable plan template to
+ * reference - the "plan" created here already carries the amount/currency
+ * for one specific subscription, so `item_id` is round-tripped through
+ * `description` instead of pointing at an external resource.
+ *
+ * @internal
+ */
+declare const Subscription$inboundSchema: (data: XenditRecurringPlan) => Subscription;
+/**
+ * @internal
+ */
+declare const Refund$inboundSchema: (data: XenditRefund) => Refund;
+/**
+ * @internal
+ */
+declare const Invoice$inboundSchema: (data: XenditInvoice) => Invoice;
+
+export { Checkout$inboundSchema, Customer$inboundSchema, Invoice$inboundSchema, Payment$inboundSchema, Refund$inboundSchema, Subscription$inboundSchema };

package/dist/utils/mapper.d.ts

@@ -0,0 +1,34 @@
+import { Payment, Checkout, Customer, Subscription, Refund, Invoice } from '@paykit-sdk/core';
+import { XenditInvoice, XenditCustomer, XenditRecurringPlan, XenditRefund } from '../schema.js';
+
+/**
+ * @internal
+ */
+declare const Payment$inboundSchema: (data: XenditInvoice, overridePaymentUrl?: string | null) => Payment;
+/**
+ * @internal
+ */
+declare const Checkout$inboundSchema: (data: XenditInvoice) => Checkout;
+/**
+ * @internal
+ */
+declare const Customer$inboundSchema: (data: XenditCustomer) => Customer;
+/**
+ * Xendit's Recurring Plans API has no separate reusable plan template to
+ * reference - the "plan" created here already carries the amount/currency
+ * for one specific subscription, so `item_id` is round-tripped through
+ * `description` instead of pointing at an external resource.
+ *
+ * @internal
+ */
+declare const Subscription$inboundSchema: (data: XenditRecurringPlan) => Subscription;
+/**
+ * @internal
+ */
+declare const Refund$inboundSchema: (data: XenditRefund) => Refund;
+/**
+ * @internal
+ */
+declare const Invoice$inboundSchema: (data: XenditInvoice) => Invoice;
+
+export { Checkout$inboundSchema, Customer$inboundSchema, Invoice$inboundSchema, Payment$inboundSchema, Refund$inboundSchema, Subscription$inboundSchema };

package/dist/utils/mapper.js

@@ -0,0 +1,169 @@
+'use strict';
+
+var core = require('@paykit-sdk/core');
+
+// src/utils/mapper.ts
+var paymentStatusMap = {
+  PENDING: "pending",
+  PAID: "succeeded",
+  SETTLED: "succeeded",
+  EXPIRED: "canceled"
+};
+var subscriptionStatusMap = {
+  ACTIVE: "active",
+  INACTIVE: "canceled",
+  PENDING: "pending",
+  REQUIRES_ACTION: "pending"
+};
+var resolveCustomerFromEmail = (email) => email ? { email } : null;
+var Payment$inboundSchema = (data, overridePaymentUrl) => {
+  const rawMeta = data.metadata ?? {};
+  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 = paymentStatusMap[data.status] ?? "pending";
+  return {
+    id: data.id,
+    amount: data.amount,
+    currency: data.currency,
+    customer: resolveCustomerFromEmail(
+      data.payer_email ?? data.customer?.email
+    ),
+    status,
+    metadata,
+    item_id: itemId,
+    requires_action: status === "pending",
+    payment_url: overridePaymentUrl ?? null
+  };
+};
+var Checkout$inboundSchema = (data) => {
+  const rawMeta = data.metadata ?? {};
+  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;
+  }
+  return {
+    id: data.id,
+    customer: resolveCustomerFromEmail(
+      data.payer_email ?? data.customer?.email
+    ),
+    payment_url: data.invoice_url,
+    metadata: Object.keys(metadata).length > 0 ? metadata : null,
+    session_type: type ?? "one_time",
+    products: [{ id: itemId, quantity }],
+    currency: data.currency,
+    amount: data.amount
+  };
+};
+var Customer$inboundSchema = (data) => {
+  const rawMeta = data.metadata ?? {};
+  const metadata = core.omitInternalMetadata(rawMeta);
+  const name = [
+    data.individual_detail?.given_names,
+    data.individual_detail?.surname
+  ].filter(Boolean).join(" ");
+  return {
+    id: data.id,
+    email: data.email ?? "",
+    name,
+    phone: data.mobile_number ?? data.phone_number ?? null,
+    metadata,
+    created_at: new Date(data.created),
+    updated_at: new Date(data.updated),
+    // Xendit-native fields with no PayKit core equivalent.
+    custom_fields: { type: data.type ?? null }
+  };
+};
+var recurringIntervalUnitMap = {
+  DAY: "day",
+  WEEK: "week",
+  MONTH: "month"
+};
+var Subscription$inboundSchema = (data) => {
+  const rawMeta = data.metadata ?? {};
+  const metadata = core.omitInternalMetadata(rawMeta);
+  const status = subscriptionStatusMap[data.status] ?? "pending";
+  const periodAnchor = data.schedule.anchor_date ? new Date(data.schedule.anchor_date) : /* @__PURE__ */ new Date(0);
+  const authAction = data.actions?.find(
+    (action) => action.action === "AUTH"
+  );
+  return {
+    id: data.id,
+    customer: { id: data.customer_id },
+    amount: data.amount,
+    currency: data.currency,
+    status,
+    current_period_start: periodAnchor,
+    current_period_end: periodAnchor,
+    item_id: data.description ?? data.reference_id,
+    billing_interval: recurringIntervalUnitMap[data.schedule.interval] ?? "month",
+    metadata: Object.keys(metadata).length > 0 ? metadata : null,
+    custom_fields: {
+      payment_tokens: data.payment_tokens,
+      recurring_cycle_count: data.recurring_cycle_count ?? null,
+      failed_cycle_action: data.failed_cycle_action ?? null
+    },
+    requires_action: status === "pending" || data.status === "REQUIRES_ACTION",
+    payment_url: authAction?.url ?? null
+  };
+};
+var Refund$inboundSchema = (data) => {
+  const rawMeta = data.metadata ?? {};
+  const metadata = core.omitInternalMetadata(rawMeta);
+  return {
+    id: data.id,
+    amount: data.amount,
+    currency: data.currency,
+    reason: data.reason ?? null,
+    metadata: Object.keys(metadata).length > 0 ? metadata : null
+  };
+};
+var Invoice$inboundSchema = (data) => {
+  const rawMeta = data.metadata ?? {};
+  const metadata = core.omitInternalMetadata(rawMeta);
+  return {
+    id: data.id,
+    customer: resolveCustomerFromEmail(
+      data.payer_email ?? data.customer?.email
+    ),
+    subscription_id: data.recurring_payment_id ?? null,
+    billing_mode: data.recurring_payment_id ? "recurring" : "one_time",
+    amount_paid: data.paid_amount ?? data.amount,
+    currency: data.currency,
+    status: "paid",
+    paid_at: data.paid_at ?? data.updated,
+    line_items: data.items?.map((item) => ({
+      id: item.name,
+      quantity: item.quantity
+    })) ?? null,
+    metadata: Object.keys(metadata).length > 0 ? metadata : null,
+    custom_fields: {
+      payment_method: data.payment_method ?? null,
+      payment_channel: data.payment_channel ?? null
+    }
+  };
+};
+
+exports.Checkout$inboundSchema = Checkout$inboundSchema;
+exports.Customer$inboundSchema = Customer$inboundSchema;
+exports.Invoice$inboundSchema = Invoice$inboundSchema;
+exports.Payment$inboundSchema = Payment$inboundSchema;
+exports.Refund$inboundSchema = Refund$inboundSchema;
+exports.Subscription$inboundSchema = Subscription$inboundSchema;