nexoraiq / connector

1.0.4 2026-11-02 12:33 UTC

Requires

• php: ~8.1.0||~8.2.0||~8.3.0||~8.4.0||~8.5.0
• laminas/laminas-uri: ^2.9
• magento/framework: ^103.0.6
• magento/module-authorization: ^100.4
• magento/module-backend: ^102.0
• magento/module-catalog: ^104.0
• magento/module-catalog-inventory: ^100.4
• magento/module-catalog-search: ^102.0
• magento/module-checkout: ^100.4
• magento/module-config: ^101.2
• magento/module-configurable-product: ^100.4
• magento/module-cron: ^100.4
• magento/module-customer: ^103.0
• magento/module-eav: ^102.1
• magento/module-indexer: ^100.4
• magento/module-integration: ^100.4
• magento/module-quote: ^101.2
• magento/module-sales: ^103.0
• magento/module-search: ^101.1
• magento/module-store: ^101.1
• magento/module-swatches: ^100.4
• magento/module-theme: ^101.1
• magento/module-ui: ^101.2
• magento/module-webapi: ^100.4

Suggests

• hyva-themes/magento2-default-theme: Hyvä storefront templates (detected automatically)
• magento/module-csp: Content Security Policy allow-list for the NexorAIQ API
• magento/module-graph-ql: GraphQL search proxy and storeConfig fields for headless storefronts
• magento/module-inventory-api: Multi-Source Inventory: salable quantity and real-time stock sync
• magento/module-inventory-sales: Multi-Source Inventory: stock updates after orders
• magento/module-review: Review ratings in the synced product data
• magento/module-store-graph-ql: NexorAIQ fields on the GraphQL storeConfig query

proprietary

• NexorAIQ

Published on Packagist.org on 2026-11-02 12:36 UTC

README

AI-powered search and multilingual product discovery for Magento.

Website · Developer Docs · GraphQL API · Service Status · Book a Demo

LinkedIn · Instagram · Facebook

The NexorAIQ Connector (NexorAIQ_Connector) is the official Magento 2 extension for integrating NexorAIQ AI-powered search, autocomplete, product discovery, and shopper telemetry.

It ships storefront search for Hyvä and for Luma / Blank-based themes (selected automatically per store view), and GraphQL / REST search endpoints that headless storefronts can call.

Key Features

• AI Search & Autocomplete: Keyword, vector semantic, or hybrid search modes configurable per store view.
• Storefront UI Takeover:
  • Autocomplete dropdown or fullscreen search overlay (1-column or 2-column layout with suggestions, categories, and brands).
  • Dedicated search results page with sorting, pagination, and layered navigation / swatches.
  • Quick "Add to Cart" directly from the search overlay and search results page.
• Unified Theme Compatibility:
  • Hyvä Theme: Native Alpine.js templates and Tailwind CSS styling.
  • Luma & Blank Themes: RequireJS and responsive CSS.
  • Headless storefronts: GraphQL and REST search endpoints (no ready-made PWA Studio components).
• Real-Time Catalog Sync: Hooks into product save/delete events to instantly sync catalog changes to NexorAIQ.
• Multi-Source Inventory (MSI) & Reservations: Captures stock changes, warehouse inventory updates, and checkout stock reservations in real-time.
• Key separation: The private Connection Key stays on the server (encrypted in Magento config). The browser only receives the read-only Public Search Key, which it uses to query the NexorAIQ search API directly; analytics events go through Magento.
• Shopper Telemetry & Analytics: Captures search query interactions, product clicks, cart adds, and order conversions to continuously train search relevance.
• Admin Sync Status: Displays real-time sync status badges per store view on the product edit page, with on-demand manual sync capability.
• Categorized Logging: Isolated logging per subsystem (var/log/NexoraIQ/) for easy troubleshooting.

Requirements & Compatibility

Magento Open Source / Adobe Commerce	PHP (per Adobe system requirements)
2.4.9	8.5 (8.4 for upgrade scenarios)
2.4.8	8.3, 8.4
2.4.7	8.2, 8.3
2.4.6	8.1, 8.2

• The module requires PHP 8.1 or later and magento/framework 103.0.6 or later (Magento 2.4.6).
• Themes: Hyvä (Hyvä Theme 1.3 or later) and Luma / Blank or themes that inherit from them. Other frontends (e.g. PWA Studio, Breeze, custom headless) need their own integration using the GraphQL / REST endpoints.
• Optional modules: Multi-Source Inventory (salable quantity, reservation-based stock sync), Magento_GraphQl / Magento_StoreGraphQl (GraphQL endpoints), Magento_Csp (CSP allow-list for api.nexoraiq.tech) and Magento_Review (ratings). The connector works without them.
• NexorAIQ account: An active account with a Connection Key and a Public Search Key.

How compatibility was verified for this release: installed and tested on Mage-OS 3.5 (Magento 2.4.9 code base) with PHP 8.3 and Hyvä 1.5; PHP 8.1–8.5 syntax compatibility checked with PHPCompatibility; every Magento class the module uses was confirmed to exist in Magento 2.4.6. Test on your exact Magento patch release and PHP version before production.

See Adobe Commerce system requirements for the authoritative platform matrix.

Installation

1. Install via Composer

Run the following command in your Magento root directory, provided the NexorAIQ Composer package repository is configured and your credentials grant access to the package:

composer require nexoraiq_tech/connector

Package availability: This command requires nexoraiq_tech/connector to be published in a Composer repository available to your project. If you have not configured the repository or the package is not publicly available, use the installation/distribution instructions supplied by NexorAIQ rather than assuming Packagist can resolve it.

2. Enable and Deploy

bin/magento module:enable NexorAIQ_Connector
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Configuration

Navigate to Stores > Configuration > NexorAIQ in the Magento Admin Panel.

1. General Settings (NexorAIQ > General Settings)

Setting	Description
Enable Extension	Enable or disable the NexorAIQ integration.
Connection Key	Your private administrator key (nxk_live_...) from the NexorAIQ dashboard.
Public Search API Key	Your public search API key (key_search_...) used by frontend search proxies.
Real-time Product Sync	Automatically push product and stock changes to NexorAIQ on save/delete.
Bulk Sync Batch Size	Number of products processed per batch during reindex (100, 150, 200, 300).
Full Reindex Skip Window	Skip products synced within X minutes during a full reindex (set 0 to reindex all).
Attributes Configuration	Select extra product attributes to sync beyond standard searchable/filterable attributes.
Brands Configuration	Map brand/manufacturer attributes for brand filtering and overlay sections.

2. Storefront Settings (NexorAIQ > Storefront)

Setting	Description
Enable Storefront UI Takeover	Enables NexorAIQ autocomplete and search results takeover.
Search Type	Retrieval strategy: Keyword, Vector, or Hybrid (configurable per store view).
Desktop / Mobile Search Layout	Choose between Autocomplete Dropdown or Overlay Layout.
Overlay Layout Type	1-Column layout or 2-Columns layout (adds Suggestions, Categories, and Brands blocks).
Search Results Page	Enable custom search page route (e.g., /search?q=...), pagination, and filters.
Add to Cart Button	Enable quick Add-to-Cart buttons on the overlay and search results page.

Admin Panel Screenshots

1. General Settings & Connection Status

Navigate to: Stores > Configuration > NexorAIQ > General Settings

• Branded Header Banner: Displays real-time connector status, live product sync counter, store views count, and active plan verification.
• Connection Key: Securely binds your Magento catalog with your NexorAIQ cluster (nxk_live_...).
• Real-Time Sync: Pushes instant updates on product saves, deletions, and MSI stock adjustments.

2. Storefront UI Takeover & Search Modes

Navigate to: Stores > Configuration > NexorAIQ > Storefront

• Search Type: Choose between Keyword, Vector (AI semantic), or Hybrid search retrieval.
• Responsive Layout: Choose Autocomplete Dropdown or Overlay Layout (1-Column or 2-Columns with suggestions, brands, and categories).
• Direct Add to Cart: Enable quick conversion actions right within the search overlay and search results page.

3. Attributes & Brands Configuration

Navigate to: Stores > Configuration > NexorAIQ > General Settings > Attributes / Brands

• Extra Attributes: Select non-standard product attributes to include in the AI search index.
• Brand Identification: Map custom manufacturer/brand attributes for brand facet filtering and dedicated overlay brand carousels.

4. Search Results Page & Add to Cart

Navigate to: Stores > Configuration > NexorAIQ > Storefront > Search Results Page / Add to Cart

• Dedicated Search Route: Configure custom URL path (e.g., /search?q=...), products per page, and layered filters.
• Quick Add to Cart: Enable direct conversion actions from the search overlay and search results page with mini cart drawer integration.

Indexing & Synchronization

Full Reindex via CLI

To reindex your entire catalog into NexorAIQ, run:

bin/magento indexer:reindex nexoraiq_catalog

To check the indexer status:

bin/magento indexer:status nexoraiq_catalog

Automated Background Queue

The connector registers a background cron job (nexoraiq_index_queue) that runs every minute to asynchronously process and synchronize queued product updates. Ensure your Magento cron is running:

bin/magento cron:run

Headless API Reference

Headless storefronts (for example Next.js or Vue Storefront) can use these GraphQL and REST endpoints; the connector does not ship frontend components for them.

GraphQL API (/graphql)

Product Search

query {
  nexoraiqSearch(
    query: "backpack"
    currentPage: 1
    pageSize: 12
    category: "Gear"
    minPrice: 10.0
    maxPrice: 150.0
    sortBy: "price_asc"
    inStockOnly: true
  ) {
    total
    currentPage
    totalPage
    searchTimeMs
    hits {
      id
      title
      sku
      price
      compareAtPrice
      imageUrl
      inStock
    }
  }
}

Autocomplete Suggestions

query {
  nexoraiqAutocomplete(query: "back") {
    suggestions
    products {
      id
      title
      sku
      price
      imageUrl
    }
  }
}

Telemetry: Track Search Query

mutation {
  nexoraiqTrackSearch(
    query: "backpack"
    sessionId: "sess_abc123"
    resultsCount: 24
    tookMs: 35
    device: "Desktop"
  )
}

Telemetry: Track Shopper Click Event

The GraphQL mutation is used for shopper click events. Add-to-cart and conversion events are recorded server-side by the extension; do not send a revenue argument to this mutation because it is not part of the declared schema.

mutation {
  nexoraiqTrackEvent(
    eventType: "CLICK"
    productId: "1234"
    query: "backpack"
    sessionId: "sess_abc123"
  )
}

REST API

All REST endpoints operate under /rest/V1/nexoraiq/:

Method	Endpoint	Description
GET	/rest/V1/nexoraiq/search?query={query}	Search catalog products
GET	/rest/V1/nexoraiq/autocomplete?query={query}	Autocomplete suggestions and products
GET	/rest/V1/nexoraiq/config	Retrieve storefront search configuration
POST	/rest/V1/nexoraiq/analytics/search	Track search query logs
POST	/rest/V1/nexoraiq/analytics/event	Track shopper events (clicks, add to cart, conversions)

Logs & Diagnostics

Subsystem-specific log files are written under the Magento var/log/NexoraIQ/ directory:

Log File	Subsystem
var/log/NexoraIQ/indexer.log	Bulk catalog reindexing and sync queue processing
var/log/NexoraIQ/cron.log	Scheduled background index queue executions
var/log/NexoraIQ/observer.log	Real-time product and stock save/delete observers
var/log/NexoraIQ/plugin.log	MSI source items and inventory reservation plugins
var/log/NexoraIQ/webhook.log	Outbound HTTP synchronization calls to NexorAIQ
var/log/NexoraIQ/api.log	REST API proxy requests and responses
var/log/NexoraIQ/graphql.log	GraphQL query and mutation resolvers
var/log/NexoraIQ/admin.log	Admin sync actions and configuration changes

Validation & Release Checklist

Before deploying to production, verify the following in a staging Magento installation:

• Confirm the exact Magento / Adobe Commerce / Mage-OS patch release and PHP runtime against the compatibility table and the official platform requirements. For 2.4.9, use PHP 8.5 for production; PHP 8.4 is listed for upgrade scenarios, not recommended for production.
• Run Magento compilation, static content deployment where required, and cache flush; check that the module enables without DI or schema errors.
• Verify the connection from Magento Admin and confirm the store view, credentials, and subscription state.
• Run bin/magento indexer:reindex nexoraiq_catalog, confirm the indexer completes, and verify queue processing with Magento cron.
• Test product create/update/delete, price and inventory changes, MSI reservations, autocomplete, search filters, pagination, add-to-cart, and analytics.
• For headless integrations, test the documented GraphQL and REST contracts against the actual schema and endpoint authorization.
• Review exposed REST endpoints and ensure synchronization or administrative operations are protected against unauthorized use and abuse.

Known documentation boundaries

• The GraphQL nexoraiqTrackEvent mutation accepts click events; add-to-cart and conversion events are logged server-side. It does not accept a revenue argument.
• The Composer install command works only when the package is published in a Composer repository accessible to the installing project.
• The connector targets Magento Open Source, Adobe Commerce, and Mage-OS 2.4.x, including 2.4.9. Platform-level PHP compatibility varies by exact patch release; Magento / Adobe Commerce 2.4.9 recommends PHP 8.5 for production, while PHP 8.4 is allowed for upgrade scenarios. Validate the connector on each target runtime before deployment.

Privacy & Data Sent to NexorAIQ

• Catalog data: product attributes, prices, stock, images and URLs of the store views activated in the NexorAIQ dashboard.
• Search and analytics: search queries, clicked / added-to-cart / ordered product ids, order line revenue and currency, store view code, device type and a browser session id.
• Shopper id: for logged-in customers an identifier derived from the customer's email address (user_ + Base64 of the email; Base64 is an encoding, not a hash, so NexorAIQ can read the email), guest_1 for guests. Mention this in your store's privacy policy.
• No payment data, addresses or passwords are sent.

Security

Please report vulnerabilities privately; see SECURITY.md. Do not publish credentials, customer data, or exploitable details in public issues. Review endpoint authorization, request validation, rate limiting, and log redaction before production deployment.

Changelog & Release Notes

See CHANGELOG.md and RELEASE_NOTES.md for full documented release notes and version history. Confirm release contents against the tagged source/package before publishing.

License

Proprietary. Copyright © NexorAIQ. All rights reserved.