@nshiab/simple-data-analysis 6.0.0 → 6.0.1

package/esm/class/SimpleTable.js

@@ -64,9 +64,9 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * This method automatically appends instructions to your prompt; set `verbose` to `true` to see the full prompt.
      *
-     * This method supports Gemini, Vertex AI, and Ollama. Set `generation.provider` explicitly, or omit it to use `AI_PROVIDER`. All other `generation` fields match the selected `askGemini` or `askOllama` function from journalism-ai. Model and credentials can also come from environment variables.
+     * This method supports Gemini, Vertex AI, and Ollama.
      *
-     * For Ollama, set `AI_PROVIDER=ollama`, ensure Ollama is running, and set `AI_MODEL`, or pass `{ provider: "ollama", ... }` through `generation`.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads `AI_PROVIDER` (`"gemini"` or `"ollama"`; defaults to `"gemini"`), `AI_MODEL` (for example, `"gemini-3-flash-preview"` or `"gemma3:4b"`), and, for Gemini, either `AI_KEY` (for example, `"your-gemini-api-key"`) or both `AI_PROJECT` (for example, `"my-google-cloud-project"`) and `AI_LOCATION` (for example, `"us-central1"`). Values passed through `generation` override the corresponding environment values. When using Ollama, ensure it is running.
      *
      * To manage rate limits, use `batchSize` to process multiple rows per request and `rateLimitPerMinute` to pace requests across the worker pool. The `concurrency` option controls how many requests may run in parallel.
      *
@@ -88,7 +88,7 @@ export default class SimpleTable extends SimpleTableCore {
      * @param options.concurrency - The number of concurrent requests to send. Defaults to `1`.
      * @param options.errorColumn - The optional column where per-row error messages are stored. When omitted, a failed batch throws.
      * @param options.logProgress - If `true`, logs request-pool progress. Defaults to `false`.
-     * @param options.generation - Gemini or Ollama generation configuration. Set `provider` explicitly or omit it to use environment selection; all other fields match the selected journalism-ai function.
+     * @param options.generation - Optional Gemini or Ollama generation configuration.
      * @param options.test - A function to validate the returned data. If it throws an error, the request will be retried (if `retry` is set). Defaults to `undefined`.
      * @param options.retry - The number of times to retry the request in case of failure. Defaults to `0`.
      * @param options.retryCheck - A function that receives an error and returns whether it should be retried. Defaults to `undefined`.
@@ -146,6 +146,10 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * @example
      * ```ts
+     * // Set these environment variables before running:
+     * // AI_PROVIDER=gemini
+     * // AI_MODEL=gemini-3-flash-preview
+     * // AI_KEY=your-gemini-api-key
      * const cities = await sdb
      *   .newTable("cities")
      *   .loadArray([
@@ -187,9 +191,9 @@ export default class SimpleTable extends SimpleTableCore {
     /**
      * Generates embeddings for a specified text column and stores the results in a new column.
      *
-     * This method supports Gemini, Vertex AI, and Ollama embeddings. Set `embeddings.provider` explicitly or omit it to use `AI_EMBEDDINGS_PROVIDER`; all other fields match `getEmbedding` from journalism-ai. Model and credentials can also come from environment variables.
+     * This method supports Gemini, Vertex AI, and Ollama embeddings.
      *
-     * For Ollama, set `AI_EMBEDDINGS_PROVIDER=ollama`, ensure Ollama is running, and set `AI_EMBEDDINGS_MODEL`, or pass `{ provider: "ollama", ... }` through `embeddings`.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads `AI_EMBEDDINGS_PROVIDER` (`"gemini"` or `"ollama"`; defaults to `"gemini"`), `AI_EMBEDDINGS_MODEL` (for example, `"gemini-embedding-001"` or `"nomic-embed-text"`), and, for Gemini, either `AI_KEY` (for example, `"your-gemini-api-key"`) or both `AI_PROJECT` (for example, `"my-google-cloud-project"`) and `AI_LOCATION` (for example, `"us-central1"`). Values passed through `embeddings` override the corresponding environment values. When using Ollama, ensure it is running.
      *
      * To manage rate limits, use `rateLimitPerMinute` to introduce delays between requests. For higher rate limits (business/professional accounts), `concurrency` allows parallel requests.
      *
@@ -211,7 +215,7 @@ export default class SimpleTable extends SimpleTableCore {
      * @param options.efSearch - The number of candidate vertices to consider during search. Higher values result in more accurate searches but increase search time. Defaults to 64.
      * @param options.M - The maximum number of neighbors to keep for each vertex in the graph. Higher values result in more accurate indexes but increase build time and memory usage. Defaults to 16.
      * @param options.concurrency - The number of concurrent requests to send. Defaults to `1`.
-     * @param options.embeddings - Gemini or Ollama embedding configuration. Set `provider` explicitly or omit it to use environment selection; all other fields match `getEmbedding` from journalism-ai.
+     * @param options.embeddings - Optional Gemini or Ollama embedding configuration.
      * @param options.rateLimitPerMinute - The rate limit for AI requests in requests per minute. The method will wait between requests if necessary. Defaults to `undefined` (no limit).
      * @param options.verbose - If `true`, logs additional debugging information. Defaults to `false`.
      * @returns The table, so methods can be chained.
@@ -219,6 +223,10 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * @example
      * ```ts
+     * // Set these environment variables before running:
+     * // AI_EMBEDDINGS_PROVIDER=gemini
+     * // AI_EMBEDDINGS_MODEL=gemini-embedding-001
+     * // AI_KEY=your-gemini-api-key
      * const food = await sdb
      *   .newTable("food")
      *   .loadArray([
@@ -230,10 +238,6 @@ export default class SimpleTable extends SimpleTableCore {
      *     { food: "tacos" },
      *   ])
      *   .aiEmbeddings("food", "embeddings", {
-     *     embeddings: {
-     *       provider: "gemini",
-     *       model: "gemini-embedding-001",
-     *     },
      *     rateLimitPerMinute: 15,
      *     createIndex: true,
      *     verbose: true,
@@ -259,7 +263,7 @@ export default class SimpleTable extends SimpleTableCore {
      * Creates an embedding from a specified text and returns the most similar text content based on their embeddings.
      * This method is useful for semantic search and text similarity tasks, computing cosine distance and sorting results by similarity.
      *
-     * To create the query embedding, omit `embeddings` to use environment variables or pass provider-specific options matching `getEmbedding` from journalism-ai.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads `AI_EMBEDDINGS_PROVIDER` (`"gemini"` or `"ollama"`; defaults to `"gemini"`), `AI_EMBEDDINGS_MODEL` (for example, `"gemini-embedding-001"` or `"nomic-embed-text"`), and, for Gemini, either `AI_KEY` (for example, `"your-gemini-api-key"`) or both `AI_PROJECT` (for example, `"my-google-cloud-project"`) and `AI_LOCATION` (for example, `"us-central1"`). Values passed through `embeddings` override the corresponding environment values.
      *
      * Gemini, Vertex AI, and Ollama are supported. The selected provider and model must match those used to create the stored embedding column so the vectors share the same dimensions and embedding space.
      *
@@ -280,13 +284,17 @@ export default class SimpleTable extends SimpleTableCore {
      * @param options.efSearch - The number of candidate vertices to consider during search. Higher values result in more accurate searches but increase search time. Defaults to 64.
      * @param options.M - The maximum number of neighbors to keep for each vertex in the graph. Higher values result in more accurate indexes but increase build time and memory usage. Defaults to 16.
      * @param options.outputTable - The name of the output table where the results will be stored. If not provided, the current table will be modified. Defaults to `undefined`.
-     * @param options.embeddings - Gemini or Ollama embedding configuration. Set `provider` explicitly or omit it to use environment selection; all other fields match `getEmbedding` from journalism-ai.
+     * @param options.embeddings - Optional Gemini or Ollama embedding configuration.
      * @param options.verbose - If `true`, logs additional debugging information. Defaults to `false`.
      * @returns The table that will contain the similarity results, so methods can be chained.
      * @category AI
      *
      * @example
      * ```ts
+     * // Set these environment variables before running:
+     * // AI_EMBEDDINGS_PROVIDER=gemini
+     * // AI_EMBEDDINGS_MODEL=gemini-embedding-001
+     * // AI_KEY=your-gemini-api-key
      * const similarFood = await sdb
      *   .newTable("food")
      *   .loadArray([
@@ -297,18 +305,9 @@ export default class SimpleTable extends SimpleTableCore {
      *     { food: "salad" },
      *     { food: "tacos" },
      *   ])
-     *   .aiEmbeddings("food", "embeddings", {
-     *     embeddings: {
-     *       provider: "gemini",
-     *       model: "gemini-embedding-001",
-     *     },
-     *   })
+     *   .aiEmbeddings("food", "embeddings")
      *   .aiVectorSimilarity("italian food", "embeddings", 3, {
      *     createIndex: true,
-     *     embeddings: {
-     *       provider: "gemini",
-     *       model: "gemini-embedding-001",
-     *     },
      *     minSimilarity: 0.6,
      *     similarityColumn: "score",
      *   })
@@ -343,7 +342,9 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * Remove `.journalism-cache` and `.sda-cache` to clear existing cache entries. Remember to add both directories to your `.gitignore`.
      *
-     * This method supports Gemini, Vertex AI, and Ollama embeddings. Set `embeddings.provider` explicitly or omit it to use environment selection; all other fields match `getEmbedding` from journalism-ai.
+     * This method supports Gemini, Vertex AI, and Ollama embeddings.
+     *
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads `AI_EMBEDDINGS_PROVIDER` (`"gemini"` or `"ollama"`; defaults to `"gemini"`), `AI_EMBEDDINGS_MODEL` (for example, `"gemini-embedding-001"` or `"nomic-embed-text"`), and, for Gemini, either `AI_KEY` (for example, `"your-gemini-api-key"`) or both `AI_PROJECT` (for example, `"my-google-cloud-project"`) and `AI_LOCATION` (for example, `"us-central1"`). Values passed through `embeddings` override the corresponding environment values.
      *
      * The selected embedding provider is used for both stored row embeddings and the query embedding.
      *
@@ -357,7 +358,7 @@ export default class SimpleTable extends SimpleTableCore {
      * @param textColumn - The name of the column containing the text content to search through.
      * @param nbResults - The number of most similar rows to retrieve.
      * @param options - Configuration options for the hybrid search.
-     * @param options.embeddings - Gemini or Ollama embedding configuration. Set `provider` explicitly or omit it to use environment selection; all other fields match `getEmbedding` from journalism-ai.
+     * @param options.embeddings - Optional Gemini or Ollama embedding configuration.
      * @param options.verbose - If `true`, logs additional debugging information. Defaults to `false`.
      * @param options.createIndex - If `true`, creates an HNSW index when vector search is enabled. The BM25 FTS index is managed automatically whenever BM25 search is enabled. Defaults to `false`.
      * @param options.efConstruction - The number of candidate vertices to consider during index construction. Higher values result in more accurate indexes but increase build time. Defaults to 128.
@@ -385,16 +386,16 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * @example
      * ```ts
+     * // Set these environment variables before running:
+     * // AI_EMBEDDINGS_PROVIDER=gemini
+     * // AI_EMBEDDINGS_MODEL=gemini-embedding-001
+     * // AI_KEY=your-gemini-api-key
      * // Load a dataset of recipes
      * const sdb = new SimpleDB();
      * const results = await sdb
      *   .newTable("recipes")
      *   .loadData("recipes.parquet")
      *   .hybridSearch("buttery pastry for breakfast", "Dish", "Recipe", 10, {
-     *     embeddings: {
-     *       provider: "gemini",
-     *       model: "gemini-embedding-001",
-     *     },
      *     verbose: true,
      *   })
      *   .log();
@@ -422,9 +423,11 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * Remove `.journalism-cache` and `.sda-cache` to clear existing cache entries. Remember to add both directories to your `.gitignore`.
      *
-     * Generation and embeddings are independently configurable. Set either nested `provider` explicitly or omit it to use that provider's environment selection; all remaining fields match journalism-ai.
+     * Generation and embeddings are independently configurable.
+     *
+     * Environment variables are named configuration values supplied to the running process. By default, generation reads `AI_PROVIDER` (`"gemini"` or `"ollama"`; defaults to `"gemini"`) and `AI_MODEL` (for example, `"gemini-3-flash-preview"` or `"gemma3:4b"`), while embeddings read `AI_EMBEDDINGS_PROVIDER` (`"gemini"` or `"ollama"`; defaults to `"gemini"`) and `AI_EMBEDDINGS_MODEL` (for example, `"gemini-embedding-001"` or `"nomic-embed-text"`). Gemini generation and embeddings also read either `AI_KEY` (for example, `"your-gemini-api-key"`) or both `AI_PROJECT` (for example, `"my-google-cloud-project"`) and `AI_LOCATION` (for example, `"us-central1"`). Values passed through either option override its environment defaults.
      *
-     * For example, `generation.provider` can be `"gemini"` while `embeddings.provider` is `"ollama"`. Environment-only mixed providers use `AI_PROVIDER` and `AI_EMBEDDINGS_PROVIDER`.
+     * For example, `generation.provider` can be `"gemini"` while `embeddings.provider` is `"ollama"`; the same mix can be selected through `AI_PROVIDER=gemini` and `AI_EMBEDDINGS_PROVIDER=ollama`.
      *
      * Ollama temperature defaults to 0. Gemini uses the provider's default temperature.
      *
@@ -437,8 +440,8 @@ export default class SimpleTable extends SimpleTableCore {
      * @param textColumn - The name of the column containing the text content to search through and use as context.
      * @param nbResults - The number of most similar rows to retrieve and use as context for the AI.
      * @param options - Configuration options for the RAG process.
-     * @param options.generation - Gemini or Ollama generation configuration. Set `provider` explicitly or omit it to use environment selection; all other relevant fields match the selected journalism-ai function.
-     * @param options.embeddings - Gemini or Ollama embedding configuration. Set `provider` explicitly or omit it to use environment selection; all other fields match `getEmbedding` from journalism-ai.
+     * @param options.generation - Optional Gemini or Ollama generation configuration.
+     * @param options.embeddings - Optional Gemini or Ollama embedding configuration.
      * @param options.verbose - If `true`, logs additional debugging information. Defaults to `false`.
      * @param options.includeThoughts - If `true`, includes the AI model's reasoning process in the logged output when using models that support extended thinking. Only relevant when used with thinking-capable models. Defaults to `false`.
      * @param options.metrics - An object to track cumulative metrics across multiple AI requests. Pass an object with totalCost, totalInputTokens, totalOutputTokens, and totalRequests properties (all initialized to 0). The function will update these values after each request. Note: totalCost is only calculated for Google GenAI models, not for Ollama.
@@ -466,6 +469,12 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * @example
      * ```ts
+     * // Set these environment variables before running:
+     * // AI_PROVIDER=gemini
+     * // AI_MODEL=gemini-3-flash-preview
+     * // AI_KEY=your-gemini-api-key
+     * // AI_EMBEDDINGS_PROVIDER=ollama
+     * // AI_EMBEDDINGS_MODEL=nomic-embed-text
      * // Load a dataset of recipes
      * const sdb = new SimpleDB();
      * const answer = await sdb
@@ -476,17 +485,7 @@ export default class SimpleTable extends SimpleTableCore {
      *     "Dish", // Column with unique IDs
      *     "Recipe", // Column with text to search
      *     10, // The 10 most relevant recipes passed to the LLM
-     *     {
-     *       generation: {
-     *         provider: "gemini",
-     *         model: "gemini-3-flash-preview",
-     *       },
-     *       embeddings: {
-     *         provider: "ollama",
-     *         model: "nomic-embed-text",
-     *       },
-     *       verbose: true, // Log debugging information and timings
-     *     },
+     *     { verbose: true }, // Log debugging information and timings
      *   );
      *
      * console.log(answer);
@@ -516,9 +515,9 @@ export default class SimpleTable extends SimpleTableCore {
      * Generates and executes a SQL query based on a prompt.
      * Additional instructions, such as column types, are automatically added to your prompt. Set `verbose` to `true` to see the full prompt.
      *
-     * This method supports Gemini, Vertex AI, and Ollama. Set `generation.provider` explicitly or omit it to use environment selection; all other relevant fields match `askGemini` or `askOllama` from journalism-ai.
+     * This method supports Gemini, Vertex AI, and Ollama.
      *
-     * For Ollama, set `AI_PROVIDER=ollama`, ensure Ollama is running, and set `AI_MODEL`, or pass `{ provider: "ollama", ... }` through `generation`.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads `AI_PROVIDER` (`"gemini"` or `"ollama"`; defaults to `"gemini"`), `AI_MODEL` (for example, `"gemini-3-flash-preview"` or `"gemma3:4b"`), and, for Gemini, either `AI_KEY` (for example, `"your-gemini-api-key"`) or both `AI_PROJECT` (for example, `"my-google-cloud-project"`) and `AI_LOCATION` (for example, `"us-central1"`). Values passed through `generation` override the corresponding environment values. When using Ollama, ensure it is running.
      *
      * Ollama temperature defaults to 0, while Gemini uses the provider's default. Provider-specific controls live under `generation`.
      *
@@ -528,7 +527,7 @@ export default class SimpleTable extends SimpleTableCore {
      * @param prompt - The input string to guide the AI in generating the SQL query.
      * @param options - Configuration options for the AI request.
      * @param options.extraInstructions - Additional instructions to append to the prompt, providing more context or guidance for the AI.
-     * @param options.generation - Gemini or Ollama generation configuration. Set `provider` explicitly or omit it to use environment selection; all other relevant fields match the selected journalism-ai function.
+     * @param options.generation - Optional Gemini or Ollama generation configuration.
      * @param options.outputTable - The name of a new table where the results will be stored. If not provided, the current table will be replaced with the query results.
      * @param options.verbose - If `true`, logs additional debugging information, including the full prompt sent to the AI. Defaults to `false`.
      * @param options.includeThoughts - If `true`, includes the AI model's reasoning process in the logged output when using models that support extended thinking. Only relevant when used with thinking-capable models. Defaults to `false`.
@@ -537,17 +536,17 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * @example
      * ```ts
+     * // Set these environment variables before running:
+     * // AI_PROVIDER=gemini
+     * // AI_MODEL=gemini-3-flash-preview
+     * // AI_KEY=your-gemini-api-key
      * // The AI will generate a query that will be executed, and
      * // the result will replace the existing table.
      * // If run again, it will use the previous query from the cache.
      * // Don't forget to add .journalism-cache to your .gitignore file!
      * const averageSalaryByDepartment = await table
      *   .aiQuery("Give me the average salary by department", {
-     *       generation: {
-     *         provider: "gemini",
-     *         model: "gemini-3-flash-preview",
-     *       },
-     *       verbose: true,
+     *     verbose: true,
      *   })
      *   .log();
      * ```
@@ -586,7 +585,9 @@ export default class SimpleTable extends SimpleTableCore {
      * Writes the table data to a Google Sheet.
      * This method uses the `pushToSheet` function from the [journalism-google library](https://jsr.io/@nshiab/journalism-google). Refer to its documentation for more details.
      *
-     * By default, the selected tab is overwritten and values are written without Google Sheets interpretation. Authentication is handled via environment variables (GOOGLE_PRIVATE_KEY and GOOGLE_SERVICE_ACCOUNT_EMAIL). Alternatively, you can use GOOGLE_APPLICATION_CREDENTIALS pointing to a service account JSON file. For detailed setup instructions, refer to the node-google-spreadsheet authentication guide: https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication.
+     * By default, the selected tab is overwritten and values are written without Google Sheets interpretation.
+     *
+     * Environment variables are named configuration values supplied to the running process. For authentication, this method reads `GOOGLE_SERVICE_ACCOUNT_EMAIL` (for example, `"service-account@example.iam.gserviceaccount.com"`) with `GOOGLE_PRIVATE_KEY` (for example, `"-----BEGIN PRIVATE KEY-----\n..."`). Alternatively, set `GOOGLE_APPLICATION_CREDENTIALS` to a service-account JSON path (for example, `"./service-account.json"`). Values passed through `options.credentials` override these environment values. For detailed setup instructions, refer to the node-google-spreadsheet authentication guide: https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication.
      *
      * @param sheetUrl - A Google Sheets URL. It can point to a spreadsheet or a specific tab.
      * @param options - An optional object with configuration options:
@@ -596,7 +597,7 @@ export default class SimpleTable extends SimpleTableCore {
      * @param options.prepend - Text to add above the header row in overwrite mode.
      * @param options.lastUpdate - If `true`, adds a UTC timestamp. Pass a Canadian time zone to use it for the timestamp. Available only in overwrite mode.
      * @param options.raw - If `true`, writes values without Google Sheets interpretation. Defaults to `true`.
-     * @param options.credentials - Explicit Google service-account credentials. These override credentials provided through environment variables or GOOGLE_APPLICATION_CREDENTIALS.
+     * @param options.credentials - Optional Google service-account credentials.
      * @param options.credentials.email - The Google service-account email.
      * @param options.credentials.privateKey - The Google service-account private key.
      * @returns A promise that resolves when the data has been written to the sheet.
@@ -604,6 +605,9 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * @example
      * ```ts
+     * // Set these environment variables before running:
+     * // GOOGLE_SERVICE_ACCOUNT_EMAIL=service-account@example.iam.gserviceaccount.com
+     * // GOOGLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...
      * // Load, transform, and write data to a Google Sheet
      * await sdb
      *   .newTable()
@@ -664,19 +668,22 @@ export default class SimpleTable extends SimpleTableCore {
      * Loads data from a Google Sheet into the table.
      * This method uses the `getSheetData` function from the [journalism library](https://jsr.io/@nshiab/journalism). Refer to its documentation for more details.
      *
-     * By default, authentication is handled via environment variables (GOOGLE_PRIVATE_KEY and GOOGLE_SERVICE_ACCOUNT_EMAIL). Alternatively, you can use GOOGLE_APPLICATION_CREDENTIALS pointing to a service account JSON file. For detailed setup instructions, refer to the node-google-spreadsheet authentication guide: https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads `GOOGLE_SERVICE_ACCOUNT_EMAIL` (for example, `"service-account@example.iam.gserviceaccount.com"`) with `GOOGLE_PRIVATE_KEY` (for example, `"-----BEGIN PRIVATE KEY-----\n..."`). Alternatively, set `GOOGLE_APPLICATION_CREDENTIALS` to a service-account JSON path (for example, `"./service-account.json"`).
      * The download is queued and runs in chain order at the next awaited observer or `run()` call.
      *
      * @param sheetUrl - The URL pointing to a specific Google Sheet (e.g., `"https://docs.google.com/spreadsheets/d/.../edit#gid=0"`).
      * @param options - An optional object with configuration options:
      * @param options.skip - The number of rows to skip from the top of the sheet before reading data. Useful when the sheet contains metadata or headers that should not be included in the data.
-     * @param options.apiEmailEnvVar - The name of the environment variable that stores your API email.
-     * @param options.apiKeyEnvVar - The name of the environment variable that stores your API key.
+     * @param options.apiEmailEnvVar - A custom environment-variable name from which to read the Google service-account email. Defaults to `"GOOGLE_SERVICE_ACCOUNT_EMAIL"`.
+     * @param options.apiKeyEnvVar - A custom environment-variable name from which to read the Google service-account private key. Defaults to `"GOOGLE_PRIVATE_KEY"`.
      * @returns The table, so methods can be chained.
      * @category Loading Data
      *
      * @example
      * ```ts
+     * // Set these environment variables before running:
+     * // GOOGLE_SERVICE_ACCOUNT_EMAIL=service-account@example.iam.gserviceaccount.com
+     * // GOOGLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...
      * // Load data from a Google Sheet
      * const sheetData = await sdb
      *   .newTable("sheetData")
@@ -702,11 +709,11 @@ export default class SimpleTable extends SimpleTableCore {
     /**
      * Writes the table data as CSV to a Datawrapper chart or table.
      *
-     * Authentication is handled via an API key stored in the environment variable `DATAWRAPPER_KEY`, or a custom variable name via `options.apiKeyEnvVar`.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads the API key from `DATAWRAPPER_KEY` (for example, `"your-datawrapper-api-key"`).
      *
      * @param chartId - The unique ID of the Datawrapper chart or table to update. This ID can be found in the Datawrapper URL or dashboard.
      * @param options - An optional object with configuration options:
-     * @param options.apiKeyEnvVar - The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). Defaults to `"DATAWRAPPER_KEY"`.
+     * @param options.apiKeyEnvVar - A custom environment-variable name from which to read the Datawrapper API key. Defaults to `"DATAWRAPPER_KEY"`.
      * @param options.note - A string to update the chart's notes field with (e.g., a last-updated timestamp).
      * @param options.republish - If `true`, republishes the chart after updating the data. Defaults to `false`.
      * @returns A promise that resolves when the data has been sent to Datawrapper.
@@ -714,6 +721,7 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * @example
      * ```ts
+     * // Set DATAWRAPPER_KEY=your-datawrapper-api-key before running.
      * // Load, transform, and send data to a Datawrapper chart
      * await sdb
      *   .newTable()
@@ -737,17 +745,18 @@ export default class SimpleTable extends SimpleTableCore {
     /**
      * Loads data from a Datawrapper chart or table into the table.
      *
-     * Authentication is handled via an API key stored in the environment variable `DATAWRAPPER_KEY`, or a custom variable name via `options.apiKeyEnvVar`.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads the API key from `DATAWRAPPER_KEY` (for example, `"your-datawrapper-api-key"`).
      * The download is queued and runs in chain order at the next awaited observer or `run()` call.
      *
      * @param chartId - The unique ID of the Datawrapper chart or table. This ID can be found in the Datawrapper URL or dashboard.
      * @param options - An optional object with configuration options:
-     * @param options.apiKeyEnvVar - The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). Defaults to `"DATAWRAPPER_KEY"`.
+     * @param options.apiKeyEnvVar - A custom environment-variable name from which to read the Datawrapper API key. Defaults to `"DATAWRAPPER_KEY"`.
      * @returns The table, so methods can be chained.
      * @category Loading Data
      *
      * @example
      * ```ts
+     * // Set DATAWRAPPER_KEY=your-datawrapper-api-key before running.
      * // Load data from a Datawrapper chart
      * const chartData = await sdb
      *   .newTable("chartData")
@@ -762,11 +771,11 @@ export default class SimpleTable extends SimpleTableCore {
     /**
      * Writes the table's geospatial data as GeoJSON to a Datawrapper map.
      *
-     * Authentication is handled via an API key stored in the environment variable `DATAWRAPPER_KEY`, or a custom variable name via `options.apiKeyEnvVar`.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads the API key from `DATAWRAPPER_KEY` (for example, `"your-datawrapper-api-key"`).
      *
      * @param chartId - The unique ID of the Datawrapper map to update. This ID can be found in the Datawrapper URL or dashboard.
      * @param options - An optional object with configuration options:
-     * @param options.apiKeyEnvVar - The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). Defaults to `"DATAWRAPPER_KEY"`.
+     * @param options.apiKeyEnvVar - A custom environment-variable name from which to read the Datawrapper API key. Defaults to `"DATAWRAPPER_KEY"`.
      * @param options.column - The name of the geometry column to use. If omitted, the method will automatically attempt to find a geometry column.
      * @param options.note - A string to update the map's notes field with.
      * @param options.republish - If `true`, republishes the map after updating the data. Defaults to `false`.
@@ -775,6 +784,7 @@ export default class SimpleTable extends SimpleTableCore {
      *
      * @example
      * ```ts
+     * // Set DATAWRAPPER_KEY=your-datawrapper-api-key before running.
      * // Load, transform, and send geospatial data to a Datawrapper map
      * await sdb
      *   .newTable()
@@ -798,19 +808,20 @@ export default class SimpleTable extends SimpleTableCore {
     /**
      * Loads geospatial data from a Datawrapper map into the table.
      *
-     * Authentication is handled via an API key stored in the environment variable `DATAWRAPPER_KEY`, or a custom variable name via `options.apiKeyEnvVar`.
+     * Environment variables are named configuration values supplied to the running process. By default, this method reads the API key from `DATAWRAPPER_KEY` (for example, `"your-datawrapper-api-key"`).
      *
      * The data is temporarily written to `.sda-cache/tmp/dataviz/<uuid>.geojson` and removed after loading. Remember to add `.sda-cache` to your `.gitignore`.
      * The download is queued and runs in chain order at the next awaited observer or `run()` call.
      *
      * @param chartId - The unique ID of the Datawrapper map. This ID can be found in the Datawrapper URL or dashboard.
      * @param options - An optional object with configuration options:
-     * @param options.apiKeyEnvVar - The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). Defaults to `"DATAWRAPPER_KEY"`.
+     * @param options.apiKeyEnvVar - A custom environment-variable name from which to read the Datawrapper API key. Defaults to `"DATAWRAPPER_KEY"`.
      * @returns The table, so methods can be chained.
      * @category Loading Data
      *
      * @example
      * ```ts
+     * // Set DATAWRAPPER_KEY=your-datawrapper-api-key before running.
      * // Load geo data from a Datawrapper map
      * const mapData = await sdb
      *   .newTable("mapData")