@applite/js-sdk 0.0.2 → 0.0.4

package/README.md

@@ -1,137 +1,254 @@
 # @applite/js-sdk
 
-A lightweight JavaScript SDK for interacting with Applite UI customer APIs.
+A comprehensive JavaScript/TypeScript SDK for interacting with the Applite Customer API. This library provides a structured, typed interface to manage application data, e-commerce operations, and service bookings.
+
+> **Full Documentation**: For detailed API references and guides, visit [docs.appliteui.com/sdk](https://docs.appliteui.com/sdk).
 
 ## Installation
 
 ```bash
 pnpm add @applite/js-sdk
+# or
+npm install @applite/js-sdk
+# or
+yarn add @applite/js-sdk
 ```
 
-## Usage
-
-Each method accepts a **single object** that always includes `appId` and `apiKey`, plus fields required by the specific route.
+## Quick Start
 
-### Instantiate the client
+Initialize the client with your API base URL (optional if using relative paths in a same-origin environment).
 
 ```ts
 import { AppliteUI } from "@applite/js-sdk";
 
 const client = new AppliteUI({
-  baseUrl: "https://api.example.com", // optional, defaults to relative paths
+  baseUrl: "https://api.applite.com", // Optional: Defaults to relative path
 });
 ```
 
-### List customers
+## Core Concepts
+
+### Authentication & Context
+
+Every request requires two key parameters to identify the context and authorize the user:
+
+- **`appId`**: The unique identifier of your application (e.g., used in URL paths).
+- **`apiKey`**: The secret key used to authenticate requests.
+
+### Method Signature
+
+All SDK methods accept a **single object** containing all parameters. This ensures better type safety and extensibility.
 
 ```ts
-await client.app.customer.list({
-  appId: "app_123", // required for the URL path
-  apiKey: "api_key_abc", // required for verification
-  plateformType: ["STORE", "TRANSPORT"], // optional filter
+// Example signature
+await client.module.resource.action({
+  appId: "...",
+  apiKey: "...",
+  ...specificParams,
 });
 ```
 
-### List a few recent customers
+## Architecture
+
+The SDK is organized into three main modules:
+
+1.  **App Module (`client.app`)**: Core application logic (Customers, Stats, Finance).
+2.  **Store Module (`client.app.store`)**: E-commerce functionality (Products, Orders, Sellers).
+3.  **Multi-Service Module (`client.app.multiService`)**: Service booking and appointments.
+
+---
+
+## App Management (`client.app`)
+
+Manage your application's users and core settings.
+
+### Customers
+
+Manage end-users of your application.
+
+#### Authenticate / Register a Customer
+
+Checks if a user exists; if not, creates a new one.
 
 ```ts
-await client.app.customer.listFew({
+const user = await client.app.customer.auth({
   appId: "app_123",
-  apiKey: "api_key_abc",
-  plateformType: ["STORE"],
+  apiKey: "your_api_key",
+  fullname: "John Doe",
+  telephone: "+2250700000000",
+  email: "john@example.com", // Optional
+  plateform: "STORE", // Optional: "STORE", "MULTI_SERVICE", etc.
 });
 ```
 
-### Authenticate or register a customer
+#### Check Customer Existence
+
+Verify if a phone number is already registered.
 
 ```ts
-await client.app.customer.auth({
+const user = await client.app.customer.check({
   appId: "app_123",
-  apiKey: "api_key_abc",
-  fullname: "Ada Lovelace",
+  apiKey: "your_api_key",
   telephone: "+2250700000000",
-  email: "ada@example.com", // optional
-  plateform: "STORE", // optional
 });
 ```
 
-### Check if a customer exists
+#### List Customers
+
+Retrieve a list of customers with optional filtering.
 
 ```ts
-await client.app.customer.check({
+const customers = await client.app.customer.list({
   appId: "app_123",
-  apiKey: "api_key_abc",
-  telephone: "+2250700000000",
-  plateform: "STORE", // optional
+  apiKey: "your_api_key",
+  plateformType: ["STORE"], // Optional filter
 });
 ```
 
-### Get a customer by id
+#### Get & Update Customer
+
+Retrieve details or update profile information.
 
 ```ts
-await client.app.customer.get({
+// Get details
+const detail = await client.app.customer.get({
+  appId: "app_123",
+  apiKey: "your_api_key",
+  id: "customer_id",
+});
+
+// Update profile
+await client.app.customer.update({
   appId: "app_123",
-  apiKey: "api_key_abc",
-  id: "customer_456",
+  apiKey: "your_api_key",
+  id: "customer_id",
+  fullname: "Jane Doe",
+  email: "jane@example.com",
 });
 ```
 
-### Update a customer profile
+### Other App Resources
+
+- **Stats**: `client.app.stats.create(...)`
+- **Finance**: `client.app.finance.balance(...)`
+- **Info**: `client.app.info.list(...)`
+
+---
+
+## E-Commerce (`client.app.store`)
+
+Full-featured e-commerce management.
+
+### Products
+
+Create and manage products.
 
 ```ts
-await client.app.customer.update({
+// Create a product
+await client.app.store.product.create({
+  appId: "app_123",
+  apiKey: "your_api_key",
+  name: "Premium T-Shirt",
+  price: 2500,
+  sellerId: "seller_123",
+  categoryId: "category_123",
+  variants: [], // Array of product variants
+});
+
+// List products
+await client.app.store.product.list({
   appId: "app_123",
-  apiKey: "api_key_abc",
-  id: "customer_456",
-  fullname: "New Name", // optional
-  email: "new-email@example.com", // optional
-  photoUrl: "https://cdn.example.com/avatar.png", // optional
-  gender: "F", // optional, "M" | "F"
-  dob: "1990-01-01", // optional
-  country: "CI", // optional
+  apiKey: "your_api_key",
 });
 ```
 
-### Work with other app modules
+### Orders
 
-Additional helpers map to the remaining API routes using the same single-object parameter style:
+Handle customer orders.
 
 ```ts
-// List all apps for the authenticated user
-await client.app.info.list({ apiKey: "api_key_abc" });
-
-// Create a product inside the store module
-await client.app.store.product.create({
+// Create an order
+await client.app.store.order.create({
   appId: "app_123",
-  apiKey: "api_key_abc",
-  name: "T-shirt",
-  sellerId: "seller_1",
-  categoryId: "cat_1",
-  variants: [{ price: 20, quantity: 5, images: [], valueIds: [] }],
+  apiKey: "your_api_key",
+  items: [
+    { productId: "prod_1", quantity: 2 }
+  ],
+  customerId: "cust_1",
+  totalAmount: 5000,
+  shippingAddress: { ... }
 });
 
-// Record statistics or query balances
-await client.app.stats.create({
+// List orders
+await client.app.store.order.list({
   appId: "app_123",
-  apiKey: "api_key_abc",
-  type: "ORDERS",
-  year: 2024,
-  month: "JANUARY",
-  amount: 10,
+  apiKey: "your_api_key",
 });
+```
+
+### Available Store Modules
+
+- `badge`
+- `category`
+- `collection`
+- `discount`
+- `option`
+- `seller`
+- `shipping`
+- `tag`
+- `tax`
+
+---
+
+## Multi-Service (`client.app.multiService`)
 
-await client.app.finance.balance({ appId: "app_123", apiKey: "api_key_abc" });
+Booking system for service-based applications.
 
-// Manage welcome screen items
-await client.app.welcomeItem.create({
+### Appointments
+
+Manage bookings between customers and agents/companies.
+
+```ts
+// Create an appointment
+await client.app.multiService.appointment.create({
   appId: "app_123",
-  apiKey: "api_key_abc",
-  fileUrl: "https://cdn.example.com/banner.png",
-  plateformType: "STORE",
+  apiKey: "your_api_key",
+  serviceId: "srv_123",
+  customerId: "cust_123",
+  date: "2024-12-25T10:00:00Z",
+  status: "PENDING",
 });
+
+// Update status
+await client.app.multiService.appointment.updateStatus({
+  appId: "app_123",
+  apiKey: "your_api_key",
+  id: "apt_123",
+  status: "CONFIRMED",
+});
+```
+
+### Available Service Modules
+
+- `company`: Manage service providers.
+- `service`: Define services offered.
+- `agent`: Manage individual staff members.
+
+---
+
+## TypeScript Support
+
+The SDK is written in TypeScript and ships with full type definitions. You can import types directly to type your application logic.
+
+```ts
+import {
+  AppCustomer,
+  CreateProductParams,
+  AppCustomerAuthParams,
+} from "@applite/js-sdk";
 ```
 
 ## Scripts
 
-- `pnpm build` – build CJS/ESM bundles with type declarations.
-- `pnpm test` – run the build with declaration output to validate types.
+- `pnpm build`: Build the SDK (ESM/CJS).
+- `pnpm test`: Run type checks.