basedone_core 1.0.5

Dart SDK for BasedOne API - Provides API and utilities for building applications on BasedOne.

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.