Algolia Search¶

Registers Algolia as an opt-in storefront search engine. When a deployment selects storefront_search_engine=algolia, storefront product search runs against an Algolia application instead of the self-hosted Typesense default, under the same compliance-filtered index contract as every other engine. The integration talks to the Algolia REST API directly over httpx — there is no Algolia SDK dependency.

What It Provides¶

• Registers a builder under the key algolia in the storefront-search-engine registry at activation. Core's storefront_search_strategy() factory resolves it when storefront_search_engine=algolia — core never imports the extension.
• AlgoliaIndexingStrategy (ext_algolia/strategy.py) implements the full StorefrontSearchStrategy contract: single and batch document indexing, search, document deletion, and index-settings configuration against the Algolia REST API.
• Browser-direct search: the storefront's storefrontSearchConfig GraphQL query returns the Algolia DSN host (https://<app_id>-dsn.algolia.net), the application id, and a per-user secured API key, so the browser queries Algolia directly without a round-trip through Vectis.
• Compliance-scoped keys: each secured key embeds the caller's compliance filter — customer-group visibility, state restrictions, license requirement, verified age — HMAC-signed so it cannot be widened client-side.

Setup¶

1. Provide Algolia credentials as environment variables on the API service: ALGOLIA_APP_ID and ALGOLIA_ADMIN_API_KEY (required), plus ALGOLIA_SEARCH_API_KEY (recommended — see Operational Notes).
2. Select the engine: set storefront_search_engine=algolia (environment variable STOREFRONT_SEARCH_ENGINE=algolia or the backend .env file). Engine selection is instance-level, not per-channel.
3. Reindex: run the reindexProducts GraphQL mutation (requires the settings.edit permission). It applies the index settings — searchable attributes and compliance facets — and indexes every storefront product into the storefront_products index.

If ALGOLIA_APP_ID or ALGOLIA_ADMIN_API_KEY is missing, engine construction fails with an explicit error instead of falling back to another engine.

Configuration Reference¶

This extension has no config_schema; it is configured entirely through environment variables:

Permissions¶

The manifest declares no permissions.

Operational Notes¶

• Secured keys are the Algolia analogue of the Typesense scoped key and the Meilisearch tenant token: an HMAC-SHA256 of the URL-encoded restrictions (filters + validUntil + restrictIndices) signed with the parent search key. They expire after 1 hour and are restricted to the storefront_products index.

• Index settings applied by reindex: searchable attributes name, description, sku_list, brand_name; faceting includes filterOnly() facets for the compliance fields (visible_group_ids, channel_ids, restricted_states, requires_license, min_age) plus brand_name, category_slug, and in_stock.
• Documents are keyed by Algolia's objectID, copied from each document's id.
• Deleting a document that is already gone (HTTP 404) is treated as success.
• Server-side Algolia API requests (indexing, settings, deletes, and server-side queries) use a 30-second request timeout with a 10-second connect timeout.
• Selecting storefront_search_engine=algolia when the engine is not registered raises an explicit error — there is deliberately no silent fallback to another engine, because a permissive fallback would be a compliance risk.
• The engine key is claimed in the registration ledger: a second extension registering algolia is a hard activation error.

See Building Extensions for the registry surfaces and Strategy Pattern for how strategies resolve.