feeef 0.8.10 → 0.8.13

package/build/src/ai/ai_calculator.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Pure utility class for estimating AI generation costs client-side.
+ *
+ * Mirrors the backend `AiCalculator` in `backend/app/services/ai_calculator.ts`.
+ * All methods are deterministic and require no network calls.
+ * The backend quote is authoritative; this calculator is a deterministic
+ * mirror for UX (showing estimated cost before the user clicks generate).
+ *
+ * Canonical `aiModels.billing` keys — keep in sync: backend `configs_controller.ts`,
+ * feeef `lib/core/app_config.dart`, admins_dashboard `src/lib/hooks/useOptions.ts`.
+ */
+/** Fallback DZD per USD when `aiModels.exchangeRate` is missing (mirror backend). */
+export declare const FALLBACK_AI_EXCHANGE_RATE = 260;
+export interface RetailMarkupBilling {
+    multiplier?: number;
+}
+export interface ReferenceAttachmentSurchargeBilling {
+    perFileUsd?: number;
+    highResolutionExtraPerFileUsd?: number;
+    lowResolutionDiscountPerFileUsd?: number;
+}
+export interface ImageGenerationBilling {
+    fallbackProviderCostPerImageUsd?: number;
+}
+export interface TextGenerationBilling {
+    freeTierMaxPromptTokens?: number;
+    estimatedPromptTokensDefault?: number;
+    estimatedOutputTokensDefault?: number;
+}
+export interface TtsTokenEstimateBilling {
+    whenScriptEmptyTokens?: number;
+    whenAttachmentsOnlyTokens?: number;
+    promptBaseTokens?: number;
+    promptPerAttachmentTokens?: number;
+    outputMinimumTokens?: number;
+    outputToTextTokenRatio?: number;
+    maxTotalTokens?: number;
+}
+export interface VoiceGenerationBilling {
+    minimumChargeUsd?: number;
+    scriptEnhancementAddonUsd?: number;
+    ttsTokenEstimate?: TtsTokenEstimateBilling;
+}
+export interface LandingPageImageBilling {
+    fixedChargeUsd?: number;
+}
+export interface AIModelsBilling {
+    retailMarkup?: RetailMarkupBilling;
+    referenceAttachmentSurcharge?: ReferenceAttachmentSurchargeBilling;
+    imageGeneration?: ImageGenerationBilling;
+    textGeneration?: TextGenerationBilling;
+    voiceGeneration?: VoiceGenerationBilling;
+    landingPageImage?: LandingPageImageBilling;
+}
+/** Fully resolved billing after merge (stable export for callers/tests). */
+export interface ResolvedAiModelsBilling {
+    retailMarkup: {
+        multiplier: number;
+    };
+    referenceAttachmentSurcharge: {
+        perFileUsd: number;
+        highResolutionExtraPerFileUsd: number;
+        lowResolutionDiscountPerFileUsd: number;
+    };
+    imageGeneration: {
+        fallbackProviderCostPerImageUsd: number;
+    };
+    textGeneration: {
+        freeTierMaxPromptTokens: number;
+        estimatedPromptTokensDefault: number;
+        estimatedOutputTokensDefault: number;
+    };
+    voiceGeneration: {
+        minimumChargeUsd: number;
+        scriptEnhancementAddonUsd: number;
+        ttsTokenEstimate: Required<TtsTokenEstimateBilling>;
+    };
+    landingPageImage: {
+        fixedChargeUsd: number;
+    };
+}
+/**
+ * Deep-merge optional server `billing` over platform defaults.
+ * Omit or pass `null` to get code defaults only.
+ */
+export declare function mergeAiModelsBilling(partial?: AIModelsBilling | null): ResolvedAiModelsBilling;
+/** Legacy flat keys for older importers (DZD leaves use `exchangeRate`). */
+export interface LegacyAiBillingFlat {
+    MULTIPLIER: number;
+    FREE_TEXT_TOKENS_THRESHOLD: number;
+    DEFAULT_EXCHANGE_RATE: number;
+    DEFAULT_GOOGLE_IMAGE_COST_USD: number;
+    DEFAULT_ATTACHMENT_COST_USD: number;
+    ATTACHMENT_HIGH_RES_EXTRA_USD: number;
+    ATTACHMENT_LOW_RES_DISCOUNT_USD: number;
+    VOICEOVER_FIXED_COST_DZD: number;
+    VOICEOVER_ENHANCE_ADDON_DZD: number;
+    IMAGE_LANDING_PAGE_FIXED_COST_DZD: number;
+    DEFAULT_TEXT_PROMPT_TOKENS: number;
+    DEFAULT_TEXT_OUTPUT_TOKENS: number;
+    VOICE_TTS_EMPTY_SCRIPT_TEXT_TOKENS: number;
+    VOICE_TTS_ATTACHMENT_ONLY_TEXT_TOKENS: number;
+    VOICE_TTS_PROMPT_BASE: number;
+    VOICE_TTS_PROMPT_PER_ATTACHMENT: number;
+    VOICE_TTS_OUTPUT_MIN: number;
+    VOICE_TTS_OUTPUT_TEXT_FACTOR: number;
+    VOICE_TTS_TOKEN_CAP: number;
+}
+export declare function getLegacyAiBillingFlat(exchangeRate: number, resolved?: ResolvedAiModelsBilling): LegacyAiBillingFlat;
+/**
+ * @deprecated Prefer `mergeAiModelsBilling` + `ResolvedAiModelsBilling`.
+ * Snapshot of defaults at `FALLBACK_AI_EXCHANGE_RATE` for DZD-derived fields.
+ */
+export declare const AI_BILLING: LegacyAiBillingFlat;
+export interface AiModelPricing {
+    input?: number;
+    output?: number;
+    unit: string;
+    contextThreshold?: string;
+}
+/**
+ * Optional operator overrides for Gemini image-generation Google Search grounding.
+ * Shapes `aiModels.models[].tools` from the app config API — same as backend `AIModel.tools`.
+ * Undefined keys mean “use platform default for this model id” (see backend `gemini_image_grounding`).
+ */
+export interface AiModelTools {
+    googleSearch?: boolean;
+    googleImageSearch?: boolean;
+}
+export interface AiModelConfig {
+    id: string;
+    pricing?: AiModelPricing[];
+    localCost?: number | null;
+    /** From aiModels — used so TTS billing does not fall back to the first (often image) row. */
+    capabilities?: string[];
+    tools?: AiModelTools;
+}
+export interface AiCalculatorConfig {
+    exchangeRate?: number;
+    defaultImageCost?: number;
+    referenceImageCost?: number;
+    resolutionCosts?: Record<string, number>;
+    models?: AiModelConfig[];
+    /** Optional `aiModels.billing` overrides (merged over [mergeAiModelsBilling] defaults). */
+    billing?: AIModelsBilling | null;
+}
+export interface AiCostEstimate {
+    providerCostUsd: number;
+    providerCostDzd: number;
+    userCostDzd: number;
+    exchangeRate: number;
+    multiplier: number;
+    usedLocalCost: boolean;
+    breakdown: Record<string, number | boolean>;
+}
+/** Keep in sync with backend `defaultVoiceTtsTokenEstimates` (default billing only). */
+export declare function defaultVoiceTtsTokenEstimates(scriptCharLength: number, attachmentCount: number): {
+    promptTokens: number;
+    outputTokens: number;
+};
+export declare class AiCalculator {
+    private config;
+    constructor(config?: AiCalculatorConfig);
+    /** TTS base DZD: localCost → flat USD row → tokens (per 1M) × estimates × rate × multiplier → floor. */
+    private _voiceoverBaseUserCostDzd;
+    private _attachmentExtraUserDzd;
+    /**
+     * Estimate the cost of an image generation action.
+     * Covers: image gen, logo gen, editOrGenerateSimpleImage.
+     */
+    estimateImageGeneration(options?: {
+        modelId?: string;
+        attachmentCount?: number;
+        attachmentResolution?: 'low' | 'medium' | 'high';
+        resolution?: string;
+        imageSize?: string;
+        iterations?: number;
+        referenceImageCount?: number;
+    }): AiCostEstimate;
+    /**
+     * Estimate the cost of a text generation action.
+     * Covers: updateProductUsingAi, generateSimpleCode, generateCustomComponentCode.
+     * Uses estimated tokens (exact cost billed post-generation).
+     */
+    estimateTextGeneration(options?: {
+        modelId?: string;
+        estimatedPromptTokens?: number;
+        estimatedOutputTokens?: number;
+    }): AiCostEstimate;
+    /**
+     * Voiceover: base + attachment surcharge + optional script-enhancement add-on.
+     */
+    estimateVoiceover(options?: {
+        modelId?: string;
+        attachmentCount?: number;
+        attachmentResolution?: 'low' | 'medium' | 'high';
+        enhanceScript?: boolean;
+        scriptCharLength?: number;
+        estimatedPromptTokens?: number;
+        estimatedOutputTokens?: number;
+    }): AiCostEstimate;
+    /** Get the fixed cost for image landing page generation. */
+    estimateImageLandingPage(): AiCostEstimate;
+}

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

@@ -58,9 +58,21 @@ export interface OrderEntity {
     deliveryStatus: DeliveryStatus;
     customStatus?: string | null;
     tags: string[] | null;
+    /**
+     * Attribution tokens: `product:…`, `product_landing_page:…`.
+     * JSON / API field name is always **`references`** (never `orderReferences`).
+     */
+    references?: string[];
     createdAt: any;
     updatedAt: any;
 }
+/** Lite orders report (8 UTC days + total), API key `lor`. */
+export interface LiteOrdersReport {
+    lastSync: string;
+    lastItemDate: string;
+    totalOrders: number;
+    data: [number, number, number][];
+}
 export interface OrderItem {
     productId: string;
     productName: string;
@@ -135,6 +147,7 @@ export interface OrderCreateInput {
     metadata?: Record<string, any>;
     storeId: string;
     tags?: string[];
+    references?: string[];
 }
 /**
  * Input for order items when creating/updating an order
@@ -180,6 +193,7 @@ export interface OrderUpdateInput {
     customFields?: Record<string, any>;
     metadata?: Record<string, any>;
     tags?: string[];
+    references?: string[];
 }
 /**
  * Order pricing calculation result

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

@@ -268,3 +268,5 @@ export interface ProductReport {
     }>;
     salesByDate?: Record<string, number>;
 }
+/** Token for `Order.references`. */
+export declare function formatProductOrderReference(productId: string): string;

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

@@ -35,3 +35,5 @@ export interface ProductLandingPageUpdate {
     productId: string | null;
     storeId?: string;
 }
+/** Token for `Order.references`. */
+export declare function formatProductLandingPageOrderReference(landingPageId: string): string;

package/build/src/delivery/delivery_carrier_client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Logical client surface for carrier integrations — mirrors backend `DeliveryService`
+ * (`feeefapps/backend/services/delivery/delivery_service.ts`).
+ */
+import type { ParcelCreate, ParcelUpdate } from './parcel.js';
+export interface DeliveryCarrierClient {
+    readonly providerId: string;
+    send(parcel: ParcelCreate): Promise<Record<string, unknown>>;
+    sendMany(parcels: ParcelCreate[]): Promise<Record<string, unknown>>;
+    unsend(trackingOrCarrierId: string): Promise<unknown>;
+    unsendMany(ids: string[]): Promise<unknown>;
+    update(input: ParcelUpdate): Promise<unknown>;
+    updateMany(updates: ParcelUpdate[]): Promise<unknown>;
+    delete(id: string): Promise<unknown>;
+    deleteMany(ids: string[]): Promise<unknown>;
+    label(tracking: string, options?: Record<string, unknown>): Promise<unknown>;
+    labels(ids: string[], options?: Record<string, unknown>): Promise<unknown>;
+    show(id: string): Promise<unknown>;
+    list(query?: Record<string, unknown>): Promise<unknown>;
+}

package/build/src/delivery/parcel.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Canonical parcel domain types — keep aligned with
+ * `feeefapps/backend/services/delivery/domain/parcel.ts`.
+ *
+ * npm package name is `feeef`; this repo is the JS SDK source (`feeefjs`).
+ */
+import type { ShippingType as FeeefShippingType } from '../core/entities/order.js';
+/** Same enum as platform `Order.shippingType` / npm `feeef` `ShippingType`. */
+export type ParcelShippingType = FeeefShippingType;
+export interface ParcelLineItem {
+    name: string;
+    quantity: number;
+    price?: number | null;
+    variantPath?: string | null;
+}
+export interface ParcelContact {
+    firstName?: string | null;
+    lastName?: string | null;
+    phones?: string[];
+    emails?: string[];
+}
+export interface ParcelAddress {
+    street: string | null;
+    cityCode: string | null;
+    stateCode: string | null;
+    country: string | null;
+    note?: string | null;
+}
+export type ParcelDimensionUnit = 'cm' | 'm' | 'in';
+export type ParcelWeightUnit = 'kg' | 'g' | 'lb' | 'oz';
+export interface ParcelPackage {
+    width?: number | null;
+    height?: number | null;
+    length?: number | null;
+    weight?: number | null;
+    fragile?: boolean | null;
+    dimensionUnit?: ParcelDimensionUnit | null;
+    weightUnit?: ParcelWeightUnit | null;
+}
+/** Shipment category (forward / return / exchange) — field name on `ParcelCreate` is `type`. */
+export type ParcelType = 'forward' | 'return' | 'exchange';
+export interface ParcelUpdate {
+    carrierId: string;
+    contact?: Partial<ParcelContact>;
+    address?: Partial<ParcelAddress>;
+    total?: number;
+    notes?: string | null;
+    summary?: string;
+    package?: Partial<ParcelPackage> | null;
+    items?: ParcelLineItem[];
+    shippingType?: ParcelShippingType | string | null;
+    extensions?: Record<string, unknown>;
+}
+export interface ParcelCreate {
+    storeId: string;
+    reference: string;
+    contact: ParcelContact;
+    address: ParcelAddress;
+    /** Charged / COD amount (typically order total). Legacy JSON: `codAmount`. */
+    total: number;
+    itemsPrice?: number | null;
+    declaredValue: number | null;
+    shippingType?: ParcelShippingType | string | null;
+    shippingPrice?: number | null;
+    freeShipping?: boolean | null;
+    /** Stop-desk / hub id (Yalidine `stopdesk_id`, ZR `hubId`). Legacy: `centerId`. */
+    pickupId?: string | null;
+    fromStock?: boolean | null;
+    items: ParcelLineItem[];
+    /** Legacy JSON: `productsSummary`. */
+    summary: string;
+    notes: string | null;
+    metadata?: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+    package?: ParcelPackage | null;
+    /** Legacy JSON: `parcelType`. */
+    type?: ParcelType | null;
+}

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

@@ -32,6 +32,7 @@ export interface SendOrderSchema {
     storeId: string;
     customFields?: Record<string, any>;
     metadata?: any;
+    references?: string[];
 }
 /**
  * Schema for guest order items
@@ -96,6 +97,8 @@ export interface OrderListOptions {
     shippingState?: string;
     shippingCity?: string;
     deliveryService?: DeliveryServiceFilter;
+    /** Filter orders whose `references` jsonb contains this token (repeat param or comma-separated). */
+    references?: string | string[];
     params?: Record<string, any>;
 }
 /**

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

@@ -1,6 +1,7 @@
 import { AxiosInstance } from 'axios';
 import { ModelRepository, ListResponse } from './repository.js';
 import { ProductLandingPage, ProductLandingPageCreate, ProductLandingPageUpdate } from '../../core/entities/product_landing_page.js';
+import type { LiteOrdersReport } from '../../core/entities/order.js';
 /**
  * Options for listing product landing pages
  */
@@ -27,4 +28,10 @@ export declare class ProductLandingPagesRepository extends ModelRepository<Produ
      * @returns A Promise that resolves to a list of ProductLandingPage entities.
      */
     list(options?: ProductLandingPageListOptions): Promise<ListResponse<ProductLandingPage>>;
+    /**
+     * Lite orders report for a product landing page in a store.
+     */
+    liteOrdersReport(storeId: string, landingPageId: string): Promise<{
+        lor: LiteOrdersReport;
+    }>;
 }

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

@@ -1,6 +1,7 @@
 import { AxiosInstance } from 'axios';
 import { ModelRepository, ListResponse } from './repository.js';
 import { ProductEntity, ProductCreateInput, ProductUpdateInput, ProductReport, ProductStatus } from '../../core/entities/product.js';
+import type { LiteOrdersReport } from '../../core/entities/order.js';
 /**
  * Options for listing products
  */
@@ -54,4 +55,10 @@ export declare class ProductRepository extends ModelRepository<ProductEntity, Pr
      * @returns A Promise that resolves to the product report.
      */
     report(productId: string, storeId: string): Promise<ProductReport>;
+    /**
+     * Lite orders report for a product in a store.
+     */
+    liteOrdersReport(storeId: string, productId: string): Promise<{
+        lor: LiteOrdersReport;
+    }>;
 }

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

@@ -1,6 +1,7 @@
 import { AxiosInstance } from 'axios';
 import { ModelRepository, ListResponse } from './repository.js';
 import { StoreEntity, StoreSummary, StoreMember, StoreSubscriptionType, AddStoreMemberInput, UpdateStoreMemberInput, StoreCreateInput, StoreUpdateInput } from '../../core/entities/store.js';
+import type { LiteOrdersReport } from '../../core/entities/order.js';
 import { StoreInvitesRepository } from './store_invites_repository.js';
 /**
  * Options for listing stores
@@ -56,6 +57,12 @@ export declare class StoreRepository extends ModelRepository<StoreEntity, StoreC
      * @returns A Promise that resolves to a map of date to order count.
      */
     chart(id: string): Promise<Map<Date, number>>;
+    /**
+     * Lite orders report for the store (8 UTC days + total).
+     */
+    liteOrdersReport(storeId: string): Promise<{
+        lor: LiteOrdersReport;
+    }>;
     /**
      * Adds a member to the store.
      * @param storeId - The store ID.

package/build/src/index.d.ts

@@ -1,4 +1,6 @@
 export * from './feeef/feeef.js';
+export * from './delivery/parcel.js';
+export * from './delivery/delivery_carrier_client.js';
 export * from './core/entities/order.js';
 export * from './core/entities/store.js';
 export * from './core/entities/product.js';
@@ -50,5 +52,6 @@ export * from './feeef/services/notifications.js';
 export * from './feeef/services/storage.js';
 export * from './feeef/services/integrations.js';
 export * from './realtime/index.js';
+export * from './ai/ai_calculator.js';
 export * from './utils.js';
 export type { StoreIntegrations } from './core/entities/store.js';

package/package.json

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