@kellanjs/actioncraft 0.0.2 → 0.2.0

package/dist/classes/executor.js

@@ -0,0 +1,354 @@
+import { safeExecuteCallback } from "../core/callbacks.js";
+import { createUnhandledErrorResult, createImplicitReturnErrorResult, } from "../core/errors.js";
+import { log } from "../core/logging.js";
+import { serializeRawInput, convertToClientError, } from "../core/transformation.js";
+import { validateInput, validateBindArgs, validateOutput, } from "../core/validation.js";
+import {} from "../types/errors.js";
+import { err, isOk, isResultOk, isResultErr, isErr } from "../types/result.js";
+import { INTERNAL } from "./internal.js";
+import { unstable_rethrow } from "next/navigation.js";
+// ============================================================================
+// EXECUTOR CLASS - Build and execute your action
+// ============================================================================
+export class Executor {
+    _config;
+    _schemas;
+    _errors;
+    _callbacks;
+    _handler;
+    _actionId;
+    constructor(crafter) {
+        this._config = crafter[INTERNAL]().config;
+        this._schemas = crafter[INTERNAL]().schemas;
+        this._errors = crafter[INTERNAL]().errors;
+        this._callbacks = crafter[INTERNAL]().callbacks;
+        this._handler = crafter[INTERNAL]().handler;
+    }
+    /**
+     * Builds and returns the final executable server action.
+     */
+    craft() {
+        if (!this._handler) {
+            throw new Error("A handler implementation is required");
+        }
+        // Generate a unique ID for this action instance
+        this._actionId = this._generateActionId();
+        const craftedAction = (...args) => {
+            return this._runAction(args);
+        };
+        // Attach the action's config and ID for runtime inspection
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        craftedAction.__ac_config = this._config;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        craftedAction.__ac_id = this._actionId;
+        return craftedAction;
+    }
+    /**
+     * Generates a unique identifier for this action instance.
+     */
+    _generateActionId() {
+        return crypto.randomUUID();
+    }
+    // --------------------------------------------------------------------------
+    // ACTION EXECUTION
+    // --------------------------------------------------------------------------
+    /**
+     * Orchestrates action execution (validation, business logic, callbacks, and result formatting.)
+     */
+    async _runAction(args) {
+        // We know these exist because craft() creates/verifies them
+        const handler = this._handler;
+        const actionId = this._actionId;
+        // Extract bindArgs, prevState, and input from the raw args
+        const { bindArgs: rawBindArgs, prevState, input: rawInput, } = this._extractActionArgs(args);
+        // Check for custom error handler
+        const handleThrownErrorFn = this._config.handleThrownError
+            ? (error) => err(this._config.handleThrownError(error), actionId)
+            : null;
+        // Track validation state for error handling
+        let validatedInput = undefined;
+        let validatedBindArgs = undefined;
+        try {
+            // Execute onStart callback before any processing
+            await this._executeOnStartCallback({
+                rawInput,
+                rawBindArgs,
+                prevState,
+                validatedInput: undefined,
+                validatedBindArgs: undefined,
+                actionId,
+            });
+            // Validate input and return on failure
+            const inputValidation = await this._validateInput(rawInput);
+            if (!isOk(inputValidation)) {
+                await this._executeResultCallbacks(inputValidation, {
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    validatedInput,
+                    validatedBindArgs,
+                    actionId,
+                });
+                return this._toActionResult(inputValidation, rawInput);
+            }
+            // Update validation state
+            validatedInput = inputValidation.value;
+            // Validate bound arguments and return on failure
+            const bindArgsValidation = await this._validateBindArgs(rawBindArgs);
+            if (!isOk(bindArgsValidation)) {
+                await this._executeResultCallbacks(bindArgsValidation, {
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    validatedInput,
+                    validatedBindArgs,
+                    actionId,
+                });
+                return this._toActionResult(bindArgsValidation, rawInput);
+            }
+            // Update validation state
+            validatedBindArgs = bindArgsValidation.value;
+            // Execute the user's action handler
+            const handlerResult = await handler({
+                input: inputValidation.value,
+                bindArgs: bindArgsValidation.value,
+                errors: this._buildErrorFunctions(),
+                metadata: {
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    actionId,
+                },
+            });
+            // Return on `undefined` (implicit return error)
+            if (handlerResult === undefined) {
+                const implicitReturnError = createImplicitReturnErrorResult(actionId);
+                await this._executeResultCallbacks(implicitReturnError, {
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    validatedInput,
+                    validatedBindArgs,
+                    actionId,
+                });
+                return this._toActionResult(implicitReturnError, rawInput);
+            }
+            let finalResult;
+            // Process different return types from the action
+            if (isResultErr(handlerResult)) {
+                // Ensure error result has correct action ID
+                finalResult = this._ensureResultActionId(handlerResult);
+            }
+            else {
+                const outputData = isResultOk(handlerResult)
+                    ? handlerResult.value
+                    : handlerResult;
+                finalResult = await this._validateOutput(outputData);
+            }
+            // Execute callbacks and return final result
+            await this._executeResultCallbacks(finalResult, {
+                rawInput,
+                rawBindArgs,
+                prevState,
+                validatedInput,
+                validatedBindArgs,
+                actionId,
+            });
+            // Use validated input for the values field on a successful run
+            const inputForValues = isOk(finalResult)
+                ? this._schemas.inputSchema
+                    ? inputValidation.value
+                    : rawInput
+                : rawInput;
+            return this._toActionResult(finalResult, inputForValues);
+        }
+        catch (error) {
+            // Re-throw Next.js framework errors
+            unstable_rethrow(error);
+            // Handle unexpected thrown errors
+            try {
+                const errorResult = this._handleThrownError(error, handleThrownErrorFn);
+                await this._executeResultCallbacks(errorResult, {
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    validatedInput,
+                    validatedBindArgs,
+                    actionId,
+                });
+                return this._toActionResult(errorResult, rawInput);
+            }
+            catch (handlerError) {
+                // If we catch another error here, then we're done
+                log(this._config.logger, "warn", "Error handling failure - both primary error and error handler threw", { primaryError: error, handlerError });
+                return this._toActionResult(createUnhandledErrorResult(actionId), rawInput);
+            }
+        }
+    }
+    /**
+     * Extracts bind arguments, previous state, and input from raw action arguments.
+     */
+    _extractActionArgs(args) {
+        const numBindSchemas = this._schemas.bindSchemas?.length ?? 0;
+        if (this._config.useActionState) {
+            return {
+                bindArgs: args.slice(0, numBindSchemas),
+                prevState: args[numBindSchemas],
+                input: args[numBindSchemas + 1],
+            };
+        }
+        // For regular actions (non-useActionState), the input is the first argument after bind args
+        // If there are no bind schemas, the input is the first argument (args[0])
+        return {
+            bindArgs: args.slice(0, numBindSchemas),
+            // When useActionState is disabled the prevState parameter is never
+            // present, so we cast to never (or undefined) to satisfy the type.
+            prevState: undefined,
+            input: args[numBindSchemas],
+        };
+    }
+    // --------------------------------------------------------------------------
+    // RESULT TRANSFORMATION
+    // --------------------------------------------------------------------------
+    /**
+     * Transforms internal Result objects to client-facing action result format.
+     */
+    _toActionResult(result, inputForValues) {
+        // Convert internal errors to client-facing errors
+        const clientResult = isOk(result)
+            ? result
+            : err(convertToClientError(result.error), this._actionId);
+        // Handle useActionState format (always returns StatefulApiResult)
+        if (this._config.useActionState) {
+            if (isOk(clientResult)) {
+                const successValues = this._schemas.inputSchema
+                    ? inputForValues
+                    : serializeRawInput(inputForValues);
+                return {
+                    success: true,
+                    data: clientResult.value,
+                    values: successValues,
+                    __ac_id: this._actionId,
+                };
+            }
+            return {
+                success: false,
+                error: clientResult.error,
+                values: serializeRawInput(inputForValues),
+                __ac_id: this._actionId,
+            };
+        }
+        const format = this._config.resultFormat ?? "api";
+        // Return functional format if configured
+        if (format === "functional") {
+            return clientResult;
+        }
+        // Default API format
+        if (isOk(clientResult)) {
+            return {
+                success: true,
+                data: clientResult.value,
+                __ac_id: this._actionId,
+            };
+        }
+        return {
+            success: false,
+            error: clientResult.error,
+            __ac_id: this._actionId,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // ERROR HANDLING
+    // --------------------------------------------------------------------------
+    /**
+     * Handles uncaught exceptions during action execution.
+     */
+    _handleThrownError(error, customHandler) {
+        const caughtErrorResult = customHandler
+            ? customHandler(error)
+            : createUnhandledErrorResult(this._actionId);
+        return caughtErrorResult;
+    }
+    // --------------------------------------------------------------------------
+    // VALIDATION
+    // --------------------------------------------------------------------------
+    /**
+     * Validates input using the shared helper.
+     */
+    _validateInput(rawInput) {
+        return validateInput(this._schemas, this._config, rawInput, this._actionId);
+    }
+    /**
+     * Validates bound arguments using the configured bind schemas.
+     */
+    _validateBindArgs(bindArgs) {
+        return validateBindArgs(this._schemas, this._config, bindArgs, this._actionId);
+    }
+    /**
+     * Validates output data using the configured output schema.
+     */
+    _validateOutput(data) {
+        return validateOutput(this._schemas, this._config, data, this._actionId);
+    }
+    // --------------------------------------------------------------------------
+    // CALLBACKS
+    // --------------------------------------------------------------------------
+    /**
+     * Executes the onStart callback if defined.
+     */
+    async _executeOnStartCallback(metadata) {
+        const callbacks = this._callbacks;
+        if (callbacks.onStart) {
+            await safeExecuteCallback(() => callbacks.onStart({ metadata }), "onStart", (level, msg, details) => log(this._config.logger, level, msg, details));
+        }
+    }
+    /**
+     * Executes result-based lifecycle callbacks (onSuccess, onError, onSettled).
+     */
+    async _executeResultCallbacks(result, metadata) {
+        const callbacks = this._callbacks;
+        // Success path
+        if (isOk(result)) {
+            await safeExecuteCallback(callbacks.onSuccess
+                ? () => callbacks.onSuccess({ data: result.value, metadata })
+                : undefined, "onSuccess", (level, msg, details) => log(this._config.logger, level, msg, details));
+        }
+        // Error path
+        if (isErr(result)) {
+            await safeExecuteCallback(callbacks.onError
+                ? () => callbacks.onError({ error: result.error, metadata })
+                : undefined, "onError", (level, msg, details) => log(this._config.logger, level, msg, details));
+        }
+        // onSettled always runs, regardless of result
+        const finalResult = this._toActionResult(result);
+        await safeExecuteCallback(callbacks.onSettled
+            ? () => callbacks.onSettled({ result: finalResult, metadata })
+            : undefined, "onSettled", (level, msg, details) => log(this._config.logger, level, msg, details));
+    }
+    // --------------------------------------------------------------------------
+    // UTILITY METHODS
+    // --------------------------------------------------------------------------
+    /**
+     * Ensures a Result object has the correct action ID.
+     */
+    _ensureResultActionId(result) {
+        if (!result.__ac_id || result.__ac_id === "unknown") {
+            return {
+                ...result,
+                __ac_id: this._actionId,
+            };
+        }
+        return result;
+    }
+    /**
+     * Creates error functions that return a Result object when called by the action handler.
+     */
+    _buildErrorFunctions() {
+        const errorFns = {};
+        for (const [key, errorDefFn] of Object.entries(this._errors)) {
+            errorFns[key] = ((...args) => err(errorDefFn(...args), this._actionId));
+        }
+        return errorFns;
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/classes/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/classes/executor.ts"],"names":[],"mappings":"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"}

package/dist/classes/internal.d.ts

@@ -0,0 +1,10 @@
+import type { Handler } from "../types/actions.js";
+import type { Config, Schemas, Errors, Callbacks } from "../types/builder.js";
+export declare const INTERNAL: unique symbol;
+export interface CrafterInternals<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TCallbacks extends Callbacks<TConfig, TSchemas, TErrors, TData>, TData> {
+    config: TConfig;
+    schemas: TSchemas;
+    errors: TErrors;
+    callbacks: TCallbacks;
+    handler?: Handler<TConfig, TSchemas, TErrors, TData>;
+}

package/dist/classes/internal.js

@@ -0,0 +1,5 @@
+// ============================================================================
+// INTERNAL INTERFACE FOR CRAFTER-EXECUTOR COMMUNICATION
+// ============================================================================
+export const INTERNAL = Symbol("INTERNAL");
+//# sourceMappingURL=internal.js.map

package/dist/classes/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/classes/internal.ts"],"names":[],"mappings":"AAGA,+EAA+E;AAC/E,wDAAwD;AACxD,+EAA+E;AAE/E,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC"}

package/dist/core/errors.d.ts

@@ -11,11 +11,11 @@ export declare const createInternalLogicError: (message: string) => InternalLogi
 /**
  * Creates Result objects for unhandled errors.
  */
-export declare function createUnhandledErrorResult<TData = never, TError = UnhandledError>(): Result<TData, TError>;
+export declare function createUnhandledErrorResult<TData = never, TError = UnhandledError>(actionId: string): Result<TData, TError>;
 /**
  * Creates Result objects for implicit return errors.
  */
-export declare function createImplicitReturnErrorResult<TData = never, TError = ImplicitReturnError>(): Result<TData, TError>;
+export declare function createImplicitReturnErrorResult<TData = never, TError = ImplicitReturnError>(actionId: string): Result<TData, TError>;
 /**
  * Formats validation issues into structured error objects based on the configured format.
  */

package/dist/core/errors.js

@@ -9,7 +9,7 @@ export const UNHANDLED_ERROR = {
 };
 export const IMPLICIT_RETURN_ERROR = {
     type: INTERNAL_ERROR_TYPES.IMPLICIT_RETURN,
-    message: "Action implementation must return a value",
+    message: "Action handler must return a value",
 };
 // ===========================================================================
 // FACTORY HELPERS
@@ -24,14 +24,14 @@ export const createInternalLogicError = (message) => ({
 /**
  * Creates Result objects for unhandled errors.
  */
-export function createUnhandledErrorResult() {
-    return err({ ...UNHANDLED_ERROR });
+export function createUnhandledErrorResult(actionId) {
+    return err({ ...UNHANDLED_ERROR }, actionId);
 }
 /**
  * Creates Result objects for implicit return errors.
  */
-export function createImplicitReturnErrorResult() {
-    return err({ ...IMPLICIT_RETURN_ERROR });
+export function createImplicitReturnErrorResult(actionId) {
+    return err({ ...IMPLICIT_RETURN_ERROR }, actionId);
 }
 // ===========================================================================
 // VALIDATION-ERROR STRUCTURING HELPERS

package/dist/core/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/logging.d.ts

@@ -1,4 +1,4 @@
-import type { CrafterConfig } from "../types/config.js";
+import type { CrafterConfig } from "../types/crafter.js";
 /**
  * Lightweight wrapper around the optional logger in `CrafterConfig`.
  */

package/dist/core/transformation.d.ts

@@ -1,6 +1,6 @@
 import type { InferSerializedErrorValues } from "../types/actions.js";
-import type { CrafterSchemas } from "../types/config.js";
-import type { CrafterConfig, CrafterErrors } from "../types/config.js";
+import type { CrafterSchemas } from "../types/crafter.js";
+import type { CrafterConfig, CrafterErrors } from "../types/crafter.js";
 import type { PossibleErrors, AllPossibleErrors } from "../types/errors.js";
 import type { InferRawInput, InferValidatedInput } from "../types/schemas.js";
 /**

package/dist/core/validation.d.ts

@@ -1,16 +1,16 @@
-import type { CrafterConfig, CrafterSchemas, CrafterErrors } from "../types/config.js";
+import type { CrafterConfig, CrafterSchemas, CrafterErrors } from "../types/crafter.js";
 import type { AllPossibleErrors } from "../types/errors.js";
 import type { Result } from "../types/result.js";
 import type { InferValidatedInput, InferRawInput, InferValidatedBindArgs, InferRawBindArgs } from "../types/schemas.js";
 /**
  * Validate input using the configured input schema.
  */
-export declare function validateInput<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors>(schemas: TSchemas, config: TConfig, rawInput: InferRawInput<TSchemas> | undefined): Promise<Result<InferValidatedInput<TSchemas>, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
+export declare function validateInput<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors>(schemas: TSchemas, config: TConfig, rawInput: InferRawInput<TSchemas> | undefined, actionId: string): Promise<Result<InferValidatedInput<TSchemas>, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
 /**
  * Validate bound arguments using configured bind schemas.
  */
-export declare function validateBindArgs<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors>(schemas: TSchemas, config: TConfig, bindArgs: InferRawBindArgs<TSchemas>): Promise<Result<InferValidatedBindArgs<TSchemas>, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
+export declare function validateBindArgs<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors>(schemas: TSchemas, config: TConfig, bindArgs: InferRawBindArgs<TSchemas>, actionId: string): Promise<Result<InferValidatedBindArgs<TSchemas>, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
 /**
  * Validate action output using configured output schema.
  */
-export declare function validateOutput<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData>(schemas: TSchemas, config: TConfig, data: TData): Promise<Result<TData, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
+export declare function validateOutput<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData>(schemas: TSchemas, config: TConfig, data: TData, actionId: string): Promise<Result<TData, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;

package/dist/core/validation.js

@@ -5,30 +5,30 @@ import { createValidationError, createInternalLogicError, formatValidationIssues
 /**
  * Validate input using the configured input schema.
  */
-export async function validateInput(schemas, config, rawInput) {
+export async function validateInput(schemas, config, rawInput, actionId) {
     if (!schemas.inputSchema) {
-        return ok(undefined);
+        return ok(undefined, actionId);
     }
     const result = await standardParse(schemas.inputSchema, rawInput);
     if (Array.isArray(result.issues) && result.issues.length > 0) {
         const format = config.validationErrorFormat ?? "flattened";
         const baseError = formatValidationIssues(result.issues, format);
         const inputValidationError = createValidationError(EXTERNAL_ERROR_TYPES.INPUT_VALIDATION, "Input validation failed", baseError);
-        return err(inputValidationError);
+        return err(inputValidationError, actionId);
     }
     if (!result.issues && "value" in result) {
-        return ok(result.value);
+        return ok(result.value, actionId);
     }
     // Should never happen
     const logicErr = createInternalLogicError("Unexpected validation state in input validation: neither success nor failure");
-    return err(logicErr);
+    return err(logicErr, actionId);
 }
 /**
  * Validate bound arguments using configured bind schemas.
  */
-export async function validateBindArgs(schemas, config, bindArgs) {
+export async function validateBindArgs(schemas, config, bindArgs, actionId) {
     if (!schemas.bindSchemas) {
-        return ok([]);
+        return ok([], actionId);
     }
     const validated = [];
     for (let i = 0; i < schemas.bindSchemas.length; i++) {
@@ -39,32 +39,32 @@ export async function validateBindArgs(schemas, config, bindArgs) {
             const format = config.validationErrorFormat ?? "flattened";
             const baseError = formatValidationIssues(result.issues, format);
             const bindError = createValidationError(EXTERNAL_ERROR_TYPES.BIND_ARGS_VALIDATION, "Bind arguments validation failed", baseError);
-            return err(bindError);
+            return err(bindError, actionId);
         }
         if ("value" in result) {
             validated.push(result.value);
         }
     }
-    return ok(validated);
+    return ok(validated, actionId);
 }
 /**
  * Validate action output using configured output schema.
  */
-export async function validateOutput(schemas, config, data) {
+export async function validateOutput(schemas, config, data, actionId) {
     if (!schemas.outputSchema) {
-        return ok(data);
+        return ok(data, actionId);
     }
     const result = await standardParse(schemas.outputSchema, data);
     if (Array.isArray(result.issues) && result.issues.length > 0) {
         const format = config.validationErrorFormat ?? "flattened";
         const baseError = formatValidationIssues(result.issues, format);
         const outputError = createValidationError(INTERNAL_ERROR_TYPES.OUTPUT_VALIDATION, "Output validation failed", baseError);
-        return err(outputError);
+        return err(outputError, actionId);
     }
     if (!result.issues && "value" in result) {
-        return ok(result.value);
+        return ok(result.value, actionId);
     }
     const logicErr = createInternalLogicError("Unexpected validation state in output validation: neither success nor failure");
-    return err(logicErr);
+    return err(logicErr, actionId);
 }
 //# sourceMappingURL=validation.js.map

package/dist/core/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/core/validation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/core/validation.ts"],"names":[],"mappings":"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"}

package/dist/craft.d.ts

@@ -0,0 +1,29 @@
+import { Crafter } from "./classes/crafter.js";
+import type { CraftedAction } from "./types/actions.js";
+import type { CrafterConfig, CrafterSchemas, CrafterErrors, CrafterCallbacks } from "./types/crafter.js";
+/**
+ * Represents the function that the user passes to `craft()` in order to build an action.
+ */
+type CraftFn<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TCallbacks extends CrafterCallbacks<TConfig, TSchemas, TErrors, TData>, TData> = (crafter: Crafter<CrafterConfig, Record<string, never>, Record<string, never>, Record<string, never>, unknown>) => Crafter<TConfig, TSchemas, TErrors, TCallbacks, TData> | Promise<Crafter<TConfig, TSchemas, TErrors, TCallbacks, TData>>;
+/**
+ * One of two entry points to the Actioncraft system.
+ * It provides you with an empty Crafter instance on which you can call any of the fluent
+ * Crafter methods to configure and define your action.
+ *
+ * Example Usage:
+ * ```ts
+ * const myAction = craft(async (action) => {
+ *   return action
+ *     .config(...)
+ *     .schemas(...)
+ *     .errors(...)
+ *     .handler(...)
+ *     .callbacks(...)
+ * });
+ * ```
+ *
+ * @param craftFn - The function that the user passes to `craft()` in order to build an action.
+ * @returns The fully-typed server action function that can be used in your app.
+ */
+export declare function craft<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TCallbacks extends CrafterCallbacks<TConfig, TSchemas, TErrors, TData>, TData>(craftFn: CraftFn<TConfig, TSchemas, TErrors, TCallbacks, TData>): CraftedAction<TConfig, TSchemas, TErrors, TData>;
+export {};