@mitumba/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,456 @@
+interface AuthTokens {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
+interface MessageResponse {
+    message: string;
+}
+interface EmailRegisterInput {
+    email: string;
+    password: string;
+    display_name?: string;
+}
+interface PhoneRegisterInput {
+    phone: string;
+}
+type RegisterInput = EmailRegisterInput | PhoneRegisterInput;
+interface EmailLoginInput {
+    email: string;
+    password: string;
+}
+interface PhoneLoginInput {
+    phone: string;
+}
+type LoginInput = EmailLoginInput | PhoneLoginInput;
+interface SendOtpInput {
+    phone: string;
+}
+interface VerifyOtpInput {
+    phone: string;
+    code: string;
+}
+
+declare const CONDITIONS: readonly ["new", "like_new", "good", "fair"];
+type Condition = typeof CONDITIONS[number];
+declare const LISTING_STATUSES: readonly ["draft", "active", "sold", "removed"];
+type ListingStatus = typeof LISTING_STATUSES[number];
+interface ListingImage {
+    id: string;
+    listing_id: string;
+    url: string;
+    position: number;
+    created_at: string;
+}
+interface SellerProfile {
+    id: string;
+    sti_score: number;
+    verification_status: string;
+    seller_type: 'individual' | 'bale';
+}
+interface Listing {
+    id: string;
+    seller_id: string;
+    title: string;
+    description: string | null;
+    category_id: string;
+    city_id: string;
+    price: number;
+    condition: Condition;
+    status: ListingStatus;
+    photo_verified: boolean;
+    vazi_eligible: boolean;
+    created_at: string;
+    updated_at: string;
+    sti_score: number;
+    verification_status: string;
+    seller_type: 'individual' | 'bale';
+    images?: ListingImage[];
+}
+interface ListingsFeedParams {
+    city_id?: string;
+    category_id?: string;
+    min_price?: number;
+    max_price?: number;
+    condition?: Condition;
+    sort?: 'recency' | 'price_asc' | 'price_desc';
+    page?: number;
+    page_size?: number;
+}
+interface CreateListingInput {
+    title: string;
+    description?: string;
+    category_id: string;
+    city_id: string;
+    price: number;
+    condition: Condition;
+}
+type UpdateListingInput = Partial<CreateListingInput>;
+interface Category {
+    id: string;
+    name: string;
+    slug: string;
+}
+interface City {
+    id: string;
+    name: string;
+    delivery_fee: number;
+}
+interface SellerStorefront {
+    seller: SellerProfile;
+    listings: Listing[];
+    total: number;
+    page: number;
+    page_size: number;
+    has_more: boolean;
+}
+interface PresignImageResponse {
+    upload_url: string;
+    image_id: string;
+}
+
+interface SearchParams {
+    q: string;
+    city_id?: string;
+    category_id?: string;
+    min_price?: number;
+    max_price?: number;
+    condition?: Condition;
+    sort?: 'relevance' | 'recency' | 'price_asc' | 'price_desc' | 'sti';
+    page?: number;
+    page_size?: number;
+}
+interface SearchResult extends Omit<Listing, 'images'> {
+    rank: number;
+}
+interface TrendingTerm {
+    term: string;
+    count: number;
+}
+
+declare const ORDER_STATUSES: readonly ["created", "payment_pending", "paid", "seller_confirmed", "shipped", "delivered", "completed", "cancelled", "disputed"];
+type OrderStatus = typeof ORDER_STATUSES[number];
+interface OrderEvent {
+    id: string;
+    order_id: string;
+    actor: string;
+    old_status: string;
+    new_status: string;
+    note: string | null;
+    created_at: string;
+}
+interface Order {
+    id: string;
+    buyer_id: string;
+    seller_id: string;
+    listing_id: string;
+    amount: number;
+    delivery_fee: number;
+    total: number;
+    status: OrderStatus;
+    city_id: string;
+    created_at: string;
+    updated_at: string;
+    events?: OrderEvent[];
+}
+interface CreateOrderInput {
+    listing_id: string;
+}
+interface TransitionOrderInput {
+    status: OrderStatus;
+    note?: string;
+}
+interface OrderHistoryParams {
+    role?: 'buyer' | 'seller';
+    page?: number;
+}
+
+interface StkPushInput {
+    order_id: string;
+    phone: string;
+}
+interface StkPushResponse {
+    payment_id: string;
+    provider: string;
+}
+declare const PAYMENT_STATUSES: readonly ["initiated", "funded", "failed", "refunded", "cancelled"];
+type PaymentStatus = typeof PAYMENT_STATUSES[number];
+interface PaymentStatusResponse {
+    id: string;
+    status: PaymentStatus;
+    total: number;
+}
+
+declare const GARMENT_TYPES: readonly ["top", "bottom", "shoes", "accessory", "dress", "outerwear", "bag", "kids"];
+type GarmentType = typeof GARMENT_TYPES[number];
+interface VAZIOutfitItem {
+    listing_id: string;
+    garment_type: GarmentType;
+    price_kes: number;
+    seller_id: string;
+    seller_sti: number;
+    seller_city: string;
+    image_url: string | null;
+    is_seed: boolean;
+    final_score: number;
+}
+interface VAZIOutfit {
+    id: string;
+    name: string;
+    items: VAZIOutfitItem[];
+    total_price_kes: number;
+    sellers_count: number;
+    is_multi_city: boolean;
+    assembled_at: string;
+}
+interface VaziFeedParams {
+    limit?: number;
+    offset?: number;
+}
+interface VaziFeedResponse {
+    outfits: VAZIOutfit[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+interface MitumbaClientConfig {
+    baseUrl: string;
+    debug?: boolean;
+    maxRetries?: number;
+    /**
+     * Optional access token for authenticated requests.
+     */
+    token?: string;
+    /**
+     * Optional refresh token. If provided, the client can automatically refresh
+     * the access token when encountering a 401 response.
+     */
+    refreshToken?: string;
+    /**
+     * Callback invoked when the token is automatically refreshed.
+     * Useful for persisting the new tokens.
+     */
+    onTokenRefresh?: (tokens: {
+        token: string;
+        refreshToken: string;
+    }) => void;
+}
+interface APIErrorResponse {
+    error: string;
+    message?: string;
+    details?: unknown;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    total: number;
+    page: number;
+    page_size: number;
+    has_more: boolean;
+}
+
+interface RequestOptions {
+    signal?: AbortSignal;
+}
+
+declare class APIError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown;
+    constructor(status: number, data: APIErrorResponse);
+}
+declare class APIClient {
+    private config;
+    private isRefreshing;
+    private refreshPromise;
+    constructor(config: MitumbaClientConfig);
+    setToken(token: string, refreshToken?: string): void;
+    clearToken(): void;
+    private request;
+    private handleTokenRefresh;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+
+declare class AuthModule {
+    private readonly client;
+    constructor(client: APIClient);
+    /**
+     * Register a new account.
+     * If using EmailRegisterInput, returns AuthTokens.
+     * If using PhoneRegisterInput, returns MessageResponse (OTP sent).
+     */
+    register(input: RegisterInput, options?: RequestOptions): Promise<AuthTokens | MessageResponse>;
+    /**
+     * Log in to an existing account.
+     * If using EmailLoginInput, returns AuthTokens.
+     * If using PhoneLoginInput, returns MessageResponse (OTP sent).
+     */
+    login(input: LoginInput, options?: RequestOptions): Promise<AuthTokens | MessageResponse>;
+    /**
+     * Send an OTP code to a phone number.
+     */
+    sendOtp(input: SendOtpInput, options?: RequestOptions): Promise<MessageResponse>;
+    /**
+     * Verify an OTP code.
+     */
+    verifyOtp(input: VerifyOtpInput, options?: RequestOptions): Promise<AuthTokens>;
+    /**
+     * Refresh the access token using a refresh token.
+     */
+    refresh(refreshToken: string, options?: RequestOptions): Promise<AuthTokens>;
+    /**
+     * Revoke the refresh token and log out.
+     */
+    logout(refreshToken: string, options?: RequestOptions): Promise<{
+        ok: boolean;
+    }>;
+}
+
+declare class ListingsModule {
+    private readonly client;
+    constructor(client: APIClient);
+    /**
+     * Browse the marketplace feed with optional filters.
+     */
+    getFeed(params?: ListingsFeedParams, options?: RequestOptions): Promise<PaginatedResponse<Listing>>;
+    /**
+     * Get full details of a single listing, including its images.
+     */
+    getById(id: string, options?: RequestOptions): Promise<Listing>;
+    /**
+     * Create a new listing (requires seller role).
+     */
+    create(input: CreateListingInput, options?: RequestOptions): Promise<Listing>;
+    /**
+     * Update an existing listing.
+     */
+    update(id: string, input: UpdateListingInput, options?: RequestOptions): Promise<Listing>;
+    /**
+     * Change the status of a listing.
+     */
+    updateStatus(id: string, status: ListingStatus, options?: RequestOptions): Promise<Listing>;
+    /**
+     * Soft delete a listing (sets status to 'removed').
+     */
+    delete(id: string, options?: RequestOptions): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Get a seller's public storefront.
+     */
+    getSellerStorefront(sellerId: string, params?: {
+        page?: number;
+        page_size?: number;
+    }, options?: RequestOptions): Promise<SellerStorefront>;
+    /**
+     * List all supported categories.
+     */
+    getCategories(options?: RequestOptions): Promise<Category[]>;
+    /**
+     * List all supported cities.
+     */
+    getCities(options?: RequestOptions): Promise<City[]>;
+    /**
+     * Get a presigned upload URL for a listing image.
+     * Index should be between 0 and 9.
+     */
+    presignImage(listingId: string, index: number, options?: RequestOptions): Promise<PresignImageResponse>;
+}
+
+declare class SearchModule {
+    private readonly client;
+    constructor(client: APIClient);
+    /**
+     * Perform a full-text search with optional filters.
+     */
+    search(params: SearchParams, options?: RequestOptions): Promise<PaginatedResponse<SearchResult>>;
+    /**
+     * Get trending search terms.
+     */
+    getTrending(cityId?: string, options?: RequestOptions): Promise<{
+        terms: TrendingTerm[];
+    }>;
+}
+
+declare class OrdersModule {
+    private readonly client;
+    constructor(client: APIClient);
+    /**
+     * Create a new order from a listing.
+     */
+    create(input: CreateOrderInput, options?: RequestOptions): Promise<{
+        order_id: string;
+        total: number;
+        delivery_fee: number;
+    }>;
+    /**
+     * Get full details of an order, including its event timeline.
+     */
+    getById(id: string, options?: RequestOptions): Promise<Order>;
+    /**
+     * Transition the status of an order.
+     */
+    transition(id: string, input: TransitionOrderInput, options?: RequestOptions): Promise<Order>;
+    /**
+     * Get the order history for the current authenticated user.
+     */
+    getHistory(params?: OrderHistoryParams, options?: RequestOptions): Promise<{
+        data: Order[];
+        page: number;
+        page_size: number;
+    }>;
+}
+
+declare class PayModule {
+    private readonly client;
+    constructor(client: APIClient);
+    /**
+     * Initiate an M-Pesa STK Push payment for an order.
+     */
+    initiateStkPush(input: StkPushInput, options?: RequestOptions): Promise<StkPushResponse>;
+    /**
+     * Poll for the current status of a payment by its order ID.
+     */
+    getStatus(orderId: string, options?: RequestOptions): Promise<PaymentStatusResponse>;
+}
+
+declare class VaziModule {
+    private readonly client;
+    constructor(client: APIClient);
+    /**
+     * Browse the AI-curated outfit feed.
+     */
+    getFeed(params?: VaziFeedParams, options?: RequestOptions): Promise<VaziFeedResponse>;
+    /**
+     * Get a complete outfit built around a specific seed listing.
+     */
+    completeOutfit(listingId: string, options?: RequestOptions): Promise<{
+        outfits: VAZIOutfit[];
+    }>;
+}
+
+declare class MitumbaClient {
+    readonly api: APIClient;
+    readonly auth: AuthModule;
+    readonly listings: ListingsModule;
+    readonly search: SearchModule;
+    readonly orders: OrdersModule;
+    readonly pay: PayModule;
+    readonly vazi: VaziModule;
+    constructor(config: MitumbaClientConfig);
+    /**
+     * Set the access token for authenticated requests.
+     * Optionally pass a refresh token to enable automatic token rotation.
+     */
+    setToken(token: string, refreshToken?: string): void;
+    /**
+     * Clear the current tokens.
+     */
+    clearToken(): void;
+}
+
+export { APIClient, APIError, type APIErrorResponse, AuthModule, type AuthTokens, CONDITIONS, type Category, type City, type Condition, type CreateListingInput, type CreateOrderInput, type EmailLoginInput, type EmailRegisterInput, GARMENT_TYPES, type GarmentType, LISTING_STATUSES, type Listing, type ListingImage, type ListingStatus, type ListingsFeedParams, ListingsModule, type LoginInput, type MessageResponse, MitumbaClient, type MitumbaClientConfig, ORDER_STATUSES, type Order, type OrderEvent, type OrderHistoryParams, type OrderStatus, OrdersModule, PAYMENT_STATUSES, type PaginatedResponse, PayModule, type PaymentStatus, type PaymentStatusResponse, type PhoneLoginInput, type PhoneRegisterInput, type PresignImageResponse, type RegisterInput, type RequestOptions, SearchModule, type SearchParams, type SearchResult, type SellerProfile, type SellerStorefront, type SendOtpInput, type StkPushInput, type StkPushResponse, type TransitionOrderInput, type TrendingTerm, type UpdateListingInput, type VAZIOutfit, type VAZIOutfitItem, type VaziFeedParams, type VaziFeedResponse, VaziModule, type VerifyOtpInput };