@shopi-lk/storefront-sdk 1.0.0

package/README.md

@@ -0,0 +1,267 @@
+# @shopi-lk/storefront-sdk
+
+Official Shopi.lk Storefront SDK for building custom storefronts across all business types — **Shop**, **Listing**, **Rental**, and **Service**.
+
+## Install
+
+```bash
+npm install @shopi-lk/storefront-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Shopi } from '@shopi-lk/storefront-sdk';
+
+const shopi = new Shopi({
+  apiKey: 'shopi_pk_your_api_key_here',
+});
+
+// Get shop info (includes business_type: "shop" | "listing" | "rental" | "service")
+const info = await shopi.getShop();
+console.log(info.business_type); // e.g. "shop"
+```
+
+## Business Types
+
+### Shop (E-Commerce)
+
+```typescript
+// List products with filtering, sorting & pagination
+const { products, total } = await shopi.products.list({
+  category: 'Electronics',
+  search: 'phone',
+  limit: 12,
+  offset: 0,
+  sort_by: 'created_at',
+  sort_order: 'desc',
+});
+
+// Get a single product by slug
+const product = await shopi.products.getBySlug('iphone-15-pro');
+
+// Get all categories
+const categories = await shopi.categories.list();
+
+// Create an order
+const order = await shopi.checkout.createOrder({
+  customer_name: 'John Doe',
+  customer_email: 'john@example.com',
+  items: [
+    { product_id: 'uuid-here', name: 'iPhone 15 Pro', price: 450000, quantity: 1 },
+  ],
+  payment_method: 'cod',
+});
+
+// Validate a promo code
+const promo = await shopi.checkout.validatePromo({
+  code: 'SAVE10',
+  subtotal: 450000,
+});
+```
+
+### Listing (Showcase / Lead Generation)
+
+For businesses like jewelry, vehicles, or gems — no cart/checkout, focused on inquiries.
+
+```typescript
+// List all visible listings
+const { listings, total } = await shopi.listings.list({
+  category: 'Rings',
+  search: 'diamond',
+  limit: 20,
+  sort_by: 'views_count',
+  sort_order: 'desc',
+});
+
+// Get a single listing by slug
+const listing = await shopi.listings.getBySlug('diamond-engagement-ring');
+console.log(listing.price);              // e.g. 125000
+console.log(listing.availability_status); // e.g. "available"
+console.log(listing.features);           // e.g. ["18K Gold", "0.5ct Diamond"]
+console.log(listing.contact_info);       // e.g. { phone: "+94...", whatsapp: "..." }
+console.log(listing.views_count);        // e.g. 342
+```
+
+### Rental (Vehicle / Equipment Rental)
+
+For businesses that rent items with availability tracking.
+
+```typescript
+// List rental items
+const { rental_items, total } = await shopi.rentalItems.list({
+  category: 'SUV',
+  limit: 10,
+  sort_by: 'daily_rate',
+  sort_order: 'asc',
+});
+
+// Get a single rental item by slug
+const item = await shopi.rentalItems.getBySlug('toyota-land-cruiser');
+console.log(item.daily_rate);           // e.g. 15000
+console.log(item.weekly_rate);          // e.g. 90000
+console.log(item.available_quantity);   // e.g. 3
+console.log(item.deposit_required);     // e.g. true
+console.log(item.deposit_amount);       // e.g. 50000
+console.log(item.pickup_available);     // e.g. true
+console.log(item.delivery_available);   // e.g. true
+console.log(item.delivery_fee);         // e.g. 2500
+```
+
+### Service (Appointments / Bookings)
+
+For businesses offering appointments like salons, mehendi artists, or consultants.
+
+```typescript
+// List services
+const { services, total } = await shopi.services.list({
+  category: 'Bridal',
+  limit: 10,
+  sort_by: 'price',
+  sort_order: 'asc',
+});
+
+// Get a single service by slug
+const service = await shopi.services.getBySlug('bridal-mehendi-package');
+console.log(service.price);               // e.g. 25000
+console.log(service.duration_minutes);     // e.g. 120
+console.log(service.deposit_required);     // e.g. true
+console.log(service.deposit_amount);       // e.g. 5000
+console.log(service.max_bookings_per_slot); // e.g. 1
+```
+
+## Common APIs (All Business Types)
+
+```typescript
+// Store settings (name, logo, shipping, social links)
+const settings = await shopi.getStoreSettings();
+
+// Theme settings (colors, fonts, section layout)
+const theme = await shopi.getThemeSettings();
+
+// Payment methods & bank details
+const { payment_methods, bank_details } = await shopi.getPaymentMethods();
+
+// CMS pages
+const pages = await shopi.pages.list();
+const page = await shopi.pages.getBySlug('about-us');
+
+// Blog posts
+const { posts } = await shopi.blog.list({ limit: 5 });
+const post = await shopi.blog.getBySlug('welcome-to-our-store');
+
+// Product reviews (works for products)
+const reviews = await shopi.reviews.list('product-uuid');
+await shopi.reviews.submit({
+  product_id: 'product-uuid',
+  rating: 5,
+  review_text: 'Amazing quality!',
+  customer_name: 'Jane',
+  customer_email: 'jane@example.com',
+});
+
+// Active discounts
+const { shop_wide, product_specific } = await shopi.getDiscounts();
+```
+
+## API Reference
+
+### `new Shopi(config)`
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `apiKey` | `string` | ✅ | Your Storefront API key (must start with `shopi_pk_`) |
+| `baseUrl` | `string` | ❌ | Override API URL (default: `https://apicall.shopi.lk/v1`) |
+| `timeoutMs` | `number` | ❌ | Request timeout in ms (default: `10000`) |
+
+### Methods
+
+| Method | Scope | Description |
+|--------|-------|-------------|
+| `getShop()` | `shop:read` | Shop info (name, domain, business_type, theme) |
+| `products.list(params?)` | `products:read` | List products with filters & pagination |
+| `products.getBySlug(slug)` | `products:read` | Single product by slug |
+| `categories.list()` | `products:read` | All product categories |
+| `listings.list(params?)` | `listings:read` | List listings with filters & pagination |
+| `listings.getBySlug(slug)` | `listings:read` | Single listing by slug |
+| `rentalItems.list(params?)` | `rentals:read` | List rental items with filters & pagination |
+| `rentalItems.getBySlug(slug)` | `rentals:read` | Single rental item by slug |
+| `services.list(params?)` | `services:read` | List services with filters & pagination |
+| `services.getBySlug(slug)` | `services:read` | Single service by slug |
+| `getStoreSettings()` | `shop:read` | Store config (logo, shipping, social) |
+| `getPaymentMethods()` | `shop:read` | Payment methods + bank details |
+| `pages.list()` | `content:read` | CMS pages |
+| `pages.getBySlug(slug)` | `content:read` | Single CMS page |
+| `blog.list(params?)` | `content:read` | Blog posts (paginated) |
+| `blog.getBySlug(slug)` | `content:read` | Single blog post |
+| `reviews.list(productId)` | `products:read` | Product reviews |
+| `reviews.submit(params)` | `checkout:write` | Submit a review |
+| `getDiscounts()` | `products:read` | Active discounts |
+| `getThemeSettings()` | `shop:read` | Theme colors, fonts, sections |
+| `checkout.createOrder(params)` | `checkout:write` | Place an order |
+| `checkout.validatePromo(params)` | `checkout:write` | Validate promo code |
+
+### List Parameters
+
+All `.list()` methods accept these common parameters:
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `category` | `string` | — | Filter by category name |
+| `search` | `string` | — | Search by name (case-insensitive) |
+| `limit` | `number` | `50` | Results per page (max 100) |
+| `offset` | `number` | `0` | Pagination offset |
+| `sort_by` | `string` | varies | Sort field (see type definitions for allowed values) |
+| `sort_order` | `"asc" \| "desc"` | `"desc"` | Sort direction |
+
+### Rate Limiting
+
+After every request, the current rate-limit state is available:
+
+```typescript
+const { products } = await shopi.products.list();
+console.log(shopi.rateLimit);
+// { limit: 60, remaining: 58, reset: 1720000000 }
+```
+
+## Error Handling
+
+```typescript
+import { Shopi, ShopiError } from '@shopi-lk/storefront-sdk';
+
+try {
+  const listings = await shopi.listings.list();
+} catch (error) {
+  if (error instanceof ShopiError) {
+    console.error(error.message, error.status);
+    // error.status === 401 → invalid API key
+    // error.status === 403 → insufficient scope
+    // error.status === 404 → resource not found
+    // error.status === 408 → request timed out
+    // error.status === 429 → rate limit exceeded
+    // error.status === 0   → network error (offline, DNS failure)
+  }
+}
+```
+
+## Reliability
+
+- **Automatic retries** — transient `5xx` and `429` responses are retried up to 2 times with exponential backoff (300ms, 600ms). For `429`, the SDK honours the `Retry-After` header.
+- **Request timeouts** — every request is cancelled after 10s by default. Override with `timeoutMs`.
+- **Safe JSON parsing** — non-JSON server responses (e.g. HTML gateway errors) throw a typed `ShopiError` instead of a raw `SyntaxError`.
+- **Rate-limit awareness** — inspect `shopi.rateLimit` after any call to monitor your quota.
+
+## Scopes
+
+API keys can be scoped to limit access. Use `*` for full access or combine specific scopes:
+
+| Scope | Access |
+|-------|--------|
+| `*` | Full access (all endpoints) |
+| `shop:read` | Shop info, store settings, payment methods, theme |
+| `products:read` | Products, categories, reviews, discounts |
+| `listings:read` | Listings |
+| `rentals:read` | Rental items |
+| `services:read` | Services |
+| `content:read` | Pages, blog posts |
+| `checkout:write` | Orders, promo validation, review submission |

package/dist/index.d.mts

@@ -0,0 +1,397 @@
+interface ShopiConfig {
+    /** Your Storefront API key (must start with shopi_pk_) */
+    apiKey: string;
+    /** Override the API base URL (default: https://apicall.shopi.lk/v1) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeoutMs?: number;
+}
+interface Shop {
+    id: string;
+    shop_name: string;
+    subdomain: string;
+    custom_domain: string | null;
+    primary_domain: string | null;
+    business_type: string | null;
+    is_active: boolean;
+    active_theme: number | null;
+}
+interface Product {
+    id: string;
+    shop_id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    price: number;
+    compare_at_price: number | null;
+    category: string | null;
+    images: string[];
+    is_visible: boolean;
+    stock_quantity: number | null;
+    track_inventory: boolean;
+    sku: string | null;
+    weight: number | null;
+    variants: ProductVariant[] | null;
+    created_at: string;
+    updated_at: string;
+}
+interface ProductVariant {
+    name: string;
+    options: string[];
+    prices?: Record<string, number>;
+}
+interface ProductListParams {
+    category?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+    sort_by?: "created_at" | "name" | "price" | "sales" | "updated_at";
+    sort_order?: "asc" | "desc";
+}
+interface ProductListResponse {
+    products: Product[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface Category {
+    id: string;
+    name: string;
+    image_url: string | null;
+}
+interface Listing {
+    id: string;
+    shop_id?: string;
+    name: string;
+    slug: string | null;
+    description: string | null;
+    price: number | null;
+    price_label: string | null;
+    currency: string | null;
+    category: string | null;
+    condition: string | null;
+    location: string | null;
+    images: string[] | null;
+    video: string | null;
+    features: string[] | null;
+    specifications: Record<string, any> | null;
+    contact_info: Record<string, any> | null;
+    availability_status: string | null;
+    is_featured: boolean | null;
+    views_count: number | null;
+    inquiries_count: number | null;
+    sort_order: number | null;
+    created_at: string;
+    updated_at: string;
+}
+interface ListingListParams {
+    category?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+    sort_by?: "created_at" | "name" | "price" | "views_count" | "updated_at" | "sort_order";
+    sort_order?: "asc" | "desc";
+}
+interface ListingListResponse {
+    listings: Listing[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface RentalItem {
+    id: string;
+    shop_id?: string;
+    name: string;
+    slug: string | null;
+    description: string | null;
+    category: string | null;
+    condition: string | null;
+    location: string | null;
+    images: string[] | null;
+    video: string | null;
+    specifications: Record<string, any> | null;
+    currency: string | null;
+    hourly_rate: number | null;
+    daily_rate: number | null;
+    weekly_rate: number | null;
+    monthly_rate: number | null;
+    deposit_required: boolean | null;
+    deposit_amount: number | null;
+    min_rental_duration_hours: number | null;
+    max_rental_duration_days: number | null;
+    total_quantity: number | null;
+    available_quantity: number | null;
+    pickup_available: boolean | null;
+    delivery_available: boolean | null;
+    delivery_fee: number | null;
+    is_featured: boolean | null;
+    sort_order: number | null;
+    created_at: string;
+    updated_at: string;
+}
+interface RentalItemListParams {
+    category?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+    sort_by?: "created_at" | "name" | "daily_rate" | "updated_at" | "sort_order";
+    sort_order?: "asc" | "desc";
+}
+interface RentalItemListResponse {
+    rental_items: RentalItem[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface Service {
+    id: string;
+    shop_id?: string;
+    name: string;
+    slug: string | null;
+    description: string | null;
+    price: number;
+    currency: string | null;
+    category: string | null;
+    duration_minutes: number;
+    images: string[] | null;
+    deposit_required: boolean | null;
+    deposit_amount: number | null;
+    max_bookings_per_slot: number | null;
+    buffer_before_minutes: number | null;
+    buffer_after_minutes: number | null;
+    sort_order: number | null;
+    created_at: string;
+    updated_at: string;
+}
+interface ServiceListParams {
+    category?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+    sort_by?: "created_at" | "name" | "price" | "sort_order" | "updated_at";
+    sort_order?: "asc" | "desc";
+}
+interface ServiceListResponse {
+    services: Service[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface StoreSettings {
+    shop_name: string;
+    tagline: string | null;
+    logo_url: string | null;
+    phone_number: string | null;
+    email: string | null;
+    address: string | null;
+    footer_text: string | null;
+    meta_title: string | null;
+    meta_description: string | null;
+    keywords: string | null;
+    business_category: string | null;
+    business_hours: any;
+    location_city: string | null;
+    location_country: string | null;
+    social_links: Record<string, string> | null;
+    shipping_regions: any;
+    is_free_shipping: boolean | null;
+    free_shipping_enabled: boolean | null;
+    free_shipping_threshold: number | null;
+    shipping_currency: string | null;
+    shipping_config: any;
+    international_shipping: any;
+}
+interface PaymentMethod {
+    method_id: string;
+    method_name: string;
+    enabled: boolean;
+}
+interface BankDetail {
+    bank_name: string;
+    branch_name: string | null;
+    account_number: string;
+    account_holder_name: string;
+}
+interface Page {
+    id: string;
+    title: string;
+    slug: string;
+    content: string | null;
+    is_visible: boolean;
+    sort_order: number | null;
+    meta_title: string | null;
+    meta_description: string | null;
+    rendered_html: string | null;
+    rendered_css: string | null;
+}
+interface BlogPost {
+    id: string;
+    title: string;
+    slug: string;
+    content?: string;
+    excerpt: string | null;
+    featured_image: string | null;
+    author_name: string | null;
+    published_at: string | null;
+    tags: string[] | null;
+    meta_title: string | null;
+    meta_description: string | null;
+    rendered_html?: string | null;
+    rendered_css?: string | null;
+}
+interface BlogListParams {
+    limit?: number;
+    offset?: number;
+}
+interface Review {
+    id: string;
+    product_id: string;
+    rating: number;
+    review_text: string | null;
+    image_url: string | null;
+    is_verified_purchase: boolean;
+    created_at: string;
+}
+interface Discount {
+    id: string;
+    name: string;
+    discount_percentage: number;
+    applies_to: string;
+    product_id: string | null;
+    start_date: string;
+    end_date: string;
+}
+interface ThemeSettings {
+    theme_id: number;
+    settings: Record<string, any>;
+    is_published: boolean;
+}
+interface CartItem {
+    product_id: string;
+    name: string;
+    price: number;
+    quantity: number;
+    image?: string;
+    variant?: string;
+}
+interface CreateOrderParams {
+    customer_name: string;
+    customer_email: string;
+    customer_phone?: string;
+    items: CartItem[];
+    shipping_address?: Record<string, any>;
+    shipping_method?: string;
+    payment_method?: string;
+    notes?: string;
+    promo_code_id?: string;
+    discount_amount?: number;
+}
+interface Order {
+    id: string;
+    order_number: string;
+    total: number;
+    status: string;
+    created_at: string;
+}
+interface PromoValidateParams {
+    code: string;
+    cart_items?: CartItem[];
+    subtotal?: number;
+}
+interface PromoValidateResult {
+    valid: boolean;
+    error?: string;
+    promo_code?: {
+        id: string;
+        code: string;
+        discount_type: string;
+        discount_value: number;
+        applies_to: string;
+    };
+    discount_amount?: number;
+    message?: string;
+}
+interface SubmitReviewParams {
+    product_id: string;
+    rating: number;
+    review_text?: string;
+    customer_name?: string;
+    customer_email?: string;
+    image_url?: string;
+}
+
+interface RateLimitState {
+    /** Maximum requests allowed per window */
+    limit: number;
+    /** Requests remaining in the current window */
+    remaining: number;
+    /** Unix timestamp (seconds) when the window resets */
+    reset: number;
+}
+declare class Shopi {
+    private apiKey;
+    private baseUrl;
+    private timeoutMs;
+    /** Populated after every request — reflects the current rate-limit window. */
+    rateLimit: RateLimitState | null;
+    constructor(config: ShopiConfig);
+    private request;
+    getShop(): Promise<Shop>;
+    products: {
+        list: (params?: ProductListParams) => Promise<ProductListResponse>;
+        getBySlug: (slug: string) => Promise<Product>;
+    };
+    categories: {
+        list: () => Promise<Category[]>;
+    };
+    listings: {
+        list: (params?: ListingListParams) => Promise<ListingListResponse>;
+        getBySlug: (slug: string) => Promise<Listing>;
+    };
+    rentalItems: {
+        list: (params?: RentalItemListParams) => Promise<RentalItemListResponse>;
+        getBySlug: (slug: string) => Promise<RentalItem>;
+    };
+    services: {
+        list: (params?: ServiceListParams) => Promise<ServiceListResponse>;
+        getBySlug: (slug: string) => Promise<Service>;
+    };
+    getStoreSettings(): Promise<StoreSettings>;
+    getPaymentMethods(): Promise<{
+        payment_methods: PaymentMethod[];
+        bank_details: BankDetail[];
+    }>;
+    pages: {
+        list: () => Promise<Page[]>;
+        getBySlug: (slug: string) => Promise<Page>;
+    };
+    blog: {
+        list: (params?: BlogListParams) => Promise<{
+            posts: BlogPost[];
+            total: number;
+        }>;
+        getBySlug: (slug: string) => Promise<BlogPost>;
+    };
+    reviews: {
+        list: (productId: string, limit?: number) => Promise<Review[]>;
+        submit: (params: SubmitReviewParams) => Promise<{
+            id: string;
+        }>;
+    };
+    getDiscounts(): Promise<{
+        shop_wide: Discount[];
+        product_specific: Discount[];
+    }>;
+    getThemeSettings(): Promise<ThemeSettings | null>;
+    checkout: {
+        createOrder: (params: CreateOrderParams) => Promise<Order>;
+        validatePromo: (params: PromoValidateParams) => Promise<PromoValidateResult>;
+    };
+}
+declare class ShopiError extends Error {
+    status: number;
+    data: unknown;
+    constructor(message: string, status: number, data?: unknown);
+}
+
+export { type BankDetail, type BlogListParams, type BlogPost, type CartItem, type Category, type CreateOrderParams, type Discount, type Listing, type ListingListParams, type ListingListResponse, type Order, type Page, type PaymentMethod, type Product, type ProductListParams, type ProductListResponse, type ProductVariant, type PromoValidateParams, type PromoValidateResult, type RateLimitState, type RentalItem, type RentalItemListParams, type RentalItemListResponse, type Review, type Service, type ServiceListParams, type ServiceListResponse, type Shop, Shopi, type ShopiConfig, ShopiError, type StoreSettings, type SubmitReviewParams, type ThemeSettings };