feeef 0.5.38-dev.2 → 0.5.38-dev.3

package/build/src/core/entities/city.d.ts

@@ -0,0 +1,17 @@
+/**
+ * City Entity
+ *
+ * Represents a city with composite key (countryCode + stateCode + name).
+ */
+export interface CityEntity {
+    /** Country code (part of composite primary key) */
+    countryCode: string;
+    /** State code (part of composite primary key) */
+    stateCode: string;
+    /** City name (part of composite primary key) */
+    name: string;
+    /** Additional metadata as key-value pairs */
+    metadata: Record<string, any>;
+    /** Creation timestamp */
+    createdAt: any;
+}

package/build/src/core/entities/country.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Country Entity
+ *
+ * Represents a country with ISO 3166-1 alpha-2 country code.
+ */
+export interface CountryEntity {
+    /** ISO 3166-1 alpha-2 country code (e.g., US, DZ, SA) */
+    code: string;
+    /** Country name (e.g., United States, Algeria, Saudi Arabia) */
+    name: string;
+    /** Phone country code without + (e.g., 1, 213, 966) */
+    phone: string;
+    /** Additional metadata as key-value pairs */
+    metadata: Record<string, any>;
+    /** Creation timestamp */
+    createdAt: any;
+}

package/build/src/core/entities/order.d.ts

@@ -33,6 +33,7 @@ export interface OrderEntity {
     shippingAddress?: string | null;
     shippingCity?: string | null;
     shippingState?: string | null;
+    shippingCountry?: string | null;
     shippingMethodId?: string | null;
     shippingType: ShippingType;
     trackingCode: string | null;

package/build/src/core/entities/product.d.ts

@@ -11,6 +11,7 @@ export interface ProductEntity {
     media: string[];
     storeId: string;
     shippingMethodId?: string | null;
+    shippingPriceId?: string | null;
     categoryId?: string | null;
     category?: EmbaddedCategory | null;
     categoryRelation?: CategoryEntity | null;

package/build/src/core/entities/shipping_price.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Shipping Price Entity
+ *
+ * A simplified, country-aware shipping pricing system that replaces
+ * the legacy array-based shipping rates with a structured approach.
+ *
+ * Key features:
+ * - Country codes as keys (ISO 3166-1 alpha-2)
+ * - State codes as keys (no fragile array indexes)
+ * - Named price types for extensibility
+ * - Gradual migration path from legacy system
+ *
+ * @example
+ * ```typescript
+ * const prices: ShippingPriceRates = {
+ *   "DZ": {
+ *     "01": { home: 800, desk: 400, pickup: 0 },
+ *     "16": { home: 600, desk: 300, pickup: 0 }
+ *   },
+ *   "IQ": {
+ *     "01": { home: 15000, desk: 10000, pickup: 5000 }
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Individual state shipping rates with named price types.
+ * Using named properties instead of array indexes for clarity and extensibility.
+ */
+export interface ShippingStateRates {
+    /** Price for home delivery (nullable if unavailable) */
+    home: number | null;
+    /** Price for desk/office pickup (nullable if unavailable) */
+    desk: number | null;
+    /** Price for store pickup (nullable if unavailable) */
+    pickup: number | null;
+}
+/**
+ * Shipping rates organized by country code and state code.
+ * Structure: { [countryCode]: { [stateCode]: ShippingStateRates } }
+ */
+export type ShippingPriceRates = Record<string, Record<string, ShippingStateRates>>;
+/**
+ * Status of the shipping price configuration.
+ */
+export declare enum ShippingPriceStatus {
+    /** Not yet published, only visible to store owner */
+    draft = "draft",
+    /** Active and used for shipping calculations */
+    published = "published"
+}
+/**
+ * Shipping Price Entity
+ *
+ * Represents a shipping pricing configuration for a store.
+ * Supports multi-country operations with state-level pricing.
+ */
+export interface ShippingPriceEntity {
+    /** Unique identifier (24-char string) */
+    id: string;
+    /** Display name for this pricing configuration */
+    name: string;
+    /** Optional logo URL for branding */
+    logoUrl: string | null;
+    /** Store this pricing belongs to */
+    storeId: string;
+    /**
+     * Pricing data structured by country and state codes.
+     * @see ShippingPriceRates
+     */
+    prices: ShippingPriceRates;
+    /** Publication status */
+    status: ShippingPriceStatus;
+    /** Creation timestamp */
+    createdAt: any;
+    /** Last update timestamp */
+    updatedAt: any;
+}
+/**
+ * Shipping type enumeration for order shipping type.
+ * Maps to the pricing structure keys.
+ */
+export type ShippingPriceType = keyof ShippingStateRates;
+/**
+ * Helper function to get shipping price from rates.
+ *
+ * @param prices - The shipping price rates object
+ * @param countryCode - ISO 3166-1 alpha-2 country code
+ * @param stateCode - State/province code
+ * @param type - Shipping type (home, desk, pickup)
+ * @returns The price or null if not available
+ *
+ * @example
+ * ```typescript
+ * const price = getShippingPrice(shippingPrice.prices, 'DZ', '16', 'home')
+ * // Returns 600 or null
+ * ```
+ */
+export declare function getShippingPrice(prices: ShippingPriceRates, countryCode: string, stateCode: string, type: ShippingPriceType): number | null;
+/**
+ * Helper function to check if shipping is available for a location.
+ *
+ * @param prices - The shipping price rates object
+ * @param countryCode - ISO 3166-1 alpha-2 country code
+ * @param stateCode - State/province code
+ * @returns True if any shipping type is available for this location
+ */
+export declare function isShippingAvailable(prices: ShippingPriceRates, countryCode: string, stateCode: string): boolean;
+/**
+ * Helper function to get all available shipping types for a location.
+ *
+ * @param prices - The shipping price rates object
+ * @param countryCode - ISO 3166-1 alpha-2 country code
+ * @param stateCode - State/province code
+ * @returns Array of available shipping types with their prices
+ */
+export declare function getAvailableShippingTypes(prices: ShippingPriceRates, countryCode: string, stateCode: string): Array<{
+    type: ShippingPriceType;
+    price: number;
+}>;

package/build/src/core/entities/state.d.ts

@@ -0,0 +1,17 @@
+/**
+ * State/Province Entity
+ *
+ * Represents a state or province with composite key (countryCode + code).
+ */
+export interface StateEntity {
+    /** Country code (part of composite primary key) */
+    countryCode: string;
+    /** State/province code (part of composite primary key) */
+    code: string;
+    /** State/province name */
+    name: string;
+    /** Additional metadata as key-value pairs */
+    metadata: Record<string, any>;
+    /** Creation timestamp */
+    createdAt: any;
+}

package/build/src/core/entities/store.d.ts

@@ -34,6 +34,7 @@ export interface StoreEntity {
     updatedAt: any;
     user?: UserEntity;
     defaultShippingRates: (number | null)[][] | null;
+    shippingPriceId?: string | null;
     subscription?: any;
     due?: number;
     configs?: StoreConfigs;

package/build/src/feeef/feeef.d.ts

@@ -5,6 +5,10 @@ import { StoreRepository } from './repositories/stores.js';
 import { UserRepository } from './repositories/users.js';
 import { DepositRepository } from './repositories/deposits.js';
 import { CategoryRepository } from './repositories/categories.js';
+import { CountryRepository } from './repositories/countries.js';
+import { StateRepository } from './repositories/states.js';
+import { CityRepository } from './repositories/cities.js';
+import { ShippingPriceRepository } from './repositories/shipping_prices.js';
 import { CartService } from './services/cart.js';
 import { ActionsService } from './services/actions.js';
 /**
@@ -67,6 +71,22 @@ export declare class FeeeF {
      * The repository for managing categories.
      */
     categories: CategoryRepository;
+    /**
+     * The repository for managing countries.
+     */
+    countries: CountryRepository;
+    /**
+     * The repository for managing states.
+     */
+    states: StateRepository;
+    /**
+     * The repository for managing cities.
+     */
+    cities: CityRepository;
+    /**
+     * The repository for managing shipping prices.
+     */
+    shippingPrices: ShippingPriceRepository;
     /**
      * The cart service for managing the cart.
      */

package/build/src/feeef/repositories/cities.d.ts

@@ -0,0 +1,78 @@
+import { AxiosInstance } from 'axios';
+import { ModelRepository, ModelListOptions } from './repository.js';
+import { CityEntity } from '../../core/entities/city.js';
+/**
+ * Repository for managing City entities.
+ * Cities have composite keys (countryCode + stateCode + name) and are nested under states.
+ */
+export declare class CityRepository extends ModelRepository<CityEntity, any, any> {
+    /**
+     * Constructs a new CityRepository instance.
+     * @param client The AxiosInstance used for making HTTP requests.
+     */
+    constructor(client: AxiosInstance);
+    /**
+     * Lists cities, optionally filtered by country code and/or state code.
+     * @param options - The options for listing cities, including filters.
+     * @returns A Promise that resolves to a list of City entities.
+     */
+    list(options?: ModelListOptions & {
+        countryCode?: string;
+        stateCode?: string;
+    }): Promise<any>;
+    /**
+     * Lists cities for a specific country and state (nested route).
+     * @param countryCode - The country code.
+     * @param stateCode - The state code.
+     * @param options - Optional list options.
+     * @returns A Promise that resolves to a list of City entities.
+     */
+    listByState(countryCode: string, stateCode: string, options?: ModelListOptions): Promise<any>;
+    /**
+     * Finds a city by country code, state code, and city name.
+     * @param countryCode - The country code.
+     * @param stateCode - The state code.
+     * @param cityName - The city name.
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves to the found City entity.
+     */
+    findByName(countryCode: string, stateCode: string, cityName: string, params?: Record<string, any>): Promise<CityEntity>;
+    /**
+     * Creates a new city (nested under country/state).
+     * @param countryCode - The country code.
+     * @param stateCode - The state code.
+     * @param data - The city data.
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves to the created City entity.
+     */
+    createByState(countryCode: string, stateCode: string, data: any, params?: Record<string, any>): Promise<CityEntity>;
+    /**
+     * Updates a city (nested under country/state).
+     * @param countryCode - The country code.
+     * @param stateCode - The state code.
+     * @param cityName - The city name.
+     * @param data - The update data.
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves to the updated City entity.
+     */
+    updateByState(countryCode: string, stateCode: string, cityName: string, data: any, params?: Record<string, any>): Promise<CityEntity>;
+    /**
+     * Deletes a city (nested under country/state).
+     * @param countryCode - The country code.
+     * @param stateCode - The state code.
+     * @param cityName - The city name.
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves when the city is deleted.
+     */
+    deleteByState(countryCode: string, stateCode: string, cityName: string, params?: Record<string, any>): Promise<void>;
+    /**
+     * Searches cities by name (autocomplete).
+     * @param query - The search query.
+     * @param options - Optional filters (countryCode, stateCode).
+     * @returns A Promise that resolves to a list of matching City entities.
+     */
+    search(query: string, options?: {
+        countryCode?: string;
+        stateCode?: string;
+    }): Promise<CityEntity[]>;
+}

package/build/src/feeef/repositories/countries.d.ts

@@ -0,0 +1,20 @@
+import { AxiosInstance } from 'axios';
+import { ModelRepository } from './repository.js';
+import { CountryEntity } from '../../core/entities/country.js';
+/**
+ * Repository for managing Country entities.
+ */
+export declare class CountryRepository extends ModelRepository<CountryEntity, any, any> {
+    /**
+     * Constructs a new CountryRepository instance.
+     * @param client The AxiosInstance used for making HTTP requests.
+     */
+    constructor(client: AxiosInstance);
+    /**
+     * Finds a country by its code (ID is the country code).
+     * @param code - The country code (ISO 3166-1 alpha-2).
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves to the found Country entity.
+     */
+    findByCode(code: string, params?: Record<string, any>): Promise<CountryEntity>;
+}

package/build/src/feeef/repositories/shipping_prices.d.ts

@@ -0,0 +1,28 @@
+import { AxiosInstance } from 'axios';
+import { ModelRepository, ModelCreateOptions } from './repository.js';
+import { ShippingPriceEntity } from '../../core/entities/shipping_price.js';
+/**
+ * Repository for managing ShippingPrice entities.
+ *
+ * ShippingPrice is the new geo-based shipping system that replaces
+ * the legacy array-based ShippingMethod rates.
+ */
+export declare class ShippingPriceRepository extends ModelRepository<ShippingPriceEntity, any, any> {
+    /**
+     * Constructs a new ShippingPriceRepository instance.
+     * @param client The AxiosInstance used for making HTTP requests.
+     */
+    constructor(client: AxiosInstance);
+    /**
+     * Creates a new ShippingPrice entity.
+     * @param options The options for creating the ShippingPrice entity.
+     * @returns A Promise that resolves to the created ShippingPrice entity.
+     */
+    create(options: ModelCreateOptions<any>): Promise<ShippingPriceEntity>;
+    /**
+     * Finds a ShippingPrice by store ID.
+     * @param storeId The store ID to search for.
+     * @returns A Promise that resolves to the ShippingPrice entities for the store.
+     */
+    listByStore(storeId: string): Promise<ShippingPriceEntity[]>;
+}

package/build/src/feeef/repositories/states.d.ts

@@ -0,0 +1,62 @@
+import { AxiosInstance } from 'axios';
+import { ModelRepository, ModelListOptions } from './repository.js';
+import { StateEntity } from '../../core/entities/state.js';
+/**
+ * Repository for managing State entities.
+ * States have composite keys (countryCode + code) and can be nested under countries.
+ */
+export declare class StateRepository extends ModelRepository<StateEntity, any, any> {
+    /**
+     * Constructs a new StateRepository instance.
+     * @param client The AxiosInstance used for making HTTP requests.
+     */
+    constructor(client: AxiosInstance);
+    /**
+     * Lists states, optionally filtered by country code.
+     * @param options - The options for listing states, including countryCode filter.
+     * @returns A Promise that resolves to a list of State entities.
+     */
+    list(options?: ModelListOptions & {
+        countryCode?: string;
+    }): Promise<any>;
+    /**
+     * Lists states for a specific country (nested route).
+     * @param countryCode - The country code.
+     * @param options - Optional list options.
+     * @returns A Promise that resolves to a list of State entities.
+     */
+    listByCountry(countryCode: string, options?: ModelListOptions): Promise<any>;
+    /**
+     * Finds a state by country code and state code.
+     * @param countryCode - The country code.
+     * @param stateCode - The state code.
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves to the found State entity.
+     */
+    findByCode(countryCode: string, stateCode: string, params?: Record<string, any>): Promise<StateEntity>;
+    /**
+     * Creates a new state (nested under country).
+     * @param countryCode - The country code.
+     * @param data - The state data.
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves to the created State entity.
+     */
+    createByCountry(countryCode: string, data: any, params?: Record<string, any>): Promise<StateEntity>;
+    /**
+     * Updates a state (nested under country).
+     * @param countryCode - The country code.
+     * @param stateCode - The state code.
+     * @param data - The update data.
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves to the updated State entity.
+     */
+    updateByCountry(countryCode: string, stateCode: string, data: any, params?: Record<string, any>): Promise<StateEntity>;
+    /**
+     * Deletes a state (nested under country).
+     * @param countryCode - The country code.
+     * @param stateCode - The state code.
+     * @param params - Optional query parameters.
+     * @returns A Promise that resolves when the state is deleted.
+     */
+    deleteByCountry(countryCode: string, stateCode: string, params?: Record<string, any>): Promise<void>;
+}

package/build/src/feeef/services/cart.d.ts

@@ -1,6 +1,7 @@
 import { ShippingType } from '../../core/entities/order.js';
 import { ProductEntity, ProductOffer } from '../../core/entities/product.js';
 import { ShippingMethodEntity } from '../../core/entities/shipping_method.js';
+import { ShippingPriceEntity } from '../../core/entities/shipping_price.js';
 import { StoreEntity } from '../../core/entities/store.js';
 import { NotifiableService } from './service.js';
 /**
@@ -37,6 +38,8 @@ export interface CartShippingAddress {
 export declare class CartService extends NotifiableService {
     private items;
     private shippingMethod;
+    private shippingPrice;
+    private store;
     private shippingAddress;
     private cachedSubtotal;
     private currentItem;
@@ -187,11 +190,48 @@ export declare class CartService extends NotifiableService {
      */
     setShippingMethod(method: ShippingMethodEntity | StoreEntity, notify?: boolean): void;
     /**
-     * Retrieves the available shipping types for the current shipping method.
+     * Sets the shipping price (new system).
+     * @param shippingPrice - The shipping price entity.
+     * @param notify - Whether to notify listeners.
+     */
+    setShippingPrice(shippingPrice: ShippingPriceEntity | null, notify?: boolean): void;
+    /**
+     * Sets the store entity.
+     * @param store - The store entity.
+     * @param notify - Whether to notify listeners.
+     */
+    setStore(store: StoreEntity | null, notify?: boolean): void;
+    /**
+     * Maps ShippingType enum to ShippingPriceType string.
+     * @param shippingType - The shipping type enum.
+     * @returns The corresponding shipping price type.
+     */
+    private mapShippingTypeToPriceType;
+    /**
+     * Resolves shipping price using the priority chain.
+     * Priority: 1. Product shippingPriceId, 2. Store shippingPriceId, 3. Product shippingMethodId, 4. Store defaultShippingRates
+     *
+     * Note: Shipping prices must be loaded and set via setShippingPrice() for the new system to work.
+     * If shipping prices are not loaded, the method falls back to the legacy system.
+     *
+     * @param countryCode - ISO 3166-1 alpha-2 country code (optional, required for new system)
+     * @param stateCode - State/province code
+     * @param shippingType - The shipping type
+     * @returns The shipping price or null if not available
+     */
+    private resolveShippingPrice;
+    /**
+     * Gets shipping price using legacy system (array-based rates).
+     * @param type - The shipping type
+     * @returns The shipping price or null if not available
+     */
+    private getShippingPriceForTypeLegacy;
+    /**
+     * Retrieves the available shipping types using the priority chain.
+     * Priority: 1. Product shippingPriceId, 2. Store shippingPriceId, 3. Product shippingMethodId, 4. Store defaultShippingRates
      *
-     *   rates is a 2D array for example `[[10, 20, 30], [5, 10, 15]]`
-     *   where the first array is for `home` fees and the second is for `pickup` fees, and the third is for `store` fees
-     *   if the fee value is 0, then it's free shipping, and if it's null, then it's not available
+     * Note: Shipping prices must be loaded and set via setShippingPrice() for the new system to work.
+     * If shipping prices are not loaded, the method falls back to the legacy system.
      *
      * @returns An array of available shipping types.
      */
@@ -217,7 +257,8 @@ export declare class CartService extends NotifiableService {
      */
     getShippingPrice(): number;
     /**
-     * Gets the shipping price for a specific shipping type using the current shipping address state.
+     * Gets the shipping price for a specific shipping type using the priority chain.
+     * Priority: 1. Product shippingPriceId, 2. Store shippingPriceId, 3. Product shippingMethodId, 4. Store defaultShippingRates
      * @param type - The shipping type to check (pickup, home, store)
      * @returns The shipping price for the specified type, or null if not available
      */

package/build/src/index.d.ts

@@ -4,8 +4,13 @@ export * from './core/entities/store.js';
 export * from './core/entities/product.js';
 export * from './core/entities/user.js';
 export * from './core/entities/shipping_method.js';
+export * from './core/entities/shipping_price.js';
 export * from './core/entities/category.js';
+export * from './core/entities/country.js';
+export * from './core/entities/state.js';
+export * from './core/entities/city.js';
 export * from './feeef/repositories/deposits.js';
+export * from './feeef/repositories/shipping_prices.js';
 export * from './core/embadded/address.js';
 export * from './core/embadded/category.js';
 export * from './core/embadded/contact.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feeef",
   "description": "feeef sdk for javascript",
-  "version": "0.5.38-dev.2",
+  "version": "0.5.38-dev.3",
   "main": "build/index.js",
   "type": "module",
   "files": [