@algolia/wizard 0.5.0 → 0.6.0-rc.51.23

package/docs/algolia-sdk/README.md

@@ -1,36 +1,64 @@
-# 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` |
+| Ruby | `algolia` | `~> 3.0` |
+| PHP | `algolia/algoliasearch-client-php` | `^4` |
+| Go | `github.com/algolia/algoliasearch-client-go/v4` | `v4` |
+| Java | `com.algolia:algoliasearch` | `4.+` |
+| Kotlin | `com.algolia:algoliasearch-client-kotlin` | `3.+` |
+| Scala | `com.algolia:algoliasearch-scala_2.13` | `2.+` |
+| C# | `Algolia.Search` | `7.*` |
+| Swift | `algoliasearch-client-swift` | `9.0.0` |
+| Dart | `algolia_client_search` | `^1.0.0` |
+
+## 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`).
+  correct types).
+- Every record needs an `objectID`. `saveObjects` auto-batches in groups of 1,000.
 
-## Files
+## Other 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.

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-csharp.md

@@ -0,0 +1,71 @@
+# Save records (Algolia.Search v7)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+The generated script is a self-contained console project at
+`.algolia-wizard/ingest/ingest.csproj` + `Program.cs`, run with
+`dotnet run --project .algolia-wizard/ingest/ingest.csproj`.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Algolia.Search" Version="7.*" />
+  </ItemGroup>
+</Project>
+```
+
+`<OutputType>Exe</OutputType>` is required — `dotnet run` on a library has no entry
+point. `<TargetFramework>` must match an installed SDK; `net8.0` (LTS) is the safe
+default. Under Central Package Management (`Directory.Packages.props` at the repo
+root) omit `Version` here and pin it there — `Version` on a `PackageReference` is
+an error under CPM (NU1008).
+
+```csharp
+using System.Text.Json;
+using Algolia.Search.Clients;
+
+var appId = Environment.GetEnvironmentVariable("ALGOLIA_APPLICATION_ID")
+    ?? throw new InvalidOperationException("ALGOLIA_APPLICATION_ID is not set");
+var writeKey = Environment.GetEnvironmentVariable("ALGOLIA_WRITE_API_KEY")
+    ?? throw new InvalidOperationException("ALGOLIA_WRITE_API_KEY is not set");
+
+var client = new SearchClient(new SearchConfig(appId, writeKey));
+var indexName = "products";
+
+var records = new List<Dictionary<string, object>>
+{
+    new() { ["objectID"] = "1", ["name"] = "Adam" },
+    new() { ["objectID"] = "2", ["name"] = "Benoit" },
+};
+
+var responses = await client.SaveObjectsAsync(indexName, records, waitForTasks: true);
+```
+
+```csharp
+Task<List<BatchResponse>> SaveObjectsAsync<T>(
+  string indexName, IEnumerable<T> objects, bool waitForTasks = false,
+  int batchSize = 1000, RequestOptions options = null,
+  CancellationToken cancellationToken = default) where T : class;
+```
+
+Records need an `objectID`; batching in 1,000s is automatic. Returns
+`List<BatchResponse>` — one entry per batch, each `{ TaskID, ObjectIDs }`, never a
+single response. `T` is constrained to `class`, so use `Dictionary<string, object>`
+or a record/class, never a struct.
+
+Read records from a JSON file:
+
+```csharp
+var json = await File.ReadAllTextAsync("records.json");
+var records = JsonSerializer.Deserialize<List<Dictionary<string, object>>>(json)
+    ?? new List<Dictionary<string, object>>();
+```
+
+After a successful ingest, print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` as the last
+stdout line; send all other logging to stderr so nothing follows it on stdout.

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

@@ -0,0 +1,74 @@
+# Save records (algolia_client_search v1)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+Use the generated v2 client `algolia_client_search`, never the legacy community
+`algolia` package. The script is run with `dart run .algolia-wizard/ingest.dart`.
+
+```yaml
+dependencies:
+  algolia_client_search: ^1.0.0
+```
+
+This client has **no `saveObjects` helper** (only `saveObjectsWithTransformation`,
+which needs an Ingestion transformation) — use `batch` with `addObject` actions.
+
+```dart
+import 'dart:convert';
+import 'dart:io';
+import 'dart:math';
+
+import 'package:algolia_client_search/algolia_client_search.dart';
+
+Future<void> main() async {
+  final appId = Platform.environment['ALGOLIA_APPLICATION_ID'];
+  final writeKey = Platform.environment['ALGOLIA_WRITE_API_KEY'];
+  if (appId == null || writeKey == null) {
+    stderr.writeln('missing Algolia credentials');
+    exit(1);
+  }
+
+  const indexName = 'products';
+  final client = SearchClient(appId: appId, apiKey: writeKey);
+
+  final records = <Map<String, dynamic>>[
+    {'objectID': '1', 'name': 'Adam'},
+    {'objectID': '2', 'name': 'Benoit'},
+  ];
+
+  try {
+    for (var i = 0; i < records.length; i += 1000) {
+      final chunk = records.sublist(i, min(i + 1000, records.length));
+      final response = await client.batch(
+        indexName: indexName,
+        batchWriteParams: BatchWriteParams(
+          requests: chunk
+              .map((r) => BatchRequest(action: Action.addObject, body: r))
+              .toList(),
+        ),
+      );
+      stderr.writeln('task ${response.taskID}');
+    }
+    print('ALGOLIA_WIZARD_RECORD_COUNT=${records.length}');
+  } finally {
+    client.dispose();
+  }
+}
+```
+
+`batch` returns a **single** `BatchResponse { int taskID, List<String> objectIDs }`,
+not a list. Gotchas: every record needs an `objectID`; there is no auto-chunking,
+so cap each call at 1,000 records yourself; use the `Action.addObject` enum value
+(`Action.updateObject` replaces instead of adds); and `client.dispose()` is
+mandatory — without it `dart run` never exits.
+
+Read records from a JSON file:
+
+```dart
+final json = await File('records.json').readAsString();
+final records = (jsonDecode(json) as List).cast<Map<String, dynamic>>();
+```
+
+After a successful ingest, print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` as the last
+stdout line (before `dispose()` is fine); send all other logging to stderr so
+nothing follows it on stdout.

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

@@ -0,0 +1,62 @@
+# Save records (algoliasearch-client-go v4)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+Imports are the dependency declaration; `go mod tidy` resolves
+`github.com/algolia/algoliasearch-client-go/v4`. Standalone `package main` file,
+run with `go run`. Nothing panics on its own — every call returns `(value, error)`.
+
+```go
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/algolia/algoliasearch-client-go/v4/algolia/search"
+)
+
+func main() {
+	client, err := search.NewClient(os.Getenv("ALGOLIA_APPLICATION_ID"), os.Getenv("ALGOLIA_WRITE_API_KEY"))
+	if err != nil {
+		panic(err) // NewClient fails on an empty/invalid app ID or key
+	}
+
+	indexName := "products"
+	records := []map[string]any{{"objectID": "1", "name": "Hot 100"}}
+
+	if _, err := client.SaveObjects(indexName, records, search.WithWaitForTasks(true)); err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("ALGOLIA_WIZARD_RECORD_COUNT=%d\n", len(records))
+}
+```
+
+```go
+func (c *APIClient) SaveObjects(
+	indexName string,
+	objects []map[string]any,   // maps only, each with an "objectID"
+	opts ...ChunkedBatchOption, // search.WithWaitForTasks(bool), search.WithBatchSize(int) (default 1000)
+) ([]BatchResponse, error)     // BatchResponse{ TaskID int64; ObjectIDs []string }
+```
+
+One `BatchResponse` per batch of 1,000, not per record — `len(res)` is the batch count.
+
+Read records from a JSON file:
+
+```go
+import "encoding/json"
+
+content, err := os.ReadFile("records.json")
+if err != nil {
+	panic(err)
+}
+var records []map[string]any
+if err := json.Unmarshal(content, &records); err != nil {
+	panic(err)
+}
+```
+
+After a successful ingest print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` (n = records
+read, not `len(res)`) as the last stdout line, trailing newline included.

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

@@ -0,0 +1,66 @@
+# Save records (algoliasearch Java v4)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+```xml
+<dependency>
+  <groupId>com.algolia</groupId>
+  <artifactId>algoliasearch</artifactId>
+  <version>4.20.0</version>
+</dependency>
+```
+
+```groovy
+implementation 'com.algolia:algoliasearch:4.20.0'
+```
+
+The class MUST be `AlgoliaWizardIngest` with a `public static void main`, in the
+**default package** (no `package` statement) — the wizard runs a fixed main class.
+
+```java
+import com.algolia.api.SearchClient;
+import java.util.List;
+import java.util.Map;
+
+public class AlgoliaWizardIngest {
+
+  public static void main(String[] args) throws Exception {
+    String indexName = "products";
+    List<Map<String, Object>> records = List.of(Map.of("objectID", "1", "name", "Hot 100"));
+
+    SearchClient client =
+        new SearchClient(System.getenv("ALGOLIA_APPLICATION_ID"), System.getenv("ALGOLIA_WRITE_API_KEY"));
+    try {
+      client.saveObjects(indexName, records);
+      System.out.printf("ALGOLIA_WIZARD_RECORD_COUNT=%d%n", records.size());
+    } finally {
+      client.close(); // required: okhttp's non-daemon threads keep the JVM alive otherwise
+    }
+  }
+}
+```
+
+Blocking API — calls return directly and throw `AlgoliaApiException` on failure.
+
+```java
+// objects: Maps or POJOs (Jackson-serialized), each with an objectID
+<T> List<BatchResponse> saveObjects(String indexName, Iterable<T> objects)
+<T> List<BatchResponse> saveObjects(String indexName, Iterable<T> objects,
+    boolean waitForTasks, int batchSize, RequestOptions requestOptions) // batchSize default 1000
+```
+
+One `BatchResponse` (`getTaskID()`, `getObjectIDs()`) per batch of 1,000, not per record.
+
+Read records from a JSON file (Jackson is a transitive dependency):
+
+```java
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.io.File;
+
+List<Map<String, Object>> records = new ObjectMapper()
+    .readValue(new File("records.json"), new TypeReference<List<Map<String, Object>>>() {});
+```
+
+After a successful ingest print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` (n = records
+read, not the returned list size) as the last stdout line.

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

@@ -0,0 +1,60 @@
+# Save records (algoliasearch-client-kotlin v3)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+Gradle Kotlin DSL. The client ships only `ktor-client-core`, so a JVM engine must
+be declared too or the first call fails with no HTTP engine found:
+
+```kotlin
+implementation("com.algolia:algoliasearch-client-kotlin:3.23.0")
+implementation("io.ktor:ktor-client-okhttp:3.2.0")
+```
+
+`saveObjects` is a `suspend` extension, so a standalone script wraps it in
+`runBlocking`. The object MUST be `AlgoliaWizardIngest` in the **default package**
+(no `package` statement), and `@JvmStatic` is required — a `fun main` inside an
+object is not a JVM entrypoint without it.
+
+```kotlin
+import com.algolia.client.api.SearchClient
+import com.algolia.client.extensions.*
+import java.io.File
+import kotlinx.coroutines.runBlocking
+import kotlinx.serialization.json.*
+
+object AlgoliaWizardIngest {
+  @JvmStatic
+  fun main(args: Array<String>): Unit = runBlocking {
+    val indexName = "products"
+    val records: List<JsonObject> = listOf(buildJsonObject { put("objectID", "1"); put("name", "Hot 100") })
+
+    // System.getenv returns String?; the constructor params are non-null
+    SearchClient(
+      appId = requireNotNull(System.getenv("ALGOLIA_APPLICATION_ID")),
+      apiKey = requireNotNull(System.getenv("ALGOLIA_WRITE_API_KEY")),
+    ).use { client -> // AutoCloseable: without use/close, okhttp's non-daemon threads hang the JVM
+      client.saveObjects(indexName = indexName, objects = records)
+      println("ALGOLIA_WIZARD_RECORD_COUNT=${records.size}")
+    }
+  }
+}
+```
+
+```kotlin
+// objects is List<JsonObject> — not arbitrary data classes; each needs an objectID
+suspend fun SearchClient.saveObjects(
+  indexName: String, objects: List<JsonObject>, waitForTasks: Boolean = false,
+  batchSize: Int = 1000, requestOptions: RequestOptions? = null,
+): List<BatchResponse>
+```
+
+One `BatchResponse` (`taskID`, `objectIDs`) per batch of 1,000, not per record.
+
+Read records from a JSON file (no serialization plugin needed for `JsonObject`):
+
+```kotlin
+val records = Json.parseToJsonElement(File("records.json").readText()).jsonArray.map { it.jsonObject }
+```
+
+After a successful ingest print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` (n = records
+read, not the returned list size) as the last stdout line.

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

@@ -0,0 +1,50 @@
+# Save records (algoliasearch-client-php v4)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+Dependency: `algolia/algoliasearch-client-php` `^4` — the wizard runs
+`composer require` for you; do not hand-edit `composer.json`.
+
+`require 'vendor/autoload.php'` before anything else, or the class won't resolve
+(from `.algolia-wizard/` the path is `__DIR__.'/../vendor/autoload.php'`).
+
+```php
+<?php
+
+require __DIR__.'/../vendor/autoload.php';
+
+use Algolia\AlgoliaSearch\Api\SearchClient;
+
+$appId = getenv('ALGOLIA_APPLICATION_ID');
+$apiKey = getenv('ALGOLIA_WRITE_API_KEY');
+$indexName = 'playlists';
+
+$client = SearchClient::create($appId, $apiKey);
+$records = [['objectID' => '1', 'name' => 'Hot 100', 'visibility' => 'public']];
+
+$responses = $client->saveObjects($indexName, $records, true);
+```
+
+```php
+saveObjects(
+    string $indexName,        // required
+    array $objects,           // required
+    bool $waitForTasks = false,
+    int $batchSize = 1000,
+    array $requestOptions = []
+) // => array of batch responses, one per 1,000-record batch
+```
+
+Unlike the typed clients, PHP returns **plain associative arrays**, not objects:
+`$responses[0]['taskID']`, `$responses[0]['objectIDs']`. Always an array of them —
+never treat it as one response.
+
+Read records from a JSON file:
+
+```php
+$records = json_decode(file_get_contents($recordsPath), true);
+```
+
+After a successful ingest, print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` as the last
+stdout line (`echo 'ALGOLIA_WIZARD_RECORD_COUNT='.count($records)."\n";`), with no
+other output after it.

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/docs/algolia-sdk/save-records-ruby.md

@@ -0,0 +1,48 @@
+# Save records (algolia v3)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+Dependency: gem `algolia`, `~> 3.0` (`gem 'algolia', '~> 3.0'`).
+
+`require "algolia"` (gem name is `algolia`, not `algoliasearch`). Build the client
+with `Algolia::SearchClient.create`.
+
+```ruby
+require "algolia"
+
+app_id = ENV.fetch("ALGOLIA_APPLICATION_ID")
+api_key = ENV.fetch("ALGOLIA_WRITE_API_KEY")
+index_name = "playlists"
+
+client = Algolia::SearchClient.create(app_id, api_key)
+
+records = [{ "objectID" => "1", "name" => "Hot 100", "visibility" => "public" }]
+
+responses = client.save_objects(index_name, records, true)
+```
+
+```ruby
+save_objects(
+  index_name,             # String, required
+  objects,                # Array<Hash>, required
+  wait_for_tasks = false,
+  batch_size = 1000,
+  request_options = {}
+) # => Array<Algolia::Search::BatchResponse>, one entry per 1,000-record batch
+```
+
+Args are **positional**, and every method/field is **snake_case**: read
+`r.task_id` and `r.object_ids`, not `taskID`/`objectIDs`. The return value is an
+array — never treat it as one object.
+
+Read records from a JSON file:
+
+```ruby
+require "json"
+
+records = JSON.parse(File.read(records_path))
+```
+
+After a successful ingest, print `ALGOLIA_WIZARD_RECORD_COUNT=<n>` as the last
+stdout line (`puts "ALGOLIA_WIZARD_RECORD_COUNT=#{records.length}"`), with no
+other output after it.