@classytic/commerce-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) Classytic. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Classytic. No part of the Software
+may be used, copied, modified, merged, published, distributed, sublicensed,
+or sold without prior written permission from Classytic.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @classytic/commerce-sdk
+
+Modular API client and React hooks for the Classytic commerce platform.
+
+## Installation
+
+```bash
+npm install @classytic/commerce-sdk
+```
+
+## Requirements
+
+- React 19+
+- Optional: Next.js 14+ for app/router usage
+- Optional: @tanstack/react-query 5+ for hooks
+
+## Quick Start
+
+```typescript
+import { initCommerceSDK } from '@classytic/commerce-sdk';
+
+// Initialize once at app startup
+initCommerceSDK({ baseUrl: process.env.NEXT_PUBLIC_API_URL! });
+```
+
+## Modules
+
+Import what you need from domain-specific modules:
+
+```typescript
+// Catalog (products, categories, size guides)
+import { productApi, useProducts, useProductDetail } from '@classytic/commerce-sdk/catalog';
+
+// Sales (orders, customers, cart, POS, transactions)
+import { orderApi, useOrders, useCart } from '@classytic/commerce-sdk/sales';
+
+// Inventory (stock, purchases, transfers, suppliers)
+import { stockApi, useInventory, useTransfers } from '@classytic/commerce-sdk/inventory';
+
+// Platform (branches, users, coupons, config)
+import { branchApi, useBranches, usePlatformConfig } from '@classytic/commerce-sdk/platform';
+
+// Auth (login, register, password reset)
+import { loginApi, UserRole, verifyManagerAuth } from '@classytic/commerce-sdk/auth';
+
+// Finance, Logistics, Content, Payments, Analytics
+import { useFinanceSummary } from '@classytic/commerce-sdk/finance';
+import { useDeliveryCharge } from '@classytic/commerce-sdk/logistics';
+import { mediaApi, useCMSPage } from '@classytic/commerce-sdk/content';
+import { usePaymentActions } from '@classytic/commerce-sdk/payments';
+import { useAnalyticsDashboard } from '@classytic/commerce-sdk/analytics';
+```
+
+## Usage Patterns
+
+### Server Components / API Routes
+
+```typescript
+import { productApi } from '@classytic/commerce-sdk/catalog';
+
+// Fetch data server-side
+const products = await productApi.getAll({ params: { page: 1 } });
+const product = await productApi.getBySlug({ slug: 'my-product' });
+```
+
+### Client Components (React Query hooks)
+
+```typescript
+import { useProducts, useProductActions } from '@classytic/commerce-sdk/catalog';
+
+function ProductList({ token }) {
+  const { items, isLoading } = useProducts(token, { page: 1 });
+  const { create, update, remove } = useProductActions(token);
+
+  // ...
+}
+```
+
+### Core Utilities
+
+```typescript
+import { handleApiRequest, BaseApi } from '@classytic/commerce-sdk/core';
+
+// Make custom API calls
+const data = await handleApiRequest('POST', '/api/v1/custom', {
+  token,
+  body: { ... }
+});
+```
+
+## Types
+
+All types are co-located with their modules:
+
+```typescript
+import type { Product, Category } from '@classytic/commerce-sdk/catalog';
+import type { Order, Customer } from '@classytic/commerce-sdk/sales';
+import type { StockEntry, Transfer } from '@classytic/commerce-sdk/inventory';
+import type { User, UserRoleType } from '@classytic/commerce-sdk/auth';
+```
+
+## License
+
+Proprietary - see `LICENSE`

package/dist/adjustment-DTSLM7AN.js

@@ -0,0 +1,5 @@
+export { AdjustmentApi, adjustmentApi } from './chunk-R5Z7NYLH.js';
+import './chunk-I5TIKUIQ.js';
+import './chunk-VR36QVX2.js';
+//# sourceMappingURL=adjustment-DTSLM7AN.js.map
+//# sourceMappingURL=adjustment-DTSLM7AN.js.map

package/dist/adjustment-DTSLM7AN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"adjustment-DTSLM7AN.js"}

package/dist/analytics/index.d.ts

@@ -0,0 +1,27 @@
+import { g as AnalyticsDashboardParams, f as AnalyticsDashboard } from '../analytics-DMcD-o8w.js';
+export { A as AnalyticsApi, b as AnalyticsPeriod, c as AnalyticsSummary, d as AnalyticsTrend, e as TopCategory, T as TopProduct, a as analyticsApi } from '../analytics-DMcD-o8w.js';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import '../api-factory-B_h4RKBm.js';
+
+declare const ANALYTICS_KEYS: {
+    all: readonly ["analytics"];
+    dashboard: (period?: string) => readonly ["analytics", "dashboard", string | undefined];
+};
+/**
+ * Hook to fetch dashboard analytics data
+ *
+ * @param token - Auth token (required)
+ * @param params.period - Time period: '7d' | '30d' | '90d' | '1y' (default: '30d')
+ * @param params.branchId - Optional branch filter
+ * @param options.enabled - Enable/disable query (default: true)
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading } = useAnalyticsDashboard(token, { period: '30d' });
+ * ```
+ */
+declare function useAnalyticsDashboard(token: string, params?: AnalyticsDashboardParams, options?: {
+    enabled?: boolean;
+}): _tanstack_react_query.UseQueryResult<AnalyticsDashboard, Error>;
+
+export { ANALYTICS_KEYS, AnalyticsDashboard, AnalyticsDashboardParams, useAnalyticsDashboard };

package/dist/analytics/index.js

@@ -0,0 +1,6 @@
+"use client";
+export { ANALYTICS_KEYS, useAnalyticsDashboard } from '../chunk-EPQN7ZKZ.js';
+export { AnalyticsApi, analyticsApi } from '../chunk-4ZQK3FFN.js';
+import '../chunk-VR36QVX2.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/analytics-DMcD-o8w.d.ts

@@ -0,0 +1,76 @@
+import { R as RequestOptions, A as ApiResponse } from './api-factory-B_h4RKBm.js';
+
+/**
+ * Analytics Types
+ */
+interface AnalyticsPeriod {
+    period: "7d" | "30d" | "90d" | "1y";
+}
+interface AnalyticsSummary {
+    totalRevenue: number;
+    totalOrders: number;
+    averageOrderValue: number;
+    conversionRate?: number;
+}
+interface AnalyticsTrend {
+    date: string;
+    revenue: number;
+    orders: number;
+}
+interface TopProduct {
+    productId: string;
+    name: string;
+    quantity: number;
+    revenue: number;
+}
+interface TopCategory {
+    categoryId: string;
+    name: string;
+    quantity: number;
+    revenue: number;
+}
+interface AnalyticsDashboard {
+    summary: AnalyticsSummary;
+    trends?: AnalyticsTrend[];
+    topProducts?: TopProduct[];
+    topCategories?: TopCategory[];
+    period: string;
+    startDate: string;
+    endDate: string;
+}
+interface AnalyticsDashboardParams {
+    period?: "7d" | "30d" | "90d" | "1y";
+    branchId?: string;
+}
+
+/**
+ * Analytics API - Dashboard and reporting
+ *
+ * Endpoints:
+ * - getDashboard({ token, params }) - Get dashboard analytics
+ *
+ * Roles:
+ * - admin, superadmin, finance-admin, finance-manager
+ */
+
+type FetchOptions = Omit<RequestOptions, "token" | "organizationId">;
+declare class AnalyticsApi {
+    private baseUrl;
+    constructor();
+    /**
+     * Get dashboard analytics
+     * GET /analytics/dashboard
+     *
+     * @param token - Auth token (required)
+     * @param params.period - Time period: '7d', '30d', '90d', '1y' (default: '30d')
+     * @param params.branchId - Optional branch filter
+     */
+    getDashboard({ token, params, options, }: {
+        token: string;
+        params?: AnalyticsDashboardParams;
+        options?: FetchOptions;
+    }): Promise<ApiResponse<AnalyticsDashboard>>;
+}
+declare const analyticsApi: AnalyticsApi;
+
+export { AnalyticsApi as A, type TopProduct as T, analyticsApi as a, type AnalyticsPeriod as b, type AnalyticsSummary as c, type AnalyticsTrend as d, type TopCategory as e, type AnalyticsDashboard as f, type AnalyticsDashboardParams as g };

package/dist/api-factory-B_h4RKBm.d.ts

@@ -0,0 +1,280 @@
+/**
+ * @classytic/commerce-sdk - API Factory
+ *
+ * Base API class that provides standardized CRUD operations.
+ * Supports direct field queries and bracket syntax: field[operator]=value
+ */
+/**
+ * Base API response wrapper
+ * All endpoints return { success: boolean, ... }
+ */
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    message?: string;
+}
+/**
+ * Offset pagination response (page-based)
+ * Used when: ?page=1&limit=10
+ */
+interface OffsetPaginationResponse<T = unknown> {
+    success: boolean;
+    method: "offset";
+    docs: T[];
+    page: number;
+    limit: number;
+    total: number;
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+    warning?: string;
+}
+/**
+ * Keyset pagination response (cursor-based)
+ * Used when: ?after=cursor&limit=10
+ */
+interface KeysetPaginationResponse<T = unknown> {
+    success: boolean;
+    method: "keyset";
+    docs: T[];
+    limit: number;
+    hasMore: boolean;
+    next: string | null;
+}
+/**
+ * Aggregate pagination response
+ * Used for complex aggregation queries
+ */
+interface AggregatePaginationResponse<T = unknown> {
+    success: boolean;
+    method: "aggregate";
+    docs: T[];
+    page: number;
+    limit: number;
+    total: number;
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+    warning?: string;
+}
+/**
+ * Union type for all paginated responses
+ */
+type PaginatedResponse<T = unknown> = OffsetPaginationResponse<T> | KeysetPaginationResponse<T> | AggregatePaginationResponse<T>;
+/**
+ * Delete operation response
+ * Supports both soft delete (default) and hard delete
+ */
+interface DeleteResponse {
+    success: boolean;
+    deleted: boolean;
+    /** ID of the deleted record */
+    id?: string;
+    /** @deprecated Use `id` instead */
+    productId?: string;
+    /** True if soft delete was performed (default behavior) */
+    soft?: boolean;
+    /** Legacy message field */
+    message?: string;
+    /** Number of records deleted (for bulk operations) */
+    count?: number;
+}
+/**
+ * Sort direction
+ */
+type SortDirection = 1 | -1 | "asc" | "desc";
+/**
+ * Sort specification
+ */
+type SortSpec = Record<string, SortDirection> | string;
+/**
+ * Filter operators supported by query parser
+ * Usage: ?field[operator]=value
+ */
+type FilterOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "contains" | "startsWith" | "endsWith" | "regex";
+/**
+ * Query parameters for list/search operations
+ */
+interface QueryParams {
+    page?: number;
+    limit?: number;
+    after?: string;
+    sort?: SortSpec;
+    [key: string]: unknown;
+}
+/**
+ * Request options
+ */
+interface RequestOptions {
+    token?: string | null;
+    organizationId?: string | null;
+    cache?: RequestCache;
+    revalidate?: number;
+    tags?: string[];
+    headerOptions?: Record<string, string>;
+    responseType?: "json" | "blob" | "text";
+}
+interface BaseApiConfig {
+    basePath?: string;
+    defaultParams?: {
+        limit?: number;
+        page?: number;
+        [key: string]: unknown;
+    };
+    cache?: RequestCache;
+    headers?: Record<string, string>;
+}
+/**
+ * Base API class that provides standardized CRUD operations
+ * Supports direct field queries and bracket syntax: field[operator]=value
+ *
+ * @template TDoc - Document type returned by the API
+ * @template TCreate - Type for create payload (defaults to Partial<TDoc>)
+ * @template TUpdate - Type for update payload (defaults to Partial<TDoc>)
+ */
+declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
+    readonly entity: string;
+    readonly config: Required<BaseApiConfig>;
+    readonly baseUrl: string;
+    constructor(entity: string, config?: BaseApiConfig);
+    /**
+     * Creates query string from parameters
+     * Delegates to shared utility from api-handler.ts
+     */
+    createQueryString(params?: Record<string, unknown>): string;
+    /**
+     * Prepares parameters for API request
+     * Handles pagination, sorting, and filters
+     * Note: Critical security filters (organizationId, ownerId) are ALWAYS sent, even if null
+     */
+    prepareParams(params?: QueryParams): Record<string, unknown>;
+    /**
+     * Get all records with pagination and filtering
+     * Returns offset or keyset pagination based on params
+     */
+    getAll({ token, organizationId, params, options, }?: {
+        token?: string | null;
+        organizationId?: string | null;
+        params?: QueryParams;
+        options?: Omit<RequestOptions, "token" | "organizationId">;
+    }): Promise<PaginatedResponse<TDoc>>;
+    /**
+     * Get a single record by ID
+     */
+    getById({ token, organizationId, id, params, options, }: {
+        token?: string | null;
+        organizationId?: string | null;
+        id: string;
+        params?: {
+            select?: string;
+            populate?: string | string[];
+        };
+        options?: Omit<RequestOptions, "token" | "organizationId">;
+    }): Promise<ApiResponse<TDoc>>;
+    /**
+     * Create a new record
+     */
+    create({ token, organizationId, data, options, }: {
+        token: string;
+        organizationId?: string | null;
+        data: TCreate;
+        options?: Omit<RequestOptions, "token" | "organizationId">;
+    }): Promise<ApiResponse<TDoc>>;
+    /**
+     * Update an existing record
+     */
+    update({ token, organizationId, id, data, options, }: {
+        token: string;
+        organizationId?: string | null;
+        id: string;
+        data: TUpdate;
+        options?: Omit<RequestOptions, "token" | "organizationId">;
+    }): Promise<ApiResponse<TDoc>>;
+    /**
+     * Delete a record
+     */
+    delete({ token, organizationId, id, options, }: {
+        token: string;
+        organizationId?: string | null;
+        id: string;
+        options?: Omit<RequestOptions, "token" | "organizationId">;
+    }): Promise<DeleteResponse>;
+    /**
+     * Search with custom parameters
+     * @example
+     * search({ searchParams: { 'brand[contains]': 'nike' } })
+     * search({ searchParams: { upc: '123456789' } })
+     */
+    search({ token, organizationId, searchParams, params, options, }?: {
+        token?: string | null;
+        organizationId?: string | null;
+        searchParams?: Record<string, unknown>;
+        params?: QueryParams;
+        options?: Omit<RequestOptions, "token" | "organizationId">;
+    }): Promise<PaginatedResponse<TDoc>>;
+    /**
+     * Find records by field with optional operator
+     * @example
+     * findBy({ field: 'brand', value: 'nike', operator: 'contains' })
+     * findBy({ field: 'status', value: ['active', 'pending'], operator: 'in' })
+     */
+    findBy({ token, organizationId, field, value, operator, params, options, }: {
+        token?: string | null;
+        organizationId?: string | null;
+        field: string;
+        value: unknown;
+        operator?: FilterOperator;
+        params?: QueryParams;
+        options?: Omit<RequestOptions, "token" | "organizationId">;
+    }): Promise<PaginatedResponse<TDoc>>;
+    /**
+     * Make a custom API request to a sub-endpoint
+     * @example
+     * request('POST', `${this.baseUrl}/${id}/action`, { token, data: { ... } })
+     */
+    request<TResponse = unknown>(method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", endpoint: string, { token, organizationId, data, params, options, }?: {
+        token?: string;
+        organizationId?: string | null;
+        data?: unknown;
+        params?: QueryParams;
+        options?: Omit<RequestOptions, "token" | "organizationId">;
+    }): Promise<TResponse>;
+}
+/**
+ * Factory function to create a typed BaseApi instance
+ *
+ * @template TDoc - Document type returned by the API
+ * @template TCreate - Type for create payload
+ * @template TUpdate - Type for update payload
+ *
+ * @example
+ * // Simple usage
+ * const productApi = createCrudApi('products');
+ *
+ * // With types
+ * interface Product { _id: string; name: string; price: number; }
+ * interface CreateProduct { name: string; price: number; }
+ * const productApi = createCrudApi<Product, CreateProduct>('products');
+ *
+ * // With custom config
+ * const productApi = createCrudApi('products', { basePath: '/api/v2' });
+ */
+declare function createCrudApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>>(entity: string, config?: BaseApiConfig): BaseApi<TDoc, TCreate, TUpdate>;
+/**
+ * Extract document type from paginated response
+ */
+type ExtractDoc<T> = T extends PaginatedResponse<infer D> ? D : never;
+/**
+ * Helper to check if response is offset pagination
+ */
+declare function isOffsetPagination<T>(response: PaginatedResponse<T>): response is OffsetPaginationResponse<T>;
+/**
+ * Helper to check if response is keyset pagination
+ */
+declare function isKeysetPagination<T>(response: PaginatedResponse<T>): response is KeysetPaginationResponse<T>;
+/**
+ * Helper to check if response is aggregate pagination
+ */
+declare function isAggregatePagination<T>(response: PaginatedResponse<T>): response is AggregatePaginationResponse<T>;
+
+export { type ApiResponse as A, BaseApi as B, type DeleteResponse as D, type ExtractDoc as E, type FilterOperator as F, type KeysetPaginationResponse as K, type OffsetPaginationResponse as O, type PaginatedResponse as P, type QueryParams as Q, type RequestOptions as R, type SortDirection as S, isKeysetPagination as a, isAggregatePagination as b, createCrudApi as c, type AggregatePaginationResponse as d, type SortSpec as e, type BaseApiConfig as f, isOffsetPagination as i };

package/dist/auth/index.d.ts

@@ -0,0 +1,39 @@
+import { i as User } from '../user-data-DdLjAGwO.js';
+export { j as AuthApiResponse, A as AuthResponse, D as DISCOUNT_ALLOWED_ROLES, F as ForgotPasswordData, L as LoginCredentials, O as OAuthLoginData, R as RefreshResponse, n as RefreshTokenData, k as RegisterData, m as ResetPasswordData, U as UserRole, h as UserRoleType, V as VerifyManagerData, p as VerifyManagerResponse, a as authApi, a as authApiDefault, d as createUser, f as forgetPassApi, e as getProfile, g as getUser, c as getUserByPhone, l as loginApi, o as oauthLoginApi, r as registerApi, b as resetPassApi, t as tokenRefreshApi, u as updateUser, v as verifyManagerAuth } from '../user-data-DdLjAGwO.js';
+
+interface UseUserSearchOptions {
+    token: string;
+}
+interface UseUserSearchReturn {
+    /** Search for user by email or phone */
+    searchUser: (value: string, by?: "email" | "phone") => void;
+    /** Found user (first match) */
+    user: User | undefined;
+    /** No user found for the search */
+    notFound: boolean;
+    /** Search in progress */
+    isSearching: boolean;
+    /** Search error */
+    error: Error | null;
+    /** Reset search state */
+    reset: () => void;
+}
+/**
+ * Hook for searching users by email or phone number
+ *
+ * @param options.token - Auth token (required)
+ *
+ * @example
+ * ```tsx
+ * const { searchUser, user, isSearching, notFound } = useUserSearch({ token });
+ *
+ * // Search by email
+ * searchUser("user@example.com");
+ *
+ * // Search by phone
+ * searchUser("01712345678", "phone");
+ * ```
+ */
+declare function useUserSearch({ token }: UseUserSearchOptions): UseUserSearchReturn;
+
+export { User, useUserSearch };

package/dist/auth/index.js

@@ -0,0 +1,5 @@
+"use client";
+export { DISCOUNT_ALLOWED_ROLES, UserRole, authApi, user_data_default as authApiDefault, createUser, forgetPassApi, getProfile, getUser, getUserByPhone, loginApi, oauthLoginApi, registerApi, resetPassApi, tokenRefreshApi, updateUser, useUserSearch, verifyManagerAuth } from '../chunk-BDA2WSJA.js';
+import '../chunk-VR36QVX2.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}