import type { ActionFailure } from "../errors.js";
/** Concurrency mode for actions called multiple times in rapid succession. */
export type ActionConcurrencyMode = "latest" | "queue" | "parallel";
/** Options for defining a typed server action. */
export interface DefineActionOptions<TInput> {
    /**
     * Optional input validator. Can be a Zod schema, a plain function, or any
     * object with a `.parse()` method. If validation fails, the action returns
     * a 400 ActionFailure with the validation error.
     */
    input?: ActionInputValidator<TInput>;
    /** Concurrency mode when the same action is called multiple times. */
    concurrency?: ActionConcurrencyMode;
    /** Whether the action is idempotent (safe to retry). */
    idempotent?: boolean;
    /** Tags to invalidate from the cache after a successful action (§9.4). */
    invalidateTags?: string[];
    /** Paths to invalidate from the cache after a successful action (§9.4). */
    invalidatePaths?: string[];
}
/** A validator that has a `.parse()` method (Zod-compatible) or is a function. */
export interface ActionInputValidator<T> {
    parse(input: unknown): T;
}
/** Context passed to a defined action. */
export interface ActionContext {
    /** The original Web Request. */
    request: Request;
    /** AbortSignal from the request — aborts if the client disconnects. */
    signal: AbortSignal;
    /** Idempotency key from the request header, if present. */
    idempotencyKey?: string;
    /** Route params (for page-scoped actions). */
    params: Record<string, string | string[]>;
    /** Per-request locals (populated by middleware). */
    locals: Record<string, unknown>;
}
/** A defined action function. */
export type DefinedActionFn<TInput, TOutput> = (input: TInput, ctx: ActionContext) => Promise<TOutput | ActionFailure<TOutput>>;
/** The return type of defineAction(): a callable with metadata. */
export interface DefinedAction<TInput, TOutput> {
    (input: TInput, ctx: ActionContext): Promise<TOutput | ActionFailure<TOutput>>;
    /** Metadata for the action (used by the runtime/manifest). */
    __nixAction: {
        name: string;
        concurrency: ActionConcurrencyMode;
        idempotent: boolean;
        invalidateTags: readonly string[];
        invalidatePaths: readonly string[];
    };
}
/**
 * Defines a typed server action with validation, abort support, and cache
 * invalidation metadata.
 *
 * ```ts
 * import { defineAction, fail } from "@deijose/nix-js-kit/action";
 *
 * export const submitContact = defineAction({
 *   input: { parse: (v) => v as { name: string; email: string } },
 *   invalidateTags: ["contacts"],
 * }, async (input, ctx) => {
 *   if (!input.email.includes("@")) return fail(400, { email: "Invalid" });
 *   await saveContact(input);
 *   return { success: true };
 * });
 * ```
 *
 * Legacy exported async functions (without `defineAction`) continue to work
 * as before — this is an opt-in upgrade.
 */
export declare function defineAction<TInput = unknown, TOutput = unknown>(options: DefineActionOptions<TInput>, handler: DefinedActionFn<TInput, TOutput>): DefinedAction<TInput, TOutput>;