@farm.js/core 0.1.61 → 0.1.63

package/dist/api-client.d-ddQBNGtu.d.ts

@@ -0,0 +1,622 @@
+import { F as FarmIntegrationAPI, g as FarmIntegrationAPIOperation, o as RoutePathParams } from './route.d-DBTEqifW.js';
+import { b as FarmClientCacheKey, a as FarmClientCacheEntry } from './client-cache.d-Deoqq-nM.js';
+import { DefinedCacheKey, RouteDataCacheKey, InferCacheKeyData } from './cache.js';
+import { F as FarmAPIStream } from './endpoint.d-BgHn0lhl.js';
+
+/** Instance defaults, resolved once per call before cache lookup or dispatch. */
+type ClientHeaders = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+
+/** Metadata shared by app-route and integration execution attempts. */
+type ClientRequestEvent = {
+    requestId: string;
+    method: string;
+    path: string;
+    attempt: number;
+    timestamp: number;
+};
+type ClientResponseEvent<TData = unknown> = ClientRequestEvent & {
+    response?: Response;
+    data?: TData;
+    error?: Error;
+    ok?: boolean;
+    status?: number;
+};
+/** Observers compose with per-call hooks; return values never replace the result. */
+type ClientLifecycleHooks<TData = unknown> = {
+    onRequest?: (event: ClientRequestEvent) => void;
+    onResponse?: (data: TData | undefined, error: Error | null, event: ClientResponseEvent<TData>) => void;
+    onError?: (error: Error) => void;
+};
+
+/**
+ * Small per-call integration metadata. When sent from a browser, values are
+ * client-controlled and should be validated before authorization decisions.
+ */
+type IntegrationClientData = Record<string, unknown>;
+type IntegrationClientOptions = ClientLifecycleHooks & {
+    baseURL?: string;
+    headers?: ClientHeaders;
+    credentials?: RequestCredentials;
+    /** Whole-call deadline in milliseconds; 0 disables it. */
+    timeoutMs?: number;
+    /** HTTP transport, including server fallback; never replaces local dispatch. */
+    fetch?: typeof globalThis.fetch;
+    data?: IntegrationClientData;
+    isServer?: false | undefined;
+};
+type IntegrationRequestOptionsBase<TData = unknown> = ClientLifecycleHooks<TData> & {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    credentials?: RequestCredentials;
+    data?: IntegrationClientData;
+};
+type IntegrationClientRequestOptions<TData = unknown> = IntegrationRequestOptionsBase<TData>;
+type IntegrationServerRequestLike = Request | {
+    url?: string;
+    headers?: HeadersInit;
+};
+type IntegrationServerClientOptions = Omit<IntegrationClientOptions, "isServer"> & {
+    isServer: true;
+    request?: IntegrationServerRequestLike;
+    forwardHeaders?: boolean | readonly string[];
+};
+type IntegrationServerClientRequestOptions<TData = unknown> = IntegrationRequestOptionsBase<TData> & {
+    baseURL?: string;
+    request?: IntegrationServerRequestLike;
+    forwardHeaders?: boolean | readonly string[];
+};
+declare class IntegrationClientError<TData = unknown> extends Error {
+    readonly status: number;
+    readonly response: Response;
+    readonly data: TData | undefined;
+    constructor(message: string, response: Response, data?: TData);
+}
+type IntegrationOperationResult<TData = unknown, TError = IntegrationClientError<unknown> | Error> = {
+    data: TData | null;
+    error: TError | null;
+};
+type ExtractOperationBody<T> = T extends {
+    __types?: {
+        body: infer TBody;
+    };
+} ? TBody : never;
+type ExtractOperationQuery<T> = T extends {
+    __types?: {
+        query: infer TQuery;
+    };
+} ? TQuery : never;
+type ExtractOperationResponse<T> = T extends {
+    __types?: {
+        response: infer TResponse;
+    };
+} ? TResponse : unknown;
+type InferIntegrationOperationBody<T> = ExtractOperationBody<T>;
+type InferIntegrationOperationQuery<T> = ExtractOperationQuery<T>;
+type InferIntegrationOperationResponse<T> = ExtractOperationResponse<T>;
+type IsNever$1<T> = [T] extends [never] ? true : false;
+type OperationInput<T> = IsNever$1<ExtractOperationBody<T>> extends true ? IsNever$1<ExtractOperationQuery<T>> extends true ? {} : {
+    query?: ExtractOperationQuery<T>;
+} : IsNever$1<ExtractOperationQuery<T>> extends true ? {
+    body: ExtractOperationBody<T>;
+} : {
+    body: ExtractOperationBody<T>;
+    query?: ExtractOperationQuery<T>;
+};
+type ClientOperation<T> = (options?: OperationInput<T>, requestOptions?: IntegrationClientRequestOptions<ExtractOperationResponse<T>>) => Promise<IntegrationOperationResult<ExtractOperationResponse<T>>>;
+type ServerOperation<T> = (options?: OperationInput<T>, requestOptions?: IntegrationServerClientRequestOptions<ExtractOperationResponse<T>>) => Promise<IntegrationOperationResult<ExtractOperationResponse<T>>>;
+type IsUnion<T, U = T> = T extends any ? ([U] extends [T] ? false : true) : never;
+type SingleKey<T> = [T] extends [never] ? never : IsUnion<T> extends true ? never : T;
+type ExtractAPIFromSource<TSource> = TSource extends {
+    api?: infer TAPI;
+} ? NonNullable<TAPI> extends FarmIntegrationAPI ? NonNullable<TAPI> : never : TSource extends FarmIntegrationAPI ? TSource : never;
+type SourceKeysWithAPI<TSources extends Record<string, any>> = {
+    [K in keyof TSources]: [ExtractAPIFromSource<TSources[K]>] extends [never] ? never : K;
+}[keyof TSources];
+type IsServerRegisteredOperation<T> = T extends {
+    isServer: true;
+} ? true : false;
+type ClientOperationKeys<TAPI> = {
+    [K in keyof TAPI]: TAPI[K] extends FarmIntegrationAPIOperation<any, any, any, any> ? IsServerRegisteredOperation<TAPI[K]> extends true ? never : K : never;
+}[keyof TAPI];
+type ClientNamespaceShape<TAPI> = {
+    [K in keyof TAPI as TAPI[K] extends FarmIntegrationAPIOperation<any, any, any, any> ? IsServerRegisteredOperation<TAPI[K]> extends true ? never : K : K]: TAPI[K] extends FarmIntegrationAPIOperation<any, any, any, any> ? ClientOperation<TAPI[K]> : TAPI[K] extends Record<string, any> ? IntegrationAPIToClient<TAPI[K]> : never;
+};
+type SingleClientOperationKey<TAPI> = Exclude<keyof TAPI, ClientOperationKeys<TAPI>> extends never ? SingleKey<ClientOperationKeys<TAPI>> : never;
+type IntegrationAPIToClient<TAPI> = TAPI extends FarmIntegrationAPIOperation<any, any, any, any> ? ClientOperation<TAPI> : TAPI extends Record<string, any> ? [SingleClientOperationKey<TAPI>] extends [never] ? ClientNamespaceShape<TAPI> : SingleClientOperationKey<TAPI> extends keyof TAPI ? ClientOperation<TAPI[SingleClientOperationKey<TAPI>]> & ClientNamespaceShape<TAPI> : ClientNamespaceShape<TAPI> : never;
+type IntegrationClient<TSources extends Record<string, any>> = {
+    [K in SourceKeysWithAPI<TSources>]: IntegrationAPIToClient<ExtractAPIFromSource<TSources[K]>>;
+};
+type IntegrationClientRoot<TSources extends Record<string, any>> = {
+    integrations: IntegrationClient<TSources>;
+};
+type ServerOperationKeys<TAPI> = {
+    [K in keyof TAPI]: TAPI[K] extends FarmIntegrationAPIOperation<any, any, any> ? K : never;
+}[keyof TAPI];
+type ServerNamespaceShape<TAPI> = {
+    [K in keyof TAPI]: TAPI[K] extends FarmIntegrationAPIOperation<any, any, any> ? ServerOperation<TAPI[K]> : TAPI[K] extends Record<string, any> ? IntegrationAPIToServerClient<TAPI[K]> : never;
+};
+type SingleServerOperationKey<TAPI> = Exclude<keyof TAPI, ServerOperationKeys<TAPI>> extends never ? SingleKey<ServerOperationKeys<TAPI>> : never;
+type IntegrationAPIToServerClient<TAPI> = TAPI extends FarmIntegrationAPIOperation<any, any, any> ? ServerOperation<TAPI> : TAPI extends Record<string, any> ? [SingleServerOperationKey<TAPI>] extends [never] ? ServerNamespaceShape<TAPI> : SingleServerOperationKey<TAPI> extends keyof TAPI ? ServerOperation<TAPI[SingleServerOperationKey<TAPI>]> & ServerNamespaceShape<TAPI> : ServerNamespaceShape<TAPI> : never;
+type IntegrationServerClient<TSources extends Record<string, any>> = {
+    [K in SourceKeysWithAPI<TSources>]: IntegrationAPIToServerClient<ExtractAPIFromSource<TSources[K]>>;
+};
+type IntegrationServerClientRoot<TSources extends Record<string, any>> = {
+    integrations: IntegrationServerClient<TSources>;
+};
+type IntegrationClientAliases<TSources extends Record<string, any>> = IntegrationClient<TSources> & {
+    integrations: IntegrationClient<TSources>;
+};
+type IntegrationServerClientAliases<TSources extends Record<string, any>> = IntegrationServerClient<TSources> & {
+    integrations: IntegrationServerClient<TSources>;
+};
+type IntegrationAPI<TSources extends Record<string, any>> = IntegrationClientAliases<TSources> & {
+    server: (options: Omit<IntegrationServerClientOptions, "isServer">) => IntegrationServerClientAliases<TSources>;
+};
+type IntegrationClients<TSources extends Record<string, any>> = {
+    api: IntegrationServerClientAliases<TSources>;
+    apiClient: IntegrationClientAliases<TSources>;
+};
+declare function createIntegrationClient<TSources extends Record<string, any>>(sources: {
+    integrations: TSources;
+}, options: IntegrationServerClientOptions): IntegrationServerClientAliases<TSources>;
+declare function createIntegrationClient<TSources extends Record<string, any>>(sources: {
+    integrations: TSources;
+}, options?: IntegrationClientOptions): IntegrationClientAliases<TSources>;
+declare function createIntegrationClient<TSources extends Record<string, any>>(sources: TSources, options: IntegrationServerClientOptions): IntegrationServerClient<TSources>;
+declare function createIntegrationClient<TSources extends Record<string, any>>(sources: TSources, options?: IntegrationClientOptions): IntegrationClient<TSources>;
+declare function integrationsClient<TSources extends Record<string, any>>(): IntegrationClientAliases<TSources>;
+declare function integrationsClient<TSources extends Record<string, any>>(options: IntegrationClientOptions): IntegrationClientAliases<TSources>;
+declare function integrationsServer<TSources extends Record<string, any>>(): IntegrationServerClientAliases<TSources>;
+declare function integrationsServer<TSources extends Record<string, any>>(options: Omit<IntegrationServerClientOptions, "isServer">): IntegrationServerClientAliases<TSources>;
+declare function createIntegrationServerClient<TSources extends Record<string, any>>(sources: {
+    integrations: TSources;
+}): IntegrationServerClientAliases<TSources>;
+declare function createIntegrationServerClient<TSources extends Record<string, any>>(sources: TSources): IntegrationServerClient<TSources>;
+declare function createIntegrationServerClient<TSources extends Record<string, any>>(sources: {
+    integrations: TSources;
+}, options: Omit<IntegrationServerClientOptions, "isServer">): IntegrationServerClientAliases<TSources>;
+declare function createIntegrationServerClient<TSources extends Record<string, any>>(sources: TSources, options: Omit<IntegrationServerClientOptions, "isServer">): IntegrationServerClient<TSources>;
+declare function createIntegrationApi<TSources extends Record<string, any>>(sources: {
+    integrations: TSources;
+}, options?: IntegrationClientOptions): IntegrationAPI<TSources>;
+declare function createIntegrationClients<TSources extends Record<string, any>>(clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+declare function createIntegrationClients<TSources extends Record<string, any>>(sources: TSources, clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+declare function createIntegrationClients<TSources extends Record<string, any>>(sources: {
+    integrations: TSources;
+}, clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+declare function createIntegrations<TSources extends Record<string, any>>(clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+declare function createIntegrations<TSources extends Record<string, any>>(sources: TSources, clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+declare function createIntegrations<TSources extends Record<string, any>>(sources: {
+    integrations: TSources;
+}, clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+declare function getIntegrationAPIManifest(): Record<string, FarmIntegrationAPI>;
+declare function integrationClients<TSources extends Record<string, any>>(clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+declare function integrationClients<TSources extends Record<string, any>>(sources: TSources, clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+declare function integrationClients<TSources extends Record<string, any>>(sources: {
+    integrations: TSources;
+}, clientOptions?: IntegrationClientOptions, serverOptions?: Omit<IntegrationServerClientOptions, "isServer">): IntegrationClients<TSources>;
+
+type APIRouteManifest = readonly {
+    readonly path: string;
+    readonly methods: readonly string[];
+}[];
+
+declare const FARM_API_ROUTE_REF_SYMBOL: unique symbol;
+declare const FARM_API_ROUTE_META_SYMBOL: unique symbol;
+type APIRouteRefMetadata = {
+    path: string;
+    method: string;
+    baseURL: string;
+    sameOrigin: boolean;
+};
+type APIClientOptions = ClientLifecycleHooks & {
+    /** Generated path/method metadata required for dynamic shorthand and $params scopes. */
+    routes?: APIRouteManifest;
+    baseURL?: string;
+    headers?: ClientHeaders;
+    credentials?: RequestCredentials;
+    /** Whole-call deadline in milliseconds. 0 (default) disables it. */
+    timeoutMs?: number;
+    /** HTTP transport only; local server dispatch does not use it. */
+    fetch?: typeof globalThis.fetch;
+    cacheDefaults?: CacheOptions;
+    integrations?: IntegrationClientOptions;
+};
+type APIClientWithoutIntegrationsOptions = Omit<APIClientOptions, "integrations"> & {
+    integrations: false;
+};
+type ServerAPIClientOptions = {
+    integrations?: Omit<IntegrationServerClientOptions, "isServer">;
+};
+type ServerAPIClientWithoutIntegrationsOptions = Omit<ServerAPIClientOptions, "integrations"> & {
+    integrations: false;
+};
+type StatusPhase = "idle" | "pending" | "success" | "error" | "revalidating" | "invalidated";
+type StatusEvent<TData = unknown, TError = unknown> = {
+    phase: StatusPhase;
+    requestId: string;
+    method: "GET" | "HEAD" | "QUERY" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+    key: string;
+    input?: unknown;
+    data?: TData;
+    error?: TError;
+    isBackground?: boolean;
+    timestamp: number;
+};
+type CacheKey<TData = unknown> = string & {
+    readonly __farmCacheData?: TData;
+};
+type APIResult<TData = unknown, TError = Error> = {
+    data: TData | undefined;
+    error: TError | null;
+    key: CacheKey<TData>;
+};
+declare class APIClientError<TCode extends string = string, TData = unknown, TStatus extends number = number> extends Error {
+    readonly code: TCode;
+    readonly data: TData;
+    readonly status: TStatus;
+    readonly response?: Response;
+    constructor(code: TCode, data: TData, options: {
+        status: TStatus;
+        message: string;
+        response?: Response;
+    });
+}
+type APIClientSystemError = APIClientError<"http_error", unknown, number> | APIClientError<"aborted" | "timeout", unknown, 0> | APIClientError<"network_error", unknown, 0>;
+type RequestEvent = {
+    requestId: string;
+    method: StatusEvent["method"];
+    key: string;
+    path: string;
+    input?: unknown;
+    attempt: number;
+    timestamp: number;
+};
+type ResponseEvent<TData = unknown, TError = Error> = {
+    requestId: string;
+    method: StatusEvent["method"];
+    key: string;
+    path: string;
+    input?: unknown;
+    attempt: number;
+    timestamp: number;
+    response?: Response;
+    data?: TData;
+    error?: TError;
+    ok?: boolean;
+    status?: number;
+};
+type CachePolicy = "cache-first" | "network-only" | "stale-while-revalidate";
+type CacheScope = "client" | "shared";
+type CacheOptions = {
+    key?: FarmClientCacheKey;
+    policy?: CachePolicy;
+    /** Select client-local or public shared storage. Identity-carrying requests always stay local. */
+    scope?: CacheScope;
+    staleTime?: number;
+    gcTime?: number;
+    dedupeMs?: number;
+    /** Allow the configured client cache persistence adapter to store this read. */
+    persist?: boolean;
+};
+type RetryAttemptContext = {
+    /** Zero-based index of the attempt that just failed. */
+    attempt: number;
+    /** Upper-case HTTP method of the request. */
+    method: string;
+    /** Response status, or undefined when the request never produced a response. */
+    status?: number;
+    error: Error;
+};
+type RetryOptions = {
+    count?: number;
+    delay?: number | ((attempt: number) => number);
+    /**
+     * Decide whether a failed attempt should be retried.
+     *
+     * Defaults to transient failures of idempotent requests only: replaying a
+     * POST or PATCH whose response was lost duplicates the write it performed.
+     * Supply this to opt a specific call in or out.
+     */
+    shouldRetry?: (context: RetryAttemptContext) => boolean;
+};
+type InvalidateTarget = FarmClientCacheKey | {
+    key: FarmClientCacheKey;
+} | {
+    path: string;
+    method?: "GET" | "HEAD" | "QUERY" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+    input?: unknown;
+} | [CallableRouteRef<any>, unknown?];
+type InvalidateOptions = InvalidateTarget[] | {
+    targets: InvalidateTarget[];
+    refetch?: boolean;
+};
+type OptimisticUpdate = [CallableRouteRef<any>, unknown, (prev: any) => any] | [CacheKey<any> | DefinedCacheKey<any> | string, (prev: any) => any];
+type OptimisticOptions<TUpdates extends readonly unknown[] = readonly OptimisticUpdate[]> = {
+    update: TUpdates & NormalizeOptimisticUpdates<TUpdates>;
+    rollbackOnError?: boolean;
+};
+type ClientOptions<TData = unknown, TError = unknown, TUpdates extends readonly unknown[] = readonly OptimisticUpdate[]> = {
+    key?: CacheKey<TData> | FarmClientCacheKey;
+    signal?: AbortSignal;
+    /** Override the instance deadline; 0 disables it for this call. */
+    timeoutMs?: number;
+    cache?: CacheOptions;
+    retry?: RetryOptions;
+    invalidate?: InvalidateOptions;
+    optimistic?: OptimisticOptions<TUpdates>;
+    onRequest?: (event: RequestEvent) => void;
+    onResponse?: (data: TData | undefined, error: TError | null, event: ResponseEvent<TData, TError>) => void;
+    onSuccess?: (data: TData) => void;
+    onError?: (err: TError) => void;
+    onSettled?: (data?: TData, err?: TError | null) => void;
+    onStatus?: (event: StatusEvent<TData, TError>) => void;
+};
+type AnyRouteRef = (...args: any[]) => any;
+type RouteRef<TData = any, TInput = any> = {
+    readonly __farmRouteInput: TInput;
+    readonly __farmRouteData: TData;
+};
+type CallableRouteRef<TData = any, TInput = any> = AnyRouteRef & RouteRef<TData, TInput>;
+type InferRouteInput<TRoute> = TRoute extends {
+    readonly __farmRouteInput: infer TInput;
+} ? TInput : never;
+type InferRouteData<TRoute> = TRoute extends {
+    readonly __farmRouteData: infer TData;
+} ? TData : never;
+type NormalizeOptimisticUpdate<TUpdate> = TUpdate extends readonly [
+    infer TRoute,
+    unknown,
+    (prev: any) => any
+] ? TRoute extends RouteRef<any, any> ? [
+    TRoute,
+    InferRouteInput<TRoute> | undefined,
+    (prev: InferRouteData<TRoute> | undefined) => InferRouteData<TRoute>
+] : never : TUpdate extends readonly [infer TKey, (prev: any) => any] ? TKey extends DefinedCacheKey<any, RouteDataCacheKey> ? [TKey, (prev: InferCacheKeyData<TKey> | undefined) => InferCacheKeyData<TKey>] : TKey extends CacheKey<infer TData> ? [TKey, (prev: TData | undefined) => TData] : TKey extends string ? [TKey, (prev: unknown) => unknown] : never : never;
+type NormalizeOptimisticUpdates<TUpdates extends readonly unknown[]> = {
+    [K in keyof TUpdates]: NormalizeOptimisticUpdate<TUpdates[K]>;
+};
+type TypedEndpointLike = {
+    __types: {
+        body: any;
+        query: any;
+        response: any;
+        errors?: any;
+    };
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type RequiredKeys<T> = T extends object ? {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T] : never;
+type BodyInputProp<TValue> = IsNever<TValue> extends true ? {} : IsAny<TValue> extends true ? {
+    body?: TValue;
+} : undefined extends TValue ? {
+    body?: TValue;
+} : {
+    body: TValue;
+};
+type APIQueryPrimitive = string | number | boolean | bigint;
+type APIQueryValue = APIQueryPrimitive | null | undefined | readonly (APIQueryPrimitive | null | undefined)[];
+type NormalizeAPIQueryValue<TValue> = TValue extends null | undefined ? TValue : TValue extends APIQueryPrimitive ? TValue : TValue extends readonly (infer TItem)[] ? Exclude<TItem, null | undefined> extends APIQueryPrimitive ? TValue : never : never;
+type NormalizeAPIQueryInput<TValue> = TValue extends URLSearchParams ? TValue : TValue extends object ? {
+    [TKey in keyof TValue]: NormalizeAPIQueryValue<TValue[TKey]>;
+} : never;
+type QueryInputProp<TValue> = IsNever<TValue> extends true ? {} : IsAny<TValue> extends true ? {
+    query?: TValue;
+} : undefined extends TValue ? {
+    query?: NormalizeAPIQueryInput<TValue>;
+} : RequiredKeys<TValue> extends never ? {
+    query?: NormalizeAPIQueryInput<TValue>;
+} : {
+    query: NormalizeAPIQueryInput<TValue>;
+};
+type HasRequiredKeys<T> = RequiredKeys<T> extends never ? false : true;
+type InferEndpointBody<T> = T extends {
+    __types: {
+        inputBody: infer TInputBody;
+    };
+} ? TInputBody : T extends {
+    __types: {
+        body: infer TBody;
+    };
+} ? TBody : never;
+type InferEndpointInput<T> = T extends {
+    __types: {
+        query: infer TQuery;
+    };
+} ? Simplify<BodyInputProp<InferEndpointBody<T>> & QueryInputProp<T extends {
+    __types: {
+        inputQuery: infer I;
+    };
+} ? I : TQuery> & (T extends {
+    __routeParams: infer P;
+} ? keyof P extends never ? {
+    params?: never;
+} : {
+    params: P;
+} : {}) & (T extends {
+    __types: {
+        inputHeaders: infer H;
+    };
+} ? IsNever<H> extends true ? {} : RequiredKeys<H> extends never ? {
+    headers?: H;
+} : {
+    headers: H;
+} : {})> : T extends {
+    __routeParams: infer P;
+} ? keyof P extends never ? {
+    params?: never;
+} : {
+    params: P;
+} : {};
+type InferEndpointOutput<T> = T extends {
+    __types: {
+        response: infer R;
+    };
+} ? R extends {
+    readonly __farmStreamItem: infer TItem;
+} ? FarmAPIStream<TItem> : R : any;
+type InferEndpointError<T> = T extends {
+    __types: {
+        errors: infer TErrors;
+    };
+} ? keyof TErrors extends never ? Error : {
+    [TCode in keyof TErrors]: TErrors[TCode] extends {
+        data: infer TData;
+        status: infer TStatus extends number;
+    } ? APIClientError<TCode & string, TData, TStatus> : never;
+}[keyof TErrors] | APIClientSystemError : Error;
+type EndpointCall<T = any> = <TUpdates extends readonly unknown[] = readonly OptimisticUpdate[]>(...args: HasRequiredKeys<InferEndpointInput<T>> extends true ? [
+    options: InferEndpointInput<T>,
+    clientOptions?: ClientOptions<InferEndpointOutput<T>, InferEndpointError<T>, TUpdates>
+] : [
+    options?: InferEndpointInput<T>,
+    clientOptions?: ClientOptions<InferEndpointOutput<T>, InferEndpointError<T>, TUpdates>
+]) => Promise<APIResult<InferEndpointOutput<T>, InferEndpointError<T>>>;
+type EndpointMethod<T = any> = EndpointCall<T> & RouteRef<InferEndpointOutput<T>, InferEndpointInput<T>>;
+type DynamicKeys<T> = Extract<keyof T, `[${string}]`>;
+type MethodKeys = "get" | "head" | "query" | "post" | "put" | "patch" | "delete" | "options";
+type OwnMethodKeys<T> = {
+    [K in Extract<keyof T, MethodKeys>]: T[K] extends TypedEndpointLike | ((...args: any[]) => any) ? K : never;
+}[Extract<keyof T, MethodKeys>];
+type WithRouteParams<T, P> = T & {
+    __routeParams: P;
+};
+type UnionToIntersection<U> = (U extends unknown ? (v: U) => void : never) extends (v: infer I) => void ? I : never;
+type ChildMethods<T> = {
+    [K in DynamicKeys<T>]: OwnMethodKeys<T[K]>;
+}[DynamicKeys<T>];
+type MethodEndpoints<T, M extends PropertyKey, P> = (M extends OwnMethodKeys<T> ? WithRouteParams<T[M], P> : never) | {
+    [K in DynamicKeys<T>]: M extends keyof T[K] ? WithRouteParams<T[K][M], P & RoutePathParams<K>> : never;
+}[DynamicKeys<T>];
+type DistributedCall<T> = T extends unknown ? EndpointCall<T> : never;
+type ScopedMethod<T> = UnionToIntersection<DistributedCall<T>> & EndpointCall<T> & RouteRef<InferEndpointOutput<T>, InferEndpointInput<T>>;
+type RouterToClient<T, P = {}> = {
+    [K in Exclude<keyof T, OwnMethodKeys<T>>]: T[K] extends TypedEndpointLike ? EndpointMethod<WithRouteParams<T[K], P>> : T[K] extends Record<string, any> ? RouterToClient<T[K], P & (K extends string ? RoutePathParams<K> : {})> : EndpointMethod<WithRouteParams<T[K], P>>;
+} & {
+    [M in OwnMethodKeys<T> | ChildMethods<T>]: M extends ChildMethods<T> ? ScopedMethod<MethodEndpoints<T, M, P>> : M extends keyof T ? EndpointMethod<WithRouteParams<T[M], P>> : never;
+} & ([DynamicKeys<T>] extends [never] ? {} : {
+    $params: UnionToIntersection<{
+        [K in DynamicKeys<T>]: (params: RoutePathParams<K>) => RouterToClient<T[K], P>;
+    }[DynamicKeys<T>]>;
+});
+type RouteAPIClient<TRouter extends Record<string, any>> = RouterToClient<TRouter>;
+type APIClient<TRouter extends Record<string, any>, TIntegrations extends Record<string, any> = {}> = RouteAPIClient<TRouter> & IntegrationClientRoot<TIntegrations>;
+type ServerAPIClient<TEndpoints extends Record<string, any>, TIntegrations extends Record<string, any> = {}> = TEndpoints & IntegrationServerClientRoot<TIntegrations>;
+type ApiClients<TRouter extends Record<string, any>, TIntegrations extends Record<string, any> = {}> = {
+    api: RouteAPIClient<TRouter> & IntegrationServerClientRoot<TIntegrations>;
+    apiClient: APIClient<TRouter, TIntegrations>;
+};
+/**
+ * Define one shared pair of typed callers. Import only generated route metadata
+ * here, not endpoint modules. `api` dispatches locally during a Farm request;
+ * `apiClient` uses HTTP. Both return the same app-route APIResult shape.
+ */
+declare function createApiClients<TRouter extends Record<string, any>>(options: APIClientWithoutIntegrationsOptions): {
+    api: RouteAPIClient<TRouter>;
+    apiClient: RouteAPIClient<TRouter>;
+};
+declare function createApiClients<TRouter extends Record<string, any>, TIntegrations extends Record<string, any> = {}>(options?: APIClientOptions): ApiClients<TRouter, TIntegrations>;
+/**
+ * Create a typed RPC client for Farm.js API routes
+ *
+ * Returns a nested proxy that supports:
+ * - api.hello.get({ query: { name: 'World' } })
+ * - api['auth/login'].post({ body: { email: '...', password: '...' } })
+ * - api.users.get({ query: { limit: '10' } })
+ * - api.integrations.billing.checkout({ body: { priceId: 'price_...' } })
+ *
+ * @example
+ * ```typescript
+ * import { createAPIClient } from 'farm/client';
+ * import type { APIRouter } from '@/api';
+ * import type { AppIntegrations } from '@/lib/integrations';
+ *
+ * export const api = createAPIClient<APIRouter, AppIntegrations>();
+ *
+ * // Use it (nested property access)
+ * const result = await api.hello.get({ query: { name: 'World' } });
+ * if (result.error) console.error(result.error);
+ * else console.log(result.data);
+ *
+ * // Or with string keys for nested paths
+ * const result = await api['auth/login'].post({
+ *   body: { email: 'test@example.com', password: 'pass123' }
+ * });
+ *
+ * // Integration APIs live under a reserved namespace.
+ * const checkout = await api.integrations.billing.checkout({
+ *   body: { priceId: 'price_123' }
+ * });
+ * ```
+ */
+declare function createAPIClient<TRouter extends Record<string, any>>(options: APIClientWithoutIntegrationsOptions): RouteAPIClient<TRouter>;
+declare function createAPIClient<TRouter extends Record<string, any>, TIntegrations extends Record<string, any> = {}>(options?: APIClientOptions): APIClient<TRouter, TIntegrations>;
+declare function isAPIRouteRef(value: unknown): value is CallableRouteRef;
+declare function getAPIRouteRefMetadata(value: unknown): APIRouteRefMetadata | null;
+/**
+ * Server-side API client that calls endpoints directly as functions
+ * No HTTP overhead for app endpoints, and registered integration routes can be exposed at
+ * api.integrations.* where Farm can dispatch them directly to the integration handler.
+ *
+ * @example
+ * ```typescript
+ * import { createServerAPIClient } from 'farm/client';
+ * import type { AppIntegrations } from '@/lib/integrations';
+ *
+ * export const api = createServerAPIClient<{}, AppIntegrations>({});
+ *
+ * const result = await api.integrations.billing.status();
+ * ```
+ */
+declare function createServerAPIClient<TEndpoints extends Record<string, any>>(endpoints: TEndpoints): TEndpoints;
+declare function createServerAPIClient<TEndpoints extends Record<string, any>>(endpoints: TEndpoints, options: ServerAPIClientWithoutIntegrationsOptions): TEndpoints;
+declare function createServerAPIClient<TEndpoints extends Record<string, any>, TIntegrations extends Record<string, any> = {}>(endpoints: TEndpoints, options?: ServerAPIClientOptions): ServerAPIClient<TEndpoints, TIntegrations>;
+declare const API_CACHE_REFETCH: unique symbol;
+type CacheEntry = FarmClientCacheEntry<any> & {
+    [API_CACHE_REFETCH]?: () => void;
+};
+type OptimisticSnapshot = {
+    key: string;
+    stack: OptimisticStack;
+    layer: OptimisticLayer;
+};
+type OptimisticStack = {
+    entry?: CacheEntry;
+    layers: OptimisticLayer[];
+    renderedEntry?: CacheEntry;
+    invalidatedAt?: number;
+};
+type OptimisticLayer = {
+    updaters: Array<(prev: any) => any>;
+    updatedAt: number;
+    staleAt: number;
+    gcAt?: number;
+    committed?: boolean;
+};
+/**
+ * @internal Apply key-targeted optimistic updates to the shared client cache
+ * for a server-function mutation. Route-reference update tuples need an API
+ * caller's route metadata and are skipped here; use structured cache keys.
+ */
+declare function applyServerFnOptimisticUpdates(updates: readonly OptimisticUpdate[], now?: number): OptimisticSnapshot[];
+/**
+ * @internal Settle a server-function mutation's optimistic snapshots with the
+ * API client's semantics: commit on success, rollback on failure with
+ * `rollbackOnError`, and mark-stale on failure without it.
+ */
+declare function settleServerFnOptimisticUpdates(snapshots: OptimisticSnapshot[], outcome: "commit" | "rollback" | "invalidate"): void;
+/**
+ * @internal Resolve a server-function mutation's invalidate targets to cache
+ * keys. Route-reference and path targets need an API caller's identity and are
+ * skipped; use structured cache keys. Keys are applied through the shared
+ * invalidation bus, matching server-declared `invalidates`.
+ */
+declare function resolveServerFnInvalidateTargets(invalidate: InvalidateOptions): string[];
+
+export { type RequestEvent as $, type APIClient as A, type InferIntegrationOperationResponse as B, type CacheKey as C, type IntegrationAPI as D, type IntegrationClient as E, FARM_API_ROUTE_META_SYMBOL as F, type IntegrationClientAliases as G, type IntegrationClientData as H, type InferIntegrationOperationBody as I, IntegrationClientError as J, type IntegrationClientOptions as K, type IntegrationClientRequestOptions as L, type IntegrationClientRoot as M, type IntegrationClients as N, type IntegrationOperationResult as O, type IntegrationServerClient as P, type IntegrationServerClientAliases as Q, type RouteAPIClient as R, type ServerAPIClient as S, type IntegrationServerClientOptions as T, type IntegrationServerClientRequestOptions as U, type IntegrationServerClientRoot as V, type IntegrationServerRequestLike as W, type InvalidateOptions as X, type InvalidateTarget as Y, type OptimisticOptions as Z, type OptimisticUpdate as _, createApiClients as a, type ResponseEvent as a0, type RetryAttemptContext as a1, type StatusEvent as a2, type StatusPhase as a3, applyServerFnOptimisticUpdates as a4, createIntegrationApi as a5, createIntegrationClient as a6, createIntegrationClients as a7, createIntegrationServerClient as a8, createIntegrations as a9, getAPIRouteRefMetadata as aa, getIntegrationAPIManifest as ab, integrationClients as ac, integrationsClient as ad, integrationsServer as ae, isAPIRouteRef as af, resolveServerFnInvalidateTargets as ag, settleServerFnOptimisticUpdates as ah, APIClientError as b, createAPIClient as c, type APIClientOptions as d, type APIClientSystemError as e, type APIClientWithoutIntegrationsOptions as f, type ApiClients as g, type ServerAPIClientOptions as h, type ServerAPIClientWithoutIntegrationsOptions as i, createServerAPIClient as j, type RetryOptions as k, type APIQueryPrimitive as l, type APIQueryValue as m, type APIResult as n, type APIRouteManifest as o, type APIRouteRefMetadata as p, type CacheOptions as q, type CachePolicy as r, type CacheScope as s, type ClientHeaders as t, type ClientLifecycleHooks as u, type ClientOptions as v, type ClientRequestEvent as w, type ClientResponseEvent as x, FARM_API_ROUTE_REF_SYMBOL as y, type InferIntegrationOperationQuery as z };