feeef 0.9.0 → 0.9.2

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

@@ -1,18 +1,24 @@
 /**
  * City Entity
  *
- * Represents a city with composite key (countryCode + stateCode + name).
+ * No separate `id` or `code`: identity is **countryCode + stateCode + name**.
+ * Use **`name`** (English-normalized) for stored values, shipping payloads, and
+ * `<option value>` — not a translated string from `locales`.
  */
 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) */
+    /**
+     * Canonical English-normalized city name (part of composite primary key).
+     * This is the value to persist (`shippingCity`, cart address) and to use as
+     * the select value — not `locales.ar` etc.
+     */
     name: string;
     /** Additional metadata as key-value pairs */
     metadata: Record<string, any>;
-    /** Localized names by language code (e.g., { en: "New York", ar: "نيويورك" }) */
+    /** Display-only translations keyed by language code (`ar`, `en`, `fr`, …). */
     locales?: Record<string, string>;
     /** Creation timestamp */
     createdAt: any;

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

@@ -43,6 +43,8 @@ export interface StoreEntity {
     googleAnalyticsId?: string | null;
     googleTagsId?: string | null;
     members?: Record<string, StoreMember>;
+    /** Active full-site template (`store_templates.id`) when set. */
+    templateId?: string | null;
 }
 export declare const generatePublicStoreIntegrations: (integrations: StoreIntegrations | null | undefined) => PublicStoreIntegrations | null;
 export declare const generatePublicStoreIntegrationCustomFields: (customFields: any | null | undefined) => PublicCustomFieldsIntegration | null | undefined;

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

@@ -0,0 +1,68 @@
+/**
+ * Full-site template package (per-store `store_templates` row).
+ *
+ * Multi-page `data` (TemplateData-shaped) plus `schema` (TemplateSchema-shaped).
+ * Same policy/version/catalog patterns as template components, without component `code`.
+ */
+import { TemplateComponentPolicy } from './template_component.js';
+/** Reuse the same wire values as `template_components` (`store_templates_policy` matches). */
+export { TemplateComponentPolicy as StoreTemplatePolicy } from './template_component.js';
+export interface StoreTemplateEntity {
+    id: string;
+    storeId: string;
+    userId: string;
+    title: string;
+    subtitle: string | null;
+    body: string | null;
+    category: string | null;
+    tags: string[];
+    imageUrl: string | null;
+    screenshots: string[];
+    demoUrl: string | null;
+    price: number;
+    discount: number | null;
+    license: string | null;
+    /** TemplateSchema-shaped editor/storefront contract. */
+    schema: Record<string, unknown>;
+    /** TemplateData-shaped site instance data (mirrors `Store.metadata.templateData` when active). */
+    data: Record<string, unknown>;
+    policy: TemplateComponentPolicy;
+    parentId: string | null;
+    version: number;
+    createdAt: any;
+    updatedAt: any | null;
+    deletedAt: any | null;
+}
+export interface StoreTemplateCreateInput {
+    title: string;
+    schema?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+    policy?: TemplateComponentPolicy;
+    subtitle?: string | null;
+    body?: string | null;
+    category?: string | null;
+    tags?: string[];
+    imageUrl?: string | null;
+    screenshots?: string[];
+    demoUrl?: string | null;
+    price?: number;
+    discount?: number | null;
+    license?: string | null;
+    parentId?: string | null;
+}
+export interface StoreTemplateUpdateInput {
+    title?: string;
+    subtitle?: string | null;
+    body?: string | null;
+    category?: string | null;
+    tags?: string[];
+    imageUrl?: string | null;
+    screenshots?: string[];
+    demoUrl?: string | null;
+    price?: number;
+    discount?: number | null;
+    license?: string | null;
+    schema?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+    policy?: TemplateComponentPolicy;
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Template-component library entry.
+ *
+ * One row in the per-store **library of reusable custom components** that
+ * the template editor can drop in by reference instead of inlining
+ * `code` + `propsSchema` per instance.
+ *
+ * Conceptual split:
+ *  - This entity holds the **identity** of a custom component: the JSX
+ *    `code`, its `propsSchema` / `slotsSchema`, and seed defaults.
+ *  - Each placement of the component in a store's `templateData` carries
+ *    only its instance-level `props` / `slots` and a reference back to
+ *    this entry by `id`. Editing this entry's `code` therefore updates
+ *    every reference in one shot.
+ *
+ * Backed by the Postgres table `template_components`
+ * (`backend/database/migrations/.../create_template_components_table.ts`).
+ */
+export interface TemplateComponentEntity {
+    /** Surrogate primary key (24-char cuid2 from backend `genid()`). */
+    id: string;
+    /** Owner store. References cascade-delete with the store. */
+    storeId: string;
+    /** Creator user. Audit field; never null. */
+    userId: string;
+    title: string;
+    /** Short one-liner shown in cards and pickers. */
+    subtitle: string | null;
+    /** Long markdown body for the entry's detail page. */
+    body: string | null;
+    /** Free-form taxonomy ('hero' | 'cta' | 'product' | …). */
+    category: string | null;
+    tags: string[];
+    /** Primary preview image (square-ish, 1:1 or 4:3). */
+    imageUrl: string | null;
+    /** Additional preview images for the marketplace gallery. */
+    screenshots: string[];
+    /** Optional public demo URL (e.g. a Lithium playground page). */
+    demoUrl: string | null;
+    /** One-time price in the platform default currency (DZD today). */
+    price: number;
+    /** Absolute discount in the same currency. Nullable; defaults to 0. */
+    discount: number | null;
+    /** Free-text license identifier (e.g. 'MIT', 'proprietary'). */
+    license: string | null;
+    /** JSX source executed by `react-live` in the storefront. */
+    code: string;
+    /** Editor schema for instance-editable props. */
+    propsSchema: Record<string, unknown>;
+    /** Editor schema for named slots, when the component supports children. */
+    slotsSchema: Record<string, unknown> | null;
+    /** Seed values for new instances — instances may override freely. */
+    propsDefault: Record<string, unknown>;
+    /** Seed slot children for new instances. */
+    slotsDefault: Record<string, unknown> | null;
+    /** Editor-only responsive layout hint for slots (sm/md/lg). */
+    slotsLayout: Record<string, unknown> | null;
+    /**
+     * Combined audience + lifecycle in a single dimension.
+     * See {@link TemplateComponentPolicy} for the precise semantics of
+     * each value.
+     */
+    policy: TemplateComponentPolicy;
+    /** Fork tree: id of the entry this one was copied from, if any. */
+    parentId: string | null;
+    /**
+     * Monotonic counter bumped on every meaningful edit.
+     * Used as a cache-key suffix and (later) as the pinning target.
+     */
+    version: number;
+    createdAt: any;
+    updatedAt: any | null;
+    /** Soft-delete marker. Resolver treats deleted entries as missing. */
+    deletedAt: any | null;
+}
+/**
+ * Combined audience + lifecycle dimension for a library entry.
+ *
+ *  - `private`     Owner-only (default). Not shareable, hidden from
+ *                  marketplace and direct-link installs.
+ *  - `unlisted`    Accessible by direct link / install token only;
+ *                  not surfaced in marketplace search.
+ *  - `public`      Discoverable and installable from the marketplace.
+ *  - `deprecated`  Still resolves for existing followers and remains
+ *                  visible in the marketplace with a "deprecated" badge,
+ *                  but new installs are discouraged.
+ */
+export declare enum TemplateComponentPolicy {
+    private = "private",
+    unlisted = "unlisted",
+    public = "public",
+    deprecated = "deprecated"
+}
+/**
+ * Input for creating a new library entry.
+ *
+ * `storeId` and `userId` are derived server-side from the authenticated
+ * request; they are intentionally absent here.
+ */
+export interface TemplateComponentCreateInput {
+    title: string;
+    code: string;
+    /** Defaults to `'private'` server-side when omitted. */
+    policy?: TemplateComponentPolicy;
+    subtitle?: string | null;
+    body?: string | null;
+    category?: string | null;
+    tags?: string[];
+    imageUrl?: string | null;
+    screenshots?: string[];
+    demoUrl?: string | null;
+    price?: number;
+    discount?: number | null;
+    license?: string | null;
+    propsSchema?: Record<string, unknown>;
+    slotsSchema?: Record<string, unknown> | null;
+    propsDefault?: Record<string, unknown>;
+    slotsDefault?: Record<string, unknown> | null;
+    slotsLayout?: Record<string, unknown> | null;
+    /** When forking an existing entry, point back at it for the fork tree. */
+    parentId?: string | null;
+}
+/**
+ * Input for updating an existing library entry.
+ *
+ * Per the Node SDK nullability convention:
+ *  - `undefined` = field unchanged
+ *  - `null`      = clear the nullable field
+ *
+ * The server bumps `version` automatically when any of `code`,
+ * `propsSchema`, `slotsSchema`, `propsDefault`, `slotsDefault`,
+ * or `slotsLayout` changes; clients do not send `version`.
+ */
+export interface TemplateComponentUpdateInput {
+    title?: string;
+    subtitle?: string | null;
+    body?: string | null;
+    category?: string | null;
+    tags?: string[];
+    imageUrl?: string | null;
+    screenshots?: string[];
+    demoUrl?: string | null;
+    price?: number;
+    discount?: number | null;
+    license?: string | null;
+    code?: string;
+    propsSchema?: Record<string, unknown>;
+    slotsSchema?: Record<string, unknown> | null;
+    propsDefault?: Record<string, unknown>;
+    slotsDefault?: Record<string, unknown> | null;
+    slotsLayout?: Record<string, unknown> | null;
+    policy?: TemplateComponentPolicy;
+}

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

@@ -20,6 +20,8 @@ import { ProductLandingPageTemplatesRepository } from './repositories/product_la
 import { ProductLandingPagesRepository } from './repositories/product_landing_pages.js';
 import { ImagePromptTemplatesRepository } from './repositories/image_prompt_templates.js';
 import { ImageGenerationsRepository } from './repositories/image_generations.js';
+import { TemplateComponentsRepository } from './repositories/template_components.js';
+import { StoreTemplatesRepository } from './repositories/store_templates.js';
 import { CartService } from './services/cart.js';
 import { ActionsService } from './services/actions.js';
 import { NotificationsService } from './services/notifications.js';
@@ -85,6 +87,19 @@ export declare class FeeeF {
      * The repository for managing async image generations.
      */
     imageGenerations: ImageGenerationsRepository;
+    /**
+     * The repository for the per-store **library of reusable custom
+     * components** + the cross-store **marketplace**. Components live in
+     * `template_components` and are referenced from store templateData by
+     * `refId` so a single source can power many placements.
+     *
+     * @see ResolveComponentsResponse for the storefront resolver path.
+     */
+    templateComponents: TemplateComponentsRepository;
+    /**
+     * Full-site template library rows (`store_templates`) + marketplace.
+     */
+    storeTemplates: StoreTemplatesRepository;
     /**
      * The repository for managing users.
      */

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

@@ -9,7 +9,10 @@ export interface OrderModelTrackOptions {
     params?: Record<string, any>;
 }
 /**
- * Schema for sending an order from an anonymous user
+ * Body for `POST .../orders/send` (matches backend `SendOrderSchema`).
+ *
+ * **Do not** use `stateCode`, `cityCode`, or `address` — the API ignores them.
+ * Use `shippingState`, `shippingCity`, `shippingAddress` respectively.
  */
 export interface SendOrderSchema {
     id?: string;
@@ -18,8 +21,11 @@ export interface SendOrderSchema {
     customerPhone: string;
     customerEmail?: string;
     source?: string;
+    /** Street / address line (not `address`). */
     shippingAddress?: string;
+    /** English-normalized city name (not `cityCode`). */
     shippingCity?: string;
+    /** State wilaya code string, e.g. `"05"` (not `stateCode`). */
     shippingState?: string;
     shippingCountry?: string;
     shippingType: ShippingType;

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

@@ -0,0 +1,40 @@
+import { AxiosInstance } from 'axios';
+import { ListResponse, ModelRepository } from './repository.js';
+import { StoreTemplateEntity, StoreTemplateCreateInput, StoreTemplateUpdateInput } from '../../core/entities/store_template.js';
+import { TemplateComponentPolicy } from '../../core/entities/template_component.js';
+export interface StoreTemplateListOptions {
+    page?: number;
+    offset?: number;
+    limit?: number;
+    storeId?: string;
+    q?: string;
+    search?: string;
+    policy?: TemplateComponentPolicy | TemplateComponentPolicy[];
+    category?: string | string[];
+    tags?: string | string[];
+    parentId?: string;
+    filterator?: string | object;
+    orderBy?: 'created_at' | 'updated_at' | 'title' | 'price';
+    params?: Record<string, unknown>;
+}
+export declare class StoreTemplatesRepository extends ModelRepository<StoreTemplateEntity, StoreTemplateCreateInput, StoreTemplateUpdateInput> {
+    constructor(client: AxiosInstance);
+    list(options?: StoreTemplateListOptions): Promise<ListResponse<StoreTemplateEntity>>;
+    fork(options: {
+        fromId: string;
+        storeId: string;
+        title?: string;
+    }): Promise<StoreTemplateEntity>;
+    /**
+     * Set `stores.template_id` to this template (same row in `store_templates`)
+     * and copy `data` into `store.metadata.templateData`. Does not create a new
+     * `store_templates` row — use [fork] to duplicate a template into a store.
+     */
+    install(options: {
+        fromId: string;
+        storeId: string;
+    }): Promise<{
+        storeTemplate: StoreTemplateEntity;
+        store: Record<string, unknown>;
+    }>;
+}

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

@@ -0,0 +1,86 @@
+import { AxiosInstance } from 'axios';
+import { ListResponse, ModelRepository } from './repository.js';
+import { TemplateComponentEntity, TemplateComponentCreateInput, TemplateComponentUpdateInput, TemplateComponentPolicy } from '../../core/entities/template_component.js';
+/**
+ * Filters accepted by `GET /api/v1/template_components`.
+ *
+ * Two surfaces share the same endpoint:
+ *  - **Library** — pass `storeId`. Returns all entries the caller has
+ *    access to under that store (private + unlisted + public + deprecated
+ *    when authenticated; only the discoverable subset for guests).
+ *  - **Marketplace** — omit `storeId`. Returns only `policy in
+ *    (public, deprecated)` across the whole platform.
+ *
+ * Free-text search and `filterator` are forwarded to the backend's
+ * filterator pipeline (`backend/app/models/filters/template_component_filter.ts`).
+ * The shape mirrors `ProductsListOptions` so this feels consistent
+ * for callers already using other repositories.
+ */
+export interface TemplateComponentListOptions {
+    page?: number;
+    offset?: number;
+    limit?: number;
+    /** Library mode — scope to one store. Omit for marketplace mode. */
+    storeId?: string;
+    /** Free-text search across title/subtitle/body/category/tags. */
+    q?: string;
+    search?: string;
+    /** Inclusive policy filter (defaults to all visible). */
+    policy?: TemplateComponentPolicy | TemplateComponentPolicy[];
+    /** Inclusive category filter. */
+    category?: string | string[];
+    /** Inclusive tag filter (any-of). */
+    tags?: string | string[];
+    /** Filter by fork ancestry. */
+    parentId?: string;
+    /**
+     * Raw `filterator` JSON payload. When set, the simple shorthand
+     * filters above are merged in so callers can mix-and-match. See
+     * the filterator README in the backend for grammar.
+     */
+    filterator?: string | object;
+    orderBy?: 'created_at' | 'updated_at' | 'title' | 'price';
+    /** Catch-all for filters this repo doesn't enumerate yet. */
+    params?: Record<string, unknown>;
+}
+/**
+ * Repository for the per-store **library of reusable custom components**
+ * and the cross-store **marketplace** of public ones.
+ *
+ * On top of the standard CRUD inherited from {@link ModelRepository}, this
+ * exposes a {@link fork} action that copies a (typically marketplace) entry
+ * into the caller's store with a fresh id and a `parentId` pointing at the
+ * source — the "I want full control of this component" escape hatch from
+ * the reference model.
+ *
+ * Note on `version`: never sent on create/update. The server bumps it
+ * automatically when one of the meaningful columns (`code`,
+ * `propsSchema`, `slotsSchema`, `propsDefault`, `slotsDefault`,
+ * `slotsLayout`) changes.
+ */
+export declare class TemplateComponentsRepository extends ModelRepository<TemplateComponentEntity, TemplateComponentCreateInput, TemplateComponentUpdateInput> {
+    constructor(client: AxiosInstance);
+    /**
+     * Override `list` to expose the full search/filter surface and accept
+     * either the structured options or a raw `filterator` payload.
+     */
+    list(options?: TemplateComponentListOptions): Promise<ListResponse<TemplateComponentEntity>>;
+    /**
+     * Fork an existing entry into a target store.
+     *
+     * Always called against the **source** entry's id (`fromId`). The
+     * destination store must be one the caller can `create` in. The new
+     * entry starts in `private` — surfacing it requires a follow-up
+     * `update`. `parentId` of the fork points at `fromId`, preserving the
+     * fork tree for analytics/audit.
+     *
+     * Optional `title` lets the caller rename at fork time so multiple
+     * forks of the same source can coexist in the destination library
+     * without collision in the picker.
+     */
+    fork(options: {
+        fromId: string;
+        storeId: string;
+        title?: string;
+    }): Promise<TemplateComponentEntity>;
+}

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

@@ -1,4 +1,45 @@
 import { AxiosInstance } from 'axios';
+import { TemplateComponentPolicy } from '../../core/entities/template_component.js';
+/**
+ * Slim, render-ready shape returned by `actions/resolveComponents` for a
+ * single library entry. The storefront merges these into the template's
+ * `reference`-typed placements before rendering.
+ *
+ * Catalog metadata (subtitle, body, tags, screenshots, …) is intentionally
+ * excluded — the resolve endpoint optimizes for cache size and wire weight,
+ * and the marketplace UI uses the regular `template_components` REST
+ * resource for browsing.
+ */
+export interface ResolvedTemplateComponent {
+    id: string;
+    storeId: string;
+    /**
+     * Monotonic version (server-managed). Storefronts can use this as a
+     * pinning target to detect drift between resolve calls.
+     */
+    version: number;
+    policy: TemplateComponentPolicy;
+    title: string;
+    /** JSX source consumed by `react-live`. */
+    code: string;
+    propsSchema: Record<string, unknown>;
+    slotsSchema: Record<string, unknown> | null;
+    propsDefault: Record<string, unknown>;
+    slotsDefault: Record<string, unknown> | null;
+    slotsLayout: Record<string, unknown> | null;
+    /** Mirror of `policy === 'deprecated'` for cheap rendering hints. */
+    deprecated: boolean;
+}
+/**
+ * Response shape for `actions/resolveComponents`. `resolved` is keyed by
+ * library entry id so the renderer can do an O(1) lookup; `missing` lists
+ * ids that did not exist or weren't visible to the caller (the renderer
+ * should fall back to a no-op for these).
+ */
+export interface ResolveComponentsResponse {
+    resolved: Record<string, ResolvedTemplateComponent>;
+    missing: string[];
+}
 /**
  * Actions service for performing various actions on the Feeef API.
  * Similar to the Dart Actions class, this provides methods for file uploads,
@@ -28,4 +69,31 @@ export declare class ActionsService {
         fieldId: string;
         storeId: string;
     }>;
+    /**
+     * Resolve a batch of library `template_components` by id for the
+     * storefront / editor renderer.
+     *
+     * Used by SSR pages that walk the template tree, gather every
+     * `reference`-typed placement's `refId`, and need the renderable
+     * `{ code, propsSchema, slotsSchema, defaults }` payload before the
+     * page can be rendered.
+     *
+     * Authorization is per-id and happens server-side: same-store entries
+     * are always returned; cross-store entries must be `policy in
+     * (public, deprecated)`. Anything else is silently dropped into
+     * `missing` so the page can render with a fallback (typically a
+     * no-op or a "This component is unavailable" placeholder).
+     *
+     * The response is cached server-side per `(storeId, version)` for 24h
+     * and the cache is invalidated automatically on any
+     * `template_components` mutation or `Store` update — clients can call
+     * this as often as they like without extra coordination.
+     *
+     * @param storeId - The store identifying the rendering context.
+     * @param ids     - Library entry ids to resolve. Deduplicated server-side.
+     */
+    resolveComponents({ storeId, ids, }: {
+        storeId: string;
+        ids: string[];
+    }): Promise<ResolveComponentsResponse>;
 }

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

@@ -43,6 +43,20 @@ export declare class CartService extends NotifiableService {
     private shippingAddress;
     private cachedSubtotal;
     private currentItem;
+    /**
+     * Monotonic counter bumped in {@link CartService.notify} for React
+     * `useSyncExternalStore` — lets storefront UI subscribe to cart changes
+     * without re-rendering unrelated provider subtrees (see Lithium FeeefCartProvider).
+     */
+    private _reactSnapshotVersion;
+    /**
+     * @override
+     */
+    notify(): void;
+    /**
+     * Snapshot for React `useSyncExternalStore` (increments on every cart mutation).
+     */
+    getReactSnapshot(): number;
     /**
      * Generates a unique key for a cart item based on product ID, variant path, offer code, and addons
      * @param item - The cart item to generate a key for

package/build/src/index.d.ts

@@ -8,6 +8,8 @@ export * from './core/entities/product_landing_page.js';
 export * from './core/entities/product_landing_page_template.js';
 export * from './core/entities/attachment.js';
 export * from './core/entities/image_prompt_template.js';
+export * from './core/entities/template_component.js';
+export * from './core/entities/store_template.js';
 export * from './core/entities/image_generation.js';
 export * from './core/entities/user.js';
 export * from './core/entities/shipping_method.js';
@@ -33,6 +35,8 @@ export * from './feeef/repositories/products.js';
 export * from './feeef/repositories/orders.js';
 export * from './feeef/repositories/image_prompt_templates.js';
 export * from './feeef/repositories/image_generations.js';
+export * from './feeef/repositories/template_components.js';
+export * from './feeef/repositories/store_templates.js';
 export * from './feeef/repositories/categories.js';
 export * from './feeef/repositories/feedbacks.js';
 export * from './feeef/repositories/countries.js';

package/package.json

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