next-action-handler 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# next-action-handler
+
+Install a ready-to-use `next-safe-action` handler setup into your Next.js project.
+
+## Usage
+
+Run the installer from the root of your project:
+
+```bash
+npx next-action-handler@latest add
+```
+
+Using `@latest` makes `npx` fetch the newest published version from npm.
+The command installs the full handler setup at once, with no component selection.
+
+## What gets installed
+
+The CLI copies the TypeScript source files into your project while preserving the folder structure:
+
+```text
+lib/next-action-handler/
+```
+
+Install path detection uses this order:
+
+1. If `lib/` exists, files are installed to `lib/next-action-handler/`.
+2. If `app/lib/` exists, files are installed to `app/lib/next-action-handler/`.
+3. Otherwise, `lib/next-action-handler/` is created at the project root.
+
+If a file already exists, the CLI prompts you to overwrite or skip it. In non-interactive environments, existing files are skipped.
+
+## Dependencies
+
+The CLI reads your project's `package.json`, detects missing packages, and installs only the packages you do not already have.
+
+Required packages:
+
+- `better-auth`
+- `next-safe-action`
+- `pino`
+- `pino-pretty`
+- `server-only`
+- `zod`
+
+The package manager is detected from lockfiles:
+
+- `bun.lockb` or `bun.lock` -> `bun add`
+- `pnpm-lock.yaml` -> `pnpm add`
+- `yarn.lock` -> `yarn add`
+- `package-lock.json` or `npm-shrinkwrap.json` -> `npm install`
+- no lockfile -> `npm install`
+
+## Auth helper requirement
+
+`safe-action.ts` preserves this import:
+
+```ts
+import { requireUser } from "../auth-helpers";
+```
+
+Your project must provide a `requireUser` export at the matching location:
+
+- `lib/auth-helpers.ts` when installed to `lib/next-action-handler/`
+- `app/lib/auth-helpers.ts` when installed to `app/lib/next-action-handler/`
+
+`requireUser` should return the authenticated user or throw when the request is not authenticated.

package/cli/index.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const childProcess = require("child_process");
+
+const REQUIRED_PACKAGES = [
+  "better-auth",
+  "next-safe-action",
+  "pino",
+  "pino-pretty",
+  "server-only",
+  "zod",
+];
+
+const USAGE = "Usage: npx next-action-handler@latest add";
+
+function main() {
+  const command = process.argv[2];
+
+  if (command !== "add") {
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  const projectRoot = process.cwd();
+  const sourceRoot = path.resolve(__dirname, "..", "src");
+
+  console.log("next-action-handler installer");
+
+  if (!fs.existsSync(sourceRoot)) {
+    fail("Could not find the bundled src/ directory.");
+  }
+
+  const installRoot = resolveInstallRoot(projectRoot);
+  console.log("Installing to " + path.relative(projectRoot, installRoot));
+
+  copySourceFiles(sourceRoot, installRoot);
+  installMissingDependencies(projectRoot);
+
+  console.log("");
+  console.log("Success! next-action-handler installed at " + path.relative(projectRoot, installRoot));
+}
+
+function resolveInstallRoot(projectRoot) {
+  const rootLib = path.join(projectRoot, "lib");
+  const appLib = path.join(projectRoot, "app", "lib");
+
+  if (isDirectory(rootLib)) {
+    return path.join(rootLib, "next-action-handler");
+  }
+
+  if (isDirectory(appLib)) {
+    return path.join(appLib, "next-action-handler");
+  }
+
+  return path.join(rootLib, "next-action-handler");
+}
+
+function copySourceFiles(sourceRoot, installRoot) {
+  const files = collectFiles(sourceRoot);
+
+  fs.mkdirSync(installRoot, { recursive: true });
+
+  for (const sourceFile of files) {
+    const relativePath = path.relative(sourceRoot, sourceFile);
+    const targetFile = path.join(installRoot, relativePath);
+
+    if (fs.existsSync(targetFile) && !shouldOverwrite(relativePath)) {
+      console.log("Skipped " + relativePath);
+      continue;
+    }
+
+    fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+    fs.copyFileSync(sourceFile, targetFile);
+    console.log("✅ " + relativePath);
+  }
+}
+
+function collectFiles(directory) {
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push.apply(files, collectFiles(fullPath));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files.sort();
+}
+
+function shouldOverwrite(relativePath) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return false;
+  }
+
+  while (true) {
+    const answer = prompt(relativePath + " already exists. Overwrite or skip? [o/s] ");
+    const normalized = answer.trim().toLowerCase();
+
+    if (
+      normalized === "o" ||
+      normalized === "overwrite" ||
+      normalized === "y" ||
+      normalized === "yes"
+    ) {
+      return true;
+    }
+
+    if (
+      normalized === "" ||
+      normalized === "s" ||
+      normalized === "skip" ||
+      normalized === "n" ||
+      normalized === "no"
+    ) {
+      return false;
+    }
+
+    console.log("Please type overwrite or skip.");
+  }
+}
+
+function prompt(question) {
+  const buffer = Buffer.alloc(1024);
+
+  fs.writeSync(1, question);
+
+  try {
+    const bytesRead = fs.readSync(0, buffer, 0, buffer.length, null);
+    return buffer.toString("utf8", 0, bytesRead);
+  } catch (error) {
+    return "";
+  }
+}
+
+function installMissingDependencies(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, "package.json");
+
+  if (!fs.existsSync(packageJsonPath)) {
+    fail("Could not find package.json in " + projectRoot + ". Run this command from your project root.");
+  }
+
+  const packageJson = readPackageJson(packageJsonPath);
+  const missingPackages = REQUIRED_PACKAGES.filter(function (packageName) {
+    return !hasPackage(packageJson, packageName);
+  });
+
+  if (missingPackages.length === 0) {
+    console.log("All dependencies are already installed.");
+    return;
+  }
+
+  const packageManager = detectPackageManager(projectRoot);
+  const installCommand = getInstallCommand(packageManager, missingPackages);
+
+  console.log("Installing missing dependencies: " + missingPackages.join(", "));
+  console.log("Running " + packageManager + " " + installCommand.join(" "));
+
+  const result = childProcess.spawnSync(packageManager, installCommand, {
+    cwd: projectRoot,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+
+  if (result.error) {
+    fail("Failed to run " + packageManager + ": " + result.error.message);
+  }
+
+  if (result.status !== 0) {
+    fail(packageManager + " exited with status " + result.status + ".");
+  }
+}
+
+function readPackageJson(packageJsonPath) {
+  try {
+    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  } catch (error) {
+    fail("Could not read " + packageJsonPath + ": " + error.message);
+  }
+}
+
+function hasPackage(packageJson, packageName) {
+  return Boolean(
+    (packageJson.dependencies && packageJson.dependencies[packageName]) ||
+      (packageJson.devDependencies && packageJson.devDependencies[packageName]) ||
+      (packageJson.peerDependencies && packageJson.peerDependencies[packageName]) ||
+      (packageJson.optionalDependencies && packageJson.optionalDependencies[packageName])
+  );
+}
+
+function detectPackageManager(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, "bun.lockb")) || fs.existsSync(path.join(projectRoot, "bun.lock"))) {
+    return "bun";
+  }
+
+  if (fs.existsSync(path.join(projectRoot, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+
+  if (fs.existsSync(path.join(projectRoot, "yarn.lock"))) {
+    return "yarn";
+  }
+
+  return "npm";
+}
+
+function getInstallCommand(packageManager, packages) {
+  if (packageManager === "npm") {
+    return ["install"].concat(packages);
+  }
+
+  return ["add"].concat(packages);
+}
+
+function isDirectory(filePath) {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch (error) {
+    return false;
+  }
+}
+
+function fail(message) {
+  console.error("Error: " + message);
+  process.exit(1);
+}
+
+main();

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "next-action-handler",
+  "version": "1.0.0",
+  "description": "CLI installer for next-action-handler TypeScript source files.",
+  "bin": {
+    "next-action-handler": "./cli/index.js"
+  },
+  "files": [
+    "cli/",
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "node --check cli/index.js"
+  },
+  "keywords": [
+    "next",
+    "server-actions",
+    "next-safe-action",
+    "cli"
+  ],
+  "license": "MIT"
+}

package/src/error/better-auth-error.ts

@@ -0,0 +1,57 @@
+import { isAPIError } from "better-auth/api";
+
+import {
+  BadRequestError,
+  InternalServerError,
+  UnauthorizedError,
+  type ActionError,
+} from "./errors";
+
+type BetterAuthApiError = {
+  message?: string;
+  statusCode?: number;
+};
+
+type BetterAuthErrorOptions = {
+  enumerationSafe?: boolean;
+  genericMessage?: string;
+};
+
+export function fromBetterAuthError(
+  error: unknown,
+  options: BetterAuthErrorOptions = {},
+): ActionError {
+  if (!isAPIError(error)) {
+    return new InternalServerError(
+      options.genericMessage ?? "Something went wrong",
+      error,
+    );
+  }
+
+  const apiError = error as BetterAuthApiError;
+
+  const message = options.enumerationSafe
+    ? (options.genericMessage ?? "Invalid credentials")
+    : (apiError.message ?? "Something went wrong");
+
+  switch (apiError.statusCode) {
+    case 400:
+      return new BadRequestError(message, error);
+
+    case 401:
+      return new UnauthorizedError(message, error);
+
+    default:
+      return new InternalServerError(message, error);
+  }
+}
+
+// use for catch better auth error
+
+// throw fromBetterAuthError(
+//     error,
+//     {
+//       enumerationSafe: true,
+//       genericMessage: "Invalid credentials",
+//     },
+//   );

package/src/error/database-error.ts

@@ -0,0 +1,8 @@
+import { DatabaseError } from "./errors";
+
+export function toDatabaseError(
+  error: unknown,
+  message = "Database operation failed",
+): DatabaseError {
+  return new DatabaseError(message, error);
+}

package/src/error/errors.ts

@@ -0,0 +1,136 @@
+export const ERROR_CODES = [
+  "BAD_REQUEST",
+  "VALIDATION_ERROR",
+
+  "UNAUTHORIZED",
+  "FORBIDDEN",
+
+  "NOT_FOUND",
+
+  "RATE_LIMITED",
+
+  "DATABASE_ERROR",
+  "INTERNAL_SERVER_ERROR",
+] as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+export class ActionError extends Error {
+  public readonly code: ErrorCode;
+  public readonly expose: boolean;
+  public readonly cause?: unknown;
+
+  constructor({
+    message,
+    code,
+    expose = true,
+    cause,
+  }: {
+    message: string;
+    code: ErrorCode;
+    expose?: boolean;
+    cause?: unknown;
+  }) {
+    super(message);
+
+    this.name = new.target.name;
+
+    this.code = code;
+    this.expose = expose;
+    this.cause = cause;
+
+    Object.setPrototypeOf(this, new.target.prototype);
+
+    Error.captureStackTrace?.(this, new.target);
+  }
+}
+
+export class BadRequestError extends ActionError {
+  constructor(message = "Bad request", cause?: unknown) {
+    super({
+      message,
+      code: "BAD_REQUEST",
+      cause,
+    });
+  }
+}
+
+export class ValidationError extends ActionError {
+  public readonly fields?: Record<string, string[]>;
+
+  constructor(
+    message = "Invalid input",
+    fields?: Record<string, string[]>,
+    cause?: unknown,
+  ) {
+    super({
+      message,
+      code: "VALIDATION_ERROR",
+      cause,
+    });
+
+    this.fields = fields;
+  }
+}
+
+export class UnauthorizedError extends ActionError {
+  constructor(message = "Unauthorized", cause?: unknown) {
+    super({
+      message,
+      code: "UNAUTHORIZED",
+      cause,
+    });
+  }
+}
+
+export class ForbiddenError extends ActionError {
+  constructor(message = "Forbidden", cause?: unknown) {
+    super({
+      message,
+      code: "FORBIDDEN",
+      cause,
+    });
+  }
+}
+
+export class NotFoundError extends ActionError {
+  constructor(message = "Resource not found", cause?: unknown) {
+    super({
+      message,
+      code: "NOT_FOUND",
+      cause,
+    });
+  }
+}
+
+export class RateLimitError extends ActionError {
+  constructor(message = "Too many requests", cause?: unknown) {
+    super({
+      message,
+      code: "RATE_LIMITED",
+      cause,
+    });
+  }
+}
+
+export class DatabaseError extends ActionError {
+  constructor(message = "Database operation failed", cause?: unknown) {
+    super({
+      message,
+      code: "DATABASE_ERROR",
+      expose: false,
+      cause,
+    });
+  }
+}
+
+export class InternalServerError extends ActionError {
+  constructor(message = "Something went wrong", cause?: unknown) {
+    super({
+      message,
+      code: "INTERNAL_SERVER_ERROR",
+      expose: false,
+      cause,
+    });
+  }
+}

package/src/error/normalize-error.ts

@@ -0,0 +1,28 @@
+import { ActionError, InternalServerError } from "./errors";
+
+import type { NormalizedError } from "../types";
+
+export function normalizeError(error: unknown): NormalizedError {
+  if (error instanceof ActionError) {
+    return {
+      code: error.code,
+      message: error.message,
+      expose: error.expose,
+
+      cause: error.cause,
+      stack: error.stack,
+    };
+  }
+
+  const internalError = new InternalServerError("Something went wrong", error);
+  const unknownCause = error instanceof Error ? error : undefined;
+
+  return {
+    code: internalError.code,
+    message: internalError.message,
+    expose: internalError.expose,
+
+    cause: unknownCause,
+    stack: unknownCause?.stack,
+  };
+}

package/src/log/logger-config.ts

@@ -0,0 +1,29 @@
+import pino from "pino";
+import type { ErrorCode } from "../error/errors";
+
+export const ERROR_LOG_LEVEL: Record<ErrorCode, "warn" | "error"> = {
+  BAD_REQUEST: "warn",
+  VALIDATION_ERROR: "warn",
+  UNAUTHORIZED: "warn",
+  FORBIDDEN: "warn",
+  NOT_FOUND: "warn",
+  RATE_LIMITED: "warn",
+
+  DATABASE_ERROR: "error",
+  INTERNAL_SERVER_ERROR: "error",
+};
+
+export const logger = pino(
+  process.env.NODE_ENV === "development"
+    ? {
+        transport: {
+          target: "pino-pretty",
+          options: {
+            colorize: true,
+            translateTime: "SYS:yyyy-mm-dd HH:MM:ss",
+            ignore: "pid,hostname",
+          },
+        },
+      }
+    : {}
+);

package/src/log/logger.ts

@@ -0,0 +1,119 @@
+import { ERROR_LOG_LEVEL, logger } from "./logger-config";
+import { ActionError } from "../error/errors";
+import type { NormalizedError } from "../types";
+
+type BaseLogOptions = {
+  action: string;
+};
+
+type LogMeta = Record<string, unknown>;
+
+type ActionLogMessageOptions = BaseLogOptions & {
+  message: string;
+  meta?: LogMeta;
+};
+
+type ActionExecutionLogOptions = BaseLogOptions & {
+  durationMs: number;
+  message?: string;
+  meta?: LogMeta;
+};
+
+type ActionErrorLogOptions = BaseLogOptions & {
+  error: NormalizedError;
+};
+
+function buildCauseMeta(
+  cause: NormalizedError["cause"],
+  isDevelopment: boolean,
+) {
+  if (cause instanceof Error) {
+    const isSafeCauseMessage =
+      cause instanceof ActionError ? cause.expose : false;
+
+    return {
+      name: cause.name,
+      message: isDevelopment || isSafeCauseMessage ? cause.message : undefined,
+      stack: isDevelopment ? cause.stack : undefined,
+    };
+  }
+
+  if (isDevelopment) {
+    return cause;
+  }
+
+  return undefined;
+}
+
+export function logWarn({ action, message, meta }: ActionLogMessageOptions) {
+  logger.warn(
+    {
+      action,
+      ...meta,
+    },
+    message,
+  );
+}
+
+export function logError({ action, message, meta }: ActionLogMessageOptions) {
+  logger.error(
+    {
+      action,
+      ...meta,
+    },
+    message,
+  );
+}
+
+export function logInfo({
+  action,
+  message,
+  durationMs,
+  meta,
+}: ActionExecutionLogOptions) {
+  logger.info(
+    {
+      action,
+      durationMs,
+      ...meta,
+    },
+    message,
+  );
+}
+
+export function logActionExecution({
+  action,
+  durationMs,
+  message = "Action executed successfully",
+  meta,
+}: ActionExecutionLogOptions) {
+  logInfo({
+    action,
+    durationMs,
+    message,
+    meta,
+  });
+}
+
+export function logActionError({ action, error }: ActionErrorLogOptions) {
+  const level = ERROR_LOG_LEVEL[error.code];
+  const isDevelopment = process.env.NODE_ENV === "development";
+
+  const logMeta = {
+    errorCode: error.code,
+    stack: isDevelopment ? error.stack : undefined,
+    cause: buildCauseMeta(error.cause, isDevelopment),
+  };
+
+  const payload = {
+    action,
+    ...logMeta,
+  };
+
+  if (level === "error") {
+    logger.error(payload, error.message);
+    return;
+  }
+
+  logger.warn(payload, error.message);
+}

package/src/safe-action.ts

@@ -0,0 +1,55 @@
+import "server-only";
+
+import z from "zod";
+
+import {
+  createSafeActionClient,
+  DEFAULT_SERVER_ERROR_MESSAGE,
+} from "next-safe-action";
+
+import { logActionError, logActionExecution } from "./log/logger";
+
+import { normalizeError } from "./error/normalize-error";
+import { requireUser } from "../auth-helpers";
+
+export const actionClient = createSafeActionClient({
+  defineMetadataSchema: () =>
+    z.object({
+      actionName: z.string(),
+    }),
+
+  handleServerError(error, ctx) {
+    const normalized = normalizeError(error);
+
+    logActionError({
+      action: ctx.metadata.actionName,
+      error: normalized,
+    });
+
+    return {
+      code: normalized.code,
+
+      message: normalized.expose
+        ? normalized.message
+        : DEFAULT_SERVER_ERROR_MESSAGE,
+    };
+  },
+}).use(async ({ next, metadata }) => {
+  const startedAt = Date.now();
+
+  const result = await next();
+
+  if (!result.serverError) {
+    logActionExecution({
+      action: metadata.actionName,
+      durationMs: Date.now() - startedAt,
+    });
+  }
+
+  return result;
+});
+
+export const authedActionClient = actionClient.use(async ({ next }) => {
+  const user = await requireUser();
+  return next({ ctx: { user } });
+});

package/src/types.ts

@@ -0,0 +1,14 @@
+import type { ErrorCode } from "./error/errors";
+
+export type PublicServerError = {
+  code: ErrorCode;
+  message: string;
+};
+
+export type NormalizedError = {
+  code: ErrorCode;
+  message: string;
+  expose: boolean;
+  cause?: unknown;
+  stack?: string;
+};