@algolia/wizard 0.16.0 → 0.18.0

package/dist/main.js

@@ -2246,7 +2246,7 @@ async function ensureApplication() {
 }
 
 // src/workflows/default.ts
-import { z as z28 } from "zod";
+import { z as z29 } from "zod";
 
 // src/actions/listIndices.ts
 import { z as z5 } from "zod";
@@ -2980,6 +2980,15 @@ import { tool as tool8 } from "ai";
 import z15 from "zod";
 import { relative as relative4 } from "node:path";
 
+// src/lib/tools/utils/prompt.ts
+var chain = Promise.resolve();
+function serializePrompt(work) {
+  const result = chain.then(work);
+  chain = result.catch(() => {
+  });
+  return result;
+}
+
 // src/lib/tools/utils/runShell.ts
 import { spawn as spawn2 } from "node:child_process";
 
@@ -3010,7 +3019,8 @@ function createToolContext(limits = DEFAULT_TOOL_LIMITS, cwd = process.cwd(), sh
     cwd,
     limits: { ...limits },
     counts: { list: 0, search: 0, read: 0, shell: 0 },
-    shell: shell2
+    shell: shell2,
+    reviewed: []
   };
 }
 
@@ -3088,13 +3098,6 @@ function storeApproval(root) {
     return answer === "approve" ? "approve" : "reject";
   };
 }
-var shellChain = Promise.resolve();
-function serialize(work) {
-  const result = shellChain.then(work);
-  shellChain = result.catch(() => {
-  });
-  return result;
-}
 async function approveAndRun(ctx, command, cwd, explanation) {
   const decision = await ctx.shell.approve({ command, cwd, explanation });
   if (decision === "reject") {
@@ -3158,20 +3161,81 @@ function runShellTool(ctx) {
       const resolved2 = resolveInRoot(ctx, cwd ?? ".");
       if (!resolved2.ok) return resolved2.error;
       logger.info({ command, cwd: resolved2.target }, "called runShell tool");
-      return serialize(
+      return serializePrompt(
         () => approveAndRun(ctx, command, resolved2.target, explanation)
       );
     }
   });
 }
 
+// src/lib/tools/reviewScript.ts
+import { tool as tool9 } from "ai";
+import z16 from "zod";
+import { stat as stat2 } from "node:fs/promises";
+import { relative as relative5 } from "node:path";
+
+// src/lib/editor.ts
+import { spawn as spawn3 } from "node:child_process";
+function openInEditor(filePath) {
+  const { command, args } = process.platform === "darwin" ? (
+    // -t forces the default *text* editor; plain `open` on an extension
+    // with no handler (.mjs, .py) pops a "choose an application" dialog.
+    { command: "open", args: ["-t", filePath] }
+  ) : process.platform === "win32" ? { command: "cmd", args: ["/c", "start", "", filePath] } : { command: "xdg-open", args: [filePath] };
+  try {
+    const child = spawn3(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
+// src/lib/tools/reviewScript.ts
+function reviewScriptTool(ctx) {
+  return tool9({
+    description: "Show a script you have written to the user and wait while they read it. Call this as soon as the script is finished and before you run it for the first time, so nothing with a side effect happens behind their back. It opens the file in their editor and returns once they have confirmed.",
+    inputSchema: z16.object({
+      filePath: z16.string().describe(
+        "Path to the script to review, relative to the project root."
+      )
+    }),
+    execute: async ({ filePath }) => {
+      logger.info({ filePath }, "called reviewScript tool");
+      const resolved2 = resolveInRoot(ctx, filePath);
+      if (resolved2.ok === false) return resolved2.error;
+      const isFile = await stat2(resolved2.target).then(
+        (s) => s.isFile(),
+        () => false
+      );
+      if (!isFile) {
+        return `Refused: ${filePath} is not a file. Write the script first, then review the path you wrote.`;
+      }
+      return serializePrompt(async () => {
+        openInEditor(resolved2.target);
+        await useWizard.getState().requestUserInput({
+          prompt: "",
+          promptType: "enterToContinue",
+          options: [],
+          messages: [
+            `Please review ${relative5(ctx.root, resolved2.target)} before it runs:`,
+            resolved2.target
+          ]
+        });
+        ctx.reviewed.push(resolved2.target);
+        return "The user has reviewed the script. You may run it now.";
+      });
+    }
+  });
+}
+
 // src/lib/tools/generateRecord.ts
-import { tool as tool9, generateText, Output, NoObjectGeneratedError } from "ai";
+import { tool as tool10, generateText, Output, NoObjectGeneratedError } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { nanoid as nanoid2 } from "nanoid";
 import { mkdir as mkdir5, writeFile as writeFile6 } from "node:fs/promises";
 import { dirname as dirname6 } from "node:path";
-import z16 from "zod";
+import z17 from "zod";
 var DATA_DIR = ".algolia-wizard/data";
 var RECORD_MODEL = "claude-haiku-4-5";
 var MAX_RECORDS = 100;
@@ -3181,19 +3245,19 @@ var anthropic = createAnthropic({
   apiKey: process.env.PROVIDER_API_KEY ?? ""
 });
 function generateRecordTool(ctx) {
-  return tool9({
+  return tool10({
     description: "Generate realistic sample records for an entity and write them to a JSON file in the worktree. Provide the entity name and its attributes; this tool asks a model to invent varied, realistic values, each with a unique objectID, and returns the file path to read them from at runtime. Do not invent the record values or objectIDs yourself, and do not inline the returned records into the script \u2014 call this tool and read the file it writes.",
-    inputSchema: z16.object({
-      entityName: z16.string().describe("Name of the entity to generate records for."),
-      attributes: z16.array(z16.string()).describe("Attribute names each record must contain."),
-      count: z16.number().int().min(1).max(MAX_RECORDS).default(10).describe(`How many records to generate (max ${MAX_RECORDS}).`),
-      hint: z16.string().optional().describe("Optional context to steer realistic values.")
+    inputSchema: z17.object({
+      entityName: z17.string().describe("Name of the entity to generate records for."),
+      attributes: z17.array(z17.string()).describe("Attribute names each record must contain."),
+      count: z17.number().int().min(1).max(MAX_RECORDS).default(10).describe(`How many records to generate (max ${MAX_RECORDS}).`),
+      hint: z17.string().optional().describe("Optional context to steer realistic values.")
     }),
     execute: async ({ entityName, attributes, count, hint }) => {
       logger.info({ entityName, count }, "called generateRecord tool");
       try {
-        const value = z16.union([z16.string(), z16.number(), z16.boolean(), z16.null()]);
-        const recordSchema = z16.object(
+        const value = z17.union([z17.string(), z17.number(), z17.boolean(), z17.null()]);
+        const recordSchema = z17.object(
           Object.fromEntries(attributes.map((attr) => [attr, value]))
         );
         const generateBatch = async (batchCount) => {
@@ -3203,8 +3267,8 @@ function generateRecordTool(ctx) {
               const { output } = await generateText({
                 model: anthropic(RECORD_MODEL),
                 output: Output.object({
-                  schema: z16.object({
-                    records: z16.array(recordSchema).length(batchCount)
+                  schema: z17.object({
+                    records: z17.array(recordSchema).length(batchCount)
                   })
                 }),
                 prompt: [
@@ -3261,13 +3325,13 @@ function generateRecordTool(ctx) {
 }
 
 // src/lib/tools/notifyUser.ts
-import { tool as tool10 } from "ai";
-import z17 from "zod";
+import { tool as tool11 } from "ai";
+import z18 from "zod";
 function notifyUserTool() {
-  return tool10({
+  return tool11({
     description: `Give the user a brief, high-level update on what you are currently doing or about to do next. This is for the big picture (e.g. "Reading through your data models", "Writing the search UI") \u2014 not granular detail like individual tool calls, which are already logged separately. Call it when you start a new phase of work or your focus shifts, just not on every step, enough to keep the user engaged. Don't say things like "starting", just describe what you are doing. Don't mention tool calls themselves, just general direction of the work.`,
-    inputSchema: z17.object({
-      message: z17.string().describe(
+    inputSchema: z18.object({
+      message: z18.string().describe(
         "Short, plain-language description of what you are doing now."
       )
     }),
@@ -3311,6 +3375,7 @@ function createTools(ctx, { output, tools }) {
     ),
     searchFiles: withLogging("searchFiles", searchFilesTool(ctx)),
     runShell: withLogging("runShell", runShellTool(ctx)),
+    reviewScript: withLogging("reviewScript", reviewScriptTool(ctx)),
     generateRecord: withLogging("generateRecord", generateRecordTool(ctx)),
     notifyUser: withLogging("notifyUser", notifyUserTool())
   };
@@ -3432,10 +3497,10 @@ async function runAgent(req) {
 }
 
 // src/actions/detectLanguage.ts
-import z20 from "zod";
-var detectLanguageSchema = z20.object({
-  languages: z20.array(z20.object({ name: z20.string(), version: z20.string() })),
-  frameworks: z20.array(z20.object({ name: z20.string(), version: z20.string() }))
+import z21 from "zod";
+var detectLanguageSchema = z21.object({
+  languages: z21.array(z21.object({ name: z21.string(), version: z21.string() })),
+  frameworks: z21.array(z21.object({ name: z21.string(), version: z21.string() }))
 });
 var detectLanguage = () => runAgent({
   instructions: [
@@ -3453,31 +3518,31 @@ var detectLanguage = () => runAgent({
 });
 
 // src/actions/analyzeCodebase.ts
-import z21 from "zod";
+import z22 from "zod";
 var READONLY_TOOLS = [
   "listFiles",
   "changeDirectory",
   "readFile",
   "searchFiles"
 ];
-var ingestionAnalysisSchema = z21.object({
-  ingestionAnalysis: z21.array(
-    z21.object({
-      name: z21.string(),
-      paths: z21.array(z21.string()),
+var ingestionAnalysisSchema = z22.object({
+  ingestionAnalysis: z22.array(
+    z22.object({
+      name: z22.string(),
+      paths: z22.array(z22.string()),
       // indexable fields the agent found for this entity
-      attributes: z21.array(z21.string())
+      attributes: z22.array(z22.string())
     })
   )
 });
-var searchImplementationAnalysisSchema = z21.object({
-  searchImplementationAnalysis: z21.string()
+var searchImplementationAnalysisSchema = z22.object({
+  searchImplementationAnalysis: z22.string()
 });
-var verificationSchema = z21.object({
-  verification: z21.array(z21.string())
+var verificationSchema = z22.object({
+  verification: z22.array(z22.string())
 });
 var confirmedEntitiesFieldSchema = ingestionAnalysisSchema.shape.ingestionAnalysis.optional();
-var analyzeCodebaseSchema = z21.object({
+var analyzeCodebaseSchema = z22.object({
   ingestionAnalysis: ingestionAnalysisSchema.shape.ingestionAnalysis.optional(),
   searchImplementationAnalysis: searchImplementationAnalysisSchema.shape.searchImplementationAnalysis.optional(),
   verification: verificationSchema.shape.verification.optional(),
@@ -3539,7 +3604,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.16.0",
+  version: "0.18.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -3658,8 +3723,8 @@ async function askList(ctx, prompt, { required = false } = {}) {
 }
 
 // src/actions/confirmLanguage.ts
-import z23 from "zod";
-var confirmLanguageSchema = z23.object({
+import z24 from "zod";
+var confirmLanguageSchema = z24.object({
   languages: detectLanguageSchema.shape.languages
 });
 async function confirmLanguage(ctx) {
@@ -3680,8 +3745,8 @@ async function confirmLanguage(ctx) {
 }
 
 // src/actions/confirmFramework.ts
-import z24 from "zod";
-var confirmFrameworkSchema = z24.object({
+import z25 from "zod";
+var confirmFrameworkSchema = z25.object({
   frameworks: detectLanguageSchema.shape.frameworks
 });
 var CURATED_FRAMEWORKS = [
@@ -3814,8 +3879,8 @@ async function promptUser(ctx, params) {
 }
 
 // src/actions/confirmEntities.ts
-import z25 from "zod";
-var confirmEntitiesSchema = z25.object({
+import z26 from "zod";
+var confirmEntitiesSchema = z26.object({
   // Final detection — the focused re-run may supersede project-scan's.
   ingestionAnalysis: ingestionAnalysisSchema.shape.ingestionAnalysis.optional(),
   confirmedEntities: confirmedEntitiesFieldSchema
@@ -3885,15 +3950,15 @@ async function confirmEntities(ctx) {
 }
 
 // src/actions/review.ts
-import { z as z26 } from "zod";
-var reviewSchema = z26.object({
+import { z as z27 } from "zod";
+var reviewSchema = z27.object({
   // Broad, high-level takeaways grouped by theme (e.g. ingestion, search UI),
   // not one entry per workflow step — a step's raw output can be a long,
   // multi-paragraph blob (see implement.ts's summaries.join), and mirroring
   // that 1:1 is what made the old per-step summary an unreadable wall of text.
-  summaryPoints: z26.array(z26.string()),
-  reviewPrompt: z26.string(),
-  nextSteps: z26.array(z26.string())
+  summaryPoints: z27.array(z27.string()),
+  reviewPrompt: z27.string(),
+  nextSteps: z27.array(z27.string())
 });
 function formatCompletedSteps(steps) {
   if (!steps.length) return "(no prior steps completed)";
@@ -3944,12 +4009,12 @@ ${formatCompletedSteps(ctx.completedSteps)}`,
 };
 
 // src/actions/implement.ts
-import z27 from "zod";
+import z28 from "zod";
 import { join as join12 } from "node:path";
 
 // src/lib/worktree.ts
 import { execFile as execFile2 } from "node:child_process";
-import { copyFile, mkdir as mkdir6, readdir as readdir3, readFile as readFile8, stat as stat2, writeFile as writeFile7 } from "node:fs/promises";
+import { copyFile, mkdir as mkdir6, readdir as readdir3, readFile as readFile8, stat as stat3, writeFile as writeFile7 } from "node:fs/promises";
 import { basename as basename2, dirname as dirname7, isAbsolute as isAbsolute2, join as join10, resolve as resolve3 } from "node:path";
 var MAX_BUFFER = 32 * 1024 * 1024;
 var MAX_WIZARD_WORKTREES = 3;
@@ -4020,7 +4085,7 @@ async function copyUploadIntoWorktree(repoRoot, worktreePath, ingestDir, sourceP
   }
   const source = isAbsolute2(trimmed) ? trimmed : resolve3(repoRoot, trimmed);
   try {
-    if (!(await stat2(source)).isFile()) {
+    if (!(await stat3(source)).isFile()) {
       return { ok: false, reason: `"${sourcePath}" is not a file` };
     }
   } catch {
@@ -4195,30 +4260,30 @@ function shellQuote(value) {
 }
 
 // src/actions/implement.ts
-var implementSchema = z27.object({
-  filesChanged: z27.array(z27.string()),
-  summary: z27.string(),
-  worktreePath: z27.string().optional(),
-  ingestCommand: z27.string().optional(),
-  ingestScriptRan: z27.boolean().optional(),
-  ingestRecordCount: z27.number().optional(),
-  ingestDurationMs: z27.number().optional(),
-  ingestionSource: z27.enum(["local", "fileUpload", "generated"]),
-  searchEnvVars: z27.array(
-    z27.object({
-      name: z27.string(),
-      value: z27.string()
+var implementSchema = z28.object({
+  filesChanged: z28.array(z28.string()),
+  summary: z28.string(),
+  worktreePath: z28.string().optional(),
+  ingestCommand: z28.string().optional(),
+  ingestScriptRan: z28.boolean().optional(),
+  ingestRecordCount: z28.number().optional(),
+  ingestDurationMs: z28.number().optional(),
+  ingestionSource: z28.enum(["local", "fileUpload", "generated"]),
+  searchEnvVars: z28.array(
+    z28.object({
+      name: z28.string(),
+      value: z28.string()
     })
   ).optional()
 });
-var implementationOutputSchema = z27.object({
-  summary: z27.string(),
-  ingestCommand: z27.string().optional()
+var implementationOutputSchema = z28.object({
+  summary: z28.string(),
+  ingestCommand: z28.string().optional()
 });
-var verificationOutputSchema = z27.object({
-  summary: z27.string(),
-  sufficient: z27.boolean(),
-  additionalInstructions: z27.string().optional()
+var verificationOutputSchema = z28.object({
+  summary: z28.string(),
+  sufficient: z28.boolean(),
+  additionalInstructions: z28.string().optional()
 });
 var MAX_IMPLEMENT_VERIFICATION_ATTEMPTS = 3;
 var DEFAULT_IMPLEMENT_USE_CASES = ["ingestion", "search"];
@@ -4351,6 +4416,7 @@ function ingestionInstructions(input) {
       "After a successful ingest, the script must print exactly one line to stdout in the form `ALGOLIA_WIZARD_RECORD_COUNT=<n>`, where <n> is the total number of records pushed to Algolia. Print it last, on its own line, with no surrounding text.",
       ...algoliaClientDoc(input),
       "Install the Algolia client with the project's own package manager via runShell, declaring it in whatever manifest the project uses (e.g. package.json, requirements.txt, Gemfile, go.mod, composer.json) so the dependency is not just installed ad hoc.",
+      "When the script is finished, call reviewScript with its path and wait: running it writes records to a live index, so the developer reads it first. Do not run it before that call returns.",
       'Then run the script yourself via runShell, and report the command you ran as "ingestCommand" so the developer can re-run it. Its explanation must say that running it writes records to Algolia.',
       "The summary should be extremely concise.",
       ...sourceSpecificInstructions(input)
@@ -4363,7 +4429,7 @@ function searchInstructions(input) {
     "Implement an in-app Algolia search experience.",
     `Build the search UI for ${input.searchUiTarget}.`,
     ...doc ? [
-      "Follow the Algolia SDK reference below for client setup and search UI wiring; prefer it over prior knowledge:",
+      "Follow the Algolia SDK reference below for client setup, search UI wiring, and Insights instrumentation \u2014 Insights is required, not optional; prefer the reference over prior knowledge:",
       doc
     ] : [
       "No bundled Algolia SDK reference exists for this stack, so rely on the project's own conventions and Algolia's official client for its language. Do not invent APIs \u2014 keep to the documented search endpoint and its parameters."
@@ -4421,6 +4487,7 @@ var useCaseToolMap = {
     "writeFile",
     "writeCredentials",
     "runShell",
+    "reviewScript",
     "notifyUser"
   ],
   search: [...FS_READ_TOOLS, "writeFile", "runShell", "notifyUser"],
@@ -4675,7 +4742,8 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES, existingWo
       const result = await runImplementationUseCase("ingestion");
       summaries.push(formatSummary("ingestion", result.summary));
       ingestCommand = result.ingestCommand;
-      const executions = (ingestionTools ?? searchTools).shell.executions;
+      const ingestionContext = ingestionTools ?? searchTools;
+      const executions = ingestionContext.shell.executions;
       const {
         run: ingestRun,
         attempt: ingestAttempt,
@@ -4684,6 +4752,15 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES, existingWo
       ingestScriptRan = ingestRun != null;
       ingestRecordCount = recordCount;
       ingestDurationMs = ingestRun?.durationMs;
+      if (ingestScriptRan && ingestionContext.reviewed.length === 0) {
+        summaries.push(
+          "\u26A0\uFE0F The ingestion script ran without being shown to you for review. Read it in the worktree before trusting the index contents."
+        );
+        logger.warn(
+          { ingestCommand },
+          "implement: ingestion ran without a reviewScript call"
+        );
+      }
       if (ingestScriptRan) {
         ingestOutcomeMessage = `\u2705 Ingestion succeeded${ingestRecordCount != null ? ` \u2014 ${ingestRecordCount} record(s) indexed.` : "."}`;
         if (ingestRecordCount != null) {
@@ -4913,8 +4990,8 @@ var defaultWorkflow = {
     defineStep({
       id: "select-index",
       title: "Set up index",
-      outputSchema: z28.object({
-        selection: z28.string()
+      outputSchema: z29.object({
+        selection: z29.string()
       }),
       run: (ctx) => selectIndexStep(ctx)
     }),

package/docs/algolia-sdk/README.md

@@ -27,6 +27,7 @@ Always install the **latest stable** within the major (use a caret range like `^
   client cache and causes re-renders.
 - For InstantSearch, import the client from `algoliasearch/lite` (smaller bundle and
   correct types — see `instantsearch-setup.md`).
+- Always enable **Insights** on the InstantSearch root with `insights: true`. Without it there are no click/conversion events, so many Algolia features will not work as expected.
 
 ## Files
 

package/docs/algolia-sdk/instantsearch-setup-js.md

@@ -22,7 +22,11 @@ import { searchBox, hits } from 'instantsearch.js/es/widgets'
 
 const searchClient = algoliasearch(APP_ID, SEARCH_ONLY_KEY)
 
-const search = instantsearch({ indexName: 'INDEX_NAME', searchClient })
+const search = instantsearch({
+  indexName: 'INDEX_NAME',
+  searchClient,
+  insights: true,
+})
 
 search.addWidgets([
   searchBox({ container: '#searchbox' }),
@@ -32,6 +36,122 @@ search.addWidgets([
 search.start()
 ```
 
+## Insights (click analytics) — always enable it
+
+The `insights` option turns on the Insights middleware (`instantsearch.js` v4.55+),
+which adds `clickAnalytics: true` to every query and keeps the `userToken` in sync
+between search and event calls. Never set `clickAnalytics` or `userToken` on the `configure` widget by hand.
+
+Use `insights: true`. The middleware loads `search-insights` from the jsDelivr CDN
+itself; do not install the package or pass `insightsClient`.
+
+If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+case, install `search-insights` from npm and pass its default export as
+`insightsClient` in the `insights` option:
+
+```js
+import aa from 'search-insights'
+
+const search = instantsearch({
+  indexName: 'INDEX_NAME',
+  searchClient,
+  insights: { insightsClient: aa },
+})
+```
+
+The middleware calls `aa('init', ...)` itself with the app ID and search key, so no
+manual `init` call is needed. Keep using the `insightsInitParams` option (for
+example `useCookie`) the same way as with the CDN path.
+
+The middleware sets an anonymous `userToken` itself, so events fire with no extra
+code. That token lives in memory only — a page reload starts a new one, which is
+enough for search→click attribution within a session but not across sessions, and not
+enough for Personalization to build a profile. To persist it in the first-party
+`_ALGOLIA` cookie, switch to the object form — only where the app's cookie-consent
+policy allows it:
+
+```js
+insights: {
+  insightsInitParams: {
+    useCookie: true
+  }
+}
+```
+
+### Click and conversion events
+
+The `hits` and `infiniteHits` widgets send `view` and `click` events on their own. A
+custom `item` template whose click target is your own element gets `sendEvent` as the
+second argument:
+
+```js
+hits({
+  container: '#hits',
+  templates: {
+    item(hit, { html, sendEvent }) {
+      return html`<a
+        href="${hit.url}"
+        onClick="${() => sendEvent('click', hit, 'Hit Clicked')}"
+        >${hit.name}</a
+      >`
+    },
+  },
+})
+```
+
+Conversions are business actions (add to cart, signup, booking), so wire them at the
+real action, not at render:
+
+```js
+sendEvent('conversion', hit, 'Product Added To Cart', {
+  eventSubtype: 'addToCart',
+  objectData: [{ price: hit.price, quantity: 1 }],
+  value: hit.price,
+  currency: 'USD',
+})
+```
+
+Where the app has no such action on a search hit, leave a TODO at the best
+candidate instead of inventing one.
+
+Connector-based custom widgets get `sendEvent` in their render options, and unlike
+the widgets above they send **no** click events automatically — wire them yourself.
+
+### Authenticated users
+
+Anonymous tokens need no code. When the app already has a stable user id, link it
+after login and clear it on logout — the anonymous `userToken` keeps flowing
+alongside it (Personalization uses that one, not the authenticated token):
+
+```js
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', userId)
+}
+```
+
+```js
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', undefined) // on logout
+}
+```
+
+The middleware installs `window.aa` as a queue before the CDN script arrives, so these
+calls need no load-order guard. Under a server-side rendering framework (Angular
+Universal, SvelteKit), `window` does not exist on the server, so `window.aa` throws
+unless you add this guard or call it only from client-side code. In TypeScript
+nothing augments `Window`, so declare it once:
+`declare global { interface Window { aa: (method: string, ...args: unknown[]) => void } }`.
+
+With the npm `insightsClient` fallback, call the same method on the imported `aa`
+function instead of `window.aa`:
+
+```js
+import aa from 'search-insights'
+
+aa('setAuthenticatedUserToken', userId)
+aa('setAuthenticatedUserToken', undefined) // on logout
+```
+
 ## Frameworks without their own flavor
 
 Only React and Vue have a maintained InstantSearch wrapper. For any other

package/docs/algolia-sdk/instantsearch-setup-react.md

@@ -28,7 +28,11 @@ const searchClient = algoliasearch(
 
 export function Search() {
   return (
-    <InstantSearch searchClient={searchClient} indexName="INDEX_NAME">
+    <InstantSearch
+      searchClient={searchClient}
+      indexName="INDEX_NAME"
+      insights={true}
+    >
       <SearchBox />
       <Hits />
     </InstantSearch>
@@ -37,3 +41,111 @@ export function Search() {
 ```
 
 Do not inline `searchClient={algoliasearch(...)}` — keep the stable reference above.
+
+## Insights (click analytics) — always enable it
+
+The `insights` prop turns on the Insights middleware, which adds
+`clickAnalytics: true` to every query and keeps the `userToken` in sync between search
+and event calls. Never set `clickAnalytics` or `userToken` on `<Configure>` by hand.
+
+Use `insights={true}`. The middleware loads `search-insights` from the jsDelivr CDN
+itself; do not install the package or pass `insightsClient`.
+
+If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+case, install `search-insights` from npm and pass its default export as
+`insightsClient`:
+
+```tsx
+import aa from 'search-insights'
+
+<InstantSearch insights={{ insightsClient: aa }} />
+```
+
+The middleware calls `aa('init', ...)` itself with the app ID and search key, so no
+manual `init` call is needed. Keep using the `insightsInitParams` option (for
+example `useCookie`) the same way as with the CDN path.
+
+The middleware sets an anonymous `userToken` itself, so events fire with no extra
+code. That token lives in memory only — a page reload starts a new one, which is
+enough for search→click attribution within a session but not across sessions, and not
+enough for Personalization to build a profile. To persist it in the first-party
+`_ALGOLIA` cookie, switch to the object form — only where the app's cookie-consent
+policy allows it:
+
+```tsx
+<InstantSearch insights={{ insightsInitParams: { useCookie: true } }} />
+```
+
+### Click and conversion events
+
+`<Hits>` and `<InfiniteHits>` send `view` and `click` events on their own. Two cases
+need explicit wiring:
+
+- A custom `hitComponent` whose click target is your own element — it receives a
+  `sendEvent` prop.
+- `useHits` / `useInfiniteHits`: `view` is automatic, `click` is **not**.
+
+```tsx
+function Hit({ hit, sendEvent }) {
+  return (
+    <a href={hit.url} onClick={() => sendEvent('click', hit, 'Hit Clicked')}>
+      {hit.name}
+    </a>
+  )
+}
+```
+
+Conversions are business actions (add to cart, signup, booking), so wire them at the
+real action, not at render:
+
+```tsx
+sendEvent('conversion', hit, 'Product Added To Cart', {
+  eventSubtype: 'addToCart',
+  objectData: [{ price: hit.price, quantity: 1 }],
+  value: hit.price,
+  currency: 'USD',
+})
+```
+
+Where the app has no such action on a search hit, leave a TODO at the best
+candidate instead of inventing one.
+
+### Authenticated users
+
+Anonymous tokens need no code. When the app already has a stable user id, link it
+after login and clear it on logout — the anonymous `userToken` keeps flowing
+alongside it (Personalization uses that one, not the authenticated token):
+
+```ts
+// `search-insights` is CDN-loaded, so nothing augments Window — declare it once.
+declare global {
+  interface Window {
+    aa: (method: string, ...args: unknown[]) => void
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', userId)
+}
+```
+
+```ts
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', undefined) // on logout
+}
+```
+
+The middleware installs `window.aa` as a queue before the CDN script arrives, so these
+calls need no load-order guard. Under Next.js SSR (and React Server Components),
+`window` does not exist on the server, so `window.aa` throws unless you add this
+guard or call it only from a client-side hook such as `useEffect`.
+
+With the npm `insightsClient` fallback, call the same method on the imported `aa`
+function instead of `window.aa`:
+
+```ts
+import aa from 'search-insights'
+
+aa('setAuthenticatedUserToken', userId)
+aa('setAuthenticatedUserToken', undefined) // on logout
+```

package/docs/algolia-sdk/instantsearch-setup-vue.md

@@ -17,7 +17,11 @@ const searchClient = algoliasearch(APP_ID, SEARCH_ONLY_KEY)
 
 ```vue
 <template>
-  <ais-instant-search :search-client="searchClient" index-name="INDEX_NAME">
+  <ais-instant-search
+    :search-client="searchClient"
+    index-name="INDEX_NAME"
+    :insights="true"
+  >
     <ais-search-box />
     <ais-hits />
   </ais-instant-search>
@@ -39,3 +43,99 @@ Register the widgets via the InstantSearch Vue plugin in your app entry:
 import InstantSearch from 'vue-instantsearch/vue3/es'
 app.use(InstantSearch)
 ```
+
+## Insights (click analytics) — always enable it
+
+The `insights` prop turns on the Insights middleware, which adds
+`clickAnalytics: true` to every query and keeps the `userToken` in sync between search
+and event calls. Never set `clickAnalytics` or `userToken` on `ais-configure` by hand.
+
+Use `:insights="true"`. The middleware loads `search-insights` from the jsDelivr CDN itself; do not install
+the package or pass `insightsClient`.
+
+If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+case, install `search-insights` from npm and pass its default export as
+`insightsClient`:
+
+```js
+import aa from 'search-insights'
+const insights = { insightsClient: aa } // then :insights="insights"
+```
+
+The middleware calls `aa('init', ...)` itself with the app ID and search key, so no
+manual `init` call is needed.
+
+The middleware sets an anonymous `userToken` itself, so events fire with no extra
+code. That token lives in memory only — a page reload starts a new one, which is
+enough for search→click attribution within a session but not across sessions, and not
+enough for Personalization to build a profile. To persist it in the first-party
+`_ALGOLIA` cookie, bind the object form — only where the app's cookie-consent policy
+allows it:
+
+```js
+const insights = { insightsInitParams: { useCookie: true } } // then :insights="insights"
+```
+
+### Click and conversion events
+
+`ais-hits` sends `view` and `click` events on its own. A custom `item` slot whose
+click target is your own element needs the slot's `sendEvent`:
+
+```vue
+<ais-hits>
+  <template v-slot:item="{ item, sendEvent }">
+    <a :href="item.url" @click="sendEvent('click', item, 'Hit Clicked')">
+      {{ item.name }}
+    </a>
+  </template>
+</ais-hits>
+```
+
+Conversions are business actions (add to cart, signup, booking), so wire them at the
+real action, not at render:
+
+```js
+sendEvent('conversion', item, 'Product Added To Cart', {
+  eventSubtype: 'addToCart',
+  objectData: [{ price: item.price, quantity: 1 }],
+  value: item.price,
+  currency: 'USD',
+})
+```
+
+Where the app has no such action on a search hit, leave a TODO at the best
+candidate instead of inventing one.
+
+### Authenticated users
+
+Anonymous tokens need no code. When the app already has a stable user id, link it
+after login and clear it on logout — the anonymous `userToken` keeps flowing
+alongside it (Personalization uses that one, not the authenticated token):
+
+```js
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', userId)
+}
+```
+
+```js
+if (typeof window !== 'undefined') {
+  window.aa('setAuthenticatedUserToken', undefined) // on logout
+}
+```
+
+The middleware installs `window.aa` as a queue before the CDN script arrives, so these
+calls need no load-order guard. Under Nuxt SSR, `window` does not exist on the server,
+so `window.aa` throws unless you add this guard or call it only from a client-side
+hook such as `onMounted`. In TypeScript nothing augments `Window`, so declare it
+once: `declare global { interface Window { aa: (method: string, ...args: unknown[]) => void } }`.
+
+With the npm `insightsClient` fallback, call the same method on the imported `aa`
+function instead of `window.aa`:
+
+```js
+import aa from 'search-insights'
+
+aa('setAuthenticatedUserToken', userId)
+aa('setAuthenticatedUserToken', undefined) // on logout
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {