@rebasepro/plugin-ai 0.12.0 → 0.12.1-canary.g009ed95

package/src/tests/review.test.tsx

@@ -0,0 +1,260 @@
+import { TextEncoder, TextDecoder } from "util";
+Object.assign(global, { TextEncoder,
+TextDecoder });
+
+import React from "react";
+import { act, renderHook, waitFor } from "@testing-library/react";
+
+import {
+    DataEnhancementControllerProvider,
+    useDataEnhancementController
+} from "../components/DataEnhancementControllerProvider";
+
+/**
+ * The propose → review → apply contract.
+ *
+ * The design this replaced streamed generated text straight into the live form
+ * fields. Its failure modes were all the same failure: the record changed
+ * before anyone agreed to it. Half-written sentences appeared mid-generation,
+ * heuristics guessed whether each token should append to or replace what the
+ * operator had typed, and getting the old value back meant retyping it.
+ *
+ * So the load-bearing assertion in this file is a negative one — `setFieldValue`
+ * is not called — and it is checked during streaming, after streaming, after a
+ * failure, and after a discard. Everything else here is detail; that is the
+ * promise.
+ */
+
+jest.mock("@rebasepro/admin", () => ({
+    getFieldId: (property: { type?: string }) => (property?.type === "string" ? "text_field" : "number_field")
+}));
+
+const COLLECTION = {
+    name: "Products",
+    singularName: "Product",
+    properties: {
+        title: { type: "string",
+name: "Title" },
+        subtitle: { type: "string",
+name: "Subtitle" },
+        stock: { type: "number",
+name: "Stock" }
+    }
+} as any;
+
+/** A `Response` whose body yields the given chunks, in order. */
+function streamingResponse(chunks: string[]): any {
+    const encoder = new TextEncoder();
+    let i = 0;
+    return {
+        ok: true,
+        status: 200,
+        body: {
+            getReader: () => ({
+                read: async () =>
+                    i < chunks.length
+                        ? { done: false,
+value: encoder.encode(chunks[i++]) }
+                        : { done: true,
+value: undefined }
+            })
+        }
+    };
+}
+
+const AUTOFILL_BODY = [
+    'event: suggestion_delta\ndata: {"key":"title","text":"Blue "}',
+    'event: suggestion_delta\ndata: {"key":"title","text":"widget"}',
+    'event: suggestion\ndata: {"key":"title","value":"Blue widget"}',
+    'event: suggestion\ndata: {"key":"stock","value":42}',
+    'event: done\ndata: {"suggestions":{"title":"Blue widget","stock":42}}',
+    ""
+].join("\n\n");
+
+/** Route `/status` to an availability answer and `/autofill` to a stream. */
+function mockService(autofill: () => any, available = true) {
+    (global as any).fetch = jest.fn((url: string) => {
+        if (String(url).endsWith("/status")) {
+            return Promise.resolve({ ok: true,
+status: 200,
+json: async () => ({ available,
+model: "gemini-3.6-flash" }) });
+        }
+        if (String(url).endsWith("/autofill")) return Promise.resolve(autofill());
+        return Promise.resolve({ ok: true,
+status: 200,
+json: async () => ({ prompts: [] }) });
+    });
+}
+
+async function mountController(formValues: Record<string, unknown> = {}) {
+    const setFieldValue = jest.fn();
+    const formContext = { values: formValues,
+setFieldValue } as any;
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+        <DataEnhancementControllerProvider
+            path={"products"}
+            collection={COLLECTION}
+            formContext={formContext}
+            {...({} as any)}>
+            {children}
+        </DataEnhancementControllerProvider>
+    );
+
+    const rendered = renderHook(() => useDataEnhancementController(), { wrapper });
+    return { ...rendered,
+setFieldValue };
+}
+
+afterEach(() => {
+    jest.restoreAllMocks();
+});
+
+describe("autofill review", () => {
+
+    it("never writes to the form while generating or after it finishes", async () => {
+        mockService(() => streamingResponse([AUTOFILL_BODY]));
+        const { result, setFieldValue } = await mountController({ title: "" });
+        await waitFor(() => expect(result.current.enabled).toBe(true));
+
+        await act(async () => {
+            await result.current.generate({ values: { title: "" } });
+        });
+
+        expect(result.current.review?.status).toBe("ready");
+        expect(result.current.review?.fields.length).toBe(2);
+        expect(setFieldValue).not.toHaveBeenCalled();
+    });
+
+    it("accumulates streamed text into the proposal, not the field", async () => {
+        mockService(() => streamingResponse([AUTOFILL_BODY]));
+        const { result, setFieldValue } = await mountController();
+        await waitFor(() => expect(result.current.enabled).toBe(true));
+
+        await act(async () => {
+            await result.current.generate({ values: {} });
+        });
+
+        const title = result.current.review?.fields.find(f => f.key === "title");
+        expect(title?.proposed).toBe("Blue widget");
+        expect(title?.pending).toBe(false);
+        expect(title?.label).toBe("Title");
+        expect(setFieldValue).not.toHaveBeenCalled();
+    });
+
+    it("writes only the selected fields, and only on apply", async () => {
+        mockService(() => streamingResponse([AUTOFILL_BODY]));
+        const { result, setFieldValue } = await mountController();
+        await waitFor(() => expect(result.current.enabled).toBe(true));
+
+        await act(async () => {
+            await result.current.generate({ values: {} });
+        });
+
+        act(() => result.current.toggleField("stock"));
+        expect(setFieldValue).not.toHaveBeenCalled();
+
+        act(() => result.current.applyReview());
+
+        expect(setFieldValue).toHaveBeenCalledTimes(1);
+        expect(setFieldValue).toHaveBeenCalledWith("title", "Blue widget");
+        // The review closes on apply — there is nothing left to decide.
+        expect(result.current.review).toBeNull();
+    });
+
+    it("writes nothing when the review is discarded", async () => {
+        mockService(() => streamingResponse([AUTOFILL_BODY]));
+        const { result, setFieldValue } = await mountController({ title: "Existing" });
+        await waitFor(() => expect(result.current.enabled).toBe(true));
+
+        await act(async () => {
+            await result.current.generate({ values: { title: "Existing" } });
+        });
+        act(() => result.current.dismissReview());
+
+        expect(setFieldValue).not.toHaveBeenCalled();
+        expect(result.current.review).toBeNull();
+    });
+
+    it("records what each proposal would overwrite", async () => {
+        // The row shows the current value struck through, which is only possible
+        // because the form was never touched — it still holds the original.
+        mockService(() => streamingResponse([AUTOFILL_BODY]));
+        const { result } = await mountController({ title: "Old title" });
+        await waitFor(() => expect(result.current.enabled).toBe(true));
+
+        await act(async () => {
+            await result.current.generate({ values: { title: "Old title" } });
+        });
+
+        const title = result.current.review?.fields.find(f => f.key === "title");
+        expect(title?.currentValue).toBe("Old title");
+        expect(title?.proposed).toBe("Blue widget");
+    });
+
+    it("toggles every field at once", async () => {
+        mockService(() => streamingResponse([AUTOFILL_BODY]));
+        const { result, setFieldValue } = await mountController();
+        await waitFor(() => expect(result.current.enabled).toBe(true));
+
+        await act(async () => {
+            await result.current.generate({ values: {} });
+        });
+
+        act(() => result.current.toggleAll(false));
+        act(() => result.current.applyReview());
+        expect(setFieldValue).not.toHaveBeenCalled();
+    });
+
+    it("keeps the fields that arrived before a mid-stream failure", async () => {
+        // A run that produced two good fields and then broke should still let
+        // the operator take the two, rather than discarding the work.
+        const truncated = [
+            'event: suggestion\ndata: {"key":"title","value":"Blue widget"}',
+            'event: error\ndata: {"message":"quota exhausted"}',
+            ""
+        ].join("\n\n");
+        mockService(() => streamingResponse([truncated]));
+        const { result, setFieldValue } = await mountController();
+        await waitFor(() => expect(result.current.enabled).toBe(true));
+
+        await act(async () => {
+            await result.current.generate({ values: {} });
+        });
+
+        expect(result.current.review?.status).toBe("failed");
+        expect(result.current.review?.error).toMatch(/quota exhausted/);
+        expect(result.current.review?.fields.map(f => f.key)).toEqual(["title"]);
+        expect(setFieldValue).not.toHaveBeenCalled();
+
+        act(() => result.current.applyReview());
+        expect(setFieldValue).toHaveBeenCalledWith("title", "Blue widget");
+    });
+
+    it("sends values flattened onto the same dotted paths as the properties", async () => {
+        // The service is told about `seo.title`, so it has to be told the value
+        // of `seo.title` — not of `seo`. Sending the nested object instead makes
+        // every existing value invisible to the model, which shows up as
+        // autofill cheerfully overwriting things the operator already wrote.
+        mockService(() => streamingResponse([AUTOFILL_BODY]));
+        const { result } = await mountController();
+        await waitFor(() => expect(result.current.enabled).toBe(true));
+
+        await act(async () => {
+            await result.current.generate({ values: { seo: { title: "Nested" } } });
+        });
+
+        const call = ((global as any).fetch as jest.Mock).mock.calls
+            .find(([url]: [string]) => String(url).endsWith("/autofill"));
+        expect(JSON.parse(call[1].body).values).toEqual({ "seo.title": "Nested" });
+    });
+
+    it("stays disabled when the service reports unavailable", async () => {
+        mockService(() => streamingResponse([AUTOFILL_BODY]), false);
+        const { result } = await mountController();
+        await waitFor(() => expect((global as any).fetch).toHaveBeenCalled());
+        expect(result.current.enabled).toBe(false);
+        expect(result.current.review).toBeNull();
+    });
+});

package/src/tests/useDataEnhancementPlugin.test.tsx

@@ -19,6 +19,7 @@ if (typeof window !== "undefined") {
 
 import { renderHook } from "@testing-library/react";
 import { useDataEnhancementPlugin } from "../useDataEnhancementPlugin";
+import { DEFAULT_AI_ENDPOINT } from "../api";
 
 jest.mock("@rebasepro/admin", () => ({
     useUrlController: () => ({})
@@ -29,23 +30,43 @@ describe("useDataEnhancementPlugin hook", () => {
         const { result } = renderHook(() => useDataEnhancementPlugin());
         const plugin = result.current;
 
-        expect(plugin.key).toBe("data_enhancement");
-        expect(plugin.slots).toBeDefined();
-        expect(plugin.slots[0].slot).toBe("form.actions");
-        expect(plugin.providers).toBeDefined();
-        expect(plugin.providers[0].scope).toBe("form");
-        expect(plugin.providers[0].props.apiKey).toBe("fcms-U9jdDii0xXWSDC34asfrf54lbkFJBfKfRWcEDEwdc4V5wDWEDF");
+        // Matched as one shape rather than indexed field by field. `slots` and
+        // `providers` are optional on `Plugin`, and a preceding
+        // `expect(...).toBeDefined()` does not narrow them for TypeScript — so
+        // the indexed form only compiled because nothing type-checked this file.
+        // `toMatchObject` needs no narrowing and pins the fields together, which
+        // is what "correct metadata" actually means.
+        expect(plugin).toMatchObject({
+            key: "data_enhancement",
+            slots: [{ slot: "form.actions" }],
+            providers: [{ scope: "form" }]
+        });
     });
 
-    it("accepts and forwards custom apiKey and host props", () => {
-        const customProps = {
-            apiKey: "custom-key",
-            host: "https://custom-host.com"
-        };
-        const { result } = renderHook(() => useDataEnhancementPlugin(customProps));
-        const plugin = result.current;
+    it("ships no credentials", () => {
+        // The FireCMS-era plugin exported a hardcoded `fcms-…` key as
+        // `DEFAULT_API_KEY` and handed it to the provider. Anyone who installed
+        // the package got a copy. Nothing key-shaped may reach the provider
+        // props again — the hosted service authenticates nobody by design.
+        const { result } = renderHook(() => useDataEnhancementPlugin());
+        const props = result.current.providers?.[0]?.props ?? {};
+        expect(Object.keys(props)).toEqual(expect.not.arrayContaining(["apiKey", "firebaseToken", "token"]));
+        expect(JSON.stringify(props)).not.toMatch(/fcms-/);
+    });
+
+    it("forwards a custom endpoint so a self-hoster can proxy the service", () => {
+        const { result } = renderHook(() => useDataEnhancementPlugin({ endpoint: "https://ai.example.com" }));
 
-        expect(plugin.providers[0].props.apiKey).toBe("custom-key");
-        expect(plugin.providers[0].props.host).toBe("https://custom-host.com");
+        expect(result.current).toMatchObject({
+            providers: [{ props: { endpoint: "https://ai.example.com" } }]
+        });
+    });
+
+    it("leaves the endpoint unset so the client falls back to the hosted default", () => {
+        // Compared against the exported constant rather than a copy of the URL:
+        // a copy pins the string, this pins the wiring.
+        const { result } = renderHook(() => useDataEnhancementPlugin());
+        expect(result.current.providers?.[0]?.props?.endpoint).toBeUndefined();
+        expect(DEFAULT_AI_ENDPOINT).toMatch(/^https:\/\//);
     });
 });

package/src/types/data_enhancement_controller.tsx

@@ -1,64 +1,131 @@
 import { EntityValues } from "@rebasepro/types";
 import { EditorAIController } from "@rebasepro/admin";
 
-export type EnhanceParams<M extends Record<string, unknown>> = {
-    entityId?: string | number;
+export type GenerateParams<M extends Record<string, unknown>> = {
+    values: EntityValues<M>;
+    /** Free-text instruction from the operator, if they gave one. */
+    instructions?: string;
+    /** Restrict the run to one field. */
     propertyKey?: string;
     propertyInstructions?: string;
-    values: EntityValues<M>;
+};
+
+/**
+ * One field the model wants to write, awaiting the operator's decision.
+ *
+ * Nothing here has touched the form. That is the entire point of the type: the
+ * previous design streamed generated text straight into the live fields, which
+ * meant a half-written sentence was indistinguishable from a bug, the
+ * operator's own words were overwritten by heuristics that tried to guess
+ * whether to append or replace, and there was no way back other than retyping.
+ */
+export type ProposedField = {
+    /** Dotted property path, e.g. `seo.title`. */
+    key: string;
+    /** The property's display name, falling back to its key. */
+    label: string;
+    /** What is in the form right now — shown so an overwrite is visible. */
+    currentValue: unknown;
+    /** What the model proposes. Grows while `pending`. */
+    proposed: unknown;
+    /** Still streaming. */
+    pending: boolean;
+    /** Whether Apply will write this one. */
+    selected: boolean;
+};
+
+export type AutofillReview = {
+    status: "generating" | "ready" | "failed";
+    /** Set when `status` is `failed`. */
+    error?: string;
+    /** In arrival order, so the list reads as the model works. */
+    fields: ProposedField[];
+    /** What was asked for, shown back to the operator while they review. */
     instructions?: string;
-    replaceValues: boolean;
 };
 
 export type DataEnhancementController = {
     /**
-     * Whether the data enhancement is enabled for the current path
+     * Whether autofill can actually be used right now.
+     *
+     * The conjunction of two separate things: the host app allows it for this
+     * collection ({@link DataEnhancementPluginProps.getConfigForPath}), *and*
+     * the service reported itself available. The second half is what the
+     * FireCMS-era plugin lacked — it rendered its button unconditionally
+     * against a host that no longer existed, so every click 404'd.
      */
     enabled: boolean;
-    suggestions: Record<string, string | number>;
-    enhance: <M extends Record<string, unknown>>(props: EnhanceParams<M>) => Promise<EnhancedDataResult | null>;
-    clearSuggestion: (key: string, suggestion: string | number) => void;
-    allowReferenceDataSelection: boolean;
-    clearAllSuggestions: () => void;
+
+    /** The run in flight or awaiting review; `null` when there is neither. */
+    review: AutofillReview | null;
+
+    /** Start a run. Opens {@link review}; never writes to the form. */
+    generate: <M extends Record<string, unknown>>(params: GenerateParams<M>) => Promise<void>;
+
+    /** Include or exclude one field from what Apply will write. */
+    toggleField: (key: string) => void;
+
+    /** Select or deselect every field at once. */
+    toggleAll: (selected: boolean) => void;
+
+    /**
+     * Write the selected fields to the form and close the review.
+     *
+     * The only path by which this plugin mutates a record, and it runs once per
+     * run rather than once per token — so it is a single undo step and a single
+     * dirty transition, not hundreds.
+     */
+    applyReview: () => void;
+
+    /** Close the review, writing nothing. The record is untouched. */
+    dismissReview: () => void;
+
     getSamplePrompts: (entityName: string, input?: string) => Promise<SamplePromptsResult>;
-    loadingSuggestions: string[],
+
     editorAIController?: EditorAIController;
-}
+};
 
-export type EnhancedDataResult = {
-    entityId?: string | number;
-    suggestions: {
-        [key: string]: string[];
-    };
-    errors: string[];
-    usage: { promptTokens?: number, completionTokens?: number, totalTokens?: number }
-}
+/** What `GET /status` answers. Everything else is gated on `available`. */
+export type AiStatus = {
+    available: boolean;
+    model?: string;
+    features?: string[];
+};
+
+export type AutofillResult = {
+    /** Every field the service completed, keyed by property path. */
+    suggestions: Record<string, unknown>;
+    usage?: { inputTokens?: number; outputTokens?: number };
+};
 
 export type SamplePrompt = {
     prompt: string;
     type: "recent" | "sample";
-}
+};
 
 export type SamplePromptsResult = {
     prompts: SamplePrompt[];
-    host?: string;
 };
 
-export type DataEnhancementRequest = {
+/**
+ * The autofill request body.
+ *
+ * The property schema travels with every request because the service has no
+ * access to the caller's collections — it is a hosted endpoint reachable from
+ * any self-hosted admin panel. That is the cost of not putting an LLM
+ * dependency in `@rebasepro/server`; had the route lived in the backend it
+ * could have read the collection registry and this would be three fields.
+ */
+export type AutofillRequest = {
     entityName: string;
     entityDescription?: string;
-    inputEntity: InputEntity;
+    values: Record<string, unknown>;
     properties: Record<string, InputProperty>;
     propertyKey?: string;
-    propertyInstructions?: string,
+    propertyInstructions?: string;
     instructions?: string;
 };
 
-export type InputEntity = {
-    entityId?: string | number;
-    values: Record<string, any>;
-};
-
 export type InputProperty = {
     name?: string;
     description?: string;
@@ -72,4 +139,4 @@ export type InputProperty = {
         typeField?: string;
         valueField?: string;
     };
-}
+};

package/src/useDataEnhancementPlugin.tsx

@@ -5,17 +5,12 @@ import { RebasePlugin } from "@rebasepro/admin-types";
 import { DataEnhancementControllerProvider } from "./components/DataEnhancementControllerProvider";
 import { FormEnhanceAction } from "./components/FormEnhanceAction";
 
-const DEFAULT_API_KEY = "fcms-U9jdDii0xXWSDC34asfrf54lbkFJBfKfRWcEDEwdc4V5wDWEDF";
-
 export interface DataEnhancementPluginProps {
 
-    apiKey?: string;
-
     /**
      * Use this function to determine if the data enhancement plugin should be enabled for a given path.
      * If this function is not provided, the plugin will be enabled for all paths.
      * If the function returns false, the plugin will be disabled for the given path.
-     * You can also return a configuration object to override the default configuration.
      *
      * @param path
      * @param collection
@@ -27,10 +22,17 @@ export interface DataEnhancementPluginProps {
     }) => boolean;
 
     /**
-     * Host to use for the data enhancement API.
-     * This prop is only use in development mode.
+     * Base URL of the AI service.
+     *
+     * Defaults to the one Rebase hosts, which is free to use and needs no
+     * configuration. Point it at your own deployment to keep generation inside
+     * your infrastructure — the wire format is documented in `src/api.ts`, and
+     * the reference implementation is `saas/backend/functions/ai.ts`.
+     *
+     * Whatever it points at, the plugin renders nothing until that host's
+     * `GET /status` reports itself available.
      */
-    host?: string;
+    endpoint?: string;
 }
 
 /**
@@ -40,8 +42,8 @@ export interface DataEnhancementPluginProps {
  */
 export function useDataEnhancementPlugin(props?: DataEnhancementPluginProps): RebasePlugin {
 
-    const apiKey = props?.apiKey ?? DEFAULT_API_KEY;
     const getConfigForPath = props?.getConfigForPath;
+    const endpoint = props?.endpoint;
 
     return React.useMemo(() => ({
         key: "data_enhancement",
@@ -57,11 +59,10 @@ export function useDataEnhancementPlugin(props?: DataEnhancementPluginProps): Re
                 scope: "form" as const,
                 Component: DataEnhancementControllerProvider as React.ComponentType<any>,
                 props: {
-                    apiKey,
                     getConfigForPath,
-                    host: props?.host
+                    endpoint
                 }
             }
         ]
-    }), [apiKey, getConfigForPath, props?.host]);
+    }), [getConfigForPath, endpoint]);
 }

package/dist/utils/diffStrings.d.ts

@@ -1,7 +0,0 @@
-type ChangeType = "equal" | "delete" | "insert";
-export interface Change {
-    type: ChangeType;
-    value: string;
-}
-export declare function diffStrings(oldStr: string, newStr: string): Change[];
-export {};

package/dist/utils/strings_counter.d.ts

@@ -1,2 +0,0 @@
-import { EntityValues, Properties } from "@rebasepro/types";
-export declare function countStringCharacters(values: EntityValues<any>, properties: Properties): number;

package/dist/utils/suggestions.d.ts

@@ -1 +0,0 @@
-export declare function getAppendableSuggestion(suggestion: string | number | undefined, value: unknown): string | undefined;