@decocms/apps-algolia 8.0.0 → 8.1.0-next.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@decocms/apps-algolia",
-  "version": "8.0.0",
+  "version": "8.1.0-next.0",
   "type": "module",
-  "description": "Deco commerce app: Algolia search integration",
+  "description": "Thin client for the Algolia Search REST API",
   "repository": {
     "type": "git",
     "url": "https://github.com/decocms/blocks.git",
@@ -22,12 +22,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "8.0.0",
-    "@decocms/apps-commerce": "8.0.0"
+    "@decocms/blocks": "8.1.0-next.0"
   },
   "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
     "algoliasearch": "^5"
   },
   "peerDependenciesMeta": {
@@ -36,8 +33,6 @@
     }
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
     "algoliasearch": "^5.53.0",
     "knip": "^5.86.0",
     "typescript": "^5.9.0"

package/src/README.md

@@ -1,5 +1,10 @@
 # Algolia app — initial scaffold
 
+> **Next major:** the package root exports `createAlgoliaClient`, a thin
+> client over the Algolia REST API built on `@decocms/blocks/fetch`
+> (see `/next/upstream-clients`). Everything below is the v7 surface, which
+> stays on the `./client`, `./loaders/client` and `./types` subpaths.
+
 This folder ports the Algolia integration from `deco-cx/apps/algolia`
 (Fresh/Deno) to `@decocms/apps/algolia` (TanStack Start/Node), following
 the same shape as `vtex/`, `magento/`, and `shopify/`.
@@ -12,10 +17,10 @@ surface plus the `loaders/client.ts` shim that matches the upstream
 Just enough for downstream sites with their own product loaders to wire
 Algolia and consume the SDK SearchClient directly.
 
-A real-world consumer (deco-sites/granadobr-tanstack) is migrating away
+A real-world consumer (a production Algolia storefront) is migrating away
 from the legacy `ctx.invoke.algolia.loaders.client({})` proxy that
 existed in the Fresh runtime. The site keeps its own product loaders
-(custom Granado transforms over the upstream toProduct) and only needs
+(custom storefront-specific transforms over the upstream toProduct) and only needs
 the SDK client from this package.
 
 ## What's here
@@ -47,16 +52,16 @@ etc.). Tracked here so the next PR series has a clear scope:
 | `workflows/index/product.ts` | `deco-cx/apps/algolia/workflows/index/product.ts` |
 | `sections/Analytics/Algolia.tsx` | `deco-cx/apps/algolia/sections/Analytics/Algolia.tsx` |
 
-The site-side `src/packs/algolia/products/*` in granadobr-tanstack
-contains a Granado-specific transform layer that is not portable as-is.
+The site-side `src/packs/algolia/products/*` in a production Algolia storefront
+contains a storefront-specific transform layer that is not portable as-is.
 Once `loaders/product/*` lands here, the upstream tract can be reused;
-the Granado overlays will keep living in the site.
+the storefront-specific overlays will keep living in the site.
 
 ## Wiring in a site
 
 ```ts
 // src/setup.ts
-import { initAlgoliaFromBlocks } from "@decocms/apps/algolia";
+import { initAlgoliaFromBlocks } from "@decocms/apps-algolia/client";
 import { blocks } from "./server/cms/blocks.gen";
 
 createSiteSetup({

package/src/__tests__/searchClient.test.ts

@@ -0,0 +1,63 @@
+/**
+ * The v8 Algolia client (/next/upstream-clients): typed REST calls through
+ * the instrumented fetch, credentials in headers, errors without bodies.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { AlgoliaError, createAlgoliaClient } from "../index";
+
+function fakeFetch(status: number, body: unknown) {
+  return vi.fn(
+    async (_input: string | URL | Request, _init?: RequestInit) =>
+      new Response(JSON.stringify(body), { status }),
+  );
+}
+
+const config = { applicationId: "APPID", apiKey: "search-key" };
+
+describe("createAlgoliaClient", () => {
+  it("search posts every query to the multi-query endpoint", async () => {
+    const fetch = fakeFetch(200, { results: [{ hits: [{ objectID: "1" }], nbHits: 1 }] });
+    const algolia = createAlgoliaClient(config, { fetch });
+
+    const { results } = await algolia.search([
+      { indexName: "products", query: "linen shirt", hitsPerPage: 12 },
+    ]);
+
+    expect(results[0].hits[0].objectID).toBe("1");
+    const [url, init] = fetch.mock.calls[0];
+    expect(String(url)).toBe("https://APPID-dsn.algolia.net/1/indexes/*/queries");
+    expect(init?.method).toBe("POST");
+    expect(init?.headers).toMatchObject({
+      "x-algolia-application-id": "APPID",
+      "x-algolia-api-key": "search-key",
+    });
+    expect(JSON.parse(String(init?.body))).toEqual({
+      requests: [{ indexName: "products", query: "linen shirt", hitsPerPage: 12 }],
+    });
+  });
+
+  it("rejects an applicationId that would change the host the key is sent to", () => {
+    expect(() =>
+      createAlgoliaClient({ applicationId: "evil.example/#", apiKey: "search-key" }),
+    ).toThrow("invalid applicationId");
+  });
+
+  it("throws the operation and status, never the body or the key", async () => {
+    const fetch = fakeFetch(403, { message: "Invalid API key search-key" });
+    const algolia = createAlgoliaClient(config, { fetch });
+
+    const error = await algolia.search([{ indexName: "products" }]).catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(AlgoliaError);
+    expect(error).toMatchObject({ operation: "search", status: 403 });
+    expect((error as Error).message).not.toContain("search-key");
+  });
+
+  it("does not retry", async () => {
+    const fetch = fakeFetch(503, {});
+    const algolia = createAlgoliaClient(config, { fetch });
+
+    await expect(algolia.search([{ indexName: "products" }])).rejects.toThrow(AlgoliaError);
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+});

package/src/index.ts

@@ -1,12 +1,90 @@
 /**
- * Algolia app entry point for @decocms/apps.
- * Re-exports client config + initializer + types.
+ * `@decocms/apps-algolia`: a thin client for the Algolia Search REST API.
+ * See /next/upstream-clients.
  *
- * For loaders, use sub-path imports:
- *   import client from "@decocms/apps/algolia/loaders/client"
+ * It calls the REST API directly rather than through the `algoliasearch`
+ * SDK, so every request goes through `createInstrumentedFetch` (provider
+ * `algolia`) like every other client. No retries or circuit breaker, and no
+ * response cache: caching upstream data is the framework binding's job.
  *
- * For the SDK SearchClient directly (no proxy hop on the server):
- *   import { getAlgoliaClient } from "@decocms/apps/algolia/client"
+ * The v7 SDK wiring (`configureAlgolia`, `getAlgoliaClient`,
+ * `initAlgoliaFromBlocks`) stays on the `./client` and `./loaders/client`
+ * subpaths for v7 sites; it needs the optional `algoliasearch` peer.
  */
-export * from "./client";
-export type { AlgoliaConfig, Indices } from "./types";
+import { createInstrumentedFetch } from "@decocms/blocks/fetch";
+
+export interface AlgoliaClientConfig {
+  applicationId: string;
+  /** A search-only key is enough for search; never send an admin key to the browser. */
+  apiKey: string;
+}
+
+/** One query: the index plus search parameters as the REST API names them (`query`, `hitsPerPage`, `filters`, ...). */
+export interface AlgoliaSearchRequest {
+  indexName: string;
+  query?: string;
+  [param: string]: unknown;
+}
+
+export type AlgoliaHit<T> = T & { objectID: string; [field: string]: unknown };
+
+export interface AlgoliaSearchResponse<T = Record<string, unknown>> {
+  hits: AlgoliaHit<T>[];
+  nbHits: number;
+  page: number;
+  nbPages: number;
+  hitsPerPage: number;
+  processingTimeMS: number;
+  query: string;
+  params: string;
+  index?: string;
+  queryID?: string;
+  facets?: Record<string, Record<string, number>>;
+  [field: string]: unknown;
+}
+
+export class AlgoliaError extends Error {
+  constructor(
+    readonly operation: string,
+    readonly status: number,
+  ) {
+    super(`algolia ${operation} failed with HTTP ${status}`);
+  }
+}
+
+export function createAlgoliaClient(
+  config: AlgoliaClientConfig,
+  options: { fetch?: typeof fetch } = {},
+) {
+  // The id becomes part of the host; reject anything that could redirect the API key elsewhere.
+  if (!/^[A-Za-z0-9]+$/.test(config.applicationId))
+    throw new Error("algolia: invalid applicationId");
+  const request = createInstrumentedFetch({ provider: "algolia", fetch: options.fetch });
+  const host = `https://${config.applicationId}-dsn.algolia.net`;
+
+  async function post<R>(operation: string, path: string, body: unknown): Promise<R> {
+    const response = await request(`${host}${path}`, {
+      operation,
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-algolia-application-id": config.applicationId,
+        "x-algolia-api-key": config.apiKey,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) throw new AlgoliaError(operation, response.status);
+    return (await response.json()) as R;
+  }
+
+  return {
+    /** Runs several queries, on one or more indices, in one request. */
+    search<T = Record<string, unknown>>(
+      requests: AlgoliaSearchRequest[],
+    ): Promise<{ results: AlgoliaSearchResponse<T>[] }> {
+      return post("search", "/1/indexes/*/queries", { requests });
+    },
+  };
+}
+
+export type AlgoliaClient = ReturnType<typeof createAlgoliaClient>;