@buiducnhat/ritel-sdk

TypeScript SDK for Ritel Mini ERP external APIs.

Installation

npm install @buiducnhat/ritel-sdk
# or
bun add @buiducnhat/ritel-sdk
# or
pnpm add @buiducnhat/ritel-sdk

Quick Start

import { RitelClient } from "@buiducnhat/ritel-sdk";

const client = new RitelClient({
  baseUrl: "https://your-ritel-server.com",
  apiKey: "your-api-key",
});

// List products
const products = await client.products.list({
  limit: 20,
  stockStatus: "in_stock",
});

// Create an order
const order = await client.orders.create({
  customerName: "John Doe",
  customerPhone: "+84901234567",
  items: [{ productId: "prod_123", quantity: 2, unitPrice: 50000 }],
  paymentMethod: "bank_transfer",
});

console.log(order.vietQrUrl); // QR code for payment

API Reference

RitelClient

const client = new RitelClient({
  baseUrl: string;    // Required: API base URL
  apiKey: string;     // Required: Your API key
  timeout?: number;   // Optional: Request timeout in ms (default: 30000)
});

Products

client.products.list(params?)

List products with optional filters.

const response = await client.products.list({
  limit: 20,           // 1-100, default 20
  offset: 0,           // Pagination offset
  search: "shirt",     // Search by name or SKU
  categoryId: "cat_1", // Filter by category
  stockStatus: "in_stock", // "in_stock" | "out_of_stock" | "all"
  minPrice: 10000,     // Min price filter
  maxPrice: 100000,    // Max price filter
  sortBy: "price",     // "name" | "price" | "created_at"
  sortOrder: "asc",    // "asc" | "desc"
});

// Response
{
  data: Product[],
  pagination: { total, limit, offset, hasMore }
}

client.products.get(id)

Get a single product by ID.

const product = await client.products.get("prod_123");

// Product interface
{
  id: string;
  name: string;
  sku: string | null;
  salePrice: number;
  currentSalePrice: number | null;  // Discounted price if applicable
  imageUrl: string | null;
  description: string | null;
  unit: string | null;              // e.g., "pcs", "kg"
  category: { id: string; name: string } | null;
  customProperties: Record<string, unknown> | null;
  stockQuantity: number;
}

Categories

client.categories.list(params?)

List product categories with optional filters.

const response = await client.categories.list({
  limit: 20,        // Pagination limit
  offset: 0,        // Pagination offset
  search: "cloth",  // Search by name
});

// Response
{
  data: Category[],
  pagination: { total, limit, offset, hasMore }
}

// Category interface
{
  id: string;
  name: string;
  slug: string;
  description: string | null;
}

Orders

client.orders.create(input)

Create a new order.

const order = await client.orders.create({
  customerName: "John Doe",
  customerPhone: "+84901234567",
  customerEmail: "[email protected]",  // Optional
  customerAddress: "123 Main St",     // Optional
  items: [
    { productId: "prod_123", quantity: 2, unitPrice: 50000 },
  ],
  paymentMethod: "cash" | "bank_transfer" | "sepay_pg",
  notes: "Gift wrap please",          // Optional
  expectedDeliveryDate: "2024-01-20", // Optional
});

// Response includes vietQrUrl and bankInfo for bank_transfer
{
  id: string;
  orderNumber: string;
  total: number;
  paymentMethod: string;
  paymentStatus: string;
  vietQrUrl: string | null;       // QR code URL for payment
  bankInfo: {                     // Bank details for manual transfer
    bankBin: string | null;
    bankAccountNumber: string | null;
    bankAccountName: string | null;
  } | null;
}

client.orders.list(params?)

List orders with optional filters.

const response = await client.orders.list({
  limit: 20,
  offset: 0,
  status: "pending", // "pending" | "completed" | "cancelled"
  paymentStatus: "pending", // "pending" | "paid" | "failed"
  orderNumber: "ORD-001", // Exact match
});

client.orders.get(id)

Get order by ID.

const order = await client.orders.get("order_abc123");

client.orders.update(id, input)

Update an order.

const order = await client.orders.update("order_abc123", {
  notes: "Updated notes",
  deliveryInfo: {
    name: "Jane Doe",
    phone: "+84909876543",
    address: "456 Other St",
  },
});

client.orders.cancel(id)

Cancel an order.

const order = await client.orders.cancel("order_abc123");

Error Handling

import {
  RitelApiError,
  RitelNetworkError,
  RitelError,
} from "@buiducnhat/ritel-sdk";

try {
  await client.orders.create(input);
} catch (error) {
  if (error instanceof RitelApiError) {
    console.error(`API Error ${error.status}: ${error.message}`);
    // error.status - HTTP status code
    // error.code - Error code from API
    // error.message - Error message
  } else if (error instanceof RitelNetworkError) {
    console.error(`Network Error: ${error.message}`);
  }
}

TypeScript

All types are exported:

import type {
  // Client config
  RitelClientConfig,

  // Products
  Product,
  ProductCategory,
  GetProductsParams,
  ProductsListResponse,

  // Categories
  Category,
  GetCategoriesParams,
  CategoriesListResponse,

  // Orders
  Order,
  OrderItem,
  OrderItemInput,
  CreateOrderInput,
  UpdateOrderInput,
  ListOrdersParams,
  OrderCreateResponse,
  OrdersListResponse,
  DeliveryInfo,

  // Common
  Pagination,
  ApiErrorResponse,
} from "@buiducnhat/ritel-sdk";

// Resource classes (for advanced usage)
import {
  ProductsResource,
  CategoriesResource,
  OrdersResource,
} from "@buiducnhat/ritel-sdk";

License

MIT