Algolia Search Contract

Overview

This skill defines the read path between application input and Algolia search results. It keeps query construction, allowed filters, pagination, and result projection explicit so UI behavior can be tested independently.

Prerequisites

• A named repository, environment, and Algolia application or index in scope
• The local lockfile and installed client types as implementation authority
• A safe read-only query or explicitly disposable test target
• Current first-party documentation for any provider behavior that affects the change

Tool Discipline

Use Read, Glob, and Grep to inspect local code, configuration names, tests, and dependency versions. Use WebFetch only for current official Algolia documentation. Use Write or Edit only after identifying the target files, constraints, and verification plan.

Current Contract

• Use searchSingleIndex for one index and pass indexName plus searchParams on the v5 client.
• Treat filters and facet filters as structured application inputs; do not concatenate untrusted syntax.
• Request only attributes the interface needs and preserve objectID as the stable result identity.
• Enable click analytics only when the product also implements the query ID and event contract.

Authentication

Browser search should use the search-only key or a backend-generated secured key. Write-capable credentials remain server-side.

Instructions

1. Inspect the installed client version, index settings, record schema, and current UI query state.
2. Define a typed search input with bounded query length, page, hits per page, filters, and facets.
3. Translate application filters through an allowlist rather than accepting raw filter strings.
4. Call the v5 search boundary and map hits into the application result type.
5. Test empty query, no results, special characters, pagination edges, and unavailable facets.
6. Verify returned attributes do not disclose fields the interface should not expose.

Approval Boundaries

Do not change index settings, enable analytics, or expose additional attributes as part of a read-path implementation without explicit review.

Output

Return the typed input/output contract, query builder, relevant tests, credential boundary, observed response metadata, and any required index-setting change.

Error Handling

Condition	Response
Invalid filter syntax	Reject or normalize at the application boundary.
Facet missing	Confirm the attribute is configured before changing the UI.
Unexpected fields returned	Tighten retrieval and index visibility settings.
No query ID	Enable click analytics only with an approved event design.

Examples

Use this compact input and expected handoff to calibrate scope and evidence quality.

Input:

query=boots; facets=brand,size; page=0; credential=search-only

Expected handoff:

hits=24; exposed-fields=objectID,name,price; raw-filter-input=blocked

Resources

• Skill-specific official documentation
• Search API client
• API keys
• Sending events