@flusys/nestjs-form-builder 8.0.3 → 8.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @flusys/nestjs-form-builder
 
-Dynamic form management for NestJS — JSON schema storage, schema versioning, access control (PUBLIC / AUTHENTICATED / ACTION_GROUP), draft submissions, and a server-side computed fields engine.
+Dynamic form management for NestJS — JSON schema storage, schema versioning, access control (PUBLIC / AUTHENTICATED / ACTION_GROUP / EMAIL_VERIFIED), draft submissions, and a server-side computed fields engine.
 
 [![npm version](https://img.shields.io/npm/v/@flusys/nestjs-form-builder.svg)](https://www.npmjs.com/package/@flusys/nestjs-form-builder)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -122,7 +122,7 @@ FormBuilderModule.forRootAsync({
 ```
 
 **Exported services** (available for injection after registration):
-`FormService`, `FormResultService`, `FormBuilderConfigService`, `FormBuilderDataSourceProvider`
+`FormService`, `FormResultService`, `FormEmailAuthService`, `FormBuilderConfigService`, `FormBuilderDataSourceProvider`
 
 ---
 
@@ -138,15 +138,56 @@ TypeOrmModule.forRoot({
 });
 ```
 
-| `enableCompanyFeature` | Entities registered             |
-| ---------------------- | ------------------------------- |
-| `false`                | `Form`, `FormResult`            |
-| `true`                 | `FormWithCompany`, `FormResult` |
+| `enableCompanyFeature` | Entities registered                                      |
+| ---------------------- | --------------------------------------------------------- |
+| `false`                | `Form`, `FormResult`, `FormEmailVerification`              |
+| `true`                 | `FormWithCompany`, `FormResult`, `FormEmailVerification` |
 
 The service selects the correct entity automatically at request time — no manual switching needed.
 
 ---
 
+## 3. EMAIL_VERIFIED Access Type
+
+A fourth `FormAccessType`, alongside `PUBLIC`/`AUTHENTICATED`/`ACTION_GROUP`, that lets an anonymous visitor prove ownership of an email via a one-time code before filling out an otherwise-public form. An already-logged-in visitor is auto-identified by their account email and skips the code entirely. The resolved email becomes a real server-side identity (`FormResult.submitterEmail`) that the existing `responseMode` form setting (`single` | `multiple`, in `schema.settings`) is enforced against — `single` blocks a second submission from the same email, `multiple` allows repeats without re-verifying (a 30-day sliding access-token session).
+
+**Wiring an email sender** — like `AUTH_EMAIL_PROVIDER`, this is a Provider Interface: without it, `EMAIL_VERIFIED` forms simply can't send codes.
+
+```typescript
+import { FORM_BUILDER_EMAIL_PROVIDER, type IFormBuilderEmailProvider } from '@flusys/nestjs-form-builder/interfaces';
+import { EmailSendService } from '@flusys/nestjs-email';
+
+const formBuilderEmailProvider: Provider = {
+  provide: FORM_BUILDER_EMAIL_PROVIDER,
+  useFactory: (emailSendService: EmailSendService): IFormBuilderEmailProvider => ({
+    async sendOtpEmail(email, code, formTitle, expiryMinutes) {
+      await emailSendService.sendTemplateEmail({
+        templateSlug: 'form-email-otp',
+        to: email,
+        variables: { code, formTitle, expiryMinutes: String(expiryMinutes) },
+      });
+    },
+  }),
+  inject: [EmailSendService],
+};
+
+FormBuilderModule.forRoot({
+  // ...
+  providers: [formBuilderEmailProvider],
+});
+```
+
+**New endpoints:**
+
+| Endpoint | Guard | Purpose |
+| --- | --- | --- |
+| `POST form-builder/form-email-auth/request-otp` | `@Public()`, throttled 3/5min | Send a 6-digit code to an email for a given `EMAIL_VERIFIED` form |
+| `POST form-builder/form-email-auth/verify-otp` | `@Public()`, throttled 10/min | Verify the code, returns an opaque `accessToken` (30-day sliding expiry) |
+| `POST form-builder/form/email-verified/:id` | `OptionalJwtGuard` | Load the form schema; resolves identity from a JWT if present, else `{ accessToken }` in the body |
+| `POST form-builder/result/submit-public` | `OptionalJwtGuard` | Now also accepts `EMAIL_VERIFIED` forms — pass `{ accessToken }` for anonymous visitors, nothing for JWT-authenticated ones |
+| `POST form-builder/result/has-submitted-email` | `OptionalJwtGuard` | Anonymous-path counterpart to `has-submitted`, resolving identity the same way |
+
+---
 
 ## License
 

package/config/message-keys.d.ts

@@ -7,6 +7,14 @@ export declare const FORM_MESSAGES: {
     readonly PERMISSION_CHECK_FAILED: "form.permission.check.failed";
     readonly GET_SUCCESS: "form.get.success";
     readonly GET_ACCESS_INFO_SUCCESS: "form.get.access.info.success";
+    readonly EMAIL_NOT_CONFIGURED: "form.email.not.configured";
+    readonly EMAIL_VERIFICATION_REQUIRED: "form.email.verification.required";
+    readonly OTP_SENT: "form.email.otp.sent";
+    readonly OTP_SEND_FAILED: "form.email.otp.send.failed";
+    readonly OTP_INVALID: "form.email.otp.invalid";
+    readonly OTP_EXPIRED: "form.email.otp.expired";
+    readonly OTP_TOO_MANY_ATTEMPTS: "form.email.otp.too.many.attempts";
+    readonly OTP_VERIFIED: "form.email.otp.verified";
 };
 export declare const FORM_RESULT_MESSAGES: {
     readonly GET_ALL_SUCCESS: "form.result.get.all.success";
@@ -16,4 +24,5 @@ export declare const FORM_RESULT_MESSAGES: {
     readonly SUBMIT_SUCCESS: "form.result.submit.success";
     readonly DRAFT_GET_SUCCESS: "form.result.draft.get.success";
     readonly DRAFT_UPDATE_SUCCESS: "form.result.draft.update.success";
+    readonly ALREADY_SUBMITTED: "form.result.already.submitted";
 };

package/controllers/form-email-auth.controller.d.ts

@@ -0,0 +1,11 @@
+import { MessageResponseDto, SingleResponseDto } from '@flusys/nestjs-shared/dtos';
+import { RequestFormEmailOtpDto, VerifyFormEmailOtpDto, VerifyOtpResponseDto } from '../dtos/index.js';
+import { FormEmailAuthService } from '../services/form-email-auth.service.js';
+import { FormService } from '../services/form.service.js';
+export declare class FormEmailAuthController {
+    private readonly formEmailAuthService;
+    private readonly formService;
+    constructor(formEmailAuthService: FormEmailAuthService, formService: FormService);
+    requestOtp(dto: RequestFormEmailOtpDto): Promise<MessageResponseDto>;
+    verifyOtp(dto: VerifyFormEmailOtpDto): Promise<SingleResponseDto<VerifyOtpResponseDto>>;
+}

package/controllers/form-result.controller.d.ts

@@ -1,6 +1,7 @@
 import { ListResponseDto, SingleResponseDto } from '@flusys/nestjs-shared/dtos';
 import { type ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
-import { CreateFormResultDto, FormResultResponseDto, GetMyDraftDto, GetResultsByFormDto, SubmitFormDto, UpdateDraftDto, UpdateFormResultDto } from '../dtos/index.js';
+import { CreateFormResultDto, FormResultResponseDto, GetMyDraftDto, GetResultsByFormDto, HasSubmittedEmailDto, SubmitFormDto, UpdateDraftDto, UpdateFormResultDto } from '../dtos/index.js';
+import { FormEmailAuthService } from '../services/form-email-auth.service.js';
 import { FormResultService } from '../services/form-result.service.js';
 declare const FormResultController_base: abstract new (service: FormResultService) => {
     readonly enabledEndpoints: import("@flusys/nestjs-shared").ApiEndpoint[] | "all";
@@ -19,12 +20,14 @@ declare const FormResultController_base: abstract new (service: FormResultServic
 };
 export declare class FormResultController extends FormResultController_base {
     formResultService: FormResultService;
-    constructor(formResultService: FormResultService);
+    private readonly formEmailAuthService;
+    constructor(formResultService: FormResultService, formEmailAuthService: FormEmailAuthService);
     submitForm(dto: SubmitFormDto, user: ILoggedUserInfo): Promise<SingleResponseDto<FormResultResponseDto>>;
-    submitPublicForm(dto: SubmitFormDto): Promise<SingleResponseDto<FormResultResponseDto>>;
+    submitPublicForm(dto: SubmitFormDto, user: ILoggedUserInfo | undefined): Promise<SingleResponseDto<FormResultResponseDto>>;
     getMyDraft(dto: GetMyDraftDto, user: ILoggedUserInfo): Promise<SingleResponseDto<FormResultResponseDto | null>>;
     updateDraft(dto: UpdateDraftDto, user: ILoggedUserInfo): Promise<SingleResponseDto<FormResultResponseDto>>;
     getByFormId(dto: GetResultsByFormDto, user: ILoggedUserInfo): Promise<ListResponseDto<FormResultResponseDto>>;
     hasUserSubmitted(dto: GetMyDraftDto, user: ILoggedUserInfo): Promise<SingleResponseDto<boolean>>;
+    hasSubmittedEmail(dto: HasSubmittedEmailDto, user: ILoggedUserInfo | undefined): Promise<SingleResponseDto<boolean>>;
 }
 export {};

package/controllers/form.controller.d.ts

@@ -1,6 +1,7 @@
 import { SingleResponseDto } from '@flusys/nestjs-shared/dtos';
 import { type ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
-import { CreateFormDto, FormAccessInfoResponseDto, FormResponseDto, PublicFormResponseDto, UpdateFormDto } from '../dtos/index.js';
+import { CreateFormDto, EmailVerifiedFormResponseDto, FormAccessInfoResponseDto, FormResponseDto, LoadEmailVerifiedFormDto, PublicFormResponseDto, UpdateFormDto } from '../dtos/index.js';
+import { FormEmailAuthService } from '../services/form-email-auth.service.js';
 import { FormService } from '../services/form.service.js';
 declare const FormController_base: abstract new (service: FormService) => {
     readonly enabledEndpoints: import("@flusys/nestjs-shared").ApiEndpoint[] | "all";
@@ -19,10 +20,12 @@ declare const FormController_base: abstract new (service: FormService) => {
 };
 export declare class FormController extends FormController_base {
     formService: FormService;
-    constructor(formService: FormService);
+    private readonly formEmailAuthService;
+    constructor(formService: FormService, formEmailAuthService: FormEmailAuthService);
     getFormAccessInfo(id: string): Promise<SingleResponseDto<FormAccessInfoResponseDto>>;
     getPublicForm(id: string): Promise<SingleResponseDto<PublicFormResponseDto>>;
     getAuthenticatedForm(id: string, user: ILoggedUserInfo): Promise<SingleResponseDto<PublicFormResponseDto>>;
+    getEmailVerifiedForm(id: string, dto: LoadEmailVerifiedFormDto, user: ILoggedUserInfo | undefined): Promise<SingleResponseDto<EmailVerifiedFormResponseDto>>;
     getBySlug(slug: string, _user: ILoggedUserInfo): Promise<SingleResponseDto<FormResponseDto | null>>;
     getPublicFormBySlug(slug: string): Promise<SingleResponseDto<PublicFormResponseDto | null>>;
 }

package/controllers/index.d.ts

@@ -1,2 +1,3 @@
 export * from './form.controller.js';
 export * from './form-result.controller.js';
+export * from './form-email-auth.controller.js';

package/dtos/form-email-auth.dto.d.ts

@@ -0,0 +1,20 @@
+export declare class RequestFormEmailOtpDto {
+    formId: string;
+    email: string;
+}
+export declare class VerifyFormEmailOtpDto {
+    formId: string;
+    email: string;
+    code: string;
+}
+export declare class VerifyOtpResponseDto {
+    accessToken: string;
+    expiresAt: Date;
+}
+export declare class LoadEmailVerifiedFormDto {
+    accessToken?: string;
+}
+export declare class HasSubmittedEmailDto {
+    formId: string;
+    accessToken?: string;
+}

package/dtos/form-result.dto.d.ts

@@ -3,6 +3,7 @@ export declare class SubmitFormDto {
     formId: string;
     data: Record<string, unknown>;
     isDraft?: boolean;
+    accessToken?: string;
 }
 export declare class CreateFormResultDto extends SubmitFormDto {
     schemaVersionSnapshot?: Record<string, unknown>;
@@ -30,6 +31,7 @@ export declare class FormResultResponseDto extends IdentityResponseDto {
     schemaVersion: number;
     data: Record<string, unknown>;
     submittedById: string | null;
+    submitterEmail: string | null;
     submittedAt: Date;
     isDraft: boolean;
 }

package/dtos/form.dto.d.ts

@@ -34,4 +34,7 @@ export declare class PublicFormResponseDto extends PublicFormResponseDto_base {
 declare const FormAccessInfoResponseDto_base: import("@nestjs/common").Type<Pick<FormResponseDto, "description" | "name" | "accessType" | "actionGroups" | "isActive" | "id">>;
 export declare class FormAccessInfoResponseDto extends FormAccessInfoResponseDto_base {
 }
+export declare class EmailVerifiedFormResponseDto extends PublicFormResponseDto {
+    verifiedEmail: string;
+}
 export {};

package/dtos/index.d.ts

@@ -1,2 +1,3 @@
 export * from './form.dto.js';
 export * from './form-result.dto.js';
+export * from './form-email-auth.dto.js';

package/entities/form-email-verification.entity.d.ts

@@ -0,0 +1,11 @@
+import { Identity } from '@flusys/nestjs-shared';
+export declare class FormEmailVerification extends Identity {
+    formId: string;
+    email: string;
+    otpHash: string | null;
+    otpExpiresAt: Date | null;
+    otpAttempts: number;
+    verifiedAt: Date | null;
+    accessTokenHash: string | null;
+    accessTokenExpiresAt: Date | null;
+}

package/entities/form-result.entity.d.ts

@@ -5,6 +5,7 @@ export declare class FormResult extends Identity {
     schemaVersion: number;
     data: Record<string, unknown>;
     submittedById: string | null;
+    submitterEmail: string | null;
     submittedAt: Date;
     isDraft: boolean;
 }

package/entities/index.d.ts

@@ -1,10 +1,12 @@
 export * from './form.entity.js';
 export * from './form-result.entity.js';
+export * from './form-email-verification.entity.js';
 export * from './form-with-company.entity.js';
+import { FormEmailVerification } from './form-email-verification.entity.js';
 import { Form } from './form.entity.js';
 import { FormResult } from './form-result.entity.js';
 import { FormWithCompany } from './form-with-company.entity.js';
-export declare const FormCoreEntities: (typeof Form | typeof FormResult)[];
-export declare const FormCompanyEntities: (typeof FormResult | typeof FormWithCompany)[];
+export declare const FormCoreEntities: (typeof Form | typeof FormResult | typeof FormEmailVerification)[];
+export declare const FormCompanyEntities: (typeof FormResult | typeof FormEmailVerification | typeof FormWithCompany)[];
 export declare function getFormBuilderEntitiesByConfig(enableCompanyFeature: boolean): any[];
 export { Form as FormBase } from './form.entity.js';

package/enums/form-access-type.enum.d.ts

@@ -1,5 +1,6 @@
 export declare enum FormAccessType {
     PUBLIC = "public",
     AUTHENTICATED = "authenticated",
-    ACTION_GROUP = "action_group"
+    ACTION_GROUP = "action_group",
+    EMAIL_VERIFIED = "email_verified"
 }