@mitumba/sdk 0.2.0

package/README.md

@@ -0,0 +1,166 @@
+# @mitumba/sdk
+
+The official isomorphic TypeScript SDK for the Mitumba marketplace platform.
+
+[![CI](https://github.com/Mitumba-Ltd/mitumba-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Mitumba-Ltd/mitumba-sdk/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@mitumba/sdk.svg)](https://www.npmjs.com/package/@mitumba/sdk)
+
+## Features
+
+- **Perfectly Typed**: 100% written in strict TypeScript. Zero `any` types.
+- **Isomorphic**: Runs natively in Node.js, Cloudflare Workers, Next.js, and the Browser using the native `fetch` API.
+- **Zero Dependencies**: Lightweight and extremely fast.
+- **Auto-Token Rotation**: Automatically handles refresh tokens under the hood.
+
+## Installation
+
+```bash
+npm install @mitumba/sdk
+# or
+yarn add @mitumba/sdk
+# or
+pnpm add @mitumba/sdk
+```
+
+## Quick Start
+
+Initialize the client with the environment's base URL:
+
+```typescript
+import { MitumbaClient } from '@mitumba/sdk'
+
+const mitumba = new MitumbaClient({
+  baseUrl: 'https://api.mitumba.stanl.ink'
+})
+```
+
+If you already have a token (e.g. from local storage), pass it to the client:
+
+```typescript
+mitumba.setToken('eyJhbGciOiJIUzI1...', 'my-refresh-token-hex')
+```
+
+## API Overview
+
+The SDK is split into 5 core modules representing the marketplace domains.
+
+### 1. Auth Module (`mitumba.auth`)
+
+Mitumba supports dual-mode authentication: Email + Password, or Phone OTP (SMS). The SDK strongly types both inputs.
+
+```typescript
+// Email Login
+const tokens = await mitumba.auth.login({ 
+  email: 'user@example.com', 
+  password: 'password123' 
+})
+
+// OTP Login
+const { message } = await mitumba.auth.login({ phone: '+254700000000' })
+const tokens = await mitumba.auth.verifyOtp({ phone: '+254700000000', code: '123456' })
+
+// Provide the tokens to the client to authenticate future requests
+mitumba.setToken(tokens.access_token, tokens.refresh_token)
+```
+
+### 2. Listings Module (`mitumba.listings`)
+
+Browse, search, and manage inventory.
+
+```typescript
+// Fetch the marketplace feed with filters
+const feed = await mitumba.listings.getFeed({
+  city_id: 'nbi_01',
+  condition: 'like_new',
+  sort: 'recency'
+})
+
+// Create a new listing (requires seller role)
+const listing = await mitumba.listings.create({
+  title: 'Vintage Denim Jacket',
+  category_id: 'cat_outerwear',
+  city_id: 'nbi_01',
+  price: 2500,
+  condition: 'good'
+})
+```
+
+### 3. Search Module (`mitumba.search`)
+
+AI-powered full-text search.
+
+```typescript
+// Search with ranking
+const results = await mitumba.search.search({
+  q: 'vintage jacket',
+  sort: 'relevance'
+})
+
+// Get trending search terms
+const trending = await mitumba.search.getTrending('nbi_01')
+```
+
+### 4. Orders & Pay Modules (`mitumba.orders`, `mitumba.pay`)
+
+End-to-end checkout and M-Pesa integration.
+
+```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' })
+
+// 3. Poll for payment status
+const status = await mitumba.pay.getStatus(order_id)
+```
+
+### 5. Vazi Module (`mitumba.vazi`)
+
+AI-assembled outfit feeds.
+
+```typescript
+// Browse the curated outfits feed
+const feed = await mitumba.vazi.getFeed({ limit: 10, offset: 0 })
+
+// Get a full outfit built around a specific seed item
+const { outfits } = await mitumba.vazi.completeOutfit('lst_123')
+```
+
+## Error Handling
+
+All API errors are wrapped in a standard `APIError` object.
+
+```typescript
+import { APIError } from '@mitumba/sdk'
+
+try {
+  await mitumba.auth.login({ email: 'bad', password: 'bad' })
+} catch (error) {
+  if (error instanceof APIError) {
+    console.error(error.code)    // e.g. "invalid_credentials"
+    console.error(error.status)  // e.g. 401
+    console.error(error.message) // "Wrong email or password"
+  }
+}
+```
+
+## License
+
+MIT
+
+---
+
+## Contributing & Releasing
+
+We use [Changesets](https://github.com/changesets/changesets) for automated versioning and changelog generation.
+
+When submitting a PR that requires a package version bump, run:
+
+```bash
+npx changeset
+```
+
+Select the appropriate version bump (`patch`, `minor`, `major`) and provide a description of your changes. Commit the generated markdown file along with your PR. 
+
+When your PR is merged, the automated workflow will handle updating the version, aggregating the changelog, and publishing to NPM.

package/dist/index.d.mts

@@ -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 };