@applite/js-sdk 0.0.1 → 0.0.3

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.

package/dist/index.d.mts

@@ -1,3 +1,6 @@
+import { CreateAppWithdraw, CreateAppSchema, CreateAgentSchema, UpdateAgentSchema, CreateAppointmentSchema, UpdateAppointmentStatusSchema, CreateCompanySchema, UpdateCompanySchema, CreateServiceSchema, UpdateServiceSchema } from '@applite/db';
+import { z } from 'zod';
+
 interface HttpClientConfig {
     /**
      * Base URL used for every request. Defaults to an empty string so that
@@ -131,12 +134,9 @@ interface TransactionListParams extends AppScopedParams {
 interface TransactionGetParams extends AppScopedParams {
     id: string;
 }
-interface WithdrawParams extends AppScopedParams {
-    amount: number;
-    phoneNumber: string;
-    password: string;
-    paymentMethod: string;
-}
+type WithdrawParams = z.infer<typeof CreateAppWithdraw> & {
+    appId: string;
+};
 declare class AppFinanceModule {
     private readonly http;
     constructor(http: HttpClient);
@@ -146,11 +146,7 @@ declare class AppFinanceModule {
     withdraw(params: WithdrawParams): Promise<ApiSuccessResponse<unknown>>;
 }
 
-interface CreateAppParams extends ApiKeyParams {
-    name: string;
-    description?: string | null;
-    planId: string;
-}
+type CreateAppParams = z.infer<typeof CreateAppSchema>;
 interface AppSummary {
     id: string;
     name: string;
@@ -165,10 +161,6 @@ interface AppSummary {
     totalOrders: number;
     ownerId: string;
     balance: number;
-    plan: {
-        id: string;
-        name: string;
-    };
 }
 interface AppDetail extends AppSummary {
     callbackUrl?: string | null;
@@ -553,7 +545,6 @@ declare class StoreTaxModule {
     delete(params: GetTaxParams): Promise<ApiSuccessResponse<unknown>>;
 }
 declare class StoreModule {
-    private readonly http;
     readonly badge: StoreBadgeModule;
     readonly category: StoreCategoryModule;
     readonly collection: StoreCollectionModule;
@@ -598,111 +589,109 @@ declare class AppWelcomeItemModule {
     delete(params: WelcomeItemGetParams): Promise<ApiSuccessResponse<unknown>>;
 }
 
-interface ListServicesParams extends AppScopedParams {
-    companyId?: string | null;
-}
-interface ListCompaniesParams extends AppScopedParams {
-}
-interface CreateCompanyParams extends AppScopedParams {
-    name: string;
-    description?: string | null;
-    email?: string | null;
-    telephone?: string | null;
-    address?: string | null;
-    logo?: string | null;
-    logoId?: string | null;
-    isDefault?: boolean;
-}
-interface GetCompanyParams extends AppScopedParams {
+type CreateAgentParams = z.infer<typeof CreateAgentSchema> & {
+    appId: string;
+};
+type EditAgentParams = z.infer<typeof UpdateAgentSchema> & {
+    appId: string;
     id: string;
-}
-interface UpdateCompanyParams extends CreateCompanyParams {
+};
+interface GetAgentParams extends AppScopedParams {
     id: string;
-}
-interface CreateServiceParams extends AppScopedParams {
-    name: string;
-    description?: string | null;
-    icon?: string | null;
-    iconId?: string | null;
-    basePrice?: number | null;
-    categories?: string[];
-    fields?: any[];
     companyId?: string | null;
 }
-interface GetServiceParams extends AppScopedParams {
-    id: string;
+interface ListAgentsParams extends AppScopedParams {
     companyId?: string | null;
+    serviceId?: string;
+    isActive?: boolean;
 }
-interface UpdateServiceParams extends CreateServiceParams {
-    id: string;
-}
-interface CreateAppointmentParams extends AppScopedParams {
-    serviceId: string;
-    agentId?: string | null;
-    userId?: string;
-    filledFields: Record<string, any>;
-    totalPrice: number;
-    date: Date | string;
-    commune: string;
+declare class MultiServiceAgentModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(params: ListAgentsParams): Promise<ApiSuccessResponse<unknown>>;
+    create(params: CreateAgentParams): Promise<ApiSuccessResponse<unknown>>;
+    get(params: GetAgentParams): Promise<ApiSuccessResponse<unknown>>;
+    update(params: EditAgentParams): Promise<ApiSuccessResponse<unknown>>;
+    delete(params: GetAgentParams): Promise<ApiSuccessResponse<unknown>>;
 }
+
+type CreateAppointmentParams = z.infer<typeof CreateAppointmentSchema> & {
+    appId: string;
+};
+type UpdateAppointmentStatusParams = z.infer<typeof UpdateAppointmentStatusSchema> & {
+    appId: string;
+    id: string;
+    companyId?: string | null;
+};
 interface ListAppointmentsParams extends AppScopedParams {
     companyId?: string | null;
     serviceId?: string;
     status?: string;
 }
-interface UpdateAppointmentStatusParams extends AppScopedParams {
+declare class MultiServiceAppointmentModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: CreateAppointmentParams): Promise<ApiSuccessResponse<unknown>>;
+    list(params: ListAppointmentsParams): Promise<ApiSuccessResponse<unknown>>;
+    updateStatus(params: UpdateAppointmentStatusParams): Promise<ApiSuccessResponse<unknown>>;
+}
+
+type CreateCompanyParams = z.infer<typeof CreateCompanySchema> & {
+    appId: string;
+};
+type EditCompanyParams = z.infer<typeof UpdateCompanySchema> & {
+    appId: string;
+    id: string;
+};
+interface GetCompanyParams extends AppScopedParams {
     id: string;
-    status: string;
-    companyId?: string | null;
 }
-interface ListAgentsParams extends AppScopedParams {
-    companyId?: string | null;
-    serviceId?: string;
-    isActive?: boolean;
+interface ListCompaniesParams extends AppScopedParams {
 }
-interface CreateAgentParams extends AppScopedParams {
-    companyId?: string | null;
-    serviceIds?: string[];
-    fullname: string;
-    email?: string | null;
-    telephone?: string | null;
-    bio?: string | null;
-    photo?: string | null;
-    photoId?: string | null;
-    isActive?: boolean;
+declare class MultiServiceCompanyModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(params: ListCompaniesParams): Promise<ApiSuccessResponse<unknown>>;
+    create(params: CreateCompanyParams): Promise<ApiSuccessResponse<unknown>>;
+    get(params: GetCompanyParams): Promise<ApiSuccessResponse<unknown>>;
+    update(params: EditCompanyParams): Promise<ApiSuccessResponse<unknown>>;
+    delete(params: GetCompanyParams): Promise<ApiSuccessResponse<unknown>>;
 }
-interface GetAgentParams extends AppScopedParams {
+
+type CreateServiceParams = z.infer<typeof CreateServiceSchema> & {
+    appId: string;
+};
+type EditServiceParams = z.infer<typeof UpdateServiceSchema> & {
+    appId: string;
+    id: string;
+};
+interface GetServiceParams extends AppScopedParams {
     id: string;
     companyId?: string | null;
 }
-interface UpdateAgentParams extends CreateAgentParams {
-    id: string;
+interface ListServicesParams extends AppScopedParams {
+    companyId?: string | null;
 }
+declare class MultiServiceServiceModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(params: ListServicesParams): Promise<ApiSuccessResponse<unknown>>;
+    create(params: CreateServiceParams): Promise<ApiSuccessResponse<unknown>>;
+    get(params: GetServiceParams): Promise<ApiSuccessResponse<unknown>>;
+    update(params: EditServiceParams): Promise<ApiSuccessResponse<unknown>>;
+    delete(params: GetServiceParams): Promise<ApiSuccessResponse<unknown>>;
+}
+
 declare class MultiServiceModule {
     private readonly http;
+    readonly company: MultiServiceCompanyModule;
+    readonly service: MultiServiceServiceModule;
+    readonly appointment: MultiServiceAppointmentModule;
+    readonly agent: MultiServiceAgentModule;
     constructor(http: HttpClient);
-    listCompanies(params: ListCompaniesParams): Promise<ApiSuccessResponse<unknown>>;
-    createCompany(params: CreateCompanyParams): Promise<ApiSuccessResponse<unknown>>;
-    getCompany(params: GetCompanyParams): Promise<ApiSuccessResponse<unknown>>;
-    updateCompany(params: UpdateCompanyParams): Promise<ApiSuccessResponse<unknown>>;
-    deleteCompany(params: GetCompanyParams): Promise<ApiSuccessResponse<unknown>>;
-    listServices(params: ListServicesParams): Promise<ApiSuccessResponse<unknown>>;
-    createService(params: CreateServiceParams): Promise<ApiSuccessResponse<unknown>>;
-    getService(params: GetServiceParams): Promise<ApiSuccessResponse<unknown>>;
-    updateService(params: UpdateServiceParams): Promise<ApiSuccessResponse<unknown>>;
-    deleteService(params: GetServiceParams): Promise<ApiSuccessResponse<unknown>>;
-    createAppointment(params: CreateAppointmentParams): Promise<ApiSuccessResponse<unknown>>;
-    listAppointments(params: ListAppointmentsParams): Promise<ApiSuccessResponse<unknown>>;
-    updateAppointmentStatus(params: UpdateAppointmentStatusParams): Promise<ApiSuccessResponse<unknown>>;
-    listAgents(params: ListAgentsParams): Promise<ApiSuccessResponse<unknown>>;
-    createAgent(params: CreateAgentParams): Promise<ApiSuccessResponse<unknown>>;
-    getAgent(params: GetAgentParams): Promise<ApiSuccessResponse<unknown>>;
-    updateAgent(params: UpdateAgentParams): Promise<ApiSuccessResponse<unknown>>;
-    deleteAgent(params: GetAgentParams): Promise<ApiSuccessResponse<unknown>>;
 }
 
 declare class AppModule {
-    private readonly http;
     readonly customer: AppCustomerModule;
     readonly stats: AppStatsModule;
     readonly finance: AppFinanceModule;
@@ -721,4 +710,4 @@ declare class AppliteUI {
     constructor(config?: AppliteUIConfig);
 }
 
-export { type ApiErrorResponse, type ApiKeyParams, type ApiResponse, type ApiSuccessResponse, type AppCustomer, type AppCustomerAuthParams, type AppCustomerCheckParams, type AppCustomerDetail, type AppCustomerGetParams, type AppCustomerListFewItem, type AppCustomerListItem, type AppCustomerListParams, AppCustomerModule, type AppCustomerUpdateParams, type AppDetail, AppFinanceModule, AppInfoModule, AppModule, type AppScopedParams, AppStatsModule, type AppSummary, AppWelcomeItemModule, AppliteUI, type AppliteUIConfig, type BalanceParams, type CreateAgentParams, type CreateAppParams, type CreateAppointmentParams, type CreateBadgeParams, type CreateCategoryParams, type CreateCollectionParams, type CreateCompanyParams, type CreateDiscountParams, type CreateOptionParams, type CreateOrderParams, type CreateProductParams, type CreateSellerParams, type CreateServiceParams, type CreateShippingProfileParams, type CreateStatisticParams, type CreateTagParams, type CreateTaxParams, type CreateWelcomeItemParams, type DeleteBadgeParams, type EditBadgeParams, type EditCategoryParams, type EditCollectionParams, type EditDiscountParams, type EditOptionParams, type EditOrderParams, type EditProductParams, type EditSellerParams, type EditShippingProfileParams, type EditTagParams, type EditTaxParams, type EditWelcomeItemParams, type GetAgentParams, type GetAppBySlugParams, type GetCategoryParams, type GetCollectionParams, type GetCompanyParams, type GetDiscountParams, type GetOptionParams, type GetOrderParams, type GetProductParams, type GetSellerParams, type GetServiceParams, type GetShippingProfileParams, type GetStatisticParams, type GetTagParams, type GetTaxParams, HttpClient, type HttpClientConfig, type ListAgentsParams, type ListAppointmentsParams, type ListCompaniesParams, type ListServicesParams, MultiServiceModule, type PlateformType, type Sexe, StoreBadgeModule, StoreCategoryModule, StoreCollectionModule, StoreDiscountModule, StoreModule, StoreOptionModule, StoreOrderModule, StoreProductModule, StoreSellerModule, StoreShippingModule, StoreTagModule, StoreTaxModule, type TransactionGetParams, type TransactionListParams, type UpdateAgentParams, type UpdateAppointmentStatusParams, type UpdateCompanyParams, type UpdateServiceParams, type UpdateStatisticParams, type WelcomeItemGetParams, type WelcomeItemParams, type WithdrawParams, plateformTypes, sexes };
+export { type ApiErrorResponse, type ApiKeyParams, type ApiResponse, type ApiSuccessResponse, type AppCustomer, type AppCustomerAuthParams, type AppCustomerCheckParams, type AppCustomerDetail, type AppCustomerGetParams, type AppCustomerListFewItem, type AppCustomerListItem, type AppCustomerListParams, AppCustomerModule, type AppCustomerUpdateParams, type AppDetail, AppFinanceModule, AppInfoModule, AppModule, type AppScopedParams, AppStatsModule, type AppSummary, AppWelcomeItemModule, AppliteUI, type AppliteUIConfig, type BalanceParams, type CreateAgentParams, type CreateAppParams, type CreateAppointmentParams, type CreateBadgeParams, type CreateCategoryParams, type CreateCollectionParams, type CreateCompanyParams, type CreateDiscountParams, type CreateOptionParams, type CreateOrderParams, type CreateProductParams, type CreateSellerParams, type CreateServiceParams, type CreateShippingProfileParams, type CreateStatisticParams, type CreateTagParams, type CreateTaxParams, type CreateWelcomeItemParams, type DeleteBadgeParams, type EditAgentParams, type EditBadgeParams, type EditCategoryParams, type EditCollectionParams, type EditCompanyParams, type EditDiscountParams, type EditOptionParams, type EditOrderParams, type EditProductParams, type EditSellerParams, type EditServiceParams, type EditShippingProfileParams, type EditTagParams, type EditTaxParams, type EditWelcomeItemParams, type GetAgentParams, type GetAppBySlugParams, type GetCategoryParams, type GetCollectionParams, type GetCompanyParams, type GetDiscountParams, type GetOptionParams, type GetOrderParams, type GetProductParams, type GetSellerParams, type GetServiceParams, type GetShippingProfileParams, type GetStatisticParams, type GetTagParams, type GetTaxParams, HttpClient, type HttpClientConfig, type ListAgentsParams, type ListAppointmentsParams, type ListCompaniesParams, type ListServicesParams, MultiServiceAgentModule, MultiServiceAppointmentModule, MultiServiceCompanyModule, MultiServiceModule, MultiServiceServiceModule, type PlateformType, type Sexe, StoreBadgeModule, StoreCategoryModule, StoreCollectionModule, StoreDiscountModule, StoreModule, StoreOptionModule, StoreOrderModule, StoreProductModule, StoreSellerModule, StoreShippingModule, StoreTagModule, StoreTaxModule, type TransactionGetParams, type TransactionListParams, type UpdateAppointmentStatusParams, type UpdateStatisticParams, type WelcomeItemGetParams, type WelcomeItemParams, type WithdrawParams, plateformTypes, sexes };