feat: Add captcha

Author: aXenDeveloper

apps/docs/content/docs/dev/captcha.mdx

@@ -0,0 +1,276 @@
+---
+title: Captcha
+description: Protect your forms and API call with captcha validation.
+---
+
+## Usage
+
+In this example, we will show you how to use captcha in your forms. We will use the `AutoForm` component to render the form and handle the captcha validation.
+
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+
+<Steps>
+<Step>
+
+### Activate captcha in route
+
+Add `withCaptcha` to your route config to enable captcha validation for this route.
+
+```ts title="plugins/{plugin_name}/src/routes/example.ts"
+import { buildRoute } from '@vitnode/core/api/lib/route';
+
+export const exampleRoute = buildRoute({
+  ...CONFIG_PLUGIN,
+  route: {
+    method: 'post',
+    description: 'Create a new user',
+    path: '/sign_up',
+    withCaptcha: true, // [!code ++]
+  },
+  handler: async c => {},
+});
+```
+
+</Step>
+<Step>
+
+### Get config from middleware API
+
+Get captcha config from middleware API in your view and pass it to your `'use client';` component.
+
+```tsx title="plugins/{plugin_name}/src/app/sing_up/page.tsx"
+import { getMiddlewareApi } from '@vitnode/core/lib/api/get-middleware-api'; // [!code ++]
+
+export const SignUpView = async () => {
+  const { captcha } = await getMiddlewareApi(); // [!code ++]
+
+  return <FormSignUp captcha={captcha} />;
+};
+```
+
+</Step>
+<Step>
+
+### Use in form
+
+Get the `captcha` config from the props and pass it to the `AutoForm` component. This will render the captcha widget in your form.
+
+```tsx title="plugins/{plugin_name}/src/components/form/sign-up/sign-up.tsx"
+'use client';
+
+import { AutoForm } from '@vitnode/core/components/form/auto-form';
+
+export const FormSignUp = ({
+  captcha, // [!code ++]
+}: {
+  captcha: z.infer<typeof routeMiddlewareSchema>['captcha']; // [!code ++]
+}) => {
+  return (
+    <AutoForm<typeof formSchema>
+      captcha={captcha} // [!code ++]
+      fields={[]}
+      formSchema={formSchema}
+    />
+  );
+};
+```
+
+<Card
+  title="AutoForm"
+  description="Lear more about the AutoForm component and how to use it."
+  href="/docs/ui/auto-form"
+/>
+
+</Step>
+<Step>
+
+### Submit form with captcha
+
+In your form submission handler, you can get the `captchaToken` from the form submission context and pass it to your mutation API.
+
+```tsx title="plugins/{plugin_name}/src/components/form/sign-up/sign-up.tsx"
+'use client';
+
+import {
+  AutoForm,
+  type AutoFormOnSubmit, // [!code ++]
+} from '@vitnode/core/components/form/auto-form';
+
+export const FormSignUp = ({
+  captcha,
+}: {
+  captcha: z.infer<typeof routeMiddlewareSchema>['captcha'];
+}) => {
+  const onSubmit: AutoFormOnSubmit<typeof formSchema> = async (
+    values,
+    form,
+    { captchaToken }, // [!code ++]
+  ) => {
+    // Call your mutation API with captcha token
+    await mutationApi({
+      ...values,
+      captchaToken, // [!code ++]
+    });
+
+    // Handle success or error
+  };
+
+  return (
+    <AutoForm<typeof formSchema>
+      captcha={captcha}
+      fields={[]}
+      onSubmit={onSubmit} // [!code ++]
+      formSchema={formSchema}
+    />
+  );
+};
+```
+
+Next, you need to set `captchaToken` in your mutation API call. This token is provided by the `AutoForm` component when the form is submitted.
+
+```tsx title="plugins/{plugin_name}/src/components/form/sign-up/mutation-api.ts"
+'use server';
+
+import type { z } from 'zod';
+
+import { fetcher } from '@vitnode/core/lib/fetcher';
+
+export const mutationApi = async ({
+  captchaToken, // [!code ++]
+  ...input
+  // [!code ++]
+}: z.infer<typeof zodSignUpSchema> & { captchaToken }) => {
+  const res = await fetcher(usersModule, {
+    path: '/sign_up',
+    method: 'post',
+    module: 'users',
+    captchaToken, // [!code ++]
+    args: {
+      body: input,
+    },
+  });
+
+  if (res.status !== 201) {
+    return { error: await res.text() };
+  }
+
+  const data = await res.json();
+
+  return { data };
+};
+```
+
+</Step>
+</Steps>
+
+## Custom Usage
+
+If you want to use captcha in your custom form or somewhere else, follow these steps.
+
+<Steps>
+<Step>
+
+### Activate captcha in route
+
+```ts title="plugins/{plugin_name}/src/routes/example.ts"
+import { buildRoute } from '@vitnode/core/api/lib/route';
+
+export const exampleRoute = buildRoute({
+  ...CONFIG_PLUGIN,
+  route: {
+    method: 'post',
+    description: 'Create a new user',
+    path: '/sign_up',
+    withCaptcha: true, // [!code ++]
+  },
+  handler: async c => {},
+});
+```
+
+</Step>
+<Step>
+
+### Get config from middleware API
+
+```tsx title="plugins/{plugin_name}/src/app/sing_up/page.tsx"
+import { getMiddlewareApi } from '@vitnode/core/lib/api/get-middleware-api'; // [!code ++]
+
+export const SignUpView = async () => {
+  const { captcha } = await getMiddlewareApi(); // [!code ++]
+
+  return <FormSignUp captcha={captcha} />;
+};
+```
+
+</Step>
+<Step>
+
+### Use `useCaptcha` hook
+
+Inside your client component, use the `useCaptcha` hook to handle captcha rendering and validation. Remember to add `div` with `id="vitnode_captcha"` where you want the captcha widget to appear.
+
+```tsx title="plugins/{plugin_name}/src/components/form/sign-up/sign-up.tsx"
+'use client';
+
+import { AutoForm } from '@vitnode/core/components/form/auto-form';
+
+export const FormSignUp = ({
+  captcha, // [!code ++]
+}: {
+  captcha: z.infer<typeof routeMiddlewareSchema>['captcha']; // [!code ++]
+}) => {
+  // [!code ++]
+  const { isReady, token, onReset } = useCaptcha(captcha);
+
+  const onSubmit = async () => {
+    await mutationApi({
+      // ...other values,
+      captchaToken: token, // [!code ++]
+    });
+
+    // Handle success or error
+    // [!code ++]
+    onReset(); // Reset captcha after submission
+  };
+
+  return (
+    <form onSubmit={onSubmit}>
+      {/* Render captcha widget */}
+      {/* [!code ++] */}
+      <div id="vitnode_captcha" />
+
+      <Button disabled={!isReady}>Submit</Button>
+    </form>
+  );
+};
+```
+
+</Step>
+<Step>
+
+### Submit form with captcha
+
+```tsx title="plugins/{plugin_name}/src/components/form/sign-up/mutation-api.ts"
+'use server';
+
+import type { z } from 'zod';
+
+import { fetcher } from '@vitnode/core/lib/fetcher';
+
+export const mutationApi = async ({
+  captchaToken, // [!code ++]
+}: {
+  // [!code ++]
+  captchaToken;
+}) => {
+  await fetcher(usersModule, {
+    path: '/test',
+    method: 'post',
+    module: 'blog',
+    captchaToken, // [!code ++]
+  });
+};
+```
+
+</Step>
+</Steps>

apps/docs/content/docs/dev/index.mdx

@@ -27,3 +27,7 @@ npx create-vitnode-app@canary
 ```
 
 </Tabs>
+
+## Why VitNode?
+
+something here

apps/docs/content/docs/dev/meta.json

@@ -21,6 +21,7 @@
     "---Framework---",
     "config",
     "logging",
+    "captcha",
     "---Advanced---",
     "..."
   ]

apps/docs/content/docs/ui/auto-form.mdx

@@ -131,11 +131,12 @@ The `onSubmit` callback provides access to the React Hook Form instance as a sec
 
 You can also define the submission handler separately:
 
+```ts
+import type { AutoFormOnSubmit } from '@vitnode/core/components/form/auto-form';
+```
+
 ```tsx
-const onSubmit = async (
-  values: z.infer<typeof formSchema>,
-  form: UseFormReturn<z.infer<typeof formSchema>>,
-) => {
+const onSubmit: AutoFormOnSubmit<typeof formSchema> = async (values, form) => {
   try {
     await saveData(values);
     toast.success('Form submitted successfully');

apps/web/src/vitnode.api.config.ts

@@ -17,6 +17,11 @@ export const POSTGRES_URL =
   process.env.POSTGRES_URL || 'postgresql://root:root@localhost:5432/vitnode';
 
 export const vitNodeApiConfig = buildApiConfig({
+  captcha: {
+    type: 'cloudflare_turnstile',
+    siteKey: process.env.CLOUDFLARE_TURNSTILE_SITE_KEY,
+    secretKey: process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY,
+  },
   plugins: [blogApiPlugin()],
   dbProvider: drizzle({
     connection: POSTGRES_URL,

packages/vitnode/src/api/config.ts

@@ -65,6 +65,7 @@ export function VitNodeAPI({
       metadata: vitNodeConfig.metadata,
       authorization: vitNodeApiConfig.authorization,
       dbProvider: vitNodeApiConfig.dbProvider,
+      captcha: vitNodeApiConfig.captcha,
     }),
   );
   app.use(async (c, next) => {

packages/vitnode/src/api/lib/route.ts

@@ -2,6 +2,7 @@ import type { RouteConfig, RouteHandler } from '@hono/zod-openapi';
 
 import { createRoute as createRouteHono } from '@hono/zod-openapi';
 
+import { captchaMiddleware } from '../middlewares/captcha.middleware';
 import {
   type EnvVitNode,
   pluginMiddleware,
@@ -21,6 +22,7 @@ export const buildRoute = <
   P extends string,
   R extends Omit<RouteConfig, 'path'> & {
     path: P;
+    withCaptcha?: boolean;
   },
   H extends ValidHandler<R & { path: P }>,
 >({
@@ -50,6 +52,7 @@ export const buildRoute = <
       tags,
       middleware: [
         pluginMiddleware(pluginId),
+        ...(route.withCaptcha ? [captchaMiddleware()] : []),
         ...(Array.isArray(route.middleware)
           ? route.middleware
           : route.middleware