BasedOne Core Dart

A Dart SDK for interacting with the BasedOne ecommerce API. This package provides type-safe clients for both customer-facing and merchant-facing operations.

Features

  • CustomerEcommerceClient - Full customer journey support:

    • Product browsing, search, and filtering
    • Shopping cart management
    • Multi-merchant checkout with USDC escrow payments
    • Order tracking and history
    • Reviews and ratings
    • Wishlists
    • Gems (loyalty points) system
    • Flash sales

  • MerchantEcommerceClient - Complete merchant dashboard API:

    • Store profile management
    • Product catalog CRUD with variants
    • Order management and fulfillment
    • Customer management
    • Coupons and discounts
    • Shipping configuration (methods, zones, rates)
    • Returns and refunds processing
    • Review management
    • Customer messaging
    • Media library
    • Promotional banners
    • Analytics and reporting
    • Inventory management with audit logs
    • Tax configuration (rules, nexus, reports)
    • Dropshipping integration

Installation

Add this to your pubspec.yaml:

dependencies:
  basedone_core: ^1.0.0

Then run:

dart pub get

Quick Start

Customer Client

import 'package:basedone_core/basedone_core.dart';

final client = CustomerEcommerceClient(
  baseUrl: 'https://api.basedone.com',
  getAccessToken: () async => authService.getToken(),
);

// Browse products
final products = await client.getProducts(
  params: ListProductsParams(limit: 20, sortBy: ProductSortBy.popular),
);

// Add to cart
await client.addToCart(AddToCartRequest(
  productId: 'prod_123',
  quantity: 1,
));

// Checkout
final checkout = await client.createCheckout(CreateCheckoutRequest(
  shippingAddressId: 'addr_456',
  paymentMethod: PaymentMethod.usdcEscrow,
));

Merchant Client

import 'package:basedone_core/basedone_core.dart';

final client = MerchantEcommerceClient(
  baseUrl: 'https://api.basedone.com',
  getAccessToken: () async => authService.getMerchantToken(),
);

// Get store profile
final profile = await client.getMerchantProfile();

// List orders
final orders = await client.getOrders(
  params: ListOrdersParams(status: OrderStatus.paymentReserved),
);

// Accept an order
await client.acceptOrder('order_789');

// Ship an order
await client.createShipment(CreateShipmentRequest(
  orderId: 'order_789',
  carrier: 'FedEx',
  trackingNumber: '1234567890',
));

Authentication

Both clients require a getAccessToken callback that returns the current user's access token. This is called before each request:

final client = CustomerEcommerceClient(
  baseUrl: 'https://api.basedone.com',
  getAccessToken: () async {
    // Return your JWT or access token
    return await secureStorage.read(key: 'access_token');
  },
);

Error Handling

The SDK uses standard Dart exceptions. Network and API errors are thrown as exceptions:

try {
  await client.getProduct('invalid_id');
} on HttpException catch (e) {
  print('HTTP Error: ${e.message}');
} catch (e) {
  print('Unexpected error: $e');
}

Retry Logic

Both clients include built-in retry logic with exponential backoff for transient failures:

  • Maximum 3 retry attempts
  • Retries on 5xx server errors and network timeouts
  • Exponential backoff: 1s, 2s, 4s delays

Models

The SDK provides comprehensive type-safe models:

Enums

  • OrderStatus - Order lifecycle states
  • PaymentMethod - USDC_ESCROW, BASEDPAY, STRIPE, POINTS
  • PaymentStatus - PENDING, RESERVED, COMPLETED, FAILED, REFUNDED
  • ShipmentStatus - PENDING, SHIPPED, DELIVERED, FAILED
  • ReturnStatus - REQUESTED, APPROVED, REJECTED, etc.
  • DiscountType - PERCENTAGE, FIXED_AMOUNT, BUY_X_GET_Y, FREE_SHIPPING
  • And more...

Entities

  • Product, ProductVariant, ProductImage
  • Order, OrderItem, OrderSummary
  • Cart, CartItem
  • Merchant, MerchantProfile
  • Review, Coupon, Discount
  • Shipment, ShippingZone, ShippingRate
  • And more...

Requirements

  • Dart SDK: >=3.0.0 <4.0.0
  • Dependencies: http, json_annotation

License

MIT License - see LICENSE file for details.

Libraries

basedone_core
BasedOne Core Dart Library