zitejs 0.9.114 → 0.9.115

package/dist/cjs/backend/index.d.ts

@@ -82,6 +82,12 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
      * `{ user: null }` for a webhook fire exactly as it does for a cron one.
      */
     webhook?: TWebhook;
+    /**
+     * Set by {@link createEndpoint}, not by hand. The worker validates
+     * `inputSchema` for bundles built before this did, and skips ones that
+     * declare it — parsing twice would apply a schema's transforms twice.
+     */
+    validatesInput?: boolean;
     execute: (params: {
         input: TInput;
         context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;
@@ -89,4 +95,11 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
         stream: ZiteStreamInterface;
     } : {})) => Promise<TOutput> | TOutput;
 }
+/**
+ * Create an endpoint definition, parsing `input` against `inputSchema` before
+ * `execute` runs. Nothing downstream parses it — the worker calls `execute` on
+ * whatever this returns — so while this was a bare `return config` a required
+ * field could be missing and the endpoint ran anyway. Parsing here is also what
+ * makes `TRawInput` -> `TInput` (defaults, transforms) true at runtime.
+ */
 export declare function createEndpoint<TInput = unknown, TOutput = unknown, TStream extends boolean = false, TSchedule extends ZiteSchedule | undefined = undefined, TWebhook extends ZiteWebhook | undefined = undefined, TRawInput = TInput>(config: EndpointConfig<TInput, TOutput, TStream, TSchedule, TWebhook, TRawInput>): EndpointConfig<TInput, TOutput, TStream, TSchedule, TWebhook, TRawInput>;

package/dist/cjs/backend/index.js

@@ -31,6 +31,68 @@ class ZiteError extends Error {
     }
 }
 exports.ZiteError = ZiteError;
+/** Injected by the runner on a platform-fired run — see `isPlatformTriggeredInput`. */
+const PLATFORM_TRIGGER_KEYS = ["__cron", "__webhook"];
+function isPlatformTriggeredInput(input) {
+    if (typeof input !== "object" || input === null)
+        return false;
+    return PLATFORM_TRIGGER_KEYS.some((key) => Object.prototype.hasOwnProperty.call(input, key));
+}
+function isIssueBearingError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        Array.isArray(error.issues));
+}
+function describeIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.map((part) => String(part)).join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}
+/**
+ * Create an endpoint definition, parsing `input` against `inputSchema` before
+ * `execute` runs. Nothing downstream parses it — the worker calls `execute` on
+ * whatever this returns — so while this was a bare `return config` a required
+ * field could be missing and the endpoint ran anyway. Parsing here is also what
+ * makes `TRawInput` -> `TInput` (defaults, transforms) true at runtime.
+ */
 function createEndpoint(config) {
-    return config;
+    const { inputSchema, execute } = config;
+    const firesWithoutARequest = Boolean(config.schedule || config.webhook);
+    // An `inputSchema` that isn't a validator stays inert, as it was.
+    if (!inputSchema || typeof inputSchema.parse !== "function")
+        return config;
+    return {
+        ...config,
+        validatesInput: true,
+        // `async` so a schema failure rejects: `execute` may be declared sync, and
+        // a sync throw would escape the caller's `.catch()`.
+        execute: async (params) => {
+            // Cron and webhook fires carry no request body, so a schema written for
+            // request callers doesn't describe them.
+            if (isPlatformTriggeredInput(params.input))
+                return execute(params);
+            // Same, for a fire with no input object to hold the sentinel: the runner
+            // only merges `__cron` into a plain object.
+            if (firesWithoutARequest && params.input === undefined) {
+                return execute(params);
+            }
+            let parsed;
+            try {
+                parsed = inputSchema.parse(params.input);
+            }
+            catch (error) {
+                throw new ZiteError({
+                    code: "BAD_REQUEST",
+                    message: isIssueBearingError(error)
+                        ? `Invalid input: ${describeIssues(error)}`
+                        : `Invalid input: ${String(error?.message ?? error)}`,
+                    userFacingMessage: "Some of the information sent with this request was missing or invalid.",
+                });
+            }
+            return execute({ ...params, input: parsed });
+        },
+    };
 }

package/dist/cjs/backend/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/backend/index.test.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const zod_1 = require("zod");
+const index_js_1 = require("./index.js");
+const index_js_2 = require("../runtime/index.js");
+const requestContext = { user: { id: "u1", email: "a@b.c" } };
+(0, vitest_1.afterEach)(() => {
+    vitest_1.vi.unstubAllGlobals();
+});
+(0, vitest_1.describe)("createEndpoint input validation", () => {
+    (0, vitest_1.it)("rejects input that does not satisfy inputSchema, without running execute", async () => {
+        const execute = vitest_1.vi.fn();
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({ token: zod_1.z.string().min(10) }),
+            execute,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({ input: {}, context: requestContext })).rejects.toBeInstanceOf(index_js_1.ZiteError);
+        (0, vitest_1.expect)(execute).not.toHaveBeenCalled();
+    });
+    (0, vitest_1.it)("surfaces the failure as BAD_REQUEST and names the offending field", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({ token: zod_1.z.string().min(10) }),
+            execute: async () => "unreachable",
+        });
+        await (0, vitest_1.expect)(endpoint.execute({ input: {}, context: requestContext })).rejects.toMatchObject({
+            code: "BAD_REQUEST",
+            message: vitest_1.expect.stringContaining("token"),
+        });
+    });
+    (0, vitest_1.it)("rejects a call with no input at all", async () => {
+        const execute = vitest_1.vi.fn();
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({ token: zod_1.z.string().min(10) }),
+            execute,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: undefined,
+            context: requestContext,
+        })).rejects.toMatchObject({ code: "BAD_REQUEST" });
+        (0, vitest_1.expect)(execute).not.toHaveBeenCalled();
+    });
+    (0, vitest_1.it)("hands execute the parsed value, so schema defaults finally apply", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({
+                token: zod_1.z.string(),
+                limit: zod_1.z.number().default(10),
+            }),
+            execute: async ({ input }) => input,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: { token: "abc" },
+            context: requestContext,
+        })).resolves.toEqual({ token: "abc", limit: 10 });
+    });
+    (0, vitest_1.it)("passes valid input through untouched", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({
+                token: zod_1.z.string().min(10),
+                action: zod_1.z.enum(["load", "accept"]),
+            }),
+            execute: async ({ input }) => input.action,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: { token: "b69779ae-eeea", action: "load" },
+            context: requestContext,
+        })).resolves.toBe("load");
+    });
+    (0, vitest_1.it)("declares that it validates, so the worker does not parse a second time", () => {
+        const withSchema = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({ token: zod_1.z.string() }),
+            execute: async () => null,
+        });
+        const withoutSchema = (0, index_js_1.createEndpoint)({ execute: async () => null });
+        (0, vitest_1.expect)(withSchema.validatesInput).toBe(true);
+        (0, vitest_1.expect)(withoutSchema.validatesInput).toBeUndefined();
+    });
+    (0, vitest_1.it)("leaves an endpoint without an inputSchema exactly as it was", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            execute: async ({ input }) => input,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: { anything: true },
+            context: requestContext,
+        })).resolves.toEqual({ anything: true });
+    });
+    (0, vitest_1.it)("preserves the stream handle for streaming endpoints", async () => {
+        const stream = { write: async () => { }, forward: async () => "" };
+        const endpoint = (0, index_js_1.createEndpoint)({
+            stream: true,
+            inputSchema: zod_1.z.object({ prompt: zod_1.z.string() }),
+            execute: async (params) => params.stream === stream,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: { prompt: "hi" },
+            context: requestContext,
+            stream,
+        })).resolves.toBe(true);
+    });
+});
+(0, vitest_1.describe)("platform-triggered runs", () => {
+    (0, vitest_1.it)("does not validate a cron fire, and leaves __cron readable", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({ token: zod_1.z.string().min(10) }),
+            schedule: {
+                scheduleType: "recurring",
+                schedule: { frequency: "hourly", interval: 6 },
+                timezone: "UTC",
+            },
+            execute: async ({ input }) => input,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: { __cron: { scheduleId: "s1" } },
+            context: { user: null },
+        })).resolves.toEqual({ __cron: { scheduleId: "s1" } });
+    });
+    (0, vitest_1.it)("does not validate a scheduled fire that carries no input object", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.string(),
+            schedule: {
+                scheduleType: "recurring",
+                schedule: { frequency: "hourly", interval: 6 },
+                timezone: "UTC",
+            },
+            execute: async ({ input }) => input ?? "(no input)",
+        });
+        await (0, vitest_1.expect)(endpoint.execute({ input: undefined, context: { user: null } })).resolves.toBe("(no input)");
+    });
+    (0, vitest_1.it)("still validates an ordinary endpoint called with no input", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.string(),
+            execute: async ({ input }) => input,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({ input: undefined, context: requestContext })).rejects.toMatchObject({ code: "BAD_REQUEST" });
+    });
+    (0, vitest_1.it)("does not validate a webhook fire", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({ token: zod_1.z.string().min(10) }),
+            webhook: {},
+            execute: async ({ input }) => input,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: { __webhook: { headers: {} }, id: 7 },
+            context: { user: null },
+        })).resolves.toEqual({ __webhook: { headers: {} }, id: 7 });
+    });
+});
+/**
+ * The failure this was written for: an endpoint that looks a customer up by a
+ * token, called with no token. The undefined was dropped on the way to the
+ * database and the unfiltered lookup returned the first row of the table.
+ * Either guard alone stops it; they fail at different layers, so both are here.
+ */
+(0, vitest_1.describe)("regression: token lookup on an endpoint called without a token", () => {
+    function buildEndpoint(onMatch) {
+        const clients = (0, index_js_2.createTableClient)("Clients");
+        return (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({
+                token: zod_1.z.string().min(10),
+                action: zod_1.z.enum(["load", "accept"]),
+            }),
+            execute: async ({ input }) => {
+                const row = await clients.findOne({ filters: { token: input.token } });
+                if (!row)
+                    return "invalid_token";
+                onMatch(row.nom);
+                return "ok";
+            },
+        });
+    }
+    (0, vitest_1.it)("stops at the schema, so the database is never reached", async () => {
+        const dispatched = [];
+        vitest_1.vi.stubGlobal("__wrapSdkCall", async (_i, _c, m) => {
+            dispatched.push(m);
+            return { id: "1", token: "", nom: "an unrelated customer" };
+        });
+        const matched = [];
+        await (0, vitest_1.expect)(buildEndpoint((nom) => matched.push(nom)).execute({
+            input: {},
+            context: requestContext,
+        })).rejects.toMatchObject({ code: "BAD_REQUEST" });
+        (0, vitest_1.expect)(dispatched).toEqual([]);
+        (0, vitest_1.expect)(matched).toEqual([]);
+    });
+    (0, vitest_1.it)("stops at the query too, if an undefined token reaches it another way", async () => {
+        const dispatched = [];
+        vitest_1.vi.stubGlobal("__wrapSdkCall", async (_i, _c, m) => {
+            dispatched.push(m);
+            return { id: "1", token: "", nom: "an unrelated customer" };
+        });
+        const warn = vitest_1.vi.spyOn(console, "warn").mockImplementation(() => { });
+        const clients = (0, index_js_2.createTableClient)("Clients");
+        const token = undefined;
+        // Answers "no match" rather than throwing: `if (!row) return
+        // { status: 'invalid_token' }` is what the endpoint already does, so this
+        // makes the incident path correct without the app changing anything.
+        const row = await clients.findOne({ filters: { token } });
+        (0, vitest_1.expect)(row).toBeUndefined();
+        (0, vitest_1.expect)(dispatched).toEqual([]);
+        (0, vitest_1.expect)(warn).toHaveBeenCalled();
+        warn.mockRestore();
+    });
+});

package/dist/cjs/runtime/index.js

@@ -8,6 +8,78 @@ exports.createAirtableClient = createAirtableClient;
 exports.createEmailClient = createEmailClient;
 const sdkCall_js_1 = require("../internal/sdkCall.js");
 const DB_INTEGRATION_ID = "databases";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Not thrown — the miss is the answer. Logged so the author can still find out
+ * their value was missing, since a silent null looks exactly like a legitimate
+ * no-match and would otherwise hide the bug that caused it.
+ */
+function warnEmptySelector(className, method, detail) {
+    console.warn(`${className}.${method}: ${detail} is undefined, so this query would have ` +
+        "run unnarrowed and returned an arbitrary record. Returning no match " +
+        "instead. Check the value before querying, or pass null to match " +
+        "records where the field is empty.");
+}
+/**
+ * Whether a selector was written with nothing in it.
+ *
+ * `JSON.stringify` drops an undefined value, so `{ filters: { token: undefined } }`
+ * reaches base-runner as `{ filters: {} }` — a valid request for no filter.
+ * `findOne` answers that with the first row of the table, and the caller reads
+ * it back as a match.
+ *
+ * `findOne` treats it as "matched nothing" instead, which is what asking for
+ * `token === undefined` should mean. Callers already handle the miss —
+ * `if (!row) return { status: 'invalid_token' }` — so the shape that caused the
+ * incident becomes correct on its own, with no app change and nothing to break.
+ *
+ * **`findOne` only.** On `findAll`, "no filter" is a coherent request, and
+ * `filters: { status: maybeUndefined }` meaning "don't narrow on status" is an
+ * idiom that type-checks today (`RecordFilters` is a `?:` map, and apps build
+ * without `exactOptionalPropertyTypes`). It is also what Prisma does with
+ * `undefined` in a `where`. Only `findOne` has no sane reading, because an
+ * unnarrowed single-row query returns an arbitrary record rather than everything.
+ *
+ * A key the caller never wrote is untouched: `findOne({ filters: {} })` still
+ * means "no filter" and still returns the first row. Only a key written with
+ * nothing in it counts. (Unknown filter keys have the same consequence — see
+ * `RecordFilters` — but those are `keyof T` and caught at build time.)
+ */
+function selectorMatchesNothing(className, method, params) {
+    if (!params)
+        return false;
+    const { filters } = params;
+    if (isPlainObject(filters)) {
+        for (const [key, value] of Object.entries(filters)) {
+            if (value === undefined) {
+                warnEmptySelector(className, method, `filter "${key}"`);
+                return true;
+            }
+            // `{ field: { contains: undefined } }` collapses to `{ field: {} }` — no
+            // condition on that field at all.
+            if (isPlainObject(value)) {
+                for (const [operator, operand] of Object.entries(value)) {
+                    if (operand === undefined) {
+                        warnEmptySelector(className, method, `filter "${key}.${operator}"`);
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    // An undefined `id` leaves the query with no selector at all. Only counts
+    // when nothing else narrows it, so `findOne({ id: maybeId, filters: {...} })`
+    // still runs on the filters.
+    const wroteId = Object.prototype.hasOwnProperty.call(params, "id");
+    const hasFilters = isPlainObject(filters) && Object.keys(filters).length > 0;
+    if (wroteId && params.id === undefined && !hasFilters) {
+        warnEmptySelector(className, method, "`id`");
+        return true;
+    }
+    return false;
+}
 function getBaseId() {
     try {
         return (globalThis.__ZITE_EXECUTION_CONFIG__?.baseId ??
@@ -34,16 +106,22 @@ function resolveTableId(className) {
 }
 function createTableClient(className) {
     return {
-        findAll: (params) => (0, sdkCall_js_1.getSdkCall)()(DB_INTEGRATION_ID, className, "findAll", {
-            baseId: getBaseId(),
-            tableId: resolveTableId(className),
-            ...params,
-        }),
-        findOne: (params) => (0, sdkCall_js_1.getSdkCall)()(DB_INTEGRATION_ID, className, "findOne", {
-            baseId: getBaseId(),
-            tableId: resolveTableId(className),
-            ...params,
-        }),
+        findAll: async (params) => {
+            return (0, sdkCall_js_1.getSdkCall)()(DB_INTEGRATION_ID, className, "findAll", {
+                baseId: getBaseId(),
+                tableId: resolveTableId(className),
+                ...params,
+            });
+        },
+        findOne: async (params) => {
+            if (selectorMatchesNothing(className, "findOne", params))
+                return undefined;
+            return (0, sdkCall_js_1.getSdkCall)()(DB_INTEGRATION_ID, className, "findOne", {
+                baseId: getBaseId(),
+                tableId: resolveTableId(className),
+                ...params,
+            });
+        },
         create: (params) => (0, sdkCall_js_1.getSdkCall)()(DB_INTEGRATION_ID, className, "create", {
             baseId: getBaseId(),
             tableId: resolveTableId(className),
@@ -74,10 +152,12 @@ function createSqlClient() {
 }
 function createAuthClient() {
     return {
-        findAllUsers: (options) => (0, sdkCall_js_1.getSdkCall)()(DB_INTEGRATION_ID, "Auth", "findAllUsers", {
-            baseId: getBaseId(),
-            ...options,
-        }),
+        findAllUsers: async (options) => {
+            return (0, sdkCall_js_1.getSdkCall)()(DB_INTEGRATION_ID, "Auth", "findAllUsers", {
+                baseId: getBaseId(),
+                ...options,
+            });
+        },
         updateUserProfile: (userId, profile) => (0, sdkCall_js_1.getSdkCall)()(DB_INTEGRATION_ID, "Auth", "updateUserProfile", {
             baseId: getBaseId(),
             userId,
@@ -87,14 +167,20 @@ function createAuthClient() {
 }
 function createAirtableClient(integrationId, className, implicitParams) {
     return {
-        findAll: (params) => (0, sdkCall_js_1.getSdkCall)()(integrationId, className, "findAll", {
-            ...implicitParams,
-            ...params,
-        }),
-        findOne: (params) => (0, sdkCall_js_1.getSdkCall)()(integrationId, className, "findOne", {
-            ...implicitParams,
-            ...params,
-        }),
+        findAll: async (params) => {
+            return (0, sdkCall_js_1.getSdkCall)()(integrationId, className, "findAll", {
+                ...implicitParams,
+                ...params,
+            });
+        },
+        findOne: async (params) => {
+            if (selectorMatchesNothing(className, "findOne", params))
+                return undefined;
+            return (0, sdkCall_js_1.getSdkCall)()(integrationId, className, "findOne", {
+                ...implicitParams,
+                ...params,
+            });
+        },
         create: (params) => (0, sdkCall_js_1.getSdkCall)()(integrationId, className, "create", {
             ...implicitParams,
             ...params,

package/dist/cjs/runtime/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/runtime/index.test.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_js_1 = require("./index.js");
+/** Captures what the runtime would have dispatched to the workflow-runner. */
+function stubSdkCall(result = undefined) {
+    const calls = [];
+    vitest_1.vi.stubGlobal("__wrapSdkCall", async (_integrationId, _className, method, params) => {
+        calls.push({ method, params });
+        return result;
+    });
+    return calls;
+}
+(0, vitest_1.afterEach)(() => {
+    vitest_1.vi.unstubAllGlobals();
+});
+(0, vitest_1.describe)("the mechanism", () => {
+    (0, vitest_1.it)("drops an undefined filter value on serialization, leaving an unfiltered read", () => {
+        const token = undefined;
+        const wire = JSON.stringify({ filters: { tokenFraisAdmin: token } });
+        (0, vitest_1.expect)(wire).toBe('{"filters":{}}');
+        (0, vitest_1.expect)(JSON.parse(wire).filters).toEqual({});
+    });
+});
+(0, vitest_1.describe)("findOne", () => {
+    (0, vitest_1.it)("matches nothing when a filter value is undefined, without dispatching", async () => {
+        // The incident shape. `if (!row) return { status: 'invalid_token' }` is
+        // what callers already write, so answering "no match" makes that code
+        // correct on its own — where returning the first row made it lie.
+        const calls = stubSdkCall();
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        const token = undefined;
+        const row = await clients.findOne({
+            filters: { tokenFraisAdmin: token },
+        });
+        (0, vitest_1.expect)(row).toBeUndefined();
+        (0, vitest_1.expect)(calls).toHaveLength(0);
+    });
+    (0, vitest_1.it)("warns so a missing value is still discoverable in the run log", async () => {
+        // A silent miss looks exactly like a legitimate no-match, which would hide
+        // the bug that produced it.
+        const warn = vitest_1.vi.spyOn(console, "warn").mockImplementation(() => { });
+        stubSdkCall();
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        await clients.findOne({ filters: { tokenFraisAdmin: undefined } });
+        (0, vitest_1.expect)(warn).toHaveBeenCalledWith(vitest_1.expect.stringContaining('filter "tokenFraisAdmin" is undefined'));
+        warn.mockRestore();
+    });
+    (0, vitest_1.it)("matches nothing on an undefined operand inside a filter condition", async () => {
+        const calls = stubSdkCall();
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        const row = await clients.findOne({
+            filters: { nom: { contains: undefined } },
+        });
+        (0, vitest_1.expect)(row).toBeUndefined();
+        (0, vitest_1.expect)(calls).toHaveLength(0);
+    });
+    (0, vitest_1.it)("matches nothing on an undefined id when nothing else narrows the query", async () => {
+        const calls = stubSdkCall();
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        const id = undefined;
+        const row = await clients.findOne({ id });
+        (0, vitest_1.expect)(row).toBeUndefined();
+        (0, vitest_1.expect)(calls).toHaveLength(0);
+    });
+    (0, vitest_1.it)("still allows an undefined id when filters narrow the query", async () => {
+        const calls = stubSdkCall();
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        await clients.findOne({ id: undefined, filters: { nom: "Henry" } });
+        (0, vitest_1.expect)(calls).toHaveLength(1);
+    });
+    (0, vitest_1.it)("still allows a deliberate unfiltered lookup", async () => {
+        const calls = stubSdkCall();
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        await clients.findOne({ filters: {} });
+        await clients.findOne({});
+        (0, vitest_1.expect)(calls).toHaveLength(2);
+    });
+    (0, vitest_1.it)("passes real values through untouched", async () => {
+        const calls = stubSdkCall();
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        await clients.findOne({ filters: { tokenFraisAdmin: "b69779ae-eeea" } });
+        (0, vitest_1.expect)(calls[0]?.params).toMatchObject({
+            filters: { tokenFraisAdmin: "b69779ae-eeea" },
+        });
+    });
+    (0, vitest_1.it)("allows null, which means the field is empty", async () => {
+        const calls = stubSdkCall();
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        await clients.findOne({ filters: { nom: { not: null } } });
+        (0, vitest_1.expect)(calls).toHaveLength(1);
+    });
+});
+(0, vitest_1.describe)("findAll", () => {
+    (0, vitest_1.it)("treats an undefined filter value as 'do not narrow on this'", async () => {
+        // Deliberately NOT guarded, unlike findOne. On a list query "no filter" is
+        // a coherent request, `filters: { x: maybeUndefined }` type-checks today,
+        // and this is what Prisma does with undefined in a `where`. The dangerous
+        // reading is findOne's, where an unnarrowed query returns an arbitrary row
+        // that the caller treats as a match.
+        const calls = stubSdkCall({ records: [], hasMore: false });
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        await clients.findAll({ filters: { tokenFraisAdmin: undefined } });
+        (0, vitest_1.expect)(calls).toHaveLength(1);
+    });
+    (0, vitest_1.it)("still allows listing a whole table on purpose", async () => {
+        const calls = stubSdkCall({ records: [], hasMore: false });
+        const clients = (0, index_js_1.createTableClient)("Clients");
+        await clients.findAll();
+        await clients.findAll({ limit: 10 });
+        (0, vitest_1.expect)(calls).toHaveLength(2);
+    });
+});
+(0, vitest_1.describe)("other clients on the same path", () => {
+    (0, vitest_1.it)("guards the Airtable client", async () => {
+        const calls = stubSdkCall();
+        const table = (0, index_js_1.createAirtableClient)("airtable", "Clients", {
+            baseId: "app1",
+            tableId: "tbl1",
+        });
+        const row = await table.findOne({
+            filters: { tokenFraisAdmin: undefined },
+        });
+        (0, vitest_1.expect)(row).toBeUndefined();
+        (0, vitest_1.expect)(calls).toHaveLength(0);
+    });
+    (0, vitest_1.it)("leaves auth user lookups alone, as a findAll", async () => {
+        const calls = stubSdkCall({ records: [], total: 0, hasMore: false });
+        const auth = (0, index_js_1.createAuthClient)();
+        await auth.findAllUsers({ filters: { email: undefined } });
+        (0, vitest_1.expect)(calls).toHaveLength(1);
+    });
+});

package/dist/cjs/sync/lib.js

@@ -541,6 +541,7 @@ function generateDbTs(inputSchema) {
     lines.push('//       `not: null` means "is set". An empty `in: []` matches nothing; an', "//       empty `notIn: []` applies no filter.");
     lines.push("//     sort is currently IGNORED here — it is stripped before the request.", "//       (it does work on zite.auth.findAllUsers). Order in SQL instead.");
     lines.push("//     limit defaults to 500, max 2000; offset is a row count (a number)");
+    lines.push('//     a filter value of `undefined` is REJECTED (it would query unfiltered', '//       and match an arbitrary record). Check the value first.');
     lines.push("//   .findOne({ id?, filters?, fields? }) → T | undefined");
     lines.push("//   .create({ record }) → T");
     lines.push("//   .update({ id, record }) → { id: string, fields: Partial<T> }");
@@ -1157,6 +1158,13 @@ function generateAirtableTs(inputLock) {
         "// Auto-generated by zitejs generate from zite.lock. Do not edit manually.",
         "// Airtable SDK — uses createAirtableClient from zitejs/runtime.",
         "//",
+        "// Usage in endpoint files (src/api/*.ts) — one client is exported per table:",
+        `//   import { ${lock.tables[0]?.sdkName ?? "TableName"} } from 'zitejs/integrations';`,
+        "//",
+        "// Always use 'zitejs/integrations' — never a relative path like",
+        "// '../../.zite/integrations/airtable'. The tsconfig aliases resolve zitejs/*",
+        "// imports to the correct .zite/ files.",
+        "//",
         "// Each exported table client has these methods (all take a single params object):",
         "//   findAll({ offset?, limit?, filters? }) => { records: T[], offset: string | undefined, hasMore: boolean }",
         "//   findOne({ id?, filters? }) => T | undefined",
@@ -1374,6 +1382,12 @@ function generateEmailSdk(integrationId) {
         "// Auto-generated by zitejs generate from zite.config.json. Do not edit manually.",
         "// Email SDK — sends through the Zite email gateway via the runtime bridge.",
         "//",
+        "// Usage in endpoint files (src/api/*.ts):",
+        "//   import { Email } from 'zitejs/email';",
+        "//",
+        "// Always use 'zitejs/email' — never a relative path like '../../.zite/integrations/email'.",
+        "// The tsconfig aliases resolve zitejs/* imports to the correct .zite/ files.",
+        "//",
         "//   await Email.send({ to, subject, body: [{ type: 'text', content: '...' }] })",
         "//     => { success: boolean; messageId: string }",
         "//",

package/dist/cjs/sync/sdkNames.d.ts

@@ -25,7 +25,8 @@ export declare function toPascalCase(name: string): string;
 export declare function toCamelCase(name: string): string;
 /**
  * camelCase for a FRESH sdkName, reading acronym runs as words: "VIP" ->
- * "vip", "APIKey" -> "apiKey" (plain toCamelCase yields "vIP" / "aPIKey").
+ * "vip", "APIKey" -> "apiKey" (plain toCamelCase yields "vIP" / "aPIKey"), and
+ * folding a diacritic into its base letter: "Filières" -> "filieres".
  *
  * Deliberately not folded into toCamelCase: that also derives endpoint
  * identifiers from existing filenames on every generate, where normalizing