@farm.js/core 0.1.0-beta.0 → 0.1.0-beta.3

package/dist/index.cjs

@@ -3052,7 +3052,7 @@ function createFarmMarkdownRouteModule(input) {
         ...props,
         components: {
           ...components,
-          ...props?.components || {}
+          ...props?.components
         }
       })
     );
@@ -3569,7 +3569,11 @@ async function prepareFarmWorkflowsForNitro(config) {
     };
   }
   const handlerPath = path28.join(generatedDir, "http-handler.mjs");
-  await fs9.writeFile(handlerPath, createNitroWorkflowHTTPHandler(workflowConfig, workflows), "utf8");
+  await fs9.writeFile(
+    handlerPath,
+    createNitroWorkflowHTTPHandler(workflowConfig, workflows),
+    "utf8"
+  );
   const manifestPath = path28.join(generatedDir, "manifest.json");
   await fs9.writeFile(
     manifestPath,
@@ -3643,13 +3647,7 @@ function normalizeSchedule(schedule) {
   return (Array.isArray(schedule) ? schedule : [schedule]).map((value) => value.trim()).filter(Boolean);
 }
 function resolveWorkflowDefinition(module2) {
-  const candidates = [
-    module2.default,
-    module2.workflow,
-    module2.cron,
-    module2.task,
-    module2.job
-  ];
+  const candidates = [module2.default, module2.workflow, module2.cron, module2.task, module2.job];
   for (const candidate of candidates) {
     if (candidate && typeof candidate === "object" && typeof candidate.run === "function") {
       return candidate;
@@ -4562,8 +4560,8 @@ function compareFarmRouteRuleSpecificity(left, right) {
 }
 function getFarmRouteRuleSpecificity(pattern) {
   return normalizeRoutePattern(pattern).split("/").filter(Boolean).reduce((score, segment) => {
-    if (segment === "**" || /^\[\[\.\.\./.test(segment)) return score + 1;
-    if (segment === "*" || /^\[\.\.\./.test(segment)) return score + 10;
+    if (segment === "**" || segment.startsWith("[[...")) return score + 1;
+    if (segment === "*" || segment.startsWith("[...")) return score + 10;
     if (/^\[.+\]$/.test(segment) || /^:.+$/.test(segment)) return score + 50;
     return score + 100;
   }, 0);
@@ -4625,7 +4623,7 @@ function routeRulesToHeaders(routeRules) {
   for (const [source, rule] of Object.entries(routeRules)) {
     const headers2 = {
       ...normalizeCorsHeaders(rule.cors),
-      ...rule.headers || {}
+      ...rule.headers
     };
     const entries = Object.entries(headers2);
     if (entries.length === 0) continue;
@@ -4655,7 +4653,7 @@ function routeRulesToNitroRouteRules(routeRules) {
       nitroRule.cors = true;
       nitroRule.headers = {
         ...normalizeCorsHeaders(rule.cors),
-        ...rule.headers || {}
+        ...rule.headers
       };
     }
     delete nitroRule.render;
@@ -4724,20 +4722,41 @@ function applyFarmCacheInvalidations(keys) {
     }
   }
 }
+function encodeFarmCacheInvalidations(keys) {
+  const normalized = Array.from(
+    new Set(keys.filter((key) => typeof key === "string" && key.length > 0))
+  );
+  if (normalized.length === 0) return null;
+  return encodeURIComponent(JSON.stringify(normalized));
+}
+function decodeFarmCacheInvalidations(value) {
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(decodeURIComponent(value));
+    return Array.isArray(parsed) ? Array.from(
+      new Set(parsed.filter((key) => typeof key === "string" && key.length > 0))
+    ) : [];
+  } catch {
+    return [];
+  }
+}
 function subscribeFarmCacheInvalidation(listener) {
   const state = getFarmCacheInvalidationState();
   state.listeners.add(listener);
   return () => state.listeners.delete(listener);
 }
-var FARM_CACHE_INVALIDATION_STATE, globalState;
+var FARM_CACHE_INVALIDATION_HEADER, FARM_CACHE_INVALIDATION_STATE, globalState;
 var init_cache_invalidation = __esm({
   "src/cache-invalidation.ts"() {
     "use strict";
+    FARM_CACHE_INVALIDATION_HEADER = "x-farm-cache-invalidations";
     FARM_CACHE_INVALIDATION_STATE = /* @__PURE__ */ Symbol.for("farm.cacheInvalidationState");
     globalState = globalThis;
     __name(getFarmCacheInvalidationState, "getFarmCacheInvalidationState");
     __name(notifyFarmCacheInvalidation, "notifyFarmCacheInvalidation");
     __name(applyFarmCacheInvalidations, "applyFarmCacheInvalidations");
+    __name(encodeFarmCacheInvalidations, "encodeFarmCacheInvalidations");
+    __name(decodeFarmCacheInvalidations, "decodeFarmCacheInvalidations");
     __name(subscribeFarmCacheInvalidation, "subscribeFarmCacheInvalidation");
   }
 });
@@ -6196,6 +6215,22 @@ var init_bridge = __esm({
 });
 
 // src/cache.ts
+function defineCacheKey() {
+  return (factory) => {
+    if (typeof factory !== "function") {
+      throw new TypeError("defineCacheKey expects a key factory function.");
+    }
+    return ((...args) => {
+      const key = factory(...args);
+      if (typeof key !== "string" && !Array.isArray(key)) {
+        throw new TypeError(
+          "A defined cache key factory must return a string or structured array."
+        );
+      }
+      return key;
+    });
+  };
+}
 function getFarmDataCache() {
   return sharedFarmDataCache;
 }
@@ -6344,6 +6379,7 @@ var init_cache = __esm({
     init_cache_invalidation();
     init_bridge();
     init_cache_invalidation();
+    __name(defineCacheKey, "defineCacheKey");
     _FarmDataCache = class _FarmDataCache {
       constructor() {
         this.entries = /* @__PURE__ */ new Map();
@@ -10138,7 +10174,7 @@ function mergeMetadata(base, next) {
 }
 function addMetadataImageReference(metadata, reference) {
   if (reference.kind === "opengraph") {
-    const openGraph = { ...metadata.openGraph || {} };
+    const openGraph = { ...metadata.openGraph };
     if (!hasMetadataImages(openGraph.images) && !hasMetadataImages(openGraph.image)) {
       openGraph.images = [
         {
@@ -10155,7 +10191,7 @@ function addMetadataImageReference(metadata, reference) {
       openGraph
     };
   }
-  const twitter = { ...metadata.twitter || {} };
+  const twitter = { ...metadata.twitter };
   if (!hasMetadataImages(twitter.images)) {
     twitter.images = [reference.href];
     twitter.card = twitter.card || "summary_large_image";
@@ -10906,8 +10942,8 @@ var init_runtime = __esm({
           cookie: this.config.cookie,
           direction: getFarmLocaleDirection(resolution.locale, this.config.direction),
           messages: {
-            ...this.catalogs[this.config.fallbackLocale] || {},
-            ...this.catalogs[resolution.locale] || {}
+            ...this.catalogs[this.config.fallbackLocale],
+            ...this.catalogs[resolution.locale]
           }
         };
       }
@@ -12466,11 +12502,7 @@ var init_app = __esm({
         _setDefaultFarmI18nRuntime(this.i18nRuntime);
         this.viteServer = viteServer;
         this.routeManager = new RouteManager(this.config, viteServer);
-        this.serverRenderer = new ServerRenderer(
-          this.config,
-          this.routeManager,
-          this.i18nRuntime
-        );
+        this.serverRenderer = new ServerRenderer(this.config, this.routeManager, this.i18nRuntime);
       }
       async initialize() {
         if (process.env.FARM_VERBOSE) {
@@ -13106,6 +13138,321 @@ var init_hmr = __esm({
   }
 });
 
+// src/api/endpoint.ts
+function isEndpointFailure(value) {
+  return value instanceof EndpointFailure;
+}
+function createEndpoint(pathOrOptions, optionsOrHandler, maybeHandler) {
+  let path28;
+  let options;
+  let handler;
+  if (typeof pathOrOptions === "string") {
+    path28 = pathOrOptions;
+    options = optionsOrHandler;
+    handler = maybeHandler;
+  } else {
+    path28 = "";
+    options = pathOrOptions;
+    handler = optionsOrHandler;
+  }
+  if (typeof handler !== "function") {
+    throw new TypeError("createEndpoint requires a handler function");
+  }
+  const middleware2 = normalizeEndpointMiddleware(options.middleware);
+  const errors = normalizeEndpointErrors(options.errors);
+  const fail = createEndpointFail(errors);
+  const wrappedHandler = /* @__PURE__ */ __name((async (ctx) => {
+    const execution = await runEndpointMiddleware(
+      middleware2,
+      ctx,
+      handler,
+      fail,
+      options.invalidates
+    );
+    return execution.result;
+  }), "wrappedHandler");
+  const {
+    middleware: _middleware,
+    errors: _errors,
+    invalidates: _invalidates,
+    ...betterCallOptions
+  } = options;
+  const endpoint2 = (0, import_better_call.createEndpoint)(
+    path28 || "/__farm_auto_path__",
+    betterCallOptions,
+    wrappedHandler
+  );
+  endpoint2.__path = path28 || void 0;
+  endpoint2.__method = options.method || "GET";
+  endpoint2.__autoPath = !path28;
+  endpoint2.__handler = wrappedHandler;
+  endpoint2.__farmInvoke = (ctx) => runEndpointMiddleware(middleware2, ctx, handler, fail, options.invalidates);
+  endpoint2.__middleware = middleware2;
+  endpoint2.__sourceHandler = handler;
+  endpoint2.__invalidates = options.invalidates;
+  endpoint2.__errors = errors;
+  endpoint2.__types = {
+    body: options.body,
+    query: options.query,
+    headers: options.headers,
+    response: null,
+    errors
+  };
+  return endpoint2;
+}
+function normalizeEndpointErrors(definitions) {
+  if (definitions === void 0) return Object.freeze({});
+  if (!isPlainEndpointContext(definitions)) {
+    throw new TypeError("createEndpoint errors must be an object");
+  }
+  const normalized = /* @__PURE__ */ Object.create(null);
+  for (const [code, definition] of Object.entries(definitions)) {
+    if (!code.trim()) {
+      throw new TypeError("Endpoint error codes cannot be empty");
+    }
+    if (!definition || typeof definition !== "object") {
+      throw new TypeError(`Endpoint error "${code}" must be an object`);
+    }
+    if (!Number.isInteger(definition.status) || definition.status < 400 || definition.status > 599) {
+      throw new TypeError(`Endpoint error "${code}" status must be an integer between 400 and 599`);
+    }
+    if (!definition.schema || typeof definition.schema.parse !== "function") {
+      throw new TypeError(`Endpoint error "${code}" requires a schema with parse()`);
+    }
+    if (definition.message !== void 0 && typeof definition.message !== "string") {
+      throw new TypeError(`Endpoint error "${code}" message must be a string`);
+    }
+    normalized[code] = Object.freeze({ ...definition });
+  }
+  return Object.freeze(normalized);
+}
+function createEndpointFail(definitions) {
+  return ((code, data) => {
+    const definition = definitions[code];
+    if (!definition) {
+      throw new TypeError(`Endpoint error "${code}" is not declared`);
+    }
+    const parsed = definition.schema.parse(data);
+    throw new EndpointFailure(code, parsed, {
+      status: definition.status,
+      message: definition.message ?? "Request failed"
+    });
+  });
+}
+function normalizeEndpointMiddleware(middleware2) {
+  if (middleware2 === void 0) return EMPTY_ENDPOINT_MIDDLEWARE;
+  if (!Array.isArray(middleware2)) {
+    throw new TypeError("createEndpoint middleware must be an array of functions");
+  }
+  const normalized = [...middleware2];
+  for (const entry of normalized) {
+    if (typeof entry !== "function") {
+      throw new TypeError("createEndpoint middleware entries must be functions");
+    }
+  }
+  return Object.freeze(normalized);
+}
+async function runEndpointMiddleware(middleware2, handlerContext, handler, fail, invalidations) {
+  let context = createInitialEndpointContext(handlerContext.context);
+  for (let index = 0; index < middleware2.length; index++) {
+    const result2 = await middleware2[index]({ ...handlerContext, context });
+    if (isEndpointResponse(result2)) {
+      return {
+        result: result2,
+        context,
+        handlerExecuted: false,
+        invalidations: []
+      };
+    }
+    if (result2 === false) {
+      return {
+        result: forbiddenEndpointResponse(),
+        context,
+        handlerExecuted: false,
+        invalidations: []
+      };
+    }
+    if (result2 === true) continue;
+    if (!isPlainEndpointContext(result2)) {
+      throw new TypeError(
+        `Endpoint middleware ${index + 1} must return an object, true, false, or a Response`
+      );
+    }
+    context = mergeEndpointContext(context, result2, index);
+  }
+  const result = await handler({ ...handlerContext, context, fail });
+  return {
+    result,
+    context,
+    handlerExecuted: true,
+    invalidations: await applyEndpointInvalidations(
+      invalidations,
+      {
+        ...handlerContext,
+        context,
+        result
+      },
+      result
+    )
+  };
+}
+async function applyEndpointInvalidations(declaration, context, result) {
+  if (!declaration || isEndpointResponse(result) && result.status >= 400) {
+    return [];
+  }
+  const targets = typeof declaration === "function" ? await declaration(context) : declaration;
+  if (!Array.isArray(targets)) {
+    throw new TypeError(
+      "Endpoint invalidates must resolve to an array of { key } or { path } targets"
+    );
+  }
+  const clientKeys = [];
+  for (const target of targets) {
+    assertEndpointInvalidationTarget(target);
+    if ("key" in target) {
+      invalidate(target.key);
+      clientKeys.push(createRouteDataCacheKey(target.key));
+    } else {
+      revalidatePath(target.path);
+    }
+  }
+  return Array.from(new Set(clientKeys));
+}
+function assertEndpointInvalidationTarget(target) {
+  if (!target || typeof target !== "object") {
+    throw new TypeError("Endpoint invalidation targets must be { key } or { path } objects");
+  }
+  if ("key" in target) {
+    const key = target.key;
+    if (typeof key === "string" || Array.isArray(key)) return;
+  } else if ("path" in target && typeof target.path === "string") {
+    return;
+  }
+  throw new TypeError(
+    "Endpoint invalidation targets must contain a string/array key or a path string"
+  );
+}
+function createInitialEndpointContext(value) {
+  if (value === void 0 || value === null) return EMPTY_ENDPOINT_CONTEXT;
+  if (!isPlainEndpointContext(value)) {
+    throw new TypeError("Endpoint context must be a plain object");
+  }
+  return mergeEndpointContext(EMPTY_ENDPOINT_CONTEXT, value);
+}
+function mergeEndpointContext(current, added, middlewareIndex) {
+  const next = Object.assign(/* @__PURE__ */ Object.create(null), current);
+  for (const key of Reflect.ownKeys(added)) {
+    if (!Object.prototype.propertyIsEnumerable.call(added, key)) continue;
+    if (typeof key === "string" && UNSAFE_ENDPOINT_CONTEXT_KEYS.has(key)) {
+      throw new TypeError(`Endpoint middleware cannot provide the unsafe context key "${key}"`);
+    }
+    if (Object.prototype.hasOwnProperty.call(current, key)) {
+      const source = middlewareIndex === void 0 ? "Endpoint context" : `Endpoint middleware ${middlewareIndex + 1}`;
+      throw new TypeError(`${source} cannot replace the existing context key "${String(key)}"`);
+    }
+    next[key] = added[key];
+  }
+  return Object.freeze(next);
+}
+function isPlainEndpointContext(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function isEndpointResponse(value) {
+  return value instanceof Response || typeof value === "object" && value !== null && "headers" in value && "status" in value && typeof value.arrayBuffer === "function";
+}
+function forbiddenEndpointResponse() {
+  return new Response(JSON.stringify({ error: "Forbidden" }), {
+    status: 403,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function GET(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "GET" }, args[0]);
+  }
+  return createEndpoint("", { ...args[0], method: "GET" }, args[1]);
+}
+function HEAD(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "HEAD" }, args[0]);
+  }
+  return createEndpoint("", { ...args[0], method: "HEAD" }, args[1]);
+}
+function POST(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "POST" }, args[0]);
+  }
+  return createEndpoint("", { ...args[0], method: "POST" }, args[1]);
+}
+function PUT(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "PUT" }, args[0]);
+  }
+  return createEndpoint("", { ...args[0], method: "PUT" }, args[1]);
+}
+function DELETE(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "DELETE" }, args[0]);
+  }
+  return createEndpoint("", { ...args[0], method: "DELETE" }, args[1]);
+}
+function PATCH(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "PATCH" }, args[0]);
+  }
+  return createEndpoint("", { ...args[0], method: "PATCH" }, args[1]);
+}
+function OPTIONS(...args) {
+  if (args.length === 1) {
+    return createEndpoint("", { method: "OPTIONS" }, args[0]);
+  }
+  return createEndpoint("", { ...args[0], method: "OPTIONS" }, args[1]);
+}
+var import_better_call, _EndpointFailure, EndpointFailure, EMPTY_ENDPOINT_MIDDLEWARE, EMPTY_ENDPOINT_CONTEXT, UNSAFE_ENDPOINT_CONTEXT_KEYS;
+var init_endpoint = __esm({
+  "src/api/endpoint.ts"() {
+    "use strict";
+    import_better_call = require("better-call");
+    init_cache();
+    _EndpointFailure = class _EndpointFailure extends Error {
+      constructor(code, data, options) {
+        super(options.message);
+        this.name = "EndpointFailure";
+        this.code = code;
+        this.data = data;
+        this.status = options.status;
+      }
+    };
+    __name(_EndpointFailure, "EndpointFailure");
+    EndpointFailure = _EndpointFailure;
+    __name(isEndpointFailure, "isEndpointFailure");
+    __name(createEndpoint, "createEndpoint");
+    EMPTY_ENDPOINT_MIDDLEWARE = Object.freeze([]);
+    EMPTY_ENDPOINT_CONTEXT = Object.freeze(/* @__PURE__ */ Object.create(null));
+    UNSAFE_ENDPOINT_CONTEXT_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+    __name(normalizeEndpointErrors, "normalizeEndpointErrors");
+    __name(createEndpointFail, "createEndpointFail");
+    __name(normalizeEndpointMiddleware, "normalizeEndpointMiddleware");
+    __name(runEndpointMiddleware, "runEndpointMiddleware");
+    __name(applyEndpointInvalidations, "applyEndpointInvalidations");
+    __name(assertEndpointInvalidationTarget, "assertEndpointInvalidationTarget");
+    __name(createInitialEndpointContext, "createInitialEndpointContext");
+    __name(mergeEndpointContext, "mergeEndpointContext");
+    __name(isPlainEndpointContext, "isPlainEndpointContext");
+    __name(isEndpointResponse, "isEndpointResponse");
+    __name(forbiddenEndpointResponse, "forbiddenEndpointResponse");
+    __name(GET, "GET");
+    __name(HEAD, "HEAD");
+    __name(POST, "POST");
+    __name(PUT, "PUT");
+    __name(DELETE, "DELETE");
+    __name(PATCH, "PATCH");
+    __name(OPTIONS, "OPTIONS");
+  }
+});
+
 // src/api/runtime.ts
 function matchAPIRoute(routes, pathname) {
   const exactRoute = routes.get(pathname);
@@ -13136,10 +13483,10 @@ async function invokeAPIRouteEndpoint(endpoint2, request, params = {}) {
 async function invokeAPIRouteEndpointInContext(endpoint2, request, params) {
   const farmHandler = endpoint2.__handler || (isFarmContextHandler(endpoint2) ? endpoint2 : null);
   if (!farmHandler) {
-    const result2 = await endpoint2(request, {
+    const result = await endpoint2(request, {
       params: Promise.resolve(params)
     });
-    return normalizeRouteResponse(result2);
+    return normalizeRouteResponse(result);
   }
   const url = new URL(request.url);
   const query = {};
@@ -13164,15 +13511,30 @@ async function invokeAPIRouteEndpointInContext(endpoint2, request, params) {
   if (headersValidation instanceof Response) {
     return headersValidation;
   }
-  const result = await farmHandler({
+  const handlerContext = {
     query: queryValidation,
     body: bodyValidation,
     headers: headersValidation,
     request,
     context: {},
     params
-  });
-  return normalizeRouteResponse(result);
+  };
+  let execution;
+  try {
+    execution = typeof endpoint2.__farmInvoke === "function" ? await endpoint2.__farmInvoke(handlerContext) : {
+      result: await farmHandler(handlerContext),
+      context: handlerContext.context,
+      handlerExecuted: true,
+      invalidations: []
+    };
+  } catch (error) {
+    if (isEndpointFailure(error)) {
+      return createEndpointFailureResponse(error);
+    }
+    throw error;
+  }
+  const response = normalizeRouteResponse(execution.result);
+  return attachEndpointInvalidations(response, execution.invalidations);
 }
 function normalizeRouteResponse(result) {
   if (isWebResponse2(result)) {
@@ -13189,6 +13551,38 @@ function normalizeRouteResponse(result) {
 function isWebResponse2(value) {
   return value instanceof Response || typeof value === "object" && value !== null && "headers" in value && "status" in value && typeof value.arrayBuffer === "function";
 }
+function attachEndpointInvalidations(response, keys) {
+  const existing = decodeFarmCacheInvalidations(
+    response.headers.get(FARM_CACHE_INVALIDATION_HEADER)
+  );
+  const encoded = encodeFarmCacheInvalidations([...existing, ...keys]);
+  if (!encoded) return response;
+  const headers2 = new Headers(response.headers);
+  headers2.set(FARM_CACHE_INVALIDATION_HEADER, encoded);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: headers2
+  });
+}
+function createEndpointFailureResponse(failure) {
+  return new Response(
+    JSON.stringify({
+      error: {
+        code: failure.code,
+        message: failure.message,
+        data: failure.data
+      }
+    }),
+    {
+      status: failure.status,
+      headers: {
+        "cache-control": "no-store",
+        "content-type": "application/json"
+      }
+    }
+  );
+}
 function isFarmContextHandler(endpoint2) {
   if (typeof endpoint2 !== "function") {
     return false;
@@ -13297,11 +13691,15 @@ var init_runtime2 = __esm({
   "src/api/runtime.ts"() {
     "use strict";
     init_request();
+    init_cache_invalidation();
+    init_endpoint();
     __name(matchAPIRoute, "matchAPIRoute");
     __name(invokeAPIRouteEndpoint, "invokeAPIRouteEndpoint");
     __name(invokeAPIRouteEndpointInContext, "invokeAPIRouteEndpointInContext");
     __name(normalizeRouteResponse, "normalizeRouteResponse");
     __name(isWebResponse2, "isWebResponse");
+    __name(attachEndpointInvalidations, "attachEndpointInvalidations");
+    __name(createEndpointFailureResponse, "createEndpointFailureResponse");
     __name(isFarmContextHandler, "isFarmContextHandler");
     __name(readJSONBody, "readJSONBody");
     __name(validateInput, "validateInput");
@@ -14262,7 +14660,7 @@ var init_manager = __esm({
         if (!nestedMatch.matched) {
           return { matched: false };
         }
-        const params = { ...nestedMatch.params || {} };
+        const params = { ...nestedMatch.params };
         delete params.__farmRest;
         return {
           matched: true,
@@ -15414,6 +15812,24 @@ var init_environment_vite = __esm({
   }
 });
 
+// package.json
+var version;
+var init_package = __esm({
+  "package.json"() {
+    version = "0.1.0-beta.3";
+  }
+});
+
+// src/version.ts
+var FARM_VERSION;
+var init_version = __esm({
+  "src/version.ts"() {
+    "use strict";
+    init_package();
+    FARM_VERSION = version;
+  }
+});
+
 // src/after.ts
 function getAfterStorage() {
   const runtime = globalThis;
@@ -16187,7 +16603,9 @@ function readManifest(contentDir) {
   const manifestPath = import_node_path7.default.join(contentDir, FARM_DOCS_LAST_MODIFIED_MANIFEST);
   if (!(0, import_node_fs5.existsSync)(manifestPath)) return null;
   try {
-    const parsed = JSON.parse((0, import_node_fs5.readFileSync)(manifestPath, "utf8"));
+    const parsed = JSON.parse(
+      (0, import_node_fs5.readFileSync)(manifestPath, "utf8")
+    );
     if (parsed.version !== 1 || !parsed.pages || typeof parsed.pages !== "object") return null;
     const pages = Object.fromEntries(
       Object.entries(parsed.pages).filter(
@@ -22558,16 +22976,7 @@ __export(devtools_client_exports, {
 function parseShortcut(shortcut) {
   const tokens = shortcut.toLowerCase().split("+").map((token) => token.trim()).filter(Boolean);
   const key = tokens.find(
-    (token) => ![
-      "alt",
-      "ctrl",
-      "control",
-      "meta",
-      "cmd",
-      "command",
-      "mod",
-      "shift"
-    ].includes(token)
+    (token) => !["alt", "ctrl", "control", "meta", "cmd", "command", "mod", "shift"].includes(token)
   );
   if (!key) {
     return null;
@@ -22998,7 +23407,7 @@ function isResolvedEnvScope(value) {
   );
 }
 function isPotentialProgrammaticRouteSourceFile(normalizedFile, srcDirSlug) {
-  return normalizedFile.startsWith(`${srcDirSlug}/`) && /\.(ts|tsx|js|jsx)$/.test(normalizedFile) && !/\.d\.ts$/.test(normalizedFile) && !normalizedFile.endsWith("/farm-routes.d.ts") && !normalizedFile.endsWith("/farm-env.d.ts") && !normalizedFile.endsWith("/lib/api.generated.ts");
+  return normalizedFile.startsWith(`${srcDirSlug}/`) && /\.(ts|tsx|js|jsx)$/.test(normalizedFile) && !normalizedFile.endsWith(".d.ts") && !normalizedFile.endsWith("/farm-routes.d.ts") && !normalizedFile.endsWith("/farm-env.d.ts") && !normalizedFile.endsWith("/lib/api.generated.ts");
 }
 function fileContainsProgrammaticPageRoute(file) {
   if (!fs7.existsSync(file)) {
@@ -26109,7 +26518,7 @@ async function defineConfig2(config = {}) {
           const isExposed = hostConfig === true || hostConfig === "0.0.0.0";
           console.log("");
           console.log(
-            `  ${pc.bold(pc.green("Farm.js"))} ${pc.dim("v1.0.0")} ${pc.dim(`ready in ${elapsed}ms`)}`
+            `  ${pc.bold(pc.green("Farm.js"))} ${pc.dim(`v${FARM_VERSION}`)} ${pc.dim(`ready in ${elapsed}ms`)}`
           );
           console.log("");
           console.log(
@@ -26233,6 +26642,7 @@ var init_vite = __esm({
     path21 = __toESM(require("path"));
     init_layers();
     init_environment_vite();
+    init_version();
     init_deferred();
     init_after();
     init_deployment();
@@ -27448,14 +27858,12 @@ export default defineEventHandler(async (event: H3Event) => {
     ...preset === "cloudflare-module" && cloudflareCronConfig ? {
       cloudflare: cloudflareCronConfig
     } : {},
-    handlers: [
-      ...farmWorkflows.handlerPath ? [
-        {
-          route: `${config.workflows.route}/**`,
-          handler: farmWorkflows.handlerPath
-        }
-      ] : []
-    ],
+    handlers: farmWorkflows.handlerPath ? [
+      {
+        route: `${config.workflows.route}/**`,
+        handler: farmWorkflows.handlerPath
+      }
+    ] : [],
     // Route rules for Vercel
     routeRules: {
       "/api/**": {
@@ -27601,6 +28009,7 @@ var init_nitro = __esm({
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  APIClientError: () => APIClientError,
   APIRouteManager: () => APIRouteManager,
   APITypeGenerator: () => APITypeGenerator,
   API_ROUTE_METHODS: () => API_ROUTE_METHODS,
@@ -27613,6 +28022,8 @@ __export(src_exports, {
   DELETE: () => DELETE,
   DeferredDataError: () => DeferredDataError,
   DocsRoute: () => DocsRoute,
+  EndpointFailure: () => EndpointFailure,
+  FARM_API_ROUTE_REF_SYMBOL: () => FARM_API_ROUTE_REF_SYMBOL,
   FARM_CRON_MANIFEST: () => FARM_CRON_MANIFEST,
   FARM_DEFERRED_BRAND: () => FARM_DEFERRED_BRAND,
   FARM_DEFERRED_CONTENT_TYPE: () => FARM_DEFERRED_CONTENT_TYPE,
@@ -27739,6 +28150,7 @@ __export(src_exports, {
   cronRoute: () => cronRoute,
   databaseStorage: () => databaseStorage,
   defer: () => defer,
+  defineCacheKey: () => defineCacheKey,
   defineConfig: () => defineConfig,
   defineCron: () => defineCron,
   defineFarmConfig: () => defineFarmConfig,
@@ -27825,9 +28237,11 @@ __export(src_exports, {
   invalidate: () => invalidate,
   invalidateRouteData: () => invalidateRouteData,
   invokeAPIRouteEndpoint: () => invokeAPIRouteEndpoint,
+  isAPIRouteRef: () => isAPIRouteRef,
   isChunkLoadError: () => isChunkLoadError,
   isCronRequestAuthorized: () => isCronRequestAuthorized,
   isDeferred: () => isDeferred,
+  isEndpointFailure: () => isEndpointFailure,
   isFarmDeploymentMismatchResponse: () => isFarmDeploymentMismatchResponse,
   isFarmDocsAPIRequest: () => isFarmDocsAPIRequest,
   isFarmDocsRequest: () => isFarmDocsRequest,
@@ -27946,6 +28360,7 @@ __export(src_exports, {
   updateTag: () => updateTag,
   upstashStorage: () => upstashStorage,
   useBlocker: () => useBlocker,
+  useMutation: () => useMutation,
   useNavigation: () => useNavigation,
   usePageState: () => usePageState,
   usePathname: () => usePathname,
@@ -28181,173 +28596,8 @@ function createLoggerPlugin({
 }
 __name(createLoggerPlugin, "createLoggerPlugin");
 
-// src/api/endpoint.ts
-var import_better_call = require("better-call");
-function createEndpoint(pathOrOptions, optionsOrHandler, maybeHandler) {
-  let path28;
-  let options;
-  let handler;
-  if (typeof pathOrOptions === "string") {
-    path28 = pathOrOptions;
-    options = optionsOrHandler;
-    handler = maybeHandler;
-  } else {
-    path28 = "";
-    options = pathOrOptions;
-    handler = optionsOrHandler;
-  }
-  if (typeof handler !== "function") {
-    throw new TypeError("createEndpoint requires a handler function");
-  }
-  const middleware2 = normalizeEndpointMiddleware(options.middleware);
-  const wrappedHandler = /* @__PURE__ */ __name(((ctx) => runEndpointMiddleware(middleware2, ctx, handler)), "wrappedHandler");
-  const { middleware: _middleware, ...betterCallOptions } = options;
-  const endpoint2 = (0, import_better_call.createEndpoint)(
-    path28 || "/__farm_auto_path__",
-    betterCallOptions,
-    wrappedHandler
-  );
-  endpoint2.__path = path28 || void 0;
-  endpoint2.__method = options.method || "GET";
-  endpoint2.__autoPath = !path28;
-  endpoint2.__handler = wrappedHandler;
-  endpoint2.__middleware = middleware2;
-  endpoint2.__sourceHandler = handler;
-  endpoint2.__types = {
-    body: options.body,
-    query: options.query,
-    headers: options.headers,
-    response: null
-  };
-  return endpoint2;
-}
-__name(createEndpoint, "createEndpoint");
-var EMPTY_ENDPOINT_MIDDLEWARE = Object.freeze([]);
-var EMPTY_ENDPOINT_CONTEXT = Object.freeze(/* @__PURE__ */ Object.create(null));
-var UNSAFE_ENDPOINT_CONTEXT_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-function normalizeEndpointMiddleware(middleware2) {
-  if (middleware2 === void 0) return EMPTY_ENDPOINT_MIDDLEWARE;
-  if (!Array.isArray(middleware2)) {
-    throw new TypeError("createEndpoint middleware must be an array of functions");
-  }
-  const normalized = [...middleware2];
-  for (const entry of normalized) {
-    if (typeof entry !== "function") {
-      throw new TypeError("createEndpoint middleware entries must be functions");
-    }
-  }
-  return Object.freeze(normalized);
-}
-__name(normalizeEndpointMiddleware, "normalizeEndpointMiddleware");
-async function runEndpointMiddleware(middleware2, handlerContext, handler) {
-  let context = createInitialEndpointContext(handlerContext.context);
-  for (let index = 0; index < middleware2.length; index++) {
-    const result = await middleware2[index]({ ...handlerContext, context });
-    if (isEndpointResponse(result)) return result;
-    if (result === false) return forbiddenEndpointResponse();
-    if (result === true) continue;
-    if (!isPlainEndpointContext(result)) {
-      throw new TypeError(
-        `Endpoint middleware ${index + 1} must return an object, true, false, or a Response`
-      );
-    }
-    context = mergeEndpointContext(context, result, index);
-  }
-  return handler({ ...handlerContext, context });
-}
-__name(runEndpointMiddleware, "runEndpointMiddleware");
-function createInitialEndpointContext(value) {
-  if (value === void 0 || value === null) return EMPTY_ENDPOINT_CONTEXT;
-  if (!isPlainEndpointContext(value)) {
-    throw new TypeError("Endpoint context must be a plain object");
-  }
-  return mergeEndpointContext(EMPTY_ENDPOINT_CONTEXT, value);
-}
-__name(createInitialEndpointContext, "createInitialEndpointContext");
-function mergeEndpointContext(current, added, middlewareIndex) {
-  const next = Object.assign(/* @__PURE__ */ Object.create(null), current);
-  for (const key of Reflect.ownKeys(added)) {
-    if (!Object.prototype.propertyIsEnumerable.call(added, key)) continue;
-    if (typeof key === "string" && UNSAFE_ENDPOINT_CONTEXT_KEYS.has(key)) {
-      throw new TypeError(`Endpoint middleware cannot provide the unsafe context key "${key}"`);
-    }
-    if (Object.prototype.hasOwnProperty.call(current, key)) {
-      const source = middlewareIndex === void 0 ? "Endpoint context" : `Endpoint middleware ${middlewareIndex + 1}`;
-      throw new TypeError(`${source} cannot replace the existing context key "${String(key)}"`);
-    }
-    next[key] = added[key];
-  }
-  return Object.freeze(next);
-}
-__name(mergeEndpointContext, "mergeEndpointContext");
-function isPlainEndpointContext(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-__name(isPlainEndpointContext, "isPlainEndpointContext");
-function isEndpointResponse(value) {
-  return value instanceof Response || typeof value === "object" && value !== null && "headers" in value && "status" in value && typeof value.arrayBuffer === "function";
-}
-__name(isEndpointResponse, "isEndpointResponse");
-function forbiddenEndpointResponse() {
-  return new Response(JSON.stringify({ error: "Forbidden" }), {
-    status: 403,
-    headers: { "Content-Type": "application/json" }
-  });
-}
-__name(forbiddenEndpointResponse, "forbiddenEndpointResponse");
-function GET(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "GET" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "GET" }, args[1]);
-}
-__name(GET, "GET");
-function HEAD(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "HEAD" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "HEAD" }, args[1]);
-}
-__name(HEAD, "HEAD");
-function POST(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "POST" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "POST" }, args[1]);
-}
-__name(POST, "POST");
-function PUT(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "PUT" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "PUT" }, args[1]);
-}
-__name(PUT, "PUT");
-function DELETE(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "DELETE" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "DELETE" }, args[1]);
-}
-__name(DELETE, "DELETE");
-function PATCH(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "PATCH" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "PATCH" }, args[1]);
-}
-__name(PATCH, "PATCH");
-function OPTIONS(...args) {
-  if (args.length === 1) {
-    return createEndpoint("", { method: "OPTIONS" }, args[0]);
-  }
-  return createEndpoint("", { ...args[0], method: "OPTIONS" }, args[1]);
-}
-__name(OPTIONS, "OPTIONS");
-
 // src/api/index.ts
+init_endpoint();
 init_route_manager2();
 
 // src/integration-client.ts
@@ -28459,7 +28709,7 @@ function mergeIntegrationClientData(...values) {
       continue;
     }
     merged = {
-      ...merged || {},
+      ...merged,
       ...data
     };
   }
@@ -29289,6 +29539,20 @@ function normalizeFarmClientCacheKey(key) {
 __name(normalizeFarmClientCacheKey, "normalizeFarmClientCacheKey");
 
 // src/api/client.ts
+init_cache_invalidation();
+var FARM_API_ROUTE_REF_SYMBOL = /* @__PURE__ */ Symbol.for("farm.api.route-ref");
+var _APIClientError = class _APIClientError extends Error {
+  constructor(code, data, options) {
+    super(options.message);
+    this.name = "APIClientError";
+    this.code = code;
+    this.data = data;
+    this.status = options.status;
+    this.response = options.response;
+  }
+};
+__name(_APIClientError, "APIClientError");
+var APIClientError = _APIClientError;
 function createAPIClient(options = {}) {
   options ?? (options = {});
   const baseURL = options.baseURL || (typeof window !== "undefined" ? window.location.origin : "http://localhost:3000");
@@ -29326,6 +29590,9 @@ function createAPIClient(options = {}) {
       fetchOptions.body = JSON.stringify(requestOptions.body);
     }
     const response = await fetch(url.toString(), fetchOptions);
+    applyFarmCacheInvalidations(
+      decodeFarmCacheInvalidations(response.headers?.get?.(FARM_CACHE_INVALIDATION_HEADER))
+    );
     let data = void 0;
     if (response.status !== 204 && response.status !== 205) {
       data = await response.json();
@@ -29565,9 +29832,15 @@ function createNestedProxy(path28, client, routeMeta, baseURL, rootAliases) {
   const proxy = new Proxy(target, {
     // When accessing a property (api.hello)
     get(_target, prop) {
+      if (prop === FARM_API_ROUTE_REF_SYMBOL) {
+        return path28.length > 0;
+      }
       if (path28.length === 0 && typeof prop === "string" && rootAliases && prop in rootAliases) {
         return rootAliases[prop];
       }
+      if (typeof prop !== "string") {
+        return Reflect.get(_target, prop);
+      }
       return createNestedProxy([...path28, prop], client, routeMeta, baseURL, rootAliases);
     },
     // When calling as a function
@@ -29590,6 +29863,10 @@ function createNestedProxy(path28, client, routeMeta, baseURL, rootAliases) {
   return proxy;
 }
 __name(createNestedProxy, "createNestedProxy");
+function isAPIRouteRef(value) {
+  return typeof value === "function" && value[FARM_API_ROUTE_REF_SYMBOL] === true;
+}
+__name(isAPIRouteRef, "isAPIRouteRef");
 function createServerAPIClient(endpoints, options = {}) {
   if (options.integrations === false || Object.prototype.hasOwnProperty.call(endpoints, "integrations")) {
     return endpoints;
@@ -29656,7 +29933,10 @@ function resolveTargetKey(routeMeta, target, input, baseURL = "http://localhost:
   }
   if (Array.isArray(target)) {
     const [route2, routeInput] = target;
-    return resolveTargetKey(routeMeta, route2, routeInput, baseURL);
+    if (typeof route2 === "function") {
+      return resolveTargetKey(routeMeta, route2, routeInput, baseURL);
+    }
+    return normalizeFarmClientCacheKey(target);
   }
   if ("key" in target) return normalizeFarmClientCacheKey(target.key);
   if ("path" in target) {
@@ -29682,18 +29962,45 @@ function resolveRouteMeta(meta) {
 }
 __name(resolveRouteMeta, "resolveRouteMeta");
 function normalizeError(error) {
-  if (error instanceof Error) return error;
-  return new Error(typeof error === "string" ? error : "Unknown error");
+  if (error instanceof APIClientError) return error;
+  const normalized = new APIClientError("network_error", void 0, {
+    status: 0,
+    message: error instanceof Error ? error.message : typeof error === "string" ? error : "Network request failed"
+  });
+  normalized.cause = error;
+  return normalized;
 }
 __name(normalizeError, "normalizeError");
 function createResponseError2(response, data) {
-  const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
-  error.status = response.status;
-  error.response = response;
-  error.data = data;
-  return error;
+  const expected = readEndpointErrorEnvelope(data);
+  if (expected) {
+    return new APIClientError(expected.code, expected.data, {
+      status: response.status,
+      message: expected.message,
+      response
+    });
+  }
+  return new APIClientError("http_error", data, {
+    status: response.status,
+    message: `HTTP ${response.status}: ${response.statusText}`,
+    response
+  });
 }
 __name(createResponseError2, "createResponseError");
+function readEndpointErrorEnvelope(data) {
+  if (!data || typeof data !== "object") return null;
+  const error = data.error;
+  if (!error || typeof error !== "object") return null;
+  const code = error.code;
+  const message = error.message;
+  if (typeof code !== "string" || typeof message !== "string") return null;
+  return {
+    code,
+    message,
+    data: error.data
+  };
+}
+__name(readEndpointErrorEnvelope, "readEndpointErrorEnvelope");
 
 // src/api/vite-plugin.ts
 init_route_manager2();
@@ -29915,69 +30222,71 @@ function farmApiPlugin(options = {}) {
         waitForDiscovery: /* @__PURE__ */ __name(() => discoveryPromise, "waitForDiscovery")
       };
       return () => {
-        server.middlewares.use(_withAfterNodeMiddleware(async (req, res, next) => {
-          const url = req.url || "/";
-          const pathname = url.split("?")[0];
-          const method = req.method || "GET";
-          if (discoveryPromise && !discoveryComplete) {
-            await discoveryPromise;
-          }
-          if (!matchAPIRoute(apiRoutesCache, pathname)) {
-            return next();
-          }
-          if (!apiRouterHandler) {
-            return next();
-          }
-          const startTime = Date.now();
-          try {
-            const farmMiddleware = server.__farmMiddleware__;
-            if (farmMiddleware) {
-              await farmMiddleware.waitForDiscovery?.();
-              const middlewareData = /* @__PURE__ */ new Map();
-              const handled = await farmMiddleware.execute(req, res, pathname, middlewareData);
-              if (handled) {
-                const duration2 = Date.now() - startTime;
-                logResponse(method, pathname, res.statusCode || 200, duration2);
-                return;
-              }
+        server.middlewares.use(
+          _withAfterNodeMiddleware(async (req, res, next) => {
+            const url = req.url || "/";
+            const pathname = url.split("?")[0];
+            const method = req.method || "GET";
+            if (discoveryPromise && !discoveryComplete) {
+              await discoveryPromise;
             }
-            const fullUrl = `http://${req.headers.host || "localhost:3000"}${url}`;
-            const headers2 = new Headers();
-            for (const [key, value] of Object.entries(req.headers)) {
-              if (value) {
-                headers2.set(key, Array.isArray(value) ? value.join(", ") : value);
-              }
+            if (!matchAPIRoute(apiRoutesCache, pathname)) {
+              return next();
             }
-            let body;
-            if (method !== "GET" && method !== "HEAD") {
-              body = await new Promise((resolve5) => {
-                let data = "";
-                req.on("data", (chunk) => {
-                  data += chunk;
-                });
-                req.on("end", () => {
-                  resolve5(data);
+            if (!apiRouterHandler) {
+              return next();
+            }
+            const startTime = Date.now();
+            try {
+              const farmMiddleware = server.__farmMiddleware__;
+              if (farmMiddleware) {
+                await farmMiddleware.waitForDiscovery?.();
+                const middlewareData = /* @__PURE__ */ new Map();
+                const handled = await farmMiddleware.execute(req, res, pathname, middlewareData);
+                if (handled) {
+                  const duration2 = Date.now() - startTime;
+                  logResponse(method, pathname, res.statusCode || 200, duration2);
+                  return;
+                }
+              }
+              const fullUrl = `http://${req.headers.host || "localhost:3000"}${url}`;
+              const headers2 = new Headers();
+              for (const [key, value] of Object.entries(req.headers)) {
+                if (value) {
+                  headers2.set(key, Array.isArray(value) ? value.join(", ") : value);
+                }
+              }
+              let body;
+              if (method !== "GET" && method !== "HEAD") {
+                body = await new Promise((resolve5) => {
+                  let data = "";
+                  req.on("data", (chunk) => {
+                    data += chunk;
+                  });
+                  req.on("end", () => {
+                    resolve5(data);
+                  });
                 });
+              }
+              const request = new Request(fullUrl, {
+                method,
+                headers: headers2,
+                body: body || void 0
               });
+              const response = await apiRouterHandler(request);
+              const duration = Date.now() - startTime;
+              logResponse(method, pathname, response.status, duration);
+              await sendWebResponse(res, response);
+            } catch (error) {
+              const duration = Date.now() - startTime;
+              logResponse(method, pathname, 500, duration);
+              console.error("[FARM] API error:", error);
+              res.statusCode = 500;
+              res.setHeader("Content-Type", "application/json");
+              res.end(JSON.stringify({ error: "Internal server error" }));
             }
-            const request = new Request(fullUrl, {
-              method,
-              headers: headers2,
-              body: body || void 0
-            });
-            const response = await apiRouterHandler(request);
-            const duration = Date.now() - startTime;
-            logResponse(method, pathname, response.status, duration);
-            await sendWebResponse(res, response);
-          } catch (error) {
-            const duration = Date.now() - startTime;
-            logResponse(method, pathname, 500, duration);
-            console.error("[FARM] API error:", error);
-            res.statusCode = 500;
-            res.setHeader("Content-Type", "application/json");
-            res.end(JSON.stringify({ error: "Internal server error" }));
-          }
-        }));
+          })
+        );
       };
     },
     async handleHotUpdate({ file, server, modules }) {
@@ -31026,7 +31335,7 @@ function matchRoutePath2(pathname, middlewarePath) {
   if (!nestedMatch.matched) {
     return { matched: false };
   }
-  const params = { ...nestedMatch.params || {} };
+  const params = { ...nestedMatch.params };
   delete params.__farmRest;
   return {
     matched: true,
@@ -32330,8 +32639,8 @@ function compareRuntimeRoutes(left, right) {
 __name(compareRuntimeRoutes, "compareRuntimeRoutes");
 function getPatternSpecificity(pattern) {
   return normalizePattern(pattern).split("/").filter(Boolean).reduce((score, segment) => {
-    if (segment === "**" || /^\[\[\.\.\./.test(segment)) return score + 1;
-    if (segment === "*" || /^\[\.\.\./.test(segment)) return score + 10;
+    if (segment === "**" || segment.startsWith("[[...")) return score + 1;
+    if (segment === "*" || segment.startsWith("[...")) return score + 10;
     if (/^\[.+\]$/.test(segment)) return score + 50;
     return score + 100;
   }, 0);
@@ -36969,9 +37278,8 @@ async function buildNitroUniversal(config, routeManager, apiRouteManager, server
   const nitroEntryPath = import_path12.default.join(ssrOutputDir, "nitro-entry.mjs");
   const nitroEntryCode = `
 // Farm.js Nitro Entry
-// This file imports h3 and the SSR handler, wrapping it for Nitro
+// This file adapts Farm's Web fetch handler to Nitro's event handler contract.
 
-import { defineEventHandler } from 'h3'
 import handler from './${ssrEntryFile}'
 
 function mergeVaryHeaders(target, source) {
@@ -37009,8 +37317,8 @@ function createResponseFinishedHook(event) {
   }
 }
 
-// Export the wrapped handler for Nitro
-export default defineEventHandler(async (event) => {
+// Export the event handler for Nitro
+export default async function farmNitroEventHandler(event) {
   const response = await handler.fetch(event.req, {
     waitUntil: (promise) => event.waitUntil(promise),
     onResponseFinished: createResponseFinishedHook(event),
@@ -37021,7 +37329,7 @@ export default defineEventHandler(async (event) => {
   const farmVary = response.headers.get('Vary')
   if (farmVary) mergeVaryHeaders(event.res.headers, farmVary)
   return response
-})
+}
   `.trim();
   await fs9.writeFile(nitroEntryPath, nitroEntryCode);
   const prebuiltSSRPlugin = createExternalSSRBundlePlugin(
@@ -37439,8 +37747,8 @@ async function copySharpRuntime(config, root, nitroFuncDir, fs9) {
     await fs9.mkdir(import_path12.default.dirname(targetDir), { recursive: true });
     const packageRequire = (0, import_module3.createRequire)(packageJsonPath);
     const dependencies = {
-      ...packageJson.dependencies || {},
-      ...packageJson.optionalDependencies || {}
+      ...packageJson.dependencies,
+      ...packageJson.optionalDependencies
     };
     await Promise.all([
       fs9.cp(packageDir, targetDir, {
@@ -37533,7 +37841,7 @@ init_environment_vite();
 // src/server/vite-config.ts
 function mergeNoExternal(farmValue, userValue) {
   if (farmValue === true || userValue === true) return true;
-  const normalize = /* @__PURE__ */ __name((value) => value == null ? [] : Array.isArray(value) ? value : [value], "normalize");
+  const normalize = /* @__PURE__ */ __name((value) => value == null || value === true ? [] : Array.isArray(value) ? value : [value], "normalize");
   return Array.from(/* @__PURE__ */ new Set([...normalize(farmValue), ...normalize(userValue)]));
 }
 __name(mergeNoExternal, "mergeNoExternal");
@@ -37933,11 +38241,170 @@ async function buildNitro(config, routeManager, apiRouteManager, serverRenderer,
 }
 __name(buildNitro, "buildNitro");
 
+// src/mutation-client.ts
+var import_react9 = require("react");
+function useMutation(target, options = {}) {
+  const initialData = options.initialData ?? null;
+  const optionsRef = (0, import_react9.useRef)(options);
+  const targetRef = (0, import_react9.useRef)(target);
+  const requestIdRef = (0, import_react9.useRef)(0);
+  const initialState = {
+    pendingCount: 0,
+    status: "idle",
+    data: initialData,
+    error: null,
+    variables: void 0
+  };
+  const stateRef = (0, import_react9.useRef)(initialState);
+  const [state, setState] = (0, import_react9.useState)(initialState);
+  optionsRef.current = options;
+  targetRef.current = target;
+  const setMutationState = (0, import_react9.useCallback)(
+    (value) => {
+      setState((current) => {
+        const next = typeof value === "function" ? value(current) : value;
+        stateRef.current = next;
+        return next;
+      });
+    },
+    []
+  );
+  const mutateAsync = (0, import_react9.useCallback)(
+    async (variables) => {
+      const requestId = ++requestIdRef.current;
+      const currentOptions = optionsRef.current;
+      const previousData = stateRef.current.data;
+      const optimisticData = currentOptions.optimistic?.({
+        variables,
+        current: previousData
+      });
+      const hasOptimisticData = optimisticData !== void 0;
+      setMutationState((current) => ({
+        pendingCount: current.pendingCount + 1,
+        status: "pending",
+        data: hasOptimisticData ? optimisticData : currentOptions.resetOnMutate === false ? current.data : null,
+        error: null,
+        variables
+      }));
+      try {
+        const mutationTarget = targetRef.current;
+        const rawResult = isAPIRouteRef(mutationTarget) ? await mutationTarget(variables, currentOptions.request) : await mutationTarget(variables);
+        const data = unwrapMutationResult(rawResult, isAPIRouteRef(mutationTarget));
+        const isLatestRequest = requestId === requestIdRef.current;
+        setMutationState((current) => {
+          const pendingCount = Math.max(0, current.pendingCount - 1);
+          if (!isLatestRequest) {
+            return {
+              ...current,
+              pendingCount,
+              status: pendingCount > 0 ? "pending" : current.status
+            };
+          }
+          return {
+            pendingCount,
+            status: "success",
+            data,
+            error: null,
+            variables
+          };
+        });
+        if (isLatestRequest) {
+          currentOptions.onSuccess?.(data, variables);
+          currentOptions.onSettled?.(data, null, variables);
+        }
+        return data;
+      } catch (cause) {
+        const error = normalizeMutationError(cause);
+        const isLatestRequest = requestId === requestIdRef.current;
+        setMutationState((current) => {
+          const pendingCount = Math.max(0, current.pendingCount - 1);
+          if (!isLatestRequest) {
+            return {
+              ...current,
+              pendingCount,
+              status: pendingCount > 0 ? "pending" : current.status
+            };
+          }
+          return {
+            pendingCount,
+            status: "error",
+            data: hasOptimisticData && currentOptions.rollbackOnError ? previousData : currentOptions.resetOnMutate === false ? current.data : null,
+            error,
+            variables
+          };
+        });
+        if (isLatestRequest) {
+          currentOptions.onError?.(error, variables);
+          currentOptions.onSettled?.(null, error, variables);
+        }
+        throw error;
+      }
+    },
+    [setMutationState]
+  );
+  const mutate = (0, import_react9.useCallback)(
+    (variables) => {
+      void mutateAsync(variables).catch(() => {
+      });
+    },
+    [mutateAsync]
+  );
+  const reset = (0, import_react9.useCallback)(() => {
+    requestIdRef.current += 1;
+    setMutationState({
+      pendingCount: 0,
+      status: "idle",
+      data: optionsRef.current.initialData ?? null,
+      error: null,
+      variables: void 0
+    });
+  }, [setMutationState]);
+  return (0, import_react9.useMemo)(
+    () => ({
+      pending: state.pendingCount > 0,
+      status: state.status,
+      data: state.data,
+      error: state.error,
+      variables: state.variables,
+      mutate,
+      mutateAsync,
+      reset
+    }),
+    [
+      mutate,
+      mutateAsync,
+      reset,
+      state.data,
+      state.error,
+      state.pendingCount,
+      state.status,
+      state.variables
+    ]
+  );
+}
+__name(useMutation, "useMutation");
+function unwrapMutationResult(result, apiRoute) {
+  if (!apiRoute) return result;
+  const apiResult = result;
+  if (apiResult.error) {
+    throw apiResult.error;
+  }
+  return apiResult.data;
+}
+__name(unwrapMutationResult, "unwrapMutationResult");
+function normalizeMutationError(error) {
+  if (error instanceof Error) return error;
+  const normalized = new Error(typeof error === "string" ? error : "Mutation failed");
+  normalized.cause = error;
+  return normalized;
+}
+__name(normalizeMutationError, "normalizeMutationError");
+
 // src/client.ts
 init_integration_api();
 
 // src/store.ts
-var import_react9 = require("react");
+var import_react10 = require("react");
 var RESERVED_STORE_KEYS = /* @__PURE__ */ new Set([
   "use",
   "get",
@@ -38069,20 +38536,20 @@ function createStore(initialState, extend) {
         }
         return lastSlice;
       }, "getSnapshot");
-      return (0, import_react9.useSyncExternalStore)(
+      return (0, import_react10.useSyncExternalStore)(
         (notify) => addSubscription(keys, () => notify()),
         getSnapshot,
         getSnapshot
       );
     }
     if (typeof keyOrKeys === "string") {
-      return (0, import_react9.useSyncExternalStore)(
+      return (0, import_react10.useSyncExternalStore)(
         (notify) => addSubscription([keyOrKeys], () => notify()),
         () => state[keyOrKeys],
         () => state[keyOrKeys]
       );
     }
-    return (0, import_react9.useSyncExternalStore)(
+    return (0, import_react10.useSyncExternalStore)(
       (notify) => addSubscription(null, () => notify()),
       () => state,
       () => state
@@ -38134,7 +38601,7 @@ function createStore(initialState, extend) {
 __name(createStore, "createStore");
 
 // src/client/link.tsx
-var import_react10 = require("react");
+var import_react11 = require("react");
 init_router();
 init_client_runtime();
 var import_jsx_runtime4 = require("react/jsx-runtime");
@@ -38196,9 +38663,9 @@ function LinkInner({
   onTouchStart,
   ...props
 }, ref) {
-  const elementRef = (0, import_react10.useRef)(null);
-  const intentTimeoutRef = (0, import_react10.useRef)(null);
-  const hasPrefetched = (0, import_react10.useRef)(false);
+  const elementRef = (0, import_react11.useRef)(null);
+  const intentTimeoutRef = (0, import_react11.useRef)(null);
+  const hasPrefetched = (0, import_react11.useRef)(false);
   const { intent, viewport, render } = normalizePrefetch(prefetch2);
   const baseHref = resolveLinkHref(href, params, {
     query,
@@ -38207,17 +38674,17 @@ function LinkInner({
   });
   const resolvedHref = localizeActiveFarmHref(baseHref, locale);
   const isExternal = isExternalUrl(resolvedHref);
-  const doPrefetch = (0, import_react10.useCallback)(() => {
+  const doPrefetch = (0, import_react11.useCallback)(() => {
     if (isExternal || hasPrefetched.current) return;
     const router = getRouter2();
     if (!router) return;
     hasPrefetched.current = true;
     router.prefetch(resolvedHref);
   }, [resolvedHref, isExternal]);
-  (0, import_react10.useEffect)(() => {
+  (0, import_react11.useEffect)(() => {
     hasPrefetched.current = false;
   }, [resolvedHref]);
-  (0, import_react10.useEffect)(() => {
+  (0, import_react11.useEffect)(() => {
     const element = elementRef.current;
     if (!element || isExternal) return;
     const router = getRouter2();
@@ -38227,7 +38694,7 @@ function LinkInner({
       return () => router.unobserveForPrefetch(element);
     }
   }, [resolvedHref, viewport, isExternal]);
-  (0, import_react10.useEffect)(() => {
+  (0, import_react11.useEffect)(() => {
     if (!render || isExternal) return;
     let cancelled = false;
     let timeoutId = null;
@@ -38249,7 +38716,7 @@ function LinkInner({
       }
     };
   }, [render, isExternal, resolvedHref]);
-  (0, import_react10.useEffect)(() => {
+  (0, import_react11.useEffect)(() => {
     return () => {
       if (intentTimeoutRef.current) {
         clearTimeout(intentTimeoutRef.current);
@@ -38257,13 +38724,13 @@ function LinkInner({
       }
     };
   }, []);
-  const cancelIntent = (0, import_react10.useCallback)(() => {
+  const cancelIntent = (0, import_react11.useCallback)(() => {
     if (intentTimeoutRef.current) {
       clearTimeout(intentTimeoutRef.current);
       intentTimeoutRef.current = null;
     }
   }, []);
-  const scheduleIntentPrefetch = (0, import_react10.useCallback)(() => {
+  const scheduleIntentPrefetch = (0, import_react11.useCallback)(() => {
     if (isExternal || !intent || hasPrefetched.current) return;
     cancelIntent();
     intentTimeoutRef.current = setTimeout(() => {
@@ -38271,42 +38738,42 @@ function LinkInner({
       doPrefetch();
     }, prefetchDelay);
   }, [intent, isExternal, prefetchDelay, doPrefetch, cancelIntent]);
-  const handleMouseEnter = (0, import_react10.useCallback)(
+  const handleMouseEnter = (0, import_react11.useCallback)(
     (event) => {
       onMouseEnter?.(event);
       scheduleIntentPrefetch();
     },
     [onMouseEnter, scheduleIntentPrefetch]
   );
-  const handleMouseLeave = (0, import_react10.useCallback)(
+  const handleMouseLeave = (0, import_react11.useCallback)(
     (event) => {
       onMouseLeave?.(event);
       cancelIntent();
     },
     [onMouseLeave, cancelIntent]
   );
-  const handleTouchStart = (0, import_react10.useCallback)(
+  const handleTouchStart = (0, import_react11.useCallback)(
     (event) => {
       onTouchStart?.(event);
       scheduleIntentPrefetch();
     },
     [onTouchStart, scheduleIntentPrefetch]
   );
-  const handleFocus = (0, import_react10.useCallback)(
+  const handleFocus = (0, import_react11.useCallback)(
     (event) => {
       onFocus?.(event);
       scheduleIntentPrefetch();
     },
     [onFocus, scheduleIntentPrefetch]
   );
-  const handleBlur = (0, import_react10.useCallback)(
+  const handleBlur = (0, import_react11.useCallback)(
     (event) => {
       onBlur?.(event);
       cancelIntent();
     },
     [onBlur, cancelIntent]
   );
-  const handleClick = (0, import_react10.useCallback)(
+  const handleClick = (0, import_react11.useCallback)(
     (event) => {
       onClick?.(event);
       if (event.defaultPrevented) return;
@@ -38331,7 +38798,7 @@ function LinkInner({
     },
     [resolvedHref, replace, scroll, viewTransition, target, isExternal, onClick]
   );
-  const setRefs = (0, import_react10.useCallback)(
+  const setRefs = (0, import_react11.useCallback)(
     (node) => {
       elementRef.current = node;
       if (typeof ref === "function") ref(node);
@@ -38360,7 +38827,7 @@ function LinkInner({
   );
 }
 __name(LinkInner, "LinkInner");
-var LinkWithRef = (0, import_react10.forwardRef)(LinkInner);
+var LinkWithRef = (0, import_react11.forwardRef)(LinkInner);
 LinkWithRef.displayName = "Link";
 var Link = LinkWithRef;
 function resolveLinkHref(href, params, options) {
@@ -39072,6 +39539,7 @@ function decodeCookiePart(value) {
 __name(decodeCookiePart, "decodeCookiePart");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  APIClientError,
   APIRouteManager,
   APITypeGenerator,
   API_ROUTE_METHODS,
@@ -39084,6 +39552,8 @@ __name(decodeCookiePart, "decodeCookiePart");
   DELETE,
   DeferredDataError,
   DocsRoute,
+  EndpointFailure,
+  FARM_API_ROUTE_REF_SYMBOL,
   FARM_CRON_MANIFEST,
   FARM_DEFERRED_BRAND,
   FARM_DEFERRED_CONTENT_TYPE,
@@ -39210,6 +39680,7 @@ __name(decodeCookiePart, "decodeCookiePart");
   cronRoute,
   databaseStorage,
   defer,
+  defineCacheKey,
   defineConfig,
   defineCron,
   defineFarmConfig,
@@ -39296,9 +39767,11 @@ __name(decodeCookiePart, "decodeCookiePart");
   invalidate,
   invalidateRouteData,
   invokeAPIRouteEndpoint,
+  isAPIRouteRef,
   isChunkLoadError,
   isCronRequestAuthorized,
   isDeferred,
+  isEndpointFailure,
   isFarmDeploymentMismatchResponse,
   isFarmDocsAPIRequest,
   isFarmDocsRequest,
@@ -39417,6 +39890,7 @@ __name(decodeCookiePart, "decodeCookiePart");
   updateTag,
   upstashStorage,
   useBlocker,
+  useMutation,
   useNavigation,
   usePageState,
   usePathname,