@paybetaby/node-sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,437 @@
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    request<T>(method: string, path: string, options?: {
+        body?: unknown;
+        query?: Record<string, string | number | boolean | undefined | null>;
+    }): Promise<T>;
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined | null>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+type TransactionStatus = 'INITIATED' | 'FUNDED' | 'IN_ESCROW' | 'RELEASED' | 'DISPUTED' | 'REFUNDED';
+interface Transaction {
+    id: string;
+    merchantId: string;
+    buyerEmail: string;
+    sellerEmail: string;
+    amount: number;
+    currency: string;
+    status: TransactionStatus;
+    metadata?: Record<string, unknown>;
+    disputeToken?: string;
+    paymentLinkToken?: string;
+    paymentLinkUrl?: string;
+    sagaStatus?: string;
+    sagaFailureReason?: string;
+    sagaFailedStep?: string;
+    createdAt: string;
+    updatedAt: string;
+    version: number;
+}
+interface CreateTransactionParams {
+    merchantId: string;
+    buyerEmail: string;
+    /** E.164 phone number — required by the API as a guaranteed WhatsApp/SMS delivery channel. */
+    buyerPhone: string;
+    sellerEmail: string;
+    /** Decimal amount in the major currency unit (naira/dollars), unlike Payment.amount which is minor-unit. */
+    amount: number;
+    currency: string;
+    metadata?: Record<string, unknown>;
+}
+interface ListTransactionsParams {
+    merchantId?: string;
+    buyerEmail?: string;
+    status?: TransactionStatus;
+    limit?: number;
+    offset?: number;
+}
+interface TransactionEvent {
+    id: string;
+    transactionId: string;
+    eventType: string;
+    previousStatus?: TransactionStatus;
+    newStatus?: TransactionStatus;
+    metadata?: Record<string, unknown>;
+    occurredAt: string;
+}
+
+interface RequestOptions {
+    idempotencyKey?: string;
+}
+
+declare class TransactionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateTransactionParams, opts?: RequestOptions): Promise<Transaction>;
+    /**
+     * Lists transactions. The bare `/transactions` endpoint is platform-role
+     * only — an API-key (merchant) caller gets a 403 there — so passing
+     * `merchantId` routes to `/transactions/merchant/:merchantId` instead.
+     */
+    list(params?: ListTransactionsParams): Promise<Transaction[]>;
+    retrieve(id: string): Promise<Transaction>;
+    listHistory(id: string): Promise<TransactionEvent[]>;
+}
+
+type PSPType = 'PAYSTACK' | 'FLUTTERWAVE' | 'BANK_DIRECT';
+type PaymentMethod = 'CARD' | 'BANK_TRANSFER' | 'USSD' | 'MOBILE_MONEY' | 'BANK_ACCOUNT';
+type PaymentStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'REFUNDED';
+interface Payment {
+    id: string;
+    paymentId?: string;
+    merchantId: string;
+    transactionId: string;
+    amount: number;
+    currency: string;
+    status: PaymentStatus;
+    paymentMethod: PaymentMethod;
+    pspType: PSPType;
+    customerEmail: string;
+    customerName?: string;
+    pspReference?: string;
+    authorizationUrl?: string;
+    paymentLinkToken?: string;
+    paymentLinkUrl?: string;
+    failureReason?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    completedAt?: string;
+    /** Number of PSP attempts recorded for this payment. */
+    attemptsCount: number;
+}
+interface PaymentAttempt {
+    id: string;
+    paymentId: string;
+    attemptNumber: number;
+    status: PaymentStatus;
+    pspReference?: string;
+    failureReason?: string;
+    attemptedAt: string;
+}
+interface InitiatePaymentParams {
+    merchantId: string;
+    transactionId: string;
+    /** Integer amount in the smallest currency unit (kobo for NGN, cents for USD) — not a decimal. */
+    amount: number;
+    currency: string;
+    paymentMethod: PaymentMethod;
+    pspType: PSPType;
+    customerEmail: string;
+    customerName?: string;
+    idempotencyKey?: string;
+    redirectUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ListPaymentsParams {
+    merchantId?: string;
+    limit?: number;
+    offset?: number;
+}
+
+declare class PaymentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    initiate(params: InitiatePaymentParams): Promise<Payment>;
+    /**
+     * Lists payments. The bare `/payments` endpoint is platform-role only —
+     * an API-key (merchant) caller gets a 403 there — so passing `merchantId`
+     * (which every merchant API key call needs) routes to
+     * `/payments/merchant/:merchantId` instead, matching what the API
+     * actually allows a merchant credential to call.
+     */
+    list(params?: ListPaymentsParams): Promise<Payment[]>;
+    retrieve(id: string): Promise<Payment>;
+    verify(id: string): Promise<Payment>;
+    retry(id: string): Promise<Payment>;
+    listAttempts(id: string): Promise<PaymentAttempt[]>;
+}
+
+type EscrowStatus = 'created' | 'funded' | 'pending_release' | 'released' | 'disputed' | 'refunded' | 'cancelled';
+type ConditionType = 'DELIVERY_CONFIRMATION' | 'BUYER_CONFIRMATION' | 'TIME_BASED' | 'MANUAL_APPROVAL';
+type ConditionLogic = 'AND' | 'OR';
+interface ReleaseCondition {
+    type: ConditionType;
+    config?: Record<string, unknown>;
+    isMet: boolean;
+    metAt?: string;
+}
+interface ReleasePolicy {
+    logic: ConditionLogic;
+    conditions: Array<{
+        type: ConditionType;
+        config?: Record<string, unknown>;
+    }>;
+}
+interface EscrowBalance {
+    escrowId: string;
+    heldAmount: string;
+    releasedAmount: string;
+    refundedAmount: string;
+    currency: string;
+}
+interface Escrow {
+    id: string;
+    transactionId: string;
+    merchantId: string;
+    buyerEmail: string;
+    sellerEmail: string;
+    /** Integer amount in kobo — the API does not divide this down to a decimal on the way out, unlike on create. */
+    amount: number;
+    currency: string;
+    status: EscrowStatus;
+    releasePolicy: ReleasePolicy | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+    /** Only present on GET /escrows/:id. */
+    deliveryTrackingReference?: string | null;
+}
+interface CreateEscrowConditionParams {
+    type: ConditionType;
+    config?: Record<string, unknown>;
+}
+interface CreateEscrowReleasePolicyParams {
+    conditionLogic?: ConditionLogic;
+    conditions?: CreateEscrowConditionParams[];
+}
+interface CreateEscrowParams {
+    transactionId: string;
+    merchantId: string;
+    buyerEmail: string;
+    /** E.164 phone number — required by the API as a guaranteed WhatsApp/SMS delivery channel. */
+    buyerPhone: string;
+    sellerEmail: string;
+    /** Decimal amount in the major currency unit (naira/dollars) — the API converts to kobo itself. */
+    amount: number;
+    currency: string;
+    releasePolicy?: CreateEscrowReleasePolicyParams;
+    idempotencyKey?: string;
+}
+interface ListEscrowsParams {
+    merchantId?: string;
+    status?: EscrowStatus;
+    limit?: number;
+    offset?: number;
+}
+interface EscrowConditionsResponse {
+    escrowId: string;
+    logic: ConditionLogic;
+    canRelease: boolean;
+    conditions: ReleaseCondition[];
+}
+interface EscrowListResponse {
+    escrows: Escrow[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface ReleaseEscrowParams {
+    /** Ignored if supplied — actorId/actorType come from the caller's own session, never the request body, per the API's audit-trail design. Kept optional for forward-compat only. */
+    actorId?: string;
+    actorType?: string;
+    idempotencyKey?: string;
+}
+interface ConfirmDeliveryParams {
+    actorId?: string;
+    idempotencyKey?: string;
+    trackingReference?: string;
+}
+interface ConfirmBuyerParams {
+    actorId?: string;
+    idempotencyKey?: string;
+}
+
+declare class EscrowsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateEscrowParams, opts?: RequestOptions): Promise<Escrow>;
+    /**
+     * Lists escrows. The bare `/escrows` endpoint is platform-role only — an
+     * API-key (merchant) caller gets a 403 there — so passing `merchantId`
+     * routes to `/escrows/merchant/:merchantId` instead. Unlike
+     * payments/transactions/disputes, this returns a `{ escrows, total,
+     * limit, offset }` envelope rather than a bare array.
+     */
+    list(params?: ListEscrowsParams): Promise<EscrowListResponse>;
+    retrieve(id: string): Promise<Escrow>;
+    retrieveBalance(id: string): Promise<EscrowBalance>;
+    retrieveConditions(id: string): Promise<EscrowConditionsResponse>;
+    release(id: string, params?: ReleaseEscrowParams): Promise<Escrow>;
+    refund(id: string): Promise<Escrow>;
+    dispute(id: string): Promise<Escrow>;
+    cancel(id: string): Promise<Escrow>;
+    confirmDelivery(id: string, params?: ConfirmDeliveryParams): Promise<Escrow>;
+    confirmBuyer(id: string, params?: ConfirmBuyerParams): Promise<Escrow>;
+}
+
+type DisputeStatus = 'OPENED' | 'EVIDENCE_COLLECTION' | 'UNDER_REVIEW' | 'ARBITRATION' | 'RESOLVED' | 'CLOSED' | 'CANCELLED';
+type DisputeStage = 'INITIAL_REVIEW' | 'EVIDENCE_REVIEW' | 'MERCHANT_RESPONSE' | 'BUYER_RESPONSE' | 'ARBITRATOR_REVIEW' | 'ESCALATION' | 'FINAL_DECISION';
+type DisputeType = 'BUYER_COMPLAINT' | 'SELLER_COMPLAINT' | 'QUALITY_ISSUE' | 'NON_DELIVERY' | 'WRONG_ITEM' | 'DAMAGED_ITEM' | 'FRAUD' | 'OTHER';
+type DisputePriority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT';
+type OpenedBy = 'BUYER' | 'SELLER';
+type ResolutionOutcome = 'BUYER_WINS' | 'SELLER_WINS' | 'PARTIAL_REFUND' | 'PARTIAL_RELEASE' | 'SPLIT' | 'CANCELLED';
+type EvidenceType = 'IMAGE' | 'DOCUMENT' | 'VIDEO' | 'OTHER';
+type UploadedBy = 'BUYER' | 'SELLER' | 'ARBITRATOR';
+interface Evidence {
+    id: string;
+    disputeId: string;
+    evidenceType: EvidenceType;
+    uploadedBy: UploadedBy;
+    description?: string;
+    fileName: string;
+    mimeType: string;
+    createdAt: string;
+}
+interface Dispute {
+    id: string;
+    transactionId: string;
+    escrowId: string;
+    merchantId: string;
+    buyerEmail: string;
+    sellerEmail: string;
+    disputeType: DisputeType;
+    priority: DisputePriority;
+    status: DisputeStatus;
+    currentStage: DisputeStage;
+    description: string;
+    amount: number;
+    currency: string;
+    openedBy: OpenedBy;
+    openedAt: string;
+    resolvedAt?: string;
+    resolutionOutcome?: ResolutionOutcome;
+    resolutionNotes?: string;
+    workflowId?: string;
+    assignedArbitratorId?: string;
+    createdAt: string;
+    updatedAt: string;
+    version: number;
+}
+interface OpenDisputeParams {
+    transactionId: string;
+    escrowId: string;
+    merchantId: string;
+    buyerEmail: string;
+    sellerEmail: string;
+    disputeType: DisputeType;
+    priority: DisputePriority;
+    description: string;
+    /** Integer amount in kobo. */
+    amount: number;
+    currency: string;
+    openedBy: OpenedBy;
+    workflowId?: string;
+}
+interface ListDisputesParams {
+    merchantId?: string;
+    status?: DisputeStatus;
+    stage?: DisputeStage;
+    limit?: number;
+    offset?: number;
+}
+interface UploadEvidenceParams {
+    evidenceType: EvidenceType;
+    uploadedBy: UploadedBy;
+    description?: string;
+    fileName: string;
+    /** Base64-encoded file content. */
+    fileData: string;
+    mimeType: string;
+}
+interface ResolveDisputeParams {
+    outcome: ResolutionOutcome;
+    notes: string;
+}
+interface CancelDisputeParams {
+    reason: string;
+}
+
+declare class DisputesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    open(params: OpenDisputeParams): Promise<Dispute>;
+    /**
+     * Lists disputes. The bare `/disputes` endpoint is platform-role only —
+     * an API-key (merchant) caller gets a 403 there — so passing
+     * `merchantId` routes to `/disputes/merchant/:merchantId` instead.
+     */
+    list(params?: ListDisputesParams): Promise<Dispute[]>;
+    retrieve(id: string): Promise<Dispute>;
+    listEvidence(id: string): Promise<Evidence[]>;
+    uploadEvidence(id: string, params: UploadEvidenceParams): Promise<Evidence>;
+    resolve(id: string, params: ResolveDisputeParams): Promise<Dispute>;
+    cancel(id: string, params: CancelDisputeParams): Promise<Dispute>;
+}
+
+type WebhookEventType = 'transaction.created' | 'transaction.funded' | 'transaction.escrowed' | 'transaction.released' | 'transaction.disputed' | 'transaction.refunded' | 'payment.received' | 'payment.failed' | 'dispute.opened' | 'dispute.resolved' | 'escrow.released';
+interface WebhookEvent<T = unknown> {
+    id: string;
+    eventType: WebhookEventType;
+    timestamp: string;
+    data: T;
+}
+type TransactionWebhookEvent = WebhookEvent<Transaction>;
+type PaymentWebhookEvent = WebhookEvent<Payment>;
+type EscrowWebhookEvent = WebhookEvent<Escrow>;
+type DisputeWebhookEvent = WebhookEvent<Dispute>;
+
+declare class WebhooksResource {
+    private readonly secret;
+    constructor(secret: string);
+    /**
+     * Verifies the signature on an incoming webhook and parses the payload.
+     *
+     * PayBeta signs the concatenation of the delivery timestamp and the raw
+     * request body — `HMAC-SHA256(secret, "${timestamp}.${rawBody}")` — and
+     * sends the result hex-encoded, prefixed with `sha256=`, in the
+     * `X-PayBeta-Signature` header (see OutboundWebhookService). The
+     * timestamp itself arrives separately in `X-PayBeta-Timestamp`, so both
+     * headers are required here, not just the signature.
+     *
+     * Pass the raw request body (before JSON parsing), the value of the
+     * `X-PayBeta-Signature` header, and the value of the `X-PayBeta-Timestamp`
+     * header. Throws `PaybetaError` if the signature is invalid or the
+     * secret was not configured.
+     */
+    constructEvent<T = unknown>(rawBody: string | Buffer, signature: string, timestamp: string): WebhookEvent<T>;
+}
+
+interface PaybetaClientConfig {
+    /** API key obtained from the Paybeta dashboard (pb_live_* or pb_test_*) */
+    apiKey: string;
+    /** Override the default API base URL. Defaults to https://api.usepaybeta.com */
+    baseUrl?: string;
+    /** Webhook signing secret used to verify incoming webhook payloads */
+    webhookSecret?: string;
+    /** Request timeout in milliseconds. Defaults to 30000 */
+    timeout?: number;
+}
+declare class PaybetaClient {
+    readonly transactions: TransactionsResource;
+    readonly payments: PaymentsResource;
+    readonly escrows: EscrowsResource;
+    readonly disputes: DisputesResource;
+    readonly webhooks: WebhooksResource;
+    constructor(config: PaybetaClientConfig);
+}
+
+declare class PaybetaError extends Error {
+    constructor(message: string);
+}
+declare class PaybetaApiError extends PaybetaError {
+    readonly status: number;
+    readonly code: string;
+    readonly traceId: string;
+    readonly timestamp: string;
+    constructor(status: number, code: string, message: string, traceId: string, timestamp: string);
+}
+
+export { type CancelDisputeParams, type ConditionLogic, type ConditionType, type ConfirmBuyerParams, type ConfirmDeliveryParams, type CreateEscrowConditionParams, type CreateEscrowParams, type CreateEscrowReleasePolicyParams, type CreateTransactionParams, type Dispute, type DisputePriority, type DisputeStage, type DisputeStatus, type DisputeType, type DisputeWebhookEvent, type Escrow, type EscrowBalance, type EscrowConditionsResponse, type EscrowListResponse, type EscrowStatus, type EscrowWebhookEvent, type Evidence, type EvidenceType, type InitiatePaymentParams, type ListDisputesParams, type ListEscrowsParams, type ListPaymentsParams, type ListTransactionsParams, type OpenDisputeParams, type OpenedBy, type PSPType, PaybetaApiError, PaybetaClient, type PaybetaClientConfig, PaybetaError, type Payment, type PaymentAttempt, type PaymentMethod, type PaymentStatus, type PaymentWebhookEvent, type ReleaseCondition, type ReleaseEscrowParams, type ReleasePolicy, type RequestOptions, type ResolutionOutcome, type ResolveDisputeParams, type Transaction, type TransactionEvent, type TransactionStatus, type TransactionWebhookEvent, type UploadEvidenceParams, type UploadedBy, type WebhookEvent, type WebhookEventType };