mavunta 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,282 @@
+import { A as AuthVerifyResult, C as CreatePaymentIntentParams, R as RequestOptions, P as PaymentIntent, L as ListResponse, a as CreatePaymentLinkParams, b as PaymentLink, c as CreateCustomerParams, d as Customer, e as Refund, B as Balance, S as Settlement, f as CreateWebhookEndpointParams, W as WebhookEndpoint, g as WebhookEvent, h as WebhooksResource, M as MavuntaOptions } from './index-C_GLtIgI.cjs';
+export { i as MavuntaEnvironment, j as PaymentMethod, k as SettlementCurrency, V as VerifyWebhookParams, v as verifyWebhook } from './index-C_GLtIgI.cjs';
+
+declare class AuthResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Verify the current API key and return its merchant, scopes, and mode. */
+    verify(): Promise<AuthVerifyResult>;
+}
+
+declare class RatesResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Current indicative FX and crypto rates used for quotes. */
+    retrieve(): Promise<Record<string, unknown>>;
+    /** Alias for {@link retrieve}. */
+    list(): Promise<Record<string, unknown>>;
+}
+
+interface CreateQuoteParams {
+    source_currency: string;
+    target_asset: string;
+    amount: string;
+    side?: 'customer_pays' | 'merchant_receives';
+}
+declare class QuotesResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Create a short-lived quote locking a rate for a conversion. */
+    create(params: CreateQuoteParams): Promise<Record<string, unknown>>;
+}
+
+interface ListPaymentIntentsParams {
+    limit?: number;
+    starting_after?: string;
+    status?: string;
+}
+declare class PaymentIntentsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Create a payment intent and get a `checkout_url` to send the customer to. */
+    create(params: CreatePaymentIntentParams, options?: RequestOptions): Promise<PaymentIntent>;
+    retrieve(id: string): Promise<PaymentIntent>;
+    list(params?: ListPaymentIntentsParams): Promise<ListResponse<PaymentIntent>>;
+    /** Cancel an intent that has not been paid yet. */
+    cancel(id: string): Promise<PaymentIntent>;
+}
+
+declare class PaymentLinksResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Create a reusable payment link (with a hosted page + QR). */
+    create(params: CreatePaymentLinkParams, options?: RequestOptions): Promise<PaymentLink>;
+    retrieve(id: string): Promise<PaymentLink>;
+}
+
+interface ListCustomersParams {
+    limit?: number;
+    starting_after?: string;
+    email?: string;
+}
+declare class CustomersResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    create(params: CreateCustomerParams, options?: RequestOptions): Promise<Customer>;
+    retrieve(id: string): Promise<Customer>;
+    list(params?: ListCustomersParams): Promise<ListResponse<Customer>>;
+}
+
+interface CreateRefundParams {
+    payment_intent: string;
+    reason?: string;
+}
+declare class RefundsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /**
+     * Refund a paid payment in full. Partial refunds are not supported, and a
+     * payment can have at most one refund (a repeat after success rejects with
+     * `already_refunded`).
+     */
+    create(params: CreateRefundParams, options?: RequestOptions): Promise<Refund>;
+    retrieve(id: string): Promise<Refund>;
+    list(params?: {
+        limit?: number;
+        starting_after?: string;
+    }): Promise<ListResponse<Refund>>;
+}
+
+declare class BalancesResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Retrieve the merchant's available and pending balances by asset. */
+    retrieve(): Promise<Balance>;
+}
+
+interface ListSettlementsParams {
+    limit?: number;
+    starting_after?: string;
+    status?: string;
+}
+declare class SettlementsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    list(params?: ListSettlementsParams): Promise<ListResponse<Settlement>>;
+}
+
+interface ReportParams {
+    /** ISO date or unix-seconds range bound, per the API docs. */
+    from?: string;
+    to?: string;
+    limit?: number;
+    starting_after?: string;
+}
+declare class ReportsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Tabular payments report for reconciliation. */
+    payments(params?: ReportParams): Promise<Record<string, unknown>>;
+    /** Tabular settlements report for reconciliation. */
+    settlements(params?: ReportParams): Promise<Record<string, unknown>>;
+}
+
+declare class WebhookEndpointsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    create(params: CreateWebhookEndpointParams, options?: RequestOptions): Promise<WebhookEndpoint>;
+    retrieve(id: string): Promise<WebhookEndpoint>;
+    list(params?: {
+        limit?: number;
+        starting_after?: string;
+    }): Promise<ListResponse<WebhookEndpoint>>;
+    delete(id: string): Promise<{
+        id: string;
+        object: string;
+        deleted: boolean;
+    }>;
+}
+
+interface ListWebhookEventsParams {
+    limit?: number;
+    starting_after?: string;
+    type?: string;
+}
+declare class WebhookEventsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    list(params?: ListWebhookEventsParams): Promise<ListResponse<WebhookEvent>>;
+    retrieve(id: string): Promise<WebhookEvent>;
+    /** Re-deliver an event to all subscribed endpoints. */
+    resend(id: string): Promise<WebhookEvent>;
+}
+
+interface TriggerWebhookParams {
+    /** The event type to simulate, e.g. `payment_intent.paid`. */
+    type: string;
+    /** Optional override data merged into the simulated event. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Sandbox-only test helpers. These work with a `cwk_test_…` key; calling them
+ * with a live key returns an error from the API.
+ */
+declare class SandboxResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Fire a simulated webhook event to your configured endpoints. */
+    triggerWebhook(params: TriggerWebhookParams): Promise<WebhookEvent>;
+}
+
+type HttpMethod = 'GET' | 'POST' | 'DELETE';
+interface InternalRequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    idempotencyKey?: string;
+}
+/**
+ * The Mavunta API client. Server-side only: it authenticates with a secret or
+ * restricted key and must never run in a browser.
+ *
+ * ```ts
+ * import Mavunta from 'mavunta'
+ * const mavunta = new Mavunta({ secretKey: process.env.MAVUNTA_SECRET_KEY! })
+ * const intent = await mavunta.paymentIntents.create({
+ *   amount: '2500', currency: 'KES', settlement_currency: 'USDT',
+ *   payment_methods: ['mpesa', 'card'],
+ * })
+ * ```
+ */
+declare class Mavunta {
+    readonly auth: AuthResource;
+    readonly rates: RatesResource;
+    readonly quotes: QuotesResource;
+    readonly paymentIntents: PaymentIntentsResource;
+    readonly paymentLinks: PaymentLinksResource;
+    readonly customers: CustomersResource;
+    readonly refunds: RefundsResource;
+    readonly balances: BalancesResource;
+    readonly settlements: SettlementsResource;
+    readonly reports: ReportsResource;
+    readonly webhookEndpoints: WebhookEndpointsResource;
+    readonly webhookEvents: WebhookEventsResource;
+    readonly sandbox: SandboxResource;
+    /** Webhook signature verification (no network call). */
+    readonly webhooks: WebhooksResource;
+    private readonly secretKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    constructor(options: MavuntaOptions);
+    /** @internal Used by resource classes; not part of the public surface. */
+    request<T>(method: HttpMethod, path: string, opts?: InternalRequestOptions): Promise<T>;
+}
+
+/**
+ * Error hierarchy for the Mavunta SDK.
+ *
+ * Every failure surfaces as a {@link MavuntaError} subclass so callers can
+ * branch on the type and read `code` / `requestId` for support. The shape
+ * mirrors the API's error envelope (spec §24):
+ *
+ *   { error: { type, code, message, param, request_id, docs_url } }
+ */
+interface MavuntaErrorBody {
+    type?: string;
+    code?: string;
+    message?: string;
+    param?: string | null;
+    request_id?: string;
+    docs_url?: string;
+}
+interface MavuntaErrorInit {
+    type?: string;
+    code?: string;
+    param?: string | null;
+    requestId?: string | null;
+    statusCode?: number | null;
+    docsUrl?: string | null;
+}
+/** Base class for everything thrown by the SDK. */
+declare class MavuntaError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly param: string | null;
+    readonly requestId: string | null;
+    readonly statusCode: number | null;
+    readonly docsUrl: string | null;
+    constructor(message: string, init?: MavuntaErrorInit);
+}
+/** A non-2xx response that does not map to a more specific class. */
+declare class MavuntaAPIError extends MavuntaError {
+}
+/** 401: missing, invalid, or revoked API key. */
+declare class MavuntaAuthenticationError extends MavuntaError {
+}
+/** 403: the key is valid but lacks the scope for this action. */
+declare class MavuntaPermissionError extends MavuntaError {
+}
+/** 400 / 422: the request was malformed or failed validation. */
+declare class MavuntaValidationError extends MavuntaError {
+}
+/** 409 on a money-moving create with a reused idempotency key. */
+declare class MavuntaIdempotencyError extends MavuntaError {
+}
+/** A network failure before a response was received. */
+declare class MavuntaConnectionError extends MavuntaError {
+}
+/** The request exceeded the configured timeout. */
+declare class MavuntaTimeoutError extends MavuntaError {
+}
+/** Webhook signature verification failed. */
+declare class MavuntaWebhookSignatureError extends MavuntaError {
+}
+/** 429: too many requests. `retryAfterMs` is parsed from `retry-after`. */
+declare class MavuntaRateLimitError extends MavuntaError {
+    readonly retryAfterMs: number | null;
+    constructor(message: string, init?: MavuntaErrorInit & {
+        retryAfterMs?: number | null;
+    });
+}
+
+export { AuthVerifyResult, Balance, CreateCustomerParams, CreatePaymentIntentParams, CreatePaymentLinkParams, type CreateQuoteParams, type CreateRefundParams, CreateWebhookEndpointParams, Customer, type ListCustomersParams, type ListPaymentIntentsParams, ListResponse, type ListSettlementsParams, type ListWebhookEventsParams, Mavunta, MavuntaAPIError, MavuntaAuthenticationError, MavuntaConnectionError, MavuntaError, type MavuntaErrorBody, MavuntaIdempotencyError, MavuntaOptions, MavuntaPermissionError, MavuntaRateLimitError, MavuntaTimeoutError, MavuntaValidationError, MavuntaWebhookSignatureError, PaymentIntent, PaymentLink, Refund, type ReportParams, RequestOptions, Settlement, type TriggerWebhookParams, WebhookEndpoint, WebhookEvent, WebhooksResource, Mavunta as default };

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import { A as AuthVerifyResult, C as CreatePaymentIntentParams, R as RequestOptions, P as PaymentIntent, L as ListResponse, a as CreatePaymentLinkParams, b as PaymentLink, c as CreateCustomerParams, d as Customer, e as Refund, B as Balance, S as Settlement, f as CreateWebhookEndpointParams, W as WebhookEndpoint, g as WebhookEvent, h as WebhooksResource, M as MavuntaOptions } from './index-C_GLtIgI.js';
+export { i as MavuntaEnvironment, j as PaymentMethod, k as SettlementCurrency, V as VerifyWebhookParams, v as verifyWebhook } from './index-C_GLtIgI.js';
+
+declare class AuthResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Verify the current API key and return its merchant, scopes, and mode. */
+    verify(): Promise<AuthVerifyResult>;
+}
+
+declare class RatesResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Current indicative FX and crypto rates used for quotes. */
+    retrieve(): Promise<Record<string, unknown>>;
+    /** Alias for {@link retrieve}. */
+    list(): Promise<Record<string, unknown>>;
+}
+
+interface CreateQuoteParams {
+    source_currency: string;
+    target_asset: string;
+    amount: string;
+    side?: 'customer_pays' | 'merchant_receives';
+}
+declare class QuotesResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Create a short-lived quote locking a rate for a conversion. */
+    create(params: CreateQuoteParams): Promise<Record<string, unknown>>;
+}
+
+interface ListPaymentIntentsParams {
+    limit?: number;
+    starting_after?: string;
+    status?: string;
+}
+declare class PaymentIntentsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Create a payment intent and get a `checkout_url` to send the customer to. */
+    create(params: CreatePaymentIntentParams, options?: RequestOptions): Promise<PaymentIntent>;
+    retrieve(id: string): Promise<PaymentIntent>;
+    list(params?: ListPaymentIntentsParams): Promise<ListResponse<PaymentIntent>>;
+    /** Cancel an intent that has not been paid yet. */
+    cancel(id: string): Promise<PaymentIntent>;
+}
+
+declare class PaymentLinksResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Create a reusable payment link (with a hosted page + QR). */
+    create(params: CreatePaymentLinkParams, options?: RequestOptions): Promise<PaymentLink>;
+    retrieve(id: string): Promise<PaymentLink>;
+}
+
+interface ListCustomersParams {
+    limit?: number;
+    starting_after?: string;
+    email?: string;
+}
+declare class CustomersResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    create(params: CreateCustomerParams, options?: RequestOptions): Promise<Customer>;
+    retrieve(id: string): Promise<Customer>;
+    list(params?: ListCustomersParams): Promise<ListResponse<Customer>>;
+}
+
+interface CreateRefundParams {
+    payment_intent: string;
+    reason?: string;
+}
+declare class RefundsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /**
+     * Refund a paid payment in full. Partial refunds are not supported, and a
+     * payment can have at most one refund (a repeat after success rejects with
+     * `already_refunded`).
+     */
+    create(params: CreateRefundParams, options?: RequestOptions): Promise<Refund>;
+    retrieve(id: string): Promise<Refund>;
+    list(params?: {
+        limit?: number;
+        starting_after?: string;
+    }): Promise<ListResponse<Refund>>;
+}
+
+declare class BalancesResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Retrieve the merchant's available and pending balances by asset. */
+    retrieve(): Promise<Balance>;
+}
+
+interface ListSettlementsParams {
+    limit?: number;
+    starting_after?: string;
+    status?: string;
+}
+declare class SettlementsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    list(params?: ListSettlementsParams): Promise<ListResponse<Settlement>>;
+}
+
+interface ReportParams {
+    /** ISO date or unix-seconds range bound, per the API docs. */
+    from?: string;
+    to?: string;
+    limit?: number;
+    starting_after?: string;
+}
+declare class ReportsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Tabular payments report for reconciliation. */
+    payments(params?: ReportParams): Promise<Record<string, unknown>>;
+    /** Tabular settlements report for reconciliation. */
+    settlements(params?: ReportParams): Promise<Record<string, unknown>>;
+}
+
+declare class WebhookEndpointsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    create(params: CreateWebhookEndpointParams, options?: RequestOptions): Promise<WebhookEndpoint>;
+    retrieve(id: string): Promise<WebhookEndpoint>;
+    list(params?: {
+        limit?: number;
+        starting_after?: string;
+    }): Promise<ListResponse<WebhookEndpoint>>;
+    delete(id: string): Promise<{
+        id: string;
+        object: string;
+        deleted: boolean;
+    }>;
+}
+
+interface ListWebhookEventsParams {
+    limit?: number;
+    starting_after?: string;
+    type?: string;
+}
+declare class WebhookEventsResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    list(params?: ListWebhookEventsParams): Promise<ListResponse<WebhookEvent>>;
+    retrieve(id: string): Promise<WebhookEvent>;
+    /** Re-deliver an event to all subscribed endpoints. */
+    resend(id: string): Promise<WebhookEvent>;
+}
+
+interface TriggerWebhookParams {
+    /** The event type to simulate, e.g. `payment_intent.paid`. */
+    type: string;
+    /** Optional override data merged into the simulated event. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Sandbox-only test helpers. These work with a `cwk_test_…` key; calling them
+ * with a live key returns an error from the API.
+ */
+declare class SandboxResource {
+    private readonly client;
+    constructor(client: Mavunta);
+    /** Fire a simulated webhook event to your configured endpoints. */
+    triggerWebhook(params: TriggerWebhookParams): Promise<WebhookEvent>;
+}
+
+type HttpMethod = 'GET' | 'POST' | 'DELETE';
+interface InternalRequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    idempotencyKey?: string;
+}
+/**
+ * The Mavunta API client. Server-side only: it authenticates with a secret or
+ * restricted key and must never run in a browser.
+ *
+ * ```ts
+ * import Mavunta from 'mavunta'
+ * const mavunta = new Mavunta({ secretKey: process.env.MAVUNTA_SECRET_KEY! })
+ * const intent = await mavunta.paymentIntents.create({
+ *   amount: '2500', currency: 'KES', settlement_currency: 'USDT',
+ *   payment_methods: ['mpesa', 'card'],
+ * })
+ * ```
+ */
+declare class Mavunta {
+    readonly auth: AuthResource;
+    readonly rates: RatesResource;
+    readonly quotes: QuotesResource;
+    readonly paymentIntents: PaymentIntentsResource;
+    readonly paymentLinks: PaymentLinksResource;
+    readonly customers: CustomersResource;
+    readonly refunds: RefundsResource;
+    readonly balances: BalancesResource;
+    readonly settlements: SettlementsResource;
+    readonly reports: ReportsResource;
+    readonly webhookEndpoints: WebhookEndpointsResource;
+    readonly webhookEvents: WebhookEventsResource;
+    readonly sandbox: SandboxResource;
+    /** Webhook signature verification (no network call). */
+    readonly webhooks: WebhooksResource;
+    private readonly secretKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    constructor(options: MavuntaOptions);
+    /** @internal Used by resource classes; not part of the public surface. */
+    request<T>(method: HttpMethod, path: string, opts?: InternalRequestOptions): Promise<T>;
+}
+
+/**
+ * Error hierarchy for the Mavunta SDK.
+ *
+ * Every failure surfaces as a {@link MavuntaError} subclass so callers can
+ * branch on the type and read `code` / `requestId` for support. The shape
+ * mirrors the API's error envelope (spec §24):
+ *
+ *   { error: { type, code, message, param, request_id, docs_url } }
+ */
+interface MavuntaErrorBody {
+    type?: string;
+    code?: string;
+    message?: string;
+    param?: string | null;
+    request_id?: string;
+    docs_url?: string;
+}
+interface MavuntaErrorInit {
+    type?: string;
+    code?: string;
+    param?: string | null;
+    requestId?: string | null;
+    statusCode?: number | null;
+    docsUrl?: string | null;
+}
+/** Base class for everything thrown by the SDK. */
+declare class MavuntaError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly param: string | null;
+    readonly requestId: string | null;
+    readonly statusCode: number | null;
+    readonly docsUrl: string | null;
+    constructor(message: string, init?: MavuntaErrorInit);
+}
+/** A non-2xx response that does not map to a more specific class. */
+declare class MavuntaAPIError extends MavuntaError {
+}
+/** 401: missing, invalid, or revoked API key. */
+declare class MavuntaAuthenticationError extends MavuntaError {
+}
+/** 403: the key is valid but lacks the scope for this action. */
+declare class MavuntaPermissionError extends MavuntaError {
+}
+/** 400 / 422: the request was malformed or failed validation. */
+declare class MavuntaValidationError extends MavuntaError {
+}
+/** 409 on a money-moving create with a reused idempotency key. */
+declare class MavuntaIdempotencyError extends MavuntaError {
+}
+/** A network failure before a response was received. */
+declare class MavuntaConnectionError extends MavuntaError {
+}
+/** The request exceeded the configured timeout. */
+declare class MavuntaTimeoutError extends MavuntaError {
+}
+/** Webhook signature verification failed. */
+declare class MavuntaWebhookSignatureError extends MavuntaError {
+}
+/** 429: too many requests. `retryAfterMs` is parsed from `retry-after`. */
+declare class MavuntaRateLimitError extends MavuntaError {
+    readonly retryAfterMs: number | null;
+    constructor(message: string, init?: MavuntaErrorInit & {
+        retryAfterMs?: number | null;
+    });
+}
+
+export { AuthVerifyResult, Balance, CreateCustomerParams, CreatePaymentIntentParams, CreatePaymentLinkParams, type CreateQuoteParams, type CreateRefundParams, CreateWebhookEndpointParams, Customer, type ListCustomersParams, type ListPaymentIntentsParams, ListResponse, type ListSettlementsParams, type ListWebhookEventsParams, Mavunta, MavuntaAPIError, MavuntaAuthenticationError, MavuntaConnectionError, MavuntaError, type MavuntaErrorBody, MavuntaIdempotencyError, MavuntaOptions, MavuntaPermissionError, MavuntaRateLimitError, MavuntaTimeoutError, MavuntaValidationError, MavuntaWebhookSignatureError, PaymentIntent, PaymentLink, Refund, type ReportParams, RequestOptions, Settlement, type TriggerWebhookParams, WebhookEndpoint, WebhookEvent, WebhooksResource, Mavunta as default };