Prompted edits

Prompted edits let users change imported data from the review step with a prompt. They can:

• Clean values and normalize formats
• Add, update, or remove rows before delivery

You choose how prompted edits work:

• Use managed prompted edits with { type: "managed" } when you want to run our standard prompt interpretation, code generation, and sandbox execution.
• Use custom prompted edits with { type: "custom", promptedEditHandler } when you want to run your own prompt interpretation and code generation logic.

Prompted edits are disabled by default.

Managed Prompted Edits

For the hosted ExpressCSV AI path, pass { type: "managed" } to useExpressCSV().

import { useExpressCSV, x } from "@expresscsv/react";

const schema = x.row({
  sku: x.string().label("SKU"),
  name: x.string().label("Product name"),
  price: x.number().min(0).label("Price"),
});

export function ImportProductsButton() {
  const { open } = useExpressCSV({
    schema,
    getSessionToken: async () => fetchSessionToken(),
    importNamespace: "product-import",
    promptedEdits: { type: "managed" }, 
  });

  return (
    <button
      onClick={() =>
        open({
          onData: async (_chunk, next) => next(),
        })
      }
    >
      Import products
    </button>
  );
}

How Prompted Edits Run

Managed prompted edits:

• Generate JavaScript for the requested operation
• Execute it in a sandbox
• Apply the result as proposed grid changes

The managed path supports two execution scopes:

If the prompt is ambiguous, impossible, or needs external data the importer does not have, the edit can return a no-op message instead of changing data.

Custom Prompted Edits

Pass type: "custom" when your own service should interpret prompts and return proposed changes. This avoids ExpressCSV's managed generation and sandbox path.

import {
  useExpressCSV,
  type PromptedEditHandler,
  type PromptedEditResult,
} from "@expresscsv/react";

const promptedEditHandler: PromptedEditHandler<typeof schema> = async ({
  sessionId,
  prompt,
  fields,
  rows,
  totalRows,
}) => {
  const response = await fetch("/your-api/ai/prompted-edits", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      sessionId,
      prompt,
      fields,
      rows,
      totalRows,
    }),
  });

  if (!response.ok) {
    throw new Error("Prompted edit failed");
  }

  return (await response.json()) as PromptedEditResult<typeof schema>;
};

const { open } = useExpressCSV({
  schema,
  getSessionToken: async () => fetchSessionToken(),
  importNamespace: "product-import",
  promptedEdits: { 
    type: "custom", 
    promptedEditHandler, 
  }, 
});

Your handler receives:

Return type: "no-op" when the request should not change data:

return {
  type: "no-op",
  message: "Tell me which column should be used for the SKU prefix.",
};

Return type: "success" with rowId-based changes when you have changes:

return {
  type: "success",
  changes: [
    { type: "add", values: { sku: "NEW-001", name: "New product", price: "12.50" } },
    {
      type: "update",
      rowId: rows[0].rowId,
      values: {
        name: "Trimmed product name",
        price: "12.50",
      },
    },
    { type: "remove", rowId: rows[4].rowId },
  ],
};

• update: only the fields in values change on the row identified by rowId
• remove: deletes rows by rowId
• add: creates new rows from values

Use rowIndex only to interpret prompts about display position (for example "update the first 10 rows"):

• Select rows where rowIndex is less than the cutoff, then return update changes using each row's rowId
• Do not use rowIndex as the stable identifier in returned changes; sorting, filtering, or row insertion can change display order