@reactionary/meilisearch 0.6.3

package/README.md

@@ -0,0 +1,11 @@
+# meilisearch
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build meilisearch` to build the library.
+
+## Running unit tests
+
+Run `nx test meilisearch` to execute the unit tests via [Vitest](https://vitest.dev/).

package/capabilities/index.js

@@ -0,0 +1,3 @@
+export * from "./product-search.capability.js";
+export * from "./product-recommendations.capability.js";
+export * from "./order-search.capability.js";

package/capabilities/order-search.capability.js

@@ -0,0 +1,165 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp(target, key, result);
+  return result;
+};
+import {
+  OrderSearchQueryByTermSchema,
+  OrderSearchResultSchema,
+  OrderSearchCapability,
+  Reactionary,
+  success,
+  AddressIdentifierSchema
+} from "@reactionary/core";
+import { MeiliSearch } from "meilisearch";
+class MeilisearchOrderSearchCapability extends OrderSearchCapability {
+  config;
+  factory;
+  constructor(config, cache, context, factory) {
+    super(cache, context);
+    this.config = config;
+    this.factory = factory;
+  }
+  queryByTermPayload(payload) {
+    const filters = [];
+    if (payload.search.orderStatus && payload.search.orderStatus.length > 0) {
+      const statusFilters = payload.search.orderStatus.map((status) => `orderStatus = "${this.mapOrderStatus(status)}"`).join(" OR ");
+      filters.push(`(${statusFilters})`);
+    }
+    if (payload.search.user) {
+      filters.push(`userIdentifier = "${payload.search.user.userId}"`);
+    }
+    if (payload.search.startDate) {
+      filters.push(`orderDateTimestamp >= ${new Date(payload.search.startDate).getTime()}`);
+    }
+    if (payload.search.endDate) {
+      filters.push(`orderDateTimestamp <= ${new Date(payload.search.endDate).getTime()}`);
+    }
+    if (payload.search.partNumber && payload.search.partNumber.length > 0) {
+      const partNumberFilters = payload.search.partNumber.map((partNumber) => `items.sku = "${partNumber}"`).join(" OR ");
+      filters.push(`(${partNumberFilters})`);
+    }
+    const searchOptions = {
+      offset: (payload.search.paginationOptions.pageNumber - 1) * payload.search.paginationOptions.pageSize,
+      limit: payload.search.paginationOptions.pageSize,
+      filter: filters.length > 0 ? filters.join(" AND ") : void 0,
+      sort: ["orderDateTimestamp:desc"]
+    };
+    return searchOptions;
+  }
+  async queryByTerm(payload) {
+    const client = new MeiliSearch({
+      host: this.config.apiUrl,
+      apiKey: this.config.apiKey
+    });
+    const index = client.index(this.config.orderIndexName);
+    const remote = await index.search(
+      payload.search.term || "",
+      this.queryByTermPayload(payload)
+    );
+    const result = this.parsePaginatedResult(remote, payload);
+    return success(this.factory.parseOrderSearchResult(this.context, result, payload));
+  }
+  mapOrderStatus(status) {
+    const statusMap = {
+      AwaitingPayment: "awaiting_payment",
+      ReleasedToFulfillment: "released_to_fulfillment",
+      Shipped: "shipped",
+      Cancelled: "cancelled"
+    };
+    return statusMap[status] || status;
+  }
+  mapFromNativeOrderStatus(nativeStatus) {
+    const statusMap = {
+      awaiting_payment: "AwaitingPayment",
+      released_to_fulfillment: "ReleasedToFulfillment",
+      shipped: "Shipped",
+      cancelled: "Cancelled"
+    };
+    return statusMap[nativeStatus] || "AwaitingPayment";
+  }
+  mapFromNativeInventoryStatus(nativeStatus) {
+    const statusMap = {
+      not_allocated: "NotAllocated",
+      allocated: "Allocated",
+      preordered: "Preordered",
+      backordered: "Backordered"
+    };
+    return statusMap[nativeStatus] || "NotAllocated";
+  }
+  composeAddressFromNativeAddress(nativeAddress) {
+    return {
+      identifier: AddressIdentifierSchema.parse({
+        nickName: "shipping"
+      }),
+      firstName: "",
+      lastName: "",
+      streetAddress: nativeAddress.address1,
+      streetNumber: nativeAddress.address2,
+      city: nativeAddress.city,
+      postalCode: nativeAddress.postalCode,
+      countryCode: nativeAddress.country,
+      region: ""
+    };
+  }
+  parseSingle(body) {
+    const identifier = { key: body.orderIdentifier };
+    const userId = {
+      userId: body.userIdentifier
+    };
+    const customerName = body.customerName;
+    const shippingAddress = this.composeAddressFromNativeAddress(body.shippingAddress);
+    const orderDate = body.orderDate;
+    const orderStatus = this.mapFromNativeOrderStatus(body.orderStatus);
+    const inventoryStatus = this.mapFromNativeInventoryStatus(body.inventoryStatus);
+    const totalAmount = {
+      currency: body.currency || this.context.languageContext.currencyCode,
+      value: body.totalAmount
+    };
+    const order = {
+      identifier,
+      userId,
+      customerName,
+      shippingAddress,
+      orderDate,
+      orderStatus,
+      inventoryStatus,
+      totalAmount
+    };
+    return order;
+  }
+  parsePaginatedResult(body, query) {
+    const identifier = {
+      ...query.search
+    };
+    const orders = body.hits.map((hit) => {
+      return this.parseSingle(hit);
+    });
+    const totalCount = body.estimatedTotalHits || body.hits.length;
+    const totalPages = Math.ceil(totalCount / (body.limit || 1));
+    const result = {
+      identifier,
+      pageNumber: Math.floor((body.offset || 0) / (body.limit || 1)) + 1,
+      pageSize: body.limit || orders.length,
+      totalCount,
+      totalPages,
+      items: orders
+    };
+    return result;
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: OrderSearchQueryByTermSchema,
+    outputSchema: OrderSearchResultSchema
+  })
+], MeilisearchOrderSearchCapability.prototype, "queryByTerm", 1);
+export {
+  MeilisearchOrderSearchCapability
+};

package/capabilities/product-recommendations.capability.js

@@ -0,0 +1,79 @@
+import {
+  ProductRecommendationsCapability,
+  ImageSchema,
+  ProductSearchResultItemVariantSchema
+} from "@reactionary/core";
+import { MeiliSearch } from "meilisearch";
+class MeilisearchProductRecommendationsCapability extends ProductRecommendationsCapability {
+  config;
+  constructor(config, cache, context) {
+    super(cache, context);
+    this.config = config;
+  }
+  getSimilarProductsRecommendationsPayload(query) {
+    return {
+      id: query.sourceProduct.key,
+      limit: query.numberOfRecommendations,
+      embedder: this.config.useAIEmbedding
+    };
+  }
+  /**
+   * Get similar product recommendations
+   * Uses semantic search to find visually or data-wise similar products
+   */
+  async getSimilarProductsRecommendations(query) {
+    const client = new MeiliSearch({
+      host: this.config.apiUrl,
+      apiKey: this.config.apiKey
+    });
+    const index = client.index(this.config.indexName);
+    if (!this.config.useAIEmbedding) {
+      console.warn("AI embedding is not enabled in configuration. Similar product recommendations will be based on keyword matching, which may not provide optimal results.");
+      return [];
+    }
+    try {
+      const response = await index.searchSimilarDocuments(this.getSimilarProductsRecommendationsPayload(query));
+      return this.parseRecommendations(response, "similar");
+    } catch (error) {
+      console.error("Error fetching similar product recommendations:", error);
+      return [];
+    }
+  }
+  /**
+   * Maps Meilisearch search results to ProductRecommendation format
+   */
+  parseRecommendations(recommendation, algorithm) {
+    return recommendation.hits.map((hit) => ({
+      recommendationIdentifier: {
+        key: hit.objectID,
+        algorithm
+      },
+      recommendationReturnType: "productSearchResultItem",
+      product: this.parseSearchResultItem(hit)
+    }));
+  }
+  parseSearchResultItem(body) {
+    const product = {
+      identifier: { key: body.objectID },
+      name: body.name || body.objectID,
+      slug: body.slug || body.objectID,
+      variants: [...body.variants || []].map((variant) => this.parseVariant(variant, body))
+    };
+    return product;
+  }
+  parseVariant(variant, product) {
+    const result = ProductSearchResultItemVariantSchema.parse({
+      variant: {
+        sku: variant.sku
+      },
+      image: ImageSchema.parse({
+        sourceUrl: variant.image,
+        altText: product.name || ""
+      })
+    });
+    return result;
+  }
+}
+export {
+  MeilisearchProductRecommendationsCapability
+};

package/capabilities/product-search.capability.js

@@ -0,0 +1,203 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result)
+    __defProp(target, key, result);
+  return result;
+};
+import {
+  FacetIdentifierSchema,
+  FacetValueIdentifierSchema,
+  ImageSchema,
+  ProductSearchCapability,
+  ProductSearchQueryByTermSchema,
+  ProductSearchResultFacetSchema,
+  ProductSearchResultFacetValueSchema,
+  ProductSearchResultItemVariantSchema,
+  ProductSearchResultSchema,
+  Reactionary,
+  success
+} from "@reactionary/core";
+import { MeiliSearch } from "meilisearch";
+class MeilisearchProductSearchCapability extends ProductSearchCapability {
+  config;
+  factory;
+  constructor(config, cache, context, factory) {
+    super(cache, context);
+    this.config = config;
+    this.factory = factory;
+  }
+  queryByTermPayload(payload) {
+    const facetsThatAreNotCategory = payload.search.facets.filter((x) => x.facet.key !== "categories");
+    const categoryFacet = payload.search.facets.find((x) => x.facet.key === "categories") || payload.search.categoryFilter;
+    const finalFilters = [...payload.search.filters || []];
+    const finalFacetFilters = [
+      ...facetsThatAreNotCategory.map(
+        (x) => `${x.facet.key}="${x.key}"`
+      )
+    ];
+    if (categoryFacet) {
+      finalFilters.push(`categories = "${categoryFacet.key}"`);
+    }
+    let filterString;
+    if (finalFilters.length > 0 || finalFacetFilters.length > 0) {
+      const allFilters = [...finalFilters, ...finalFacetFilters];
+      filterString = allFilters.join(" AND ");
+    }
+    const searchOptions = {
+      offset: (payload.search.paginationOptions.pageNumber - 1) * payload.search.paginationOptions.pageSize,
+      limit: payload.search.paginationOptions.pageSize,
+      facets: ["*"],
+      filter: filterString
+    };
+    if (this.config.useAIEmbedding) {
+      searchOptions.hybrid = {
+        embedder: this.config.useAIEmbedding
+      };
+    }
+    return searchOptions;
+  }
+  async queryByTerm(payload) {
+    const client = new MeiliSearch({
+      host: this.config.apiUrl,
+      apiKey: this.config.apiKey
+    });
+    const index = client.index(this.config.indexName);
+    const remote = await index.search(payload.search.term, this.queryByTermPayload(payload));
+    const result = this.parsePaginatedResult(remote, payload);
+    for (const selectedFacet of payload.search.facets) {
+      const facet = result.facets.find((f) => f.identifier.key === selectedFacet.facet.key);
+      if (facet) {
+        const value = facet.values.find((v) => v.identifier.key === selectedFacet.key);
+        if (value) {
+          value.active = true;
+        }
+      }
+    }
+    return success(this.factory.parseSearchResult(this.context, result, payload));
+  }
+  async createCategoryNavigationFilter(payload) {
+    const facetIdentifier = FacetIdentifierSchema.parse({
+      key: "categories"
+    });
+    const facetValueIdentifier = FacetValueIdentifierSchema.parse({
+      facet: facetIdentifier,
+      key: payload.categoryPath.map((c) => c.name).join(" > ")
+    });
+    return success(facetValueIdentifier);
+  }
+  parseSingle(body) {
+    const product = {
+      identifier: { key: body.objectID },
+      name: body.name || body.objectID,
+      slug: body.slug || body.objectID,
+      variants: [...body.variants || []].map((variant) => this.parseVariant(variant, body))
+    };
+    return product;
+  }
+  parseVariant(variant, product) {
+    const result = ProductSearchResultItemVariantSchema.parse({
+      variant: {
+        sku: variant.sku
+      },
+      image: ImageSchema.parse({
+        sourceUrl: variant.image,
+        altText: product.name || ""
+      })
+    });
+    return result;
+  }
+  parsePaginatedResult(body, query) {
+    const items = body.hits.map((hit) => this.parseSingle(hit));
+    let facets = [];
+    if (body.facetDistribution) {
+      for (const id in body.facetDistribution) {
+        const f = body.facetDistribution[id];
+        const facetId = FacetIdentifierSchema.parse({
+          key: id
+        });
+        const facet = this.parseFacet(facetId, f);
+        if (facet.values.length > 0) {
+          facets.push(facet);
+        }
+      }
+    }
+    const selectedCategoryFacet = query.search.facets.find((x) => x.facet.key === "categories") || query.search.categoryFilter;
+    let subCategoryFacet;
+    if (selectedCategoryFacet) {
+      const valueDepth = selectedCategoryFacet.key.split(" > ").length;
+      subCategoryFacet = facets.find((f) => f.identifier.key === `hierarchy.lvl${valueDepth}`);
+    } else {
+      subCategoryFacet = facets.find((f) => f.identifier.key === "hierarchy.lvl0");
+    }
+    if (subCategoryFacet) {
+      subCategoryFacet.identifier = FacetIdentifierSchema.parse({
+        key: "categories"
+      });
+      subCategoryFacet.name = "Categories";
+      for (const v of subCategoryFacet.values) {
+        const pathParts = v.identifier.key.split(" > ");
+        v.identifier.facet = subCategoryFacet.identifier;
+        v.name = pathParts[pathParts.length - 1];
+      }
+    }
+    facets = facets.filter((f) => !f.identifier.key.startsWith("hierarchy.lvl"));
+    const totalPages = Math.ceil((body.estimatedTotalHits || 0) / query.search.paginationOptions.pageSize);
+    const result = {
+      identifier: {
+        term: query.search.term,
+        facets: query.search.facets,
+        filters: query.search.filters,
+        paginationOptions: query.search.paginationOptions
+      },
+      pageNumber: query.search.paginationOptions.pageNumber,
+      pageSize: query.search.paginationOptions.pageSize,
+      totalCount: body.estimatedTotalHits || 0,
+      totalPages,
+      items,
+      facets
+    };
+    return result;
+  }
+  parseFacet(facetIdentifier, facetValues) {
+    const result = ProductSearchResultFacetSchema.parse({
+      identifier: facetIdentifier,
+      name: facetIdentifier.key.replace(/_/g, " "),
+      values: []
+    });
+    for (const vid in facetValues) {
+      const fv = facetValues[vid];
+      const facetValueIdentifier = FacetValueIdentifierSchema.parse({
+        facet: facetIdentifier,
+        key: vid
+      });
+      result.values.push(this.parseFacetValue(facetValueIdentifier, vid, fv));
+    }
+    return result;
+  }
+  parseFacetValue(facetValueIdentifier, label, count) {
+    return ProductSearchResultFacetValueSchema.parse({
+      identifier: facetValueIdentifier,
+      name: label,
+      count,
+      active: false
+    });
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: ProductSearchQueryByTermSchema,
+    outputSchema: ProductSearchResultSchema,
+    cache: true,
+    cacheTimeToLiveInSeconds: 300,
+    currencyDependentCaching: false,
+    localeDependentCaching: true
+  })
+], MeilisearchProductSearchCapability.prototype, "queryByTerm", 1);
+export {
+  MeilisearchProductSearchCapability
+};

package/core/initialize.js

@@ -0,0 +1,78 @@
+import { OrderSearchResultSchema, ProductSearchResultSchema } from "@reactionary/core";
+import { MeilisearchProductSearchCapability } from "../capabilities/product-search.capability.js";
+import { MeilisearchProductRecommendationsCapability } from "../capabilities/product-recommendations.capability.js";
+import { MeilisearchOrderSearchCapability } from "../capabilities/order-search.capability.js";
+import {
+  MeilisearchCapabilitiesSchema
+} from "../schema/capabilities.schema.js";
+import { MeilisearchOrderSearchFactory } from "../factories/order-search/order-search.factory.js";
+import { MeilisearchProductSearchFactory } from "../factories/product-search/product-search.factory.js";
+import {
+  resolveCapabilityWithFactory,
+  resolveDirectCapability
+} from "./initialize.types.js";
+function withMeilisearchCapabilities(configuration, capabilities) {
+  return (cache, context) => {
+    const client = {};
+    const caps = MeilisearchCapabilitiesSchema.parse(capabilities);
+    if (caps.productSearch?.enabled) {
+      client.productSearch = resolveCapabilityWithFactory(
+        capabilities.productSearch,
+        {
+          factory: new MeilisearchProductSearchFactory(ProductSearchResultSchema),
+          capability: (args) => new MeilisearchProductSearchCapability(
+            args.config,
+            args.cache,
+            args.context,
+            args.factory
+          )
+        },
+        (factory) => ({
+          cache,
+          context,
+          config: configuration,
+          factory
+        })
+      );
+    }
+    if (caps.orderSearch?.enabled) {
+      client.orderSearch = resolveCapabilityWithFactory(
+        capabilities.orderSearch,
+        {
+          factory: new MeilisearchOrderSearchFactory(OrderSearchResultSchema),
+          capability: (args) => new MeilisearchOrderSearchCapability(
+            args.config,
+            args.cache,
+            args.context,
+            args.factory
+          )
+        },
+        (factory) => ({
+          cache,
+          context,
+          config: configuration,
+          factory
+        })
+      );
+    }
+    if (caps.productRecommendations?.enabled) {
+      client.productRecommendations = resolveDirectCapability(
+        capabilities.productRecommendations,
+        (args) => new MeilisearchProductRecommendationsCapability(
+          args.config,
+          args.cache,
+          args.context
+        ),
+        {
+          cache,
+          context,
+          config: configuration
+        }
+      );
+    }
+    return client;
+  };
+}
+export {
+  withMeilisearchCapabilities
+};

package/core/initialize.types.js

@@ -0,0 +1,13 @@
+function resolveCapabilityWithFactory(capability, defaults, buildCapabilityArgs) {
+  const factory = capability?.factory ?? defaults.factory;
+  const capabilityFactory = capability?.capability ?? defaults.capability;
+  return capabilityFactory(buildCapabilityArgs(factory));
+}
+function resolveDirectCapability(capability, defaultCapability, args) {
+  const capabilityFactory = capability?.capability ?? defaultCapability;
+  return capabilityFactory(args);
+}
+export {
+  resolveCapabilityWithFactory,
+  resolveDirectCapability
+};

package/factories/index.js

@@ -0,0 +1,2 @@
+export * from "./order-search/order-search.factory.js";
+export * from "./product-search/product-search.factory.js";

package/factories/order-search/order-search.factory.js

@@ -0,0 +1,12 @@
+class MeilisearchOrderSearchFactory {
+  orderSearchResultSchema;
+  constructor(orderSearchResultSchema) {
+    this.orderSearchResultSchema = orderSearchResultSchema;
+  }
+  parseOrderSearchResult(_context, data, _query) {
+    return this.orderSearchResultSchema.parse(data);
+  }
+}
+export {
+  MeilisearchOrderSearchFactory
+};

package/factories/product-search/product-search.factory.js

@@ -0,0 +1,12 @@
+class MeilisearchProductSearchFactory {
+  productSearchResultSchema;
+  constructor(productSearchResultSchema) {
+    this.productSearchResultSchema = productSearchResultSchema;
+  }
+  parseSearchResult(_context, data, _query) {
+    return this.productSearchResultSchema.parse(data);
+  }
+}
+export {
+  MeilisearchProductSearchFactory
+};

package/index.js

@@ -0,0 +1,8 @@
+export * from "./core/initialize.js";
+export * from "./core/initialize.types.js";
+export * from "./factories/index.js";
+export * from "./capabilities/product-search.capability.js";
+export * from "./capabilities/product-recommendations.capability.js";
+export * from "./capabilities/order-search.capability.js";
+export * from "./schema/configuration.schema.js";
+export * from "./schema/capabilities.schema.js";

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@reactionary/meilisearch",
+  "version": "0.6.3",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "vitest": "^4.0.9",
+    "@nx/vite": "22.4.5",
+    "@reactionary/core": "0.6.3",
+    "zod": "4.1.9",
+    "meilisearch": "^0.55.0"
+  },
+  "sideEffects": false
+}

package/schema/capabilities.schema.js

@@ -0,0 +1,23 @@
+import { CapabilitiesSchema } from "@reactionary/core";
+import * as z from "zod";
+const SearchCapabilitySchema = z.looseObject({
+  enabled: z.boolean(),
+  factory: z.unknown().optional(),
+  capability: z.unknown().optional()
+});
+const DirectCapabilitySchema = z.looseObject({
+  enabled: z.boolean(),
+  capability: z.unknown().optional()
+});
+const MeilisearchCapabilitiesSchema = CapabilitiesSchema.pick({
+  productSearch: true,
+  productRecommendations: true,
+  orderSearch: true
+}).extend({
+  productSearch: SearchCapabilitySchema.optional(),
+  orderSearch: SearchCapabilitySchema.optional(),
+  productRecommendations: DirectCapabilitySchema.optional()
+}).partial();
+export {
+  MeilisearchCapabilitiesSchema
+};

package/schema/configuration.schema.js

@@ -0,0 +1,11 @@
+import * as z from "zod";
+const MeilisearchConfigurationSchema = z.looseObject({
+  apiUrl: z.string(),
+  apiKey: z.string(),
+  indexName: z.string(),
+  orderIndexName: z.string(),
+  useAIEmbedding: z.string().optional()
+});
+export {
+  MeilisearchConfigurationSchema
+};

package/schema/index.js

@@ -0,0 +1,3 @@
+export * from "./configuration.schema.js";
+export * from "./capabilities.schema.js";
+export * from "./search.schema.js";

package/schema/search.schema.js

@@ -0,0 +1,13 @@
+import { ProductSearchIdentifierSchema, ProductSearchResultSchema } from "@reactionary/core";
+import * as z from "zod";
+const MeilisearchProductSearchIdentifierSchema = ProductSearchIdentifierSchema.extend({
+  key: z.string(),
+  index: z.string()
+});
+const MeilisearchProductSearchResultSchema = ProductSearchResultSchema.extend({
+  identifier: MeilisearchProductSearchIdentifierSchema.default(() => MeilisearchProductSearchIdentifierSchema.parse({}))
+});
+export {
+  MeilisearchProductSearchIdentifierSchema,
+  MeilisearchProductSearchResultSchema
+};

package/src/capabilities/index.d.ts

@@ -0,0 +1,3 @@
+export * from './product-search.capability.js';
+export * from './product-recommendations.capability.js';
+export * from './order-search.capability.js';

package/src/capabilities/order-search.capability.d.ts

@@ -0,0 +1,37 @@
+import { type Cache, type OrderSearchQueryByTerm, type OrderSearchResult, type OrderSearchResultItem, OrderSearchCapability, type RequestContext, type Result, type OrderStatus, type Address, type OrderInventoryStatus, type OrderSearchFactory, type OrderSearchFactoryOutput, type OrderSearchFactoryWithOutput } from '@reactionary/core';
+import { type SearchParams, type SearchResponse } from 'meilisearch';
+import type { MeilisearchConfiguration } from '../schema/configuration.schema.js';
+import type { MeilisearchOrderSearchFactory } from '../factories/order-search/order-search.factory.js';
+interface MeilisearchNativeOrderAddress {
+    address1: string;
+    address2: string;
+    city: string;
+    postalCode: string;
+    country: string;
+}
+interface MeilisearchNativeOrderRecord {
+    orderIdentifier: string;
+    userIdentifier: string;
+    customerName: string;
+    shippingAddress: MeilisearchNativeOrderAddress;
+    orderDate: string;
+    orderDateTimestamp: number;
+    orderStatus: string;
+    inventoryStatus: string;
+    totalAmount: number;
+    currency: string;
+}
+export declare class MeilisearchOrderSearchCapability<TFactory extends OrderSearchFactory = MeilisearchOrderSearchFactory> extends OrderSearchCapability<OrderSearchFactoryOutput<TFactory>> {
+    protected config: MeilisearchConfiguration;
+    protected factory: OrderSearchFactoryWithOutput<TFactory>;
+    constructor(config: MeilisearchConfiguration, cache: Cache, context: RequestContext, factory: OrderSearchFactoryWithOutput<TFactory>);
+    protected queryByTermPayload(payload: OrderSearchQueryByTerm): SearchParams;
+    queryByTerm(payload: OrderSearchQueryByTerm): Promise<Result<OrderSearchFactoryOutput<TFactory>>>;
+    protected mapOrderStatus(status: OrderStatus): string;
+    protected mapFromNativeOrderStatus(nativeStatus: string): OrderStatus;
+    protected mapFromNativeInventoryStatus(nativeStatus: string): OrderInventoryStatus;
+    protected composeAddressFromNativeAddress(nativeAddress: MeilisearchNativeOrderAddress): Address;
+    protected parseSingle(body: MeilisearchNativeOrderRecord): OrderSearchResultItem;
+    protected parsePaginatedResult(body: SearchResponse<MeilisearchNativeOrderRecord>, query: OrderSearchQueryByTerm): OrderSearchResult;
+}
+export {};

package/src/capabilities/product-recommendations.capability.d.ts

@@ -0,0 +1,37 @@
+import { type Cache, ProductRecommendationsCapability, type ProductRecommendation, type ProductRecommendationAlgorithmSimilarProductsQuery, type RequestContext, type ProductSearchResultItemVariant } from '@reactionary/core';
+import { type SearchResponse, type SearchSimilarDocumentsParams } from 'meilisearch';
+import type { MeilisearchConfiguration } from '../schema/configuration.schema.js';
+import type { MeilisearchNativeRecord, MeilisearchNativeVariant } from '../schema/index.js';
+/**
+ * MeilisearchProductRecommendationsCapability
+ *
+ * Provides product recommendations using Meilisearch's hybrid search and filtering capabilities.
+ * Supports frequentlyBoughtTogether, similar, related, and trendingInCategory algorithms.
+ *
+ * Note: This implementation uses semantic search (if AI embedding is enabled) and facet-based filtering.
+ * For production use, consider implementing more sophisticated recommendation logic or integrating
+ * with a dedicated recommendation engine.
+ */
+export declare class MeilisearchProductRecommendationsCapability extends ProductRecommendationsCapability {
+    protected config: MeilisearchConfiguration;
+    constructor(config: MeilisearchConfiguration, cache: Cache, context: RequestContext);
+    protected getSimilarProductsRecommendationsPayload(query: ProductRecommendationAlgorithmSimilarProductsQuery): SearchSimilarDocumentsParams;
+    /**
+     * Get similar product recommendations
+     * Uses semantic search to find visually or data-wise similar products
+     */
+    protected getSimilarProductsRecommendations(query: ProductRecommendationAlgorithmSimilarProductsQuery): Promise<ProductRecommendation[]>;
+    /**
+     * Maps Meilisearch search results to ProductRecommendation format
+     */
+    protected parseRecommendations(recommendation: SearchResponse<MeilisearchNativeRecord>, algorithm: string): ProductRecommendation[];
+    protected parseSearchResultItem(body: MeilisearchNativeRecord): {
+        identifier: {
+            key: string;
+        };
+        name: string;
+        slug: string;
+        variants: ProductSearchResultItemVariant[];
+    };
+    protected parseVariant(variant: MeilisearchNativeVariant, product: MeilisearchNativeRecord): ProductSearchResultItemVariant;
+}

package/src/capabilities/product-search.capability.d.ts

@@ -0,0 +1,53 @@
+import { type Cache, type FacetIdentifier, type FacetValueIdentifier, ProductSearchCapability, type ProductSearchFactory, type ProductSearchFactoryOutput, type ProductSearchFactoryWithOutput, type ProductSearchQueryByTerm, type ProductSearchQueryCreateNavigationFilter, type ProductSearchResultFacet, type ProductSearchResultFacetValue, type ProductSearchResultItemVariant, type RequestContext, type Result } from '@reactionary/core';
+import { type SearchParams, type SearchResponse } from 'meilisearch';
+import type { MeilisearchConfiguration } from '../schema/configuration.schema.js';
+import type { MeilisearchNativeRecord, MeilisearchNativeVariant } from '../schema/search.schema.js';
+import type { MeilisearchProductSearchFactory } from '../factories/product-search/product-search.factory.js';
+export declare class MeilisearchProductSearchCapability<TFactory extends ProductSearchFactory = MeilisearchProductSearchFactory> extends ProductSearchCapability<ProductSearchFactoryOutput<TFactory>> {
+    protected config: MeilisearchConfiguration;
+    protected factory: ProductSearchFactoryWithOutput<TFactory>;
+    constructor(config: MeilisearchConfiguration, cache: Cache, context: RequestContext, factory: ProductSearchFactoryWithOutput<TFactory>);
+    protected queryByTermPayload(payload: ProductSearchQueryByTerm): SearchParams;
+    queryByTerm(payload: ProductSearchQueryByTerm): Promise<Result<ProductSearchFactoryOutput<TFactory>>>;
+    createCategoryNavigationFilter(payload: ProductSearchQueryCreateNavigationFilter): Promise<Result<FacetValueIdentifier>>;
+    protected parseSingle(body: MeilisearchNativeRecord): {
+        identifier: {
+            key: string;
+        };
+        name: string;
+        slug: string;
+        variants: ProductSearchResultItemVariant[];
+    };
+    protected parseVariant(variant: MeilisearchNativeVariant, product: MeilisearchNativeRecord): ProductSearchResultItemVariant;
+    protected parsePaginatedResult(body: SearchResponse<MeilisearchNativeRecord>, query: ProductSearchQueryByTerm): {
+        identifier: {
+            term: string;
+            facets: {
+                facet: {
+                    key: string;
+                };
+                key: string;
+            }[];
+            filters: string[];
+            paginationOptions: {
+                pageNumber: number;
+                pageSize: number;
+            };
+        };
+        pageNumber: number;
+        pageSize: number;
+        totalCount: number;
+        totalPages: number;
+        items: {
+            identifier: {
+                key: string;
+            };
+            name: string;
+            slug: string;
+            variants: ProductSearchResultItemVariant[];
+        }[];
+        facets: ProductSearchResultFacet[];
+    };
+    protected parseFacet(facetIdentifier: FacetIdentifier, facetValues: Record<string, number>): ProductSearchResultFacet;
+    protected parseFacetValue(facetValueIdentifier: FacetValueIdentifier, label: string, count: number): ProductSearchResultFacetValue;
+}

package/src/core/initialize.d.ts

@@ -0,0 +1,5 @@
+import type { Cache, RequestContext } from '@reactionary/core';
+import { type MeilisearchCapabilities } from '../schema/capabilities.schema.js';
+import type { MeilisearchConfiguration } from '../schema/configuration.schema.js';
+import { type MeilisearchClientFromCapabilities } from './initialize.types.js';
+export declare function withMeilisearchCapabilities<T extends MeilisearchCapabilities>(configuration: MeilisearchConfiguration, capabilities: T): (cache: Cache, context: RequestContext) => MeilisearchClientFromCapabilities<T>;

package/src/core/initialize.types.d.ts

@@ -0,0 +1,45 @@
+import type { ClientFromCapabilities, OrderSearchFactory, ProductSearchFactory } from '@reactionary/core';
+import type { MeilisearchCapabilities } from '../schema/capabilities.schema.js';
+import type { MeilisearchOrderSearchFactory } from '../factories/order-search/order-search.factory.js';
+import type { MeilisearchProductSearchFactory } from '../factories/product-search/product-search.factory.js';
+import type { MeilisearchOrderSearchCapability } from '../capabilities/order-search.capability.js';
+import type { MeilisearchProductRecommendationsCapability } from '../capabilities/product-recommendations.capability.js';
+import type { MeilisearchProductSearchCapability } from '../capabilities/product-search.capability.js';
+type EnabledCapability<TCapability> = TCapability extends {
+    enabled: true;
+} ? true : false;
+type NormalizeConfiguredCapabilities<T extends MeilisearchCapabilities> = Omit<T, 'productSearch' | 'orderSearch' | 'productRecommendations'> & {
+    productSearch?: EnabledCapability<T['productSearch']>;
+    orderSearch?: EnabledCapability<T['orderSearch']>;
+    productRecommendations?: EnabledCapability<T['productRecommendations']>;
+};
+type ExtractCapabilityFactory<TCapability, TContract, TDefaultFactory> = TCapability extends {
+    enabled: true;
+    factory?: infer TFactory;
+} ? TFactory extends TContract ? TFactory : TDefaultFactory : TDefaultFactory;
+type ExtractCapabilityImplementation<TCapability, TDefaultCapability> = TCapability extends {
+    enabled: true;
+    capability?: infer TCapabilityFactory;
+} ? TCapabilityFactory extends (...args: unknown[]) => infer TResolvedCapability ? TResolvedCapability : TDefaultCapability : TDefaultCapability;
+type CapabilityOverride<TCapability, TKey extends string, TResolvedCapability> = TCapability extends {
+    enabled: true;
+} ? {
+    [K in TKey]: TResolvedCapability;
+} : Record<never, never>;
+type ProductSearchFactoryFor<T extends MeilisearchCapabilities> = ExtractCapabilityFactory<T['productSearch'], ProductSearchFactory, MeilisearchProductSearchFactory>;
+type OrderSearchFactoryFor<T extends MeilisearchCapabilities> = ExtractCapabilityFactory<T['orderSearch'], OrderSearchFactory, MeilisearchOrderSearchFactory>;
+type ProductSearchCapabilityFor<T extends MeilisearchCapabilities> = ExtractCapabilityImplementation<T['productSearch'], MeilisearchProductSearchCapability<ProductSearchFactoryFor<T>>>;
+type OrderSearchCapabilityFor<T extends MeilisearchCapabilities> = ExtractCapabilityImplementation<T['orderSearch'], MeilisearchOrderSearchCapability<OrderSearchFactoryFor<T>>>;
+type ProductRecommendationsCapabilityFor<T extends MeilisearchCapabilities> = ExtractCapabilityImplementation<T['productRecommendations'], MeilisearchProductRecommendationsCapability>;
+export type MeilisearchClientFromCapabilities<T extends MeilisearchCapabilities> = Omit<ClientFromCapabilities<NormalizeConfiguredCapabilities<T>>, 'productSearch' | 'orderSearch' | 'productRecommendations'> & CapabilityOverride<T['productSearch'], 'productSearch', ProductSearchCapabilityFor<T>> & CapabilityOverride<T['orderSearch'], 'orderSearch', OrderSearchCapabilityFor<T>> & CapabilityOverride<T['productRecommendations'], 'productRecommendations', ProductRecommendationsCapabilityFor<T>>;
+export declare function resolveCapabilityWithFactory<TFactory, TResolvedCapability, TCapabilityArgs>(capability: {
+    factory?: TFactory;
+    capability?: (args: TCapabilityArgs) => TResolvedCapability;
+} | undefined, defaults: {
+    factory: TFactory;
+    capability: (args: TCapabilityArgs) => TResolvedCapability;
+}, buildCapabilityArgs: (factory: TFactory) => TCapabilityArgs): TResolvedCapability;
+export declare function resolveDirectCapability<TResolvedCapability, TCapabilityArgs>(capability: {
+    capability?: (args: TCapabilityArgs) => TResolvedCapability;
+} | undefined, defaultCapability: (args: TCapabilityArgs) => TResolvedCapability, args: TCapabilityArgs): TResolvedCapability;
+export {};

package/src/factories/index.d.ts

@@ -0,0 +1,2 @@
+export * from './order-search/order-search.factory.js';
+export * from './product-search/product-search.factory.js';

package/src/factories/order-search/order-search.factory.d.ts

@@ -0,0 +1,7 @@
+import type { AnyOrderSearchResultSchema, OrderSearchFactory, OrderSearchQueryByTerm, OrderSearchResultSchema, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+export declare class MeilisearchOrderSearchFactory<TOrderSearchResultSchema extends AnyOrderSearchResultSchema = typeof OrderSearchResultSchema> implements OrderSearchFactory<TOrderSearchResultSchema> {
+    readonly orderSearchResultSchema: TOrderSearchResultSchema;
+    constructor(orderSearchResultSchema: TOrderSearchResultSchema);
+    parseOrderSearchResult(_context: RequestContext, data: unknown, _query: OrderSearchQueryByTerm): z.output<TOrderSearchResultSchema>;
+}

package/src/factories/product-search/product-search.factory.d.ts

@@ -0,0 +1,7 @@
+import type { AnyProductSearchResultSchema, ProductSearchFactory, ProductSearchQueryByTerm, ProductSearchResultSchema, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+export declare class MeilisearchProductSearchFactory<TProductSearchResultSchema extends AnyProductSearchResultSchema = typeof ProductSearchResultSchema> implements ProductSearchFactory<TProductSearchResultSchema> {
+    readonly productSearchResultSchema: TProductSearchResultSchema;
+    constructor(productSearchResultSchema: TProductSearchResultSchema);
+    parseSearchResult(_context: RequestContext, data: unknown, _query: ProductSearchQueryByTerm): z.output<TProductSearchResultSchema>;
+}

package/src/index.d.ts

@@ -0,0 +1,8 @@
+export * from './core/initialize.js';
+export * from './core/initialize.types.js';
+export * from './factories/index.js';
+export * from './capabilities/product-search.capability.js';
+export * from './capabilities/product-recommendations.capability.js';
+export * from './capabilities/order-search.capability.js';
+export * from './schema/configuration.schema.js';
+export * from './schema/capabilities.schema.js';

package/src/schema/capabilities.schema.d.ts

@@ -0,0 +1,49 @@
+import type { Cache, OrderSearchFactory, OrderSearchFactoryWithOutput, OrderSearchCapability, ProductRecommendationsCapability, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability, RequestContext } from '@reactionary/core';
+import type { MeilisearchConfiguration } from './configuration.schema.js';
+import * as z from 'zod';
+export declare const MeilisearchCapabilitiesSchema: z.ZodObject<{
+    productSearch: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    orderSearch: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    productRecommendations: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export interface MeilisearchCapabilityFactoryArgs {
+    cache: Cache;
+    context: RequestContext;
+    config: MeilisearchConfiguration;
+}
+export interface MeilisearchProductSearchCapabilityFactoryArgs<TFactory extends ProductSearchFactory = ProductSearchFactory> extends MeilisearchCapabilityFactoryArgs {
+    factory: ProductSearchFactoryWithOutput<TFactory>;
+}
+export interface MeilisearchOrderSearchCapabilityFactoryArgs<TFactory extends OrderSearchFactory = OrderSearchFactory> extends MeilisearchCapabilityFactoryArgs {
+    factory: OrderSearchFactoryWithOutput<TFactory>;
+}
+export interface MeilisearchProductSearchCapabilityConfig<TFactory extends ProductSearchFactory = ProductSearchFactory, TCapability extends ProductSearchCapability = ProductSearchCapability> {
+    enabled: boolean;
+    factory?: ProductSearchFactoryWithOutput<TFactory>;
+    capability?: (args: MeilisearchProductSearchCapabilityFactoryArgs<TFactory>) => TCapability;
+}
+export interface MeilisearchOrderSearchCapabilityConfig<TFactory extends OrderSearchFactory = OrderSearchFactory, TCapability extends OrderSearchCapability = OrderSearchCapability> {
+    enabled: boolean;
+    factory?: OrderSearchFactoryWithOutput<TFactory>;
+    capability?: (args: MeilisearchOrderSearchCapabilityFactoryArgs<TFactory>) => TCapability;
+}
+export interface MeilisearchProductRecommendationsCapabilityConfig<TCapability extends ProductRecommendationsCapability = ProductRecommendationsCapability> {
+    enabled: boolean;
+    capability?: (args: MeilisearchCapabilityFactoryArgs) => TCapability;
+}
+export type MeilisearchCapabilities<TProductSearchFactory extends ProductSearchFactory = ProductSearchFactory, TProductSearchCapability extends ProductSearchCapability = ProductSearchCapability, TOrderSearchFactory extends OrderSearchFactory = OrderSearchFactory, TOrderSearchCapability extends OrderSearchCapability = OrderSearchCapability, TProductRecommendationsCapability extends ProductRecommendationsCapability = ProductRecommendationsCapability> = {
+    productSearch?: MeilisearchProductSearchCapabilityConfig<TProductSearchFactory, TProductSearchCapability>;
+    orderSearch?: MeilisearchOrderSearchCapabilityConfig<TOrderSearchFactory, TOrderSearchCapability>;
+    productRecommendations?: MeilisearchProductRecommendationsCapabilityConfig<TProductRecommendationsCapability>;
+};

package/src/schema/configuration.schema.d.ts

@@ -0,0 +1,9 @@
+import * as z from 'zod';
+export declare const MeilisearchConfigurationSchema: z.ZodObject<{
+    apiUrl: z.ZodString;
+    apiKey: z.ZodString;
+    indexName: z.ZodString;
+    orderIndexName: z.ZodString;
+    useAIEmbedding: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type MeilisearchConfiguration = z.infer<typeof MeilisearchConfigurationSchema>;

package/src/schema/index.d.ts

@@ -0,0 +1,3 @@
+export * from './configuration.schema.js';
+export * from './capabilities.schema.js';
+export * from './search.schema.js';

package/src/schema/search.schema.d.ts

@@ -0,0 +1,113 @@
+import * as z from 'zod';
+export declare const MeilisearchProductSearchIdentifierSchema: z.ZodObject<{
+    term: z.ZodString;
+    facets: z.ZodArray<z.ZodObject<{
+        facet: z.ZodObject<{
+            key: z.ZodString;
+        }, z.core.$loose>;
+        key: z.ZodString;
+    }, z.core.$strip>>;
+    filters: z.ZodArray<z.ZodString>;
+    paginationOptions: z.ZodObject<{
+        pageNumber: z.ZodDefault<z.ZodNumber>;
+        pageSize: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>;
+    categoryFilter: z.ZodOptional<z.ZodObject<{
+        facet: z.ZodObject<{
+            key: z.ZodString;
+        }, z.core.$loose>;
+        key: z.ZodString;
+    }, z.core.$strip>>;
+    key: z.ZodString;
+    index: z.ZodString;
+}, z.core.$loose>;
+export declare const MeilisearchProductSearchResultSchema: z.ZodObject<{
+    pageNumber: z.ZodNumber;
+    pageSize: z.ZodNumber;
+    totalCount: z.ZodNumber;
+    totalPages: z.ZodNumber;
+    items: z.ZodArray<z.ZodObject<{
+        identifier: z.ZodObject<{
+            key: z.ZodString;
+        }, z.core.$loose>;
+        name: z.ZodString;
+        slug: z.ZodString;
+        variants: z.ZodArray<z.ZodObject<{
+            variant: z.ZodObject<{
+                sku: z.ZodString;
+            }, z.core.$loose>;
+            image: z.ZodObject<{
+                sourceUrl: z.ZodDefault<z.ZodString>;
+                altText: z.ZodDefault<z.ZodString>;
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>;
+            options: z.ZodOptional<z.ZodObject<{
+                identifier: z.ZodObject<{
+                    key: z.ZodString;
+                }, z.core.$loose>;
+                name: z.ZodString;
+                value: z.ZodObject<{
+                    identifier: z.ZodObject<{
+                        option: z.ZodObject<{
+                            key: z.ZodString;
+                        }, z.core.$loose>;
+                        key: z.ZodString;
+                    }, z.core.$loose>;
+                    label: z.ZodString;
+                }, z.core.$loose>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    facets: z.ZodArray<z.ZodObject<{
+        identifier: z.ZodObject<{
+            key: z.ZodString;
+        }, z.core.$loose>;
+        name: z.ZodString;
+        values: z.ZodArray<z.ZodObject<{
+            identifier: z.ZodObject<{
+                facet: z.ZodObject<{
+                    key: z.ZodString;
+                }, z.core.$loose>;
+                key: z.ZodString;
+            }, z.core.$strip>;
+            name: z.ZodString;
+            count: z.ZodNumber;
+            active: z.ZodBoolean;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    identifier: z.ZodDefault<z.ZodObject<{
+        term: z.ZodString;
+        facets: z.ZodArray<z.ZodObject<{
+            facet: z.ZodObject<{
+                key: z.ZodString;
+            }, z.core.$loose>;
+            key: z.ZodString;
+        }, z.core.$strip>>;
+        filters: z.ZodArray<z.ZodString>;
+        paginationOptions: z.ZodObject<{
+            pageNumber: z.ZodDefault<z.ZodNumber>;
+            pageSize: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$loose>;
+        categoryFilter: z.ZodOptional<z.ZodObject<{
+            facet: z.ZodObject<{
+                key: z.ZodString;
+            }, z.core.$loose>;
+            key: z.ZodString;
+        }, z.core.$strip>>;
+        key: z.ZodString;
+        index: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export type MeilisearchProductSearchResult = z.infer<typeof MeilisearchProductSearchResultSchema>;
+export type MeilisearchProductSearchIdentifier = z.infer<typeof MeilisearchProductSearchIdentifierSchema>;
+export interface MeilisearchNativeVariant {
+    sku: string;
+    image: string;
+}
+export interface MeilisearchNativeRecord {
+    objectID: string;
+    slug?: string;
+    name?: string;
+    variants: Array<MeilisearchNativeVariant>;
+}