feeef 0.12.11 → 0.12.12

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

@@ -1,13 +1,44 @@
 /**
- * Pure utility class for estimating AI generation costs client-side.
+ * Client-side AI cost estimator — deterministic mirror of the backend engine
+ * in `backend/app/services/ai_calculator.ts`.
  *
- * 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).
+ * The backend quote is always authoritative (it performs the wallet debit);
+ * this class exists so UIs can show "you will pay X DZD" before generating,
+ * with the SAME formulas and the SAME config inputs (`aiModels` + `models`
+ * catalog from the app-config endpoint). No network calls, no side effects.
  *
- * Canonical `aiModels.billing` keys — keep in sync: backend `configs_controller.ts`,
- * feeef `lib/core/app_config.dart`, admins_dashboard `src/lib/hooks/useOptions.ts`.
+ * ## Money model (identical to backend)
+ *
+ * ```
+ * provider cost (USD)                 what the AI provider charges
+ *   × exchangeRate                    → provider cost (DZD)
+ *   × retailMarkup.multiplier         → retail user cost (DZD)
+ *   + flat retail add-ons (DZD)       reference images, resolution tiers,
+ *                                     feature add-ons, attachment surcharge…
+ *   = userCostDzd
+ * ```
+ *
+ * Invariants:
+ *  1. `providerCostUsd`/`providerCostDzd` are ALWAYS the pre-markup provider
+ *     cost; `0` when unknown (retail floors) — never back-computed from the
+ *     retail price.
+ *  2. `userCostDzd` is the final retail amount, rounded to 3 decimals.
+ *
+ * ## Pricing precedence (identical to backend)
+ *
+ *  - **Text**  : legacy exact-id row (context tiers) → catalog
+ *    `pricing.prompt/completion` → named default legacy row
+ *    (`gemini-flash-lite-latest`) → free. Never `models[0]`.
+ *  - **Image** : catalog (`image_output_per_size_usd` → `image_output`) →
+ *    legacy exact-id `unit:'image'` row → `defaultImageCost` floor.
+ *    Legacy `localCost` (DZD) stays an explicit retail override.
+ *  - **Voice** : legacy row (`localCost` → flat `audio`/`voice` USD → `image`
+ *    unit for voice-capable rows → `tokens` per-1M), floored by
+ *    `voiceGeneration.minimumChargeUsd` unless `localCost` is set.
+ *
+ * Canonical `aiModels.billing` keys — keep in sync: backend
+ * `ai_models_billing.ts`, feeef.dart `ai_calculator.dart`, admins_dashboard
+ * `useOptions.ts`.
  */
 import { ModelsCatalogConfig } from '../core/models_catalog.js';
 /** Fallback DZD per USD when `aiModels.exchangeRate` is missing (mirror backend). */
@@ -107,6 +138,7 @@ export interface LegacyAiBillingFlat {
     VOICE_TTS_OUTPUT_TEXT_FACTOR: number;
     VOICE_TTS_TOKEN_CAP: number;
 }
+/** @deprecated Prefer `mergeAiModelsBilling` + `ResolvedAiModelsBilling`. */
 export declare function getLegacyAiBillingFlat(exchangeRate: number, resolved?: ResolvedAiModelsBilling): LegacyAiBillingFlat;
 /**
  * @deprecated Prefer `mergeAiModelsBilling` + `ResolvedAiModelsBilling`.
@@ -114,15 +146,18 @@ export declare function getLegacyAiBillingFlat(exchangeRate: number, resolved?:
  */
 export declare const AI_BILLING: LegacyAiBillingFlat;
 export interface AiModelPricing {
+    /** USD per 1M tokens (`unit: 'tokens'`) — `input` prompt / `output` completion. */
     input?: number;
+    /** For `unit: 'image' | 'audio' | 'voice'`: USD per single generation. */
     output?: number;
     unit: string;
+    /** Optional context tier, e.g. `<=200K` / `>200K` (tokens unit only). */
     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`).
+ * Undefined keys mean "use platform default for this model id" (see backend `gemini_image_grounding`).
  */
 export interface AiModelTools {
     googleSearch?: boolean;
@@ -131,6 +166,7 @@ export interface AiModelTools {
 export interface AiModelConfig {
     id: string;
     pricing?: AiModelPricing[];
+    /** Explicit admin retail price (DZD) for one generation — overrides computed retail. */
     localCost?: number | null;
     /** From aiModels — used so TTS billing does not fall back to the first (often image) row. */
     capabilities?: string[];
@@ -138,15 +174,24 @@ export interface AiModelConfig {
 }
 export interface AiCalculatorConfig {
     exchangeRate?: number;
+    /** Floor retail-provider DZD for one image when no source prices the model. */
     defaultImageCost?: number;
+    /** Flat retail DZD per reference image. */
     referenceImageCost?: number;
+    /** Flat retail DZD per resolution tier (`MEDIA_RESOLUTION_LOW|MEDIUM|HIGH`). */
     resolutionCosts?: Record<string, number>;
+    /** Legacy `aiModels.models` rows (admin overrides). */
     models?: AiModelConfig[];
-    /** Optional model catalog (`models` option): allows pricing.prompt/completion to price text models without aiModels rows. */
+    /** Multi-provider catalog (`models` option) — preferred pricing source. */
     modelsCatalog?: ModelsCatalogConfig;
     /** Optional `aiModels.billing` overrides (merged over [mergeAiModelsBilling] defaults). */
     billing?: AIModelsBilling | null;
 }
+/**
+ * Result of a cost estimation.
+ * `providerCostUsd`/`providerCostDzd` are pre-markup provider cost (0 when
+ * unknown); `userCostDzd` is the retail amount the wallet would be debited.
+ */
 export interface AiCostEstimate {
     providerCostUsd: number;
     providerCostDzd: number;
@@ -156,34 +201,92 @@ export interface AiCostEstimate {
     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;
-};
+/**
+ * Deterministic client-side mirror of the backend `AiCalculator`.
+ *
+ * ```ts
+ * const calc = new AiCalculator({ ...appConfig.aiModels, modelsCatalog: appConfig.models })
+ * const { userCostDzd } = calc.estimateImageGeneration({ modelId, imageSize: '2K' })
+ * ```
+ */
 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;
+    /** Exact-id legacy row (namespace tolerant). NO `models[0]` fallback. */
+    private findLegacyModel;
+    private findCatalogRow;
+    private modelHasVoiceCapability;
+    /** Context-tier row from a legacy `tokens` pricing list (mirror backend). */
+    private pickLegacyTokenRow;
+    /** Catalog `pricing.prompt`/`completion` (USD per token) → USD per 1M. */
+    private pickCatalogTokenPricing;
+    /**
+     * USD-per-1M pricing: legacy exact-id → catalog → named default legacy row →
+     * `null` (free). Mirrors backend `resolveTextTokenPricing`.
+     */
+    private resolveTextTokenPricing;
+    /**
+     * Catalog per-image USD, preferring the per-tier map
+     * (`image_output_per_size_usd`: requested tier → 1K → 2K → 4K → first
+     * positive), then flat `image_output`.
+     */
+    private pickCatalogImageUsd;
+    /** Legacy exact-id `unit:'image'` row output (USD per image). */
+    private pickLegacyImageUsd;
+    /** Attachment surcharge (stores/products/audio context files) in retail DZD. */
+    private attachmentExtraUserDzd;
     /**
-     * Estimate the cost of an image generation action.
-     * Covers: image gen, logo gen, editOrGenerateSimpleImage.
+     * Flat DZD resolution extras — ONE rule, mirror of backend
+     * `computeResolutionExtrasDzd`:
+     *  - output extra only when an output size tier is requested (1K→LOW,
+     *    2K→MEDIUM, 4K→HIGH),
+     *  - input extra only when an explicit input resolution is requested
+     *    (`max(0, cost[resolution] − cost[LOW])`).
+     */
+    private resolutionExtrasDzd;
+    /** Voice row: exact id → named TTS default → any voice-capable row. */
+    private findVoiceModel;
+    /**
+     * Flat provider USD per TTS generation: `audio`/`voice` units; for
+     * voice-capable rows also the `image` unit (legacy admin editor artifact).
+     */
+    private pickTtsFlatUsd;
+    /**
+     * Base TTS pricing (mirror backend `computeBaseVoiceoverBilling`):
+     * `localCost` → flat USD → tokens per-1M → floor; non-localCost paths are
+     * floored by `voiceGeneration.minimumChargeUsd`. Provider cost is honest
+     * (0 when only a retail figure is known).
+     */
+    private voiceoverBase;
+    private ttsTokenEstimates;
+    /**
+     * Image generation cost (image studio, logo studio, landing-page image).
+     *
+     * `userCostDzd = base(model, tier) × iterations + referenceImages ×
+     * referenceImageCost + attachment surcharge + resolution extras + feature
+     * add-ons`. Base precedence: catalog → legacy `unit:'image'` row →
+     * `defaultImageCost` floor; legacy `localCost` overrides retail.
      */
     estimateImageGeneration(options?: {
         modelId?: string;
         attachmentCount?: number;
         attachmentResolution?: 'low' | 'medium' | 'high';
+        /** Explicit input/reference processing resolution (input extra). */
         resolution?: string;
+        /**
+         * Effective output size tier (`1K`/`2K`/`4K`). Pass only for models that
+         * support output tiers — the backend resolves it via `pickImageSize`.
+         */
         imageSize?: string;
         iterations?: number;
         referenceImageCount?: number;
+        /** Catalog-driven feature add-ons (DZD), e.g. transparent background. */
+        featureAddonsDzd?: number;
     }): AiCostEstimate;
     /**
-     * Estimate the cost of a text generation action.
-     * Covers: updateProductUsingAi, generateSimpleCode, generateCustomComponentCode.
-     * Uses estimated tokens (exact cost billed post-generation).
+     * Text generation estimate (actual billing happens post-success from real
+     * token usage on the backend). Free when the model is unpriced everywhere
+     * or `promptTokens < freeTierMaxPromptTokens` (prompt tokens — not total).
      */
     estimateTextGeneration(options?: {
         modelId?: string;
@@ -191,7 +294,10 @@ export declare class AiCalculator {
         estimatedOutputTokens?: number;
     }): AiCostEstimate;
     /**
-     * Voiceover: base + attachment surcharge + optional script-enhancement add-on.
+     * Voiceover estimate: TTS base (heuristic tokens unless explicitly given) +
+     * attachment surcharge + optional script-enhancement add-on. The backend
+     * settles from ACTUAL usage (`computeVoiceoverSettlement`); this preview
+     * uses the same retail policy.
      */
     estimateVoiceover(options?: {
         modelId?: string;
@@ -202,6 +308,24 @@ export declare class AiCalculator {
         estimatedPromptTokens?: number;
         estimatedOutputTokens?: number;
     }): AiCostEstimate;
-    /** Get the fixed cost for image landing page generation. */
-    estimateImageLandingPage(): AiCostEstimate;
+    /**
+     * Landing-page image cost — identical formula to [estimateImageGeneration]
+     * (image-studio parity). Without an image model id, returns the fixed
+     * `billing.landingPageImage` charge (provider cost unknown → 0). A ≤ 0
+     * image quote also falls back to the fixed charge (zero-guard).
+     */
+    estimateImageLandingPage(options?: {
+        imageModelId?: string;
+        attachmentCount?: number;
+        attachmentResolution?: 'low' | 'medium' | 'high';
+        resolution?: string;
+        imageSize?: string;
+        referenceImageCount?: number;
+        featureAddonsDzd?: number;
+    }): AiCostEstimate;
 }
+/** Heuristic TTS token counts using **default** billing only (keep in sync with backend). */
+export declare function defaultVoiceTtsTokenEstimates(scriptCharLength: number, attachmentCount: number): {
+    promptTokens: number;
+    outputTokens: number;
+};

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

@@ -3,6 +3,8 @@ export declare enum OrderStatus {
     pending = "pending",
     review = "review",
     accepted = "accepted",
+    /** Confirmed, but still needs merchant action before processing/completed. */
+    followup = "followup",
     processing = "processing",
     completed = "completed",
     cancelled = "cancelled"

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

@@ -303,6 +303,10 @@ export interface ProductUpdateInput {
     type?: ProductType;
     decoration?: ProductDecoration;
     integrationsData?: IntegrationsData;
+    /** Moderation (admin): ISO date to verify, null to unverify. */
+    verifiedAt?: string | null;
+    /** Moderation (admin): ISO date to block, null to unblock. */
+    blockedAt?: string | null;
 }
 /**
  * Product report/analytics data

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

@@ -219,6 +219,8 @@ export interface PublicInventoryIntegration {
     showUnavailableOnFrontend: boolean;
 }
 export interface PublicStoreIntegrations {
+    /** Global Meta integration; credentials and ad accounts never included. */
+    meta: PublicMetaIntegration | null;
     metaPixel: PublicMetaPixelIntegration | null;
     tiktokPixel: PublicTiktokPixelIntegration | null;
     googleAnalytics: PublicGoogleAnalyticsIntegration | null;
@@ -253,6 +255,12 @@ export interface StoreMember {
     createdAt: any;
     active: boolean;
     metadata: Record<string, any>;
+    /**
+     * Fine-grained RBAC scopes (e.g. `orders`, `products.read`, `store.integrations`).
+     * Empty/undefined = legacy unrestricted access for the member's role.
+     * Parent scopes imply `.read` children (`orders` ⇒ `orders.read`).
+     */
+    scopes?: string[];
 }
 export declare enum StoreInviteStatus {
     pending = "pending",
@@ -277,12 +285,16 @@ export interface StoreInvite {
         name: string;
         iconUrl?: string;
     };
+    /** RBAC scopes copied onto the member when the invite is accepted. */
+    scopes?: string[];
 }
 export interface CreateStoreInviteInput {
     email: string;
     role: StoreMemberRole;
     expiresAt?: string;
     metadata?: Record<string, any>;
+    /** RBAC scopes to grant on acceptance (see {@link StoreMember.scopes}). */
+    scopes?: string[];
 }
 /** How order sync handles line items with no inventory bucket for their SKU. */
 export type MissingInventoryBucketPolicy = 'ignore' | 'reject';
@@ -514,6 +526,79 @@ export interface TiktokPixel {
     id: string;
     accessToken?: string;
 }
+/**
+ * An ad account the merchant chose to manage from Feeef.
+ */
+export interface MetaAdAccountRef {
+    /** Graph node id, `act_123`. */
+    id: string;
+    /** Bare numeric id, `123`. */
+    accountId: string;
+    name?: string;
+    currency?: string;
+    timezoneName?: string;
+    accountStatus?: number;
+}
+/** Everything ads-related on the Meta integration. */
+export interface MetaAdsConfig {
+    active?: boolean;
+    adAccounts?: MetaAdAccountRef[];
+    defaultAdAccountId?: string | null;
+    /** Default insights window for the dashboard, e.g. `last_7d`. */
+    defaultDatePreset?: string | null;
+    /** Extra hosts that count as this store's storefront when matching ad links. */
+    extraStoreHosts?: string[];
+    metadata?: Record<string, any>;
+}
+/**
+ * Meta OAuth credentials.
+ *
+ * Server-side only — the token is encrypted at rest and written exclusively by
+ * the OAuth callback. It is stripped from every client-facing projection, and
+ * `mergeIntegrationsPatch` in the backend refuses to accept it from a client.
+ */
+export interface MetaOAuthCredentials {
+    /** AES-encrypted access token. Never present in API responses. */
+    accessTokenEnc: string;
+    tokenType?: string;
+    expiresAt?: string;
+    /** Scopes Meta actually granted, from `debug_token`. */
+    scopes?: string[];
+    connectedAt?: string;
+    connectedByUserId?: string;
+    metaUserId?: string;
+}
+/**
+ * Global Meta integration (`store.integrations.meta`).
+ *
+ * Credentials live at the top level and are shared by every Meta feature.
+ * Ads live under `ads`; pixels remain on the legacy {@link MetaPixelIntegration}
+ * key for now and may move here later.
+ */
+export interface MetaIntegration {
+    active: boolean;
+    oauth2?: MetaOAuthCredentials | null;
+    /** Meta identity the token belongs to, for display + reconnect detection. */
+    account?: {
+        id: string;
+        name?: string;
+    } | null;
+    ads?: MetaAdsConfig | null;
+    metadata?: Record<string, any>;
+}
+/** Storefront-safe Meta integration — credentials and ad accounts excluded. */
+export interface PublicMetaIntegration {
+    active: boolean;
+    ads: {
+        active: boolean;
+    } | null;
+}
+/**
+ * Generates public Meta integration data.
+ * `oauth2`, `account`, and the ad-account list are intentionally excluded — none
+ * of it belongs on a storefront page.
+ */
+export declare const generatePublicStoreIntegrationMeta: (meta: MetaIntegration | null | undefined) => PublicMetaIntegration | null;
 export interface MetaPixelIntegration {
     id: string;
     pixels: MetaPixel[];
@@ -559,6 +644,19 @@ export interface GoogleSheetsIntegration {
     metadata: Record<string, any>;
     simple?: boolean;
     columns?: GoogleSheetsColumn<any>[];
+    /**
+     * When true, draft (abandoned-cart) orders are written to a dedicated
+     * sheet tab (`draftSheetName`) instead of the main tab (`name`).
+     * When the order leaves the draft status (e.g. becomes pending), its row is
+     * removed from the draft tab and a fresh row is inserted into the main tab.
+     * Disabled by default.
+     */
+    draftSheetEnabled?: boolean;
+    /**
+     * Tab title used for draft orders when `draftSheetEnabled` is true.
+     * Falls back to the platform default ("الطلبات المتروكة") when empty.
+     */
+    draftSheetName?: string | null;
 }
 export interface GoogleTagsIntegration {
     id: string;
@@ -786,12 +884,15 @@ export interface PublicSecurityIntegration {
     options: PublicSecurityOptions;
 }
 /**
- * Webhook event types for order lifecycle
+ * Webhook event types for order and product lifecycle
  */
 export declare enum WebhookEvent {
     ORDER_CREATED = "orderCreated",
     ORDER_UPDATED = "orderUpdated",
-    ORDER_DELETED = "orderDeleted"
+    ORDER_DELETED = "orderDeleted",
+    PRODUCT_CREATED = "productCreated",
+    PRODUCT_UPDATED = "productUpdated",
+    PRODUCT_DELETED = "productDeleted"
 }
 /**
  * Individual webhook configuration
@@ -815,7 +916,7 @@ export interface WebhookConfig {
     metadata: Record<string, any>;
 }
 /**
- * Webhooks integration configuration for real-time order notifications
+ * Webhooks integration configuration for real-time order and product notifications
  */
 export interface WebhooksIntegration {
     /** List of configured webhooks */
@@ -952,6 +1053,11 @@ export interface PublicConnectorsIntegration {
 export interface StoreIntegrations {
     [key: string]: any;
     metadata?: Record<string, any>;
+    /**
+     * Global Meta integration — credentials shared by every Meta feature.
+     * Ads live here today; pixels may move over from `metaPixel` later.
+     */
+    meta?: MetaIntegration;
     metaPixel?: MetaPixelIntegration;
     tiktokPixel?: TiktokPixelIntegration;
     googleAnalytics?: GoogleAnalyticsIntegration;
@@ -1115,6 +1221,8 @@ export interface AddStoreMemberInput {
     role: StoreMemberRole;
     name?: string;
     metadata?: Record<string, any>;
+    /** RBAC scopes to grant (see {@link StoreMember.scopes}). Empty/undefined = unrestricted for the role. */
+    scopes?: string[];
 }
 /**
  * Input for updating a store member
@@ -1123,4 +1231,6 @@ export interface UpdateStoreMemberInput {
     role?: StoreMemberRole;
     name?: string;
     metadata?: Record<string, any>;
+    /** Replacement RBAC scopes (see {@link StoreMember.scopes}). Omit to keep current scopes. */
+    scopes?: string[];
 }

package/build/src/core/oauth_scopes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OAuth / member RBAC scope catalog — aligned with backend
+ * `app/oauth_scopes.ts` (`MEMBER_SCOPES` + `auth`, `apps`).
+ *
+ * Keep this list in sync when adding a store resource. Unknown strings are
+ * rejected by the API validators.
+ */
+/** Store member RBAC scopes (parent implies `.read` child). */
+export declare const MEMBER_SCOPES: readonly ["store", "store.read", "store.settings", "store.integrations", "store.members", "orders", "orders.read", "products", "products.read", "categories", "categories.read", "pages", "pages.read", "product_landing_pages", "product_landing_pages.read", "shipping_prices", "shipping_prices.read", "template_components", "template_components.read", "store_templates", "store_templates.read", "finance", "finance.read", "inventory", "inventory.read"];
+export type MemberScope = (typeof MEMBER_SCOPES)[number];
+/** Scopes for developer tooling / delegation (not store-specific RBAC). */
+export declare const OAUTH_PLATFORM_SCOPES: readonly ["auth", "apps"];
+/**
+ * Identity-only grant when an app is registered without scopes.
+ * Never `*` — empty registration must not escalate to full access.
+ */
+export declare const DEFAULT_OAUTH_SCOPES: readonly ["auth"];
+/** Every scope string allowed on OAuth apps and access tokens. */
+export declare const OAUTH_SCOPES: readonly ["store", "store.read", "store.settings", "store.integrations", "store.members", "orders", "orders.read", "products", "products.read", "categories", "categories.read", "pages", "pages.read", "product_landing_pages", "product_landing_pages.read", "shipping_prices", "shipping_prices.read", "template_components", "template_components.read", "store_templates", "store_templates.read", "finance", "finance.read", "inventory", "inventory.read", "auth", "apps"];
+export type OAuthScope = (typeof OAUTH_SCOPES)[number];

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

@@ -197,7 +197,7 @@ export declare class FeeeF {
      * @param {AxiosInstance} config.client - The Axios instance used for making HTTP requests.
      * @param {boolean | number} config.cache - The caching configuration. Set to `false` to disable caching, or provide a number to set the cache TTL in milliseconds.
      */
-    constructor({ apiKey, client, cache, baseURL }: FeeeFConfig);
+    constructor({ apiKey, client, baseURL }: FeeeFConfig);
     /**
      * Sets a header for all requests
      * @param {string} key - The header key.

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

@@ -30,7 +30,11 @@ export interface AppCreateInput {
     /** Optional app logo URL. */
     logoUrl?: string;
     redirectUris: string[];
-    scopes: string[];
+    /**
+     * Registered scope catalog. Optional — omit or pass `[]` for an
+     * identity-only app (`auth`). Never treated as full access.
+     */
+    scopes?: string[];
     userId?: string;
 }
 /**

package/build/src/index.d.ts

@@ -1,5 +1,6 @@
 export * from './feeef/feeef.js';
 export * from './core/models_catalog.js';
+export * from './core/oauth_scopes.js';
 export * from './delivery/parcel.js';
 export * from './delivery/delivery_carrier_client.js';
 export * from './core/entities/order.js';

package/package.json

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