@mitumba/sdk 1.27.1 → 1.29.0

package/README.md

@@ -102,19 +102,45 @@ const trending = await mitumba.search.getTrending('nbi_01')
 
 ### 4. Orders & Pay Modules (`mitumba.orders`, `mitumba.pay`)
 
-End-to-end checkout and M-Pesa integration.
+End-to-end checkout with provider-neutral payment initiation.
+
+> `pay.initiateCheckout()` is available on the production API. Payment initiation can be temporarily paused and return `payment_initiation_paused`.
 
 ```typescript
 // 1. Create an order
 const { order_id, total } = await mitumba.orders.create({ listing_id: 'lst_123' })
 
-// 2. Initiate M-Pesa STK Push
-await mitumba.pay.initiateStkPush({ order_id, phone: '+254700000000' })
+// 2. Select a payment method; the API selects the provider
+const initiation = await mitumba.pay.initiateCheckout({
+  order_id,
+  idempotency_key: 'checkout-attempt-123',
+  method: { type: 'mobile_money', phone: '+254700000000' }
+})
+
+// 3. Continue only through the returned action
+if (initiation.next_action.type === 'redirect') {
+  const { url, expires_at } = initiation.next_action
+  // Open the absolute HTTPS URL in your app's navigation layer.
+} else {
+  // Wait for out-of-band confirmation on the buyer's device.
+}
+
+// 4. Initiation is not payment success; poll the checkout lifecycle
+const checkout = await mitumba.pay.getCheckoutStatus(order_id)
 
-// 3. Poll for payment status
-const status = await mitumba.pay.getStatus(order_id)
+if (!checkout.terminal) {
+  console.log(`Poll again after ${checkout.poll_after_ms}ms`)
+}
+
+if (checkout.checkout_status === 'paid') {
+  console.log(`Order ${checkout.order_id} is paid`)
+}
 ```
 
+If an initiation request is cancelled or its result is lost, retry the identical input with the same `idempotency_key` to recover the authoritative result. Reusing the key with different input returns `idempotency_conflict`.
+
+`pay.initMpesa()`, `pay.initPaystack()`, and `pay.initiateStk()` remain source- and runtime-compatible while the provider-neutral endpoint is introduced. `pay.getStatus(orderId)` also remains available, but is deprecated because its legacy response does not represent the aggregate retail/bale checkout lifecycle. New integrations should use `getCheckoutStatus()` and follow `terminal`, `retryable`, and `poll_after_ms` rather than interpreting an individual payment attempt as order success.
+
 ### 5. Vazi Module (`mitumba.vazi`)
 
 AI-assembled outfit feeds.

package/dist/index.d.mts

@@ -404,6 +404,136 @@ interface OrderHistoryParams {
     page?: number;
 }
 
+type BaleGrade = 'Cream' | 'A' | 'B' | 'C';
+type BaleType = 'original' | 'sorted';
+interface WholesaleStore {
+    id: string;
+    name: string;
+    slug: string;
+    tagline: string | null;
+    description: string | null;
+    logo_url: string | null;
+    origins: string[];
+    verified: boolean;
+}
+interface WholesaleDepot {
+    id: string;
+    name: string;
+    address: string | null;
+    city_id: string | null;
+    is_primary: boolean;
+}
+interface Bale {
+    id: string;
+    store_id: string;
+    seller_id: string;
+    title: string;
+    category: string;
+    grade: BaleGrade;
+    bale_type: BaleType;
+    weight_kg: number;
+    origin: string | null;
+    est_pieces: number | null;
+    price_kes: number;
+    moq: number;
+    mix: string | null;
+    description: string | null;
+    city_id: string | null;
+    status: 'draft' | 'active' | 'sold_out';
+    created_at: string;
+}
+interface BaleDetail extends Bale {
+    images: string[];
+    store: {
+        name: string;
+        slug: string;
+        verified: boolean;
+        sti: number | null;
+    };
+}
+interface CreateBaleInput {
+    title: string;
+    category: string;
+    grade: BaleGrade;
+    bale_type?: BaleType;
+    weight_kg: number;
+    origin?: string;
+    est_pieces?: number;
+    price_kes: number;
+    moq?: number;
+    mix?: string;
+    description?: string;
+    city_id?: string;
+    status?: 'draft' | 'active' | 'sold_out';
+}
+interface WholesaleFeedParams {
+    q?: string;
+    category?: string;
+    grade?: BaleGrade;
+    origin?: string;
+    city_id?: string;
+    limit?: number;
+    offset?: number;
+}
+interface BaleFeedItem extends Bale {
+    image_url: string | null;
+    store: {
+        name: string;
+        slug: string;
+        verified: boolean;
+        sti: number | null;
+    };
+}
+interface SaveWholesaleStoreInput {
+    name: string;
+    tagline?: string;
+    description?: string;
+    logo_url?: string;
+    origins?: string[];
+}
+interface AddDepotInput {
+    name: string;
+    address?: string;
+    city_id?: string;
+    is_primary?: boolean;
+}
+declare const BALE_ORDER_STATUSES: readonly ["pending_payment", "paid", "confirmed", "in_transit", "delivered", "completed", "cancelled"];
+type BaleOrderStatus = typeof BALE_ORDER_STATUSES[number];
+type BaleFulfillment = 'pickup' | 'courier';
+interface BaleOrder {
+    id: string;
+    bale_id: string;
+    buyer_id: string;
+    seller_id: string;
+    store_id: string;
+    title: string;
+    grade: string;
+    origin: string | null;
+    image_url: string | null;
+    qty: number;
+    unit_kes: number;
+    total_kes: number;
+    fulfillment: BaleFulfillment;
+    freight_kes: number | null;
+    status: BaleOrderStatus;
+    city_id: string | null;
+    buyer_name: string | null;
+    store_name: string | null;
+    created_at: string;
+}
+interface BaleOrderEvent {
+    actor: string;
+    old_status: string | null;
+    new_status: string;
+    note: string | null;
+    created_at: string;
+}
+interface CreateBaleOrderInput {
+    bale_id: string;
+    qty?: number;
+    fulfillment: BaleFulfillment;
+}
+
 interface StkPushInput {
     order_id: string;
     phone: string;
@@ -429,6 +559,73 @@ interface PaymentStatusResponse {
     status: PaymentStatus;
     total: number;
 }
+type KnownPaymentProvider = 'daraja' | 'intasend' | 'paystack' | 'airtel';
+type ProviderId = KnownPaymentProvider | (string & {});
+type PaymentProvider = ProviderId;
+type CheckoutPaymentMethod = {
+    type: 'mobile_money';
+    phone: string;
+} | {
+    type: 'card';
+};
+interface InitiateCheckoutInput {
+    order_id: string;
+    idempotency_key: string;
+    method: CheckoutPaymentMethod;
+}
+type CheckoutNextAction = {
+    type: 'await_confirmation';
+} | {
+    type: 'redirect';
+    url: string;
+    expires_at: string | null;
+};
+interface InitiateCheckoutResponse {
+    version: 1;
+    order_id: string;
+    attempt: {
+        id: string;
+        sequence: number;
+        provider: ProviderId;
+        status: 'initiated';
+    };
+    next_action: CheckoutNextAction;
+}
+type PaymentAttemptStatus = 'initiated' | 'funded' | 'failed' | 'refunded' | 'cancelled';
+type CheckoutStatus = 'pending' | 'paid' | 'failed' | 'cancelled' | 'refunded';
+type CheckoutOrder = {
+    type: 'retail';
+    status: OrderStatus;
+} | {
+    type: 'bale';
+    status: BaleOrderStatus;
+};
+interface CheckoutStatusResponse {
+    version: 1;
+    order_id: string;
+    order: CheckoutOrder;
+    checkout_status: CheckoutStatus;
+    terminal: boolean;
+    retryable: boolean;
+    amount: {
+        currency: 'KES';
+        minor_units: number;
+    };
+    latest_attempt: {
+        id: string;
+        sequence: number;
+        provider: PaymentProvider;
+        status: PaymentAttemptStatus;
+        terminal: boolean;
+        created_at: string;
+        updated_at: string;
+    } | null;
+    attempt_count: number;
+    order_updated_at: string;
+    status_updated_at: string;
+    server_time: string;
+    poll_after_ms: number;
+}
 
 interface VAZIOutfitItem {
     id: string;
@@ -1040,136 +1237,6 @@ interface DisputeListParams {
     page?: number;
 }
 
-type BaleGrade = 'Cream' | 'A' | 'B' | 'C';
-type BaleType = 'original' | 'sorted';
-interface WholesaleStore {
-    id: string;
-    name: string;
-    slug: string;
-    tagline: string | null;
-    description: string | null;
-    logo_url: string | null;
-    origins: string[];
-    verified: boolean;
-}
-interface WholesaleDepot {
-    id: string;
-    name: string;
-    address: string | null;
-    city_id: string | null;
-    is_primary: boolean;
-}
-interface Bale {
-    id: string;
-    store_id: string;
-    seller_id: string;
-    title: string;
-    category: string;
-    grade: BaleGrade;
-    bale_type: BaleType;
-    weight_kg: number;
-    origin: string | null;
-    est_pieces: number | null;
-    price_kes: number;
-    moq: number;
-    mix: string | null;
-    description: string | null;
-    city_id: string | null;
-    status: 'draft' | 'active' | 'sold_out';
-    created_at: string;
-}
-interface BaleDetail extends Bale {
-    images: string[];
-    store: {
-        name: string;
-        slug: string;
-        verified: boolean;
-        sti: number | null;
-    };
-}
-interface CreateBaleInput {
-    title: string;
-    category: string;
-    grade: BaleGrade;
-    bale_type?: BaleType;
-    weight_kg: number;
-    origin?: string;
-    est_pieces?: number;
-    price_kes: number;
-    moq?: number;
-    mix?: string;
-    description?: string;
-    city_id?: string;
-    status?: 'draft' | 'active' | 'sold_out';
-}
-interface WholesaleFeedParams {
-    q?: string;
-    category?: string;
-    grade?: BaleGrade;
-    origin?: string;
-    city_id?: string;
-    limit?: number;
-    offset?: number;
-}
-interface BaleFeedItem extends Bale {
-    image_url: string | null;
-    store: {
-        name: string;
-        slug: string;
-        verified: boolean;
-        sti: number | null;
-    };
-}
-interface SaveWholesaleStoreInput {
-    name: string;
-    tagline?: string;
-    description?: string;
-    logo_url?: string;
-    origins?: string[];
-}
-interface AddDepotInput {
-    name: string;
-    address?: string;
-    city_id?: string;
-    is_primary?: boolean;
-}
-declare const BALE_ORDER_STATUSES: readonly ["pending_payment", "paid", "confirmed", "in_transit", "delivered", "completed", "cancelled"];
-type BaleOrderStatus = typeof BALE_ORDER_STATUSES[number];
-type BaleFulfillment = 'pickup' | 'courier';
-interface BaleOrder {
-    id: string;
-    bale_id: string;
-    buyer_id: string;
-    seller_id: string;
-    store_id: string;
-    title: string;
-    grade: string;
-    origin: string | null;
-    image_url: string | null;
-    qty: number;
-    unit_kes: number;
-    total_kes: number;
-    fulfillment: BaleFulfillment;
-    freight_kes: number | null;
-    status: BaleOrderStatus;
-    city_id: string | null;
-    buyer_name: string | null;
-    store_name: string | null;
-    created_at: string;
-}
-interface BaleOrderEvent {
-    actor: string;
-    old_status: string | null;
-    new_status: string;
-    note: string | null;
-    created_at: string;
-}
-interface CreateBaleOrderInput {
-    bale_id: string;
-    qty?: number;
-    fulfillment: BaleFulfillment;
-}
-
 interface MitumbaClientConfig {
     baseUrl: string;
     debug?: boolean;
@@ -1602,10 +1669,30 @@ declare class PayModule {
      * Initiate a Paystack payment — returns access_code for inline popup.
      */
     initPaystack(input: PaystackInput, options?: RequestOptions): Promise<PaystackInitResponse>;
+    /**
+     * Initiate a provider-neutral checkout for an order.
+     *
+     * The payment provider is selected by the API. Continue checkout using the
+     * returned next action, then poll {@link getCheckoutStatus} for payment state.
+     * Retrying after cancellation requires the same input and idempotency key.
+     *
+     * @param input - Order, idempotency key, and buyer-selected payment method.
+     * @param options - Request options, including an optional abort signal.
+     * @returns The initiated attempt and its required continuation action.
+     * @throws {APIError} When the API rejects or cannot initiate the checkout.
+     */
+    initiateCheckout(input: InitiateCheckoutInput, options?: RequestOptions): Promise<InitiateCheckoutResponse>;
     /**
      * Poll for the current status of a payment by its order ID.
+     *
+     * @deprecated Use {@link getCheckoutStatus} for the typed checkout lifecycle.
+     * This method retains its legacy route and response for compatibility.
      */
     getStatus(orderId: string, options?: RequestOptions): Promise<PaymentStatusResponse>;
+    /**
+     * Get the buyer-visible checkout lifecycle for a retail or bale order.
+     */
+    getCheckoutStatus(orderId: string, options?: RequestOptions): Promise<CheckoutStatusResponse>;
 }
 
 declare class VaziModule {
@@ -2399,4 +2486,4 @@ declare class MitumbaClient {
     isAuthenticated(): Promise<boolean>;
 }
 
-export { APIClient, APIError, type APIErrorResponse, type Add2FAMethodInput, type Add2FAMethodResult, type AddAddressInput, type AddDepotInput, type AddPaymentMethodInput, type Address, type AdminListingItem, AdminModule, type AdminOrderDetail, type AdminOrderListItem, type AdminPayoutItem, type AdminReport, type AdminStoreDetail, type AdminStoreListItem, type AdminUserDetail, type AdminUserListItem, type AdminVaziOutfit, type AdminVerificationItem, AuthModule, type AuthTokens, type AuthenticationResponseJSON, BALE_ORDER_STATUSES, type Bale, type BaleDetail, type BaleFeedItem, type BaleFulfillment, type BaleGrade, type BaleOrder, type BaleOrderEvent, type BaleOrderStatus, type BaleType, type BecomeBaleSellerInput, type BecomeSellerInput, type BlockedIp, type Business, type BusinessType, BusinessesModule, CONDITIONS, type CartItem, CartModule, type Category, type ChangePasswordInput, type City, type CompleteOnboardingInput, type Condition, type Conversation, type CreateBaleInput, type CreateBaleOrderInput, type CreateListingInput, type CreateOrderInput, type CreateReportInput, type CreateReviewInput, type CreateStoreInput, DESIRED_RESOLUTIONS, DISPUTE_REASONS, DISPUTE_STATUSES, type DeliveryAddress, type DesiredResolution, type Dispute, type DisputeEvent, type DisputeEvidence, type DisputeListParams, type DisputeReason, type DisputeStatus, DisputesModule, type EmailLoginInput, type EmailRegisterInput, type FollowedStore, type ForgotPasswordInput, IDBTokenStore, type InboxRealtimeEvent, LISTING_STATUSES, type LinkedAccount, type LinkedAccountProvider, type Listing, type ListingImage, type ListingStatus, type ListingsFeedParams, ListingsModule, type LoginInput, MailerModule, type MailerTemplate, MemoryTokenStore, type Message, type MessageResponse, MessagesModule, MitumbaClient, type MitumbaClientConfig, type MpesaInput, type Notification, type NotificationPref, type NotificationType, NotificationsModule, ORDER_STATUSES, type Order, type OrderEvent, type OrderHistoryParams, type OrderStatus, OrdersModule, PAYMENT_STATUSES, type PaginatedResponse, PayModule, type PaymentMethod, type PaymentMethodType, type PaymentStatus, type PaymentStatusResponse, type PaystackInitResponse, type PaystackInput, type PhoneLoginInput, type PhoneRegisterInput, type PresignImageResponse, type PublicKeyCredentialCreationOptionsJSON, type PublicKeyCredentialRequestOptionsJSON, type RaiseDisputeInput, type RegisterInput, type RegistrationResponseJSON, ReportsModule, type RequestOptions, type ResetPasswordInput, type ResolveDisputeInput, type RespondDisputeInput, type Review, type ReviewableOrder, ReviewsModule, type SaveSearchInput, type SaveWholesaleStoreInput, type SearchHistoryItem, SearchModule, type SearchParams, type SearchResult, type SellerProfile, type SellerStorefront, type SellerType, type SendEmailInput, type SendMessageInput, type SendOtpInput, type Session, SettingsModule, type SimilarListing, type StiEvent, type StkPushInput, type StkPushResponse, type Store, type StoreAnalytics, type StoreSettings, type StoreStats, StoresModule, type SubscriptionTier, type SystemStats, TWO_FACTOR_METHOD_TYPES, type TokenStore, type TransitionOrderInput, type TrendingTerm, type TwoFactorMethod, type TwoFactorMethodType, type TwoFactorRequired, type UpdateBusinessInput, type UpdateListingInput, type UpdateProfileInput, type UpdateStoreInput, UploadsModule, type UserProfile, type VAZIOutfit, type VAZIOutfitDetail, type VAZIOutfitDetailItem, type VAZIOutfitItem, type VaziFeedParams, type VaziFeedResponse, VaziModule, type Verify2FAInput, type VerifyOtpInput, type WholesaleDepot, type WholesaleFeedParams, WholesaleModule, type WholesaleStore, type WishlistListing, WishlistsModule, createTokenStore };
+export { APIClient, APIError, type APIErrorResponse, type Add2FAMethodInput, type Add2FAMethodResult, type AddAddressInput, type AddDepotInput, type AddPaymentMethodInput, type Address, type AdminListingItem, AdminModule, type AdminOrderDetail, type AdminOrderListItem, type AdminPayoutItem, type AdminReport, type AdminStoreDetail, type AdminStoreListItem, type AdminUserDetail, type AdminUserListItem, type AdminVaziOutfit, type AdminVerificationItem, AuthModule, type AuthTokens, type AuthenticationResponseJSON, BALE_ORDER_STATUSES, type Bale, type BaleDetail, type BaleFeedItem, type BaleFulfillment, type BaleGrade, type BaleOrder, type BaleOrderEvent, type BaleOrderStatus, type BaleType, type BecomeBaleSellerInput, type BecomeSellerInput, type BlockedIp, type Business, type BusinessType, BusinessesModule, CONDITIONS, type CartItem, CartModule, type Category, type ChangePasswordInput, type CheckoutNextAction, type CheckoutOrder, type CheckoutPaymentMethod, type CheckoutStatus, type CheckoutStatusResponse, type City, type CompleteOnboardingInput, type Condition, type Conversation, type CreateBaleInput, type CreateBaleOrderInput, type CreateListingInput, type CreateOrderInput, type CreateReportInput, type CreateReviewInput, type CreateStoreInput, DESIRED_RESOLUTIONS, DISPUTE_REASONS, DISPUTE_STATUSES, type DeliveryAddress, type DesiredResolution, type Dispute, type DisputeEvent, type DisputeEvidence, type DisputeListParams, type DisputeReason, type DisputeStatus, DisputesModule, type EmailLoginInput, type EmailRegisterInput, type FollowedStore, type ForgotPasswordInput, IDBTokenStore, type InboxRealtimeEvent, type InitiateCheckoutInput, type InitiateCheckoutResponse, type KnownPaymentProvider, LISTING_STATUSES, type LinkedAccount, type LinkedAccountProvider, type Listing, type ListingImage, type ListingStatus, type ListingsFeedParams, ListingsModule, type LoginInput, MailerModule, type MailerTemplate, MemoryTokenStore, type Message, type MessageResponse, MessagesModule, MitumbaClient, type MitumbaClientConfig, type MpesaInput, type Notification, type NotificationPref, type NotificationType, NotificationsModule, ORDER_STATUSES, type Order, type OrderEvent, type OrderHistoryParams, type OrderStatus, OrdersModule, PAYMENT_STATUSES, type PaginatedResponse, PayModule, type PaymentAttemptStatus, type PaymentMethod, type PaymentMethodType, type PaymentProvider, type PaymentStatus, type PaymentStatusResponse, type PaystackInitResponse, type PaystackInput, type PhoneLoginInput, type PhoneRegisterInput, type PresignImageResponse, type ProviderId, type PublicKeyCredentialCreationOptionsJSON, type PublicKeyCredentialRequestOptionsJSON, type RaiseDisputeInput, type RegisterInput, type RegistrationResponseJSON, ReportsModule, type RequestOptions, type ResetPasswordInput, type ResolveDisputeInput, type RespondDisputeInput, type Review, type ReviewableOrder, ReviewsModule, type SaveSearchInput, type SaveWholesaleStoreInput, type SearchHistoryItem, SearchModule, type SearchParams, type SearchResult, type SellerProfile, type SellerStorefront, type SellerType, type SendEmailInput, type SendMessageInput, type SendOtpInput, type Session, SettingsModule, type SimilarListing, type StiEvent, type StkPushInput, type StkPushResponse, type Store, type StoreAnalytics, type StoreSettings, type StoreStats, StoresModule, type SubscriptionTier, type SystemStats, TWO_FACTOR_METHOD_TYPES, type TokenStore, type TransitionOrderInput, type TrendingTerm, type TwoFactorMethod, type TwoFactorMethodType, type TwoFactorRequired, type UpdateBusinessInput, type UpdateListingInput, type UpdateProfileInput, type UpdateStoreInput, UploadsModule, type UserProfile, type VAZIOutfit, type VAZIOutfitDetail, type VAZIOutfitDetailItem, type VAZIOutfitItem, type VaziFeedParams, type VaziFeedResponse, VaziModule, type Verify2FAInput, type VerifyOtpInput, type WholesaleDepot, type WholesaleFeedParams, WholesaleModule, type WholesaleStore, type WishlistListing, WishlistsModule, createTokenStore };