@algolia/wizard 0.8.0-rc.58.45 → 0.8.0-rc.60.48

package/docs/algolia-sdk/README.md

@@ -1,36 +1,50 @@
-# Algolia JS SDK reference (search)
+# Algolia SDK reference
 
-Authoritative reference for wiring **Algolia search** in JavaScript/TypeScript apps.
-Prefer the method shapes documented here over prior knowledge — they are pinned to
-the current stable majors and avoid known pitfalls (e.g. v5 type mismatches with
-InstantSearch).
+Authoritative reference for the code the wizard generates. Prefer the method shapes
+documented here over prior knowledge — they are pinned to the current stable majors
+and avoid known pitfalls (e.g. v5 type mismatches with InstantSearch).
 
-## Versions
+Docs are loaded by exact name (`<name>-<key>.md`), keyed off the language registry in
+`src/lib/languages.ts` and the framework registry in `src/lib/frameworks.ts`. Adding a
+language means adding its `save-records-<key>.md`, or the doc-coverage test fails.
 
-- `algoliasearch` v5 (install `^5`)
-- `react-instantsearch` v7 (install `^7`)
-- `vue-instantsearch` v4 (install `^4`)
-- `instantsearch.js` v4 (install `^4`) — also the recommended choice for Angular
-- `angular-instantsearch` — DEPRECATED/archived (Sep 2024); do not use, prefer `instantsearch.js`
+## Ingestion clients
 
-Always install the **latest stable** within the major (use a caret range like `^5` /
-`^7`); never pin an exact patch.
+One `save-records-<key>.md` per language Algolia ships an official API client for.
+Install the latest stable within the major; never pin an exact patch.
+
+| Language | Package | Version |
+| --- | --- | --- |
+| JavaScript/TypeScript | `algoliasearch` | `^5` |
+| Python | `algoliasearch` | `>=4,<5` |
+
+## Search UI
+
+| Strategy | Doc | Packages |
+| --- | --- | --- |
+| React (incl. Next.js) | `instantsearch-setup-react.md` | `react-instantsearch` v7 |
+| Vue (incl. Nuxt) | `instantsearch-setup-vue.md` | `vue-instantsearch` v4 |
+| Angular | `instantsearch-setup-angular.md` | `instantsearch.js` v4 |
+| Plain JavaScript | `instantsearch-setup-js.md` | `instantsearch.js` v4 |
+| Server-rendered templates | `instantsearch-setup-templates.md` | CDN script tags, no bundler |
+
+`angular-instantsearch` is DEPRECATED/archived (Sep 2024); use `instantsearch.js`.
+
+Server-rendered templates cover Algolia's official framework integrations — Rails,
+Django, Laravel, Symfony — and any backend with no JavaScript build.
 
 ## Golden rules
 
+- Ingestion is a **write** op: it needs a write key and must stay server-side. Read the
+  credentials from the `ALGOLIA_APPLICATION_ID` and `ALGOLIA_WRITE_API_KEY` env vars.
 - Use a **search-only API key** in any browser/client code. It is safe to expose.
-  NEVER ship an admin or any write-capable key to the client.
-- Read the Application ID and search-only key from **public env vars**, never hardcode
-  them inline.
+  NEVER ship an admin or any write-capable key to the client, and never render one into
+  HTML.
+- Read the Application ID and search-only key from env vars or server-side config, never
+  hardcode them inline.
 - Instantiate the search client **once, outside your components**, and pass a stable
-  reference. Do not inline `algoliasearch(...)` as a prop value — it breaks the
-  client cache and causes re-renders.
+  reference. Do not inline `algoliasearch(...)` as a prop value — it breaks the client
+  cache and causes re-renders.
 - For InstantSearch, import the client from `algoliasearch/lite` (smaller bundle and
-  correct types — see `instantsearch-setup.md`).
-
-## Files
-
-- `instantsearch-setup.md` — framework-specific InstantSearch wiring (React, Vue,
-  Angular, vanilla). Use this for the in-app search UI.
-- `search-single-index.md` — direct/manual search via the core client
-  (`searchSingleIndex`), for cases where InstantSearch is not used.
+  correct types).
+- Every record needs an `objectID`. `saveObjects` auto-batches in groups of 1,000.

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

@@ -0,0 +1,92 @@
+# InstantSearch setup (CDN, server-rendered templates)
+
+Use this when HTML is rendered server-side and there is no bundler or npm build
+step: Rails ERB, Django templates, Laravel Blade, Symfony Twig.
+
+## CDN tags (shared layout)
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@8/themes/satellite-min.css">
+<script src="https://cdn.jsdelivr.net/npm/algoliasearch@5/dist/lite/builds/browser.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/instantsearch.js@4/dist/instantsearch.production.min.js"></script>
+```
+
+Globals these expose:
+
+- `window['algoliasearch/lite']` → `{ liteClient }`. The lite UMD build's global is
+  the literal string key `algoliasearch/lite`, **not** `algoliasearch.liteClient`.
+  (`dist/algoliasearch.umd.js` is the full write-capable client under
+  `window.algoliasearch` — don't use it for search UI.)
+- `window.instantsearch` → the callable factory, with `.widgets`, `.connectors`.
+
+Floating `@5`/`@4`/`@8` track the newest patch. Adding SRI `integrity` requires
+exact pins instead (Algolia's install page publishes hashes for
+`algoliasearch@5.56.0`, `instantsearch.js@4.108.0`, `instantsearch.css@8.18.0`).
+
+## Containers
+
+```html
+<div id="search"
+     data-algolia-app-id="APP_ID"
+     data-algolia-search-key="SEARCH_ONLY_KEY"
+     data-algolia-index="products">
+  <div id="searchbox"></div>
+  <div id="hits"></div>
+</div>
+```
+
+## Init
+
+Inline `<script>` must run after both CDN scripts — put it at the end of `<body>`,
+not in `<head>`.
+
+```html
+<script>
+  const el = document.getElementById('search')
+  const { liteClient: algoliasearch } = window['algoliasearch/lite']
+  const searchClient = algoliasearch(
+    el.dataset.algoliaAppId,
+    el.dataset.algoliaSearchKey
+  )
+
+  const search = instantsearch({ indexName: el.dataset.algoliaIndex, searchClient })
+
+  search.addWidgets([
+    instantsearch.widgets.searchBox({ container: '#searchbox' }),
+    instantsearch.widgets.hits({
+      container: '#hits',
+      templates: {
+        item(hit, { html, components }) {
+          return html`
+            <article>
+              <h3>${components.Highlight({ attribute: 'name', hit })}</h3>
+              <p>${hit.description}</p>
+            </article>
+          `
+        },
+      },
+    }),
+  ])
+
+  search.start()
+</script>
+```
+
+`html` arrives as a property of the template function's second argument — it is
+not an import and not a global. It escapes interpolated values, so it is the XSS
+guard: never string-concatenate hit values or assign them to `innerHTML`.
+
+## Injecting credentials from server config
+
+Render App ID and the search-only key into `data-` attributes (every engine below
+escapes attribute output), then read them from `dataset` — attribute dashes become
+camelCase: `data-algolia-app-id` → `el.dataset.algoliaAppId`. Never interpolate a
+credential into a JS string literal.
+
+- ERB: `data-algolia-app-id="<%= Rails.application.credentials.algolia[:app_id] %>"`
+- Django: `data-algolia-app-id="{{ algolia_app_id }}"` (from the view context)
+- Blade: `data-algolia-app-id="{{ config('services.algolia.app_id') }}"`
+- Twig: `data-algolia-app-id="{{ algolia_app_id }}"` (from a Twig global/parameter)
+
+Only ever a **search-only** API key client-side. A write or admin key must never
+appear in HTML, a `data-` attribute, or inline JS.

package/docs/algolia-sdk/save-records-python.md

@@ -0,0 +1,51 @@
+# Save records (algoliasearch v4)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+Dependency: `algoliasearch>=4,<5` (PyPI).
+
+v4 is async-first: `SearchClient` is coroutine-based (every method needs `await`).
+**`SearchClientSync` is the sync twin** — use it in a standalone script, via `with`
+so the transport closes.
+
+```python
+import os
+
+from algoliasearch.search.client import SearchClientSync
+
+app_id = os.environ["ALGOLIA_APPLICATION_ID"]
+api_key = os.environ["ALGOLIA_WRITE_API_KEY"]
+index_name = "playlists"
+records = [{"objectID": "1", "name": "Hot 100", "visibility": "public"}]
+
+with SearchClientSync(app_id, api_key) as client:
+    responses = client.save_objects(
+        index_name=index_name,
+        objects=records,
+        wait_for_tasks=True,
+    )
+```
+
+```python
+save_objects(
+    index_name: str,                     # required
+    objects: Iterable[Dict[str, Any]],   # required
+    wait_for_tasks: bool = False,
+    batch_size: int = 1000,
+) -> List[BatchResponse]                 # one entry per 1,000-record batch
+```
+
+`BatchResponse` attributes are **snake_case**: `r.task_id`, `r.object_ids` (the
+wire keys are `taskID`/`objectIDs`). It is a list — never treat it as one object.
+
+Read records from a JSON file:
+
+```python
+import json
+
+with open(records_path, encoding="utf-8") as f:
+    records = json.load(f)
+```
+
+After a successful ingest, print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` as the last
+stdout line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.8.0-rc.58.45",
+  "version": "0.8.0-rc.60.48",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {
@@ -22,7 +22,7 @@
     "prepare": "husky",
     "prepublishOnly": "pnpm build",
     "reset": "tsx ./scripts/reset-state.ts",
-    "test:fixtures": "touch .env && tsx --env-file=.env ./fixtures/run-fixtures.ts",
+    "test:toolchains": "tsx ./scripts/verify-toolchains.ts",
     "test:tools": "tsx ./tool-evals/toolEval.ts",
     "test": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json"

package/docs/algolia-sdk/search-single-index.md

@@ -1,42 +0,0 @@
-# Direct search with the core client (v5)
-
-Use this only when NOT using InstantSearch (e.g. a custom search box, a server
-route, or programmatic queries). For UI, prefer `instantsearch-setup-<framework>.md`.
-
-## Client
-
-```ts
-import { algoliasearch } from 'algoliasearch'
-
-const client = algoliasearch(APP_ID, SEARCH_ONLY_KEY)
-```
-
-In v5 there is no `client.initIndex(...)`. Index methods take the index name as a
-parameter on the client. Every method takes a single options object.
-
-## Search a single index
-
-```ts
-const { hits, nbHits } = await client.searchSingleIndex({
-  indexName: 'INDEX_NAME',
-  searchParams: { query: 'shoes', hitsPerPage: 20, page: 0 },
-})
-```
-
-## Search multiple indices / queries in one request
-
-```ts
-const { results } = await client.search({
-  requests: [
-    { indexName: 'INDEX_NAME', query: 'shoes' },
-    { indexName: 'OTHER_INDEX', query: 'shoes' },
-  ],
-})
-```
-
-## Notes
-
-- `searchSingleIndex` returns up to 1,000 hits. For larger exports use the `browse`
-  operation instead.
-- Keep using a **search-only** key for any client-exposed search. Use an admin key
-  only in trusted server-side code.