The client

@orbsearch/client calls the Query API with typed requests and answers. It needs no framework, and the React components build on it:

import { createSearch } from "@orbsearch/client";

export const search = createSearch({ endpoint: "http://127.0.0.1:7800" });

const answer = await search.query("graues Sofa");
const sofa = await search.product({ id: "SOFA-ASKA-2" });
const page = await search.resolve("/wohnen/sofas?color=grey");

The calls search for "graues Sofa" (grey sofa), fetch one sofa and ask what the sofa page /wohnen/sofas (wohnen: living) with grey chosen is. Hover a call to read what it answers.

The packages are not on npm yet. A shop inside this repository's pnpm workspace depends on them as workspace:*, as the demo storefront in apps/demo does, and its bundler compiles their TypeScript source:

{
    "dependencies": {
        "@orbsearch/client": "workspace:*",
        "@orbsearch/react": "workspace:*"
    }
}

The callsCopy Anchor Link

Each call is one request. The second argument is the request without its text, with filters in the shape a listing's URL holds, and the third cancels the call when the shopper moves on:

const navigation = new AbortController();
const sofas = await search.query(
    "",
    { on: "category_page", category: "wohnen/sofas", filters: { color: ["grey"] }, sort: "price_asc" },
    { signal: navigation.signal },
);

• query searches or browses a category (Search and browse).
• product fetches one product by id or url, or null when the channel sells none (Product pages).
• resolve says what one of the merchant's URLs is: a listing with its results, a product, a redirect or nothing (URLs and redirects).
• facets counts named facets in full, without products, for a facet that loads when opened.
• suggestions returns the store a search box runs on (Autocomplete).

In the browser, registerAgentTools offers the same client to agents as WebMCP tools (Agents).

Reference: POST /v1/search · GET /v1/product · GET /v1/resolve

One client per page loadCopy Anchor Link

A client's searches name one page view, which Insights counts queries by. Make one client per page the shopper loads: once in the browser, and once per request on a server, with the shopper's User-Agent:

import { createSearch } from "@orbsearch/client";

export function searchFor(request: Request) {
    const userAgent = request.headers.get("user-agent");

    return createSearch({ endpoint: "http://127.0.0.1:7800", ...(userAgent && { userAgent }) });
}

The user agent tells a crawler from a shopper, which the server's own would hide. The page view lives in memory only: pass the server's to the browser's client as pageView, and a page load counts once. traffic: "test" or "bench" marks searches the merchant's reports leave out.

Reference: page_view · traffic

ErrorsCopy Anchor Link

A call the Query API refuses throws a SearchError, whose problem says why in words a person can read:

import { createSearch, SearchError } from "@orbsearch/client";

const search = createSearch({ endpoint: "http://127.0.0.1:7800" });

try {
    await search.query("sofa", { sort: "cheapest" });
} catch (error) {
    if (!(error instanceof SearchError)) throw error;
    console.error(error.problem.status, error.problem.detail);
}

• 400 means the request cannot be answered as sent, such as the unknown sort above, and problem.violations names each wrong field.
• 503 means nothing is searchable yet or the engine is unreachable. Offer the shopper the same page again.

Reference: Problems

Types from the contractCopy Anchor Link

Every request, answer, release file and catalog entity is a type generated from the contract, such as SearchResponse, FacetResult or PageResponse. Hover one to read its fields:

import type { SearchResponse } from "@orbsearch/client";

export function entitiesOf(answer: SearchResponse): string[] {
    return (answer.sections ?? []).flatMap((section) => section.hits.map((hit) => hit.entity));
}

The contract's values come as constants, such as SEARCH_PATH, RELEVANCE_SORT and LATENCY_BUDGETS. Mind one name: Product from the client is a product page's product, Product from @orbsearch/react a tile's.

Reference: Query API

A listing's URLCopy Anchor Link

A search, category or brand page keeps its whole state in its URL, so a link, the back button and a crawler see what the shopper sees. listingHref writes it:

import { listingHref } from "@orbsearch/client";

listingHref("/suche", {
    query: "sofa",
    filters: { color: ["grey", "green"], price: { gte: 100, lte: 300 }, on_sale: true },
    sort: "price_asc",
    page: 2,
});
// "/suche?q=sofa&color=green&color=grey&on_sale=1&price.gte=100&price.lte=300&sort=price_asc&page=2"

Fields stand in alphabetical order and values sorted, so one choice has one URL. Leave page out after a change of filters or sort, and the page starts at 1. Three helpers read a listing back:

• listingOf(page) reads it from resolve's answer, since the merchant may rename parameters.
• keptParams(listing) holds what a form that changes filters or sort keeps as hidden fields, such as q.
• filtersOf(url, facets) reads filters for facets you hold yourself. It needs the facets, since seats=1 is a value where on_sale=1 is a toggle.

The helpers write each parameter by its code, as a release without parameters in routes.json does; URLs and redirects says what renamed parameters change.

Reference: routes.json

NextCopy Anchor Link

• React components: the search box and the pages built on this client.
• Your storefront: a whole shop on the client in a few minutes.
• Clicks and views: report what shoppers open and see.