Generate docs

npm run generate-docs

@capibox/bridge-interface

A shared library for DTO (Data Transfer Object) definitions between NestJS (backend) and React/NextJS (frontend) applications.

Installation

npm install @capibox/bridge-interface

Usage

In NestJS (Backend)

import { dto } from '@capibox/bridge-interface';

@Controller('mail')
export class MailController {
  @Post('support')
  async sendMailToSupport(@Body() mailData: dto.SendMailToSupportDto) {
    // Validate the request body against the schema
    const result = dto.sendMailToSupportSchema.safeParse(mailData);
    if (!result.success) {
      throw new BadRequestException(result.error);
    }

    return this.mailService.sendToSupport(mailData);
  }
}

In React/NextJS (Frontend)

import { dto } from '@capibox/bridge-interface';

// Create a type-safe object based on the DTO
const mailData: dto.SendMailToSupportDto = {
  subject: 'Important information about your account',
  htmlPart: '<p>Hello, this is an <strong>important</strong> message.</p>',
  textPart: 'Hello, this is an important message.',
};

// Validate the data with the schema (client-side validation)
const validationResult = dto.sendMailToSupportSchema.safeParse(mailData);
if (!validationResult.success) {
  console.error('Validation error:', validationResult.error);
} else {
  // Use in API calls
  const sendMailToSupport = async (data: dto.SendMailToSupportDto) => {
    const response = await fetch('/api/mail/support', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });
    return response.json();
  };

  sendMailToSupport(mailData);
}

Available DTOs

CAPI

• CapiPayloadDto: DTO for CAPI payload.
• FacebookCapiDtoType: DTO for Facebook CAPI.
• TiktokCapiDtoType: DTO for TikTok CAPI.

CRM Auth

• SignInCrmUserDtoType: DTO for signing in a CRM user.
• SignInCrmResponseDtoType: DTO for the response of a CRM user sign-in.
• VerifyCrmUserDtoType: DTO for verifying a CRM user.
• VerifyCrmResponseDtoType: DTO for the response of a CRM user verification.

Facebook Insights

• CreateFacebookBusinessManagerDto: DTO for creating a new Facebook Business Manager.
• CreateFacebookAdAccountDto: DTO for creating a new Facebook Ad Account.
• FacebookBusinessManagerResponseDto: DTO for the response of a Facebook Business Manager.
• FacebookAdAccountResponseDto: DTO for the response of a Facebook Ad Account.

Funnel

• CreateFunnelDtoType: DTO for creating a new funnel.
• UpdateFunnelDtoType: DTO for updating a funnel.
• CreateFunnelBridgeDtoType: DTO for creating a new funnel bridge.
• CreateFunnelEndpointDtoType: DTO for creating a new funnel endpoint.
• FunnelResponseDtoType: DTO for the response of a funnel.

Integration

• CreateIntegrationDtoType: DTO for creating a new integration.
• UpdateIntegrationDtoType: DTO for updating an integration.
• IntegrationResponseDtoType: DTO for the response of an integration.

Mail

• SendMailToSupportDto: DTO for sending emails to support.
• SendMailToRecipientDto: DTO for sending emails to a specific recipient.
• SendMailResponseDto: DTO for email sending response.

Project

• CreateProjectDtoType: DTO for creating a new project.
• UpdateProjectDtoType: DTO for updating a project.
• ProjectResponseDtoType: DTO for the response of a project.

Session

• AppendSessionDtoType: DTO for appending a session.
• AppendSessionBrowserPublicDtoType: DTO for appending a session from a public browser.
• CreateSessionBridgeDtoType: DTO for creating a session bridge.
• CreateSessionBrowserDtoType: DTO for creating a session from a browser.
• CreateSessionBrowserPublicDtoType: DTO for creating a session from a public browser.
• CreateSessionEndpointDtoType: DTO for creating a session endpoint.
• SessionResponseDtoType: DTO for the response of a session.

Split

• CreateSplitDtoType: DTO for creating a new split.
• UpdateSplitDtoType: DTO for updating a split.
• CreateSplitBridgeDtoType: DTO for creating a new split bridge.
• CreateSplitEndpointDtoType: DTO for creating a new split endpoint.
• SplitResponseDtoType: DTO for the response of a split.

Webhook

• CreateWebhookBridgeDtoType: DTO for creating a new webhook bridge.
• CreateWebhookEndpointDtoType: DTO for creating a new webhook endpoint.
• UpdateWebhookDtoType: DTO for updating a webhook.
• WebhookResponseDtoType: DTO for the response of a webhook.

Schema Validation and Documentation

This library uses zod for schema validation and documentation. Each DTO has a corresponding zod schema that can be used for validation:

• sendMailToSupportSchema: Schema for validating support email data
• sendMailToRecipientSchema: Schema for validating recipient email data
• sendMailResponseSchema: Schema for validating email response data

DTO Documentation

The library includes a script to generate a table of contents for all DTOs. To generate the documentation, run:

npm run generate-docs

This will create a markdown file in the docs/dto directory with a table of contents for all DTOs. The documentation includes:

• A categorized list of all DTOs organized by directory
• Links to the source files for each DTO

The table of contents provides a quick overview of all available DTOs in the library and makes it easy to navigate to their source files.

NestJS Swagger Integration

For NestJS applications that use Swagger for API documentation, the library provides class-based DTOs that can be used with the @nestjs/swagger decorators:

import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
import { dto } from '@capibox/bridge-interface';

@ApiTags('mail')
@Controller('mail')
export class MailController {
  @Post('recipient')
  @ApiOperation({ summary: 'Send email to a recipient' })
  @ApiResponse({
    status: 200,
    description: 'Email sent successfully',
    type: dto.SendMailResponseDto,
  })
  async sendMailToRecipient(@Body() mailData: dto.SendMailToRecipientDto) {
    // Validate with zod schema
    const result = dto.sendMailToRecipientSchema.safeParse(mailData);
    if (!result.success) {
      throw new BadRequestException(result.error);
    }

    return this.mailService.sendToRecipient(mailData);
  }
}

The class-based DTOs have the same properties as their zod schema counterparts, making them compatible for both validation and documentation. They also include Swagger-compatible decorators that match the metadata in the zod schemas, ensuring that descriptions and examples are properly displayed in the Swagger UI.

For example, the SendMailToRecipientDto class includes decorators like:

export class SendMailToRecipientDto {
  @ApiProperty({
    description: 'Email recipient address',
    example: '[email protected]',
    type: String,
  })
  to!: string;

  // ... other properties
}

These decorators are automatically generated from the metadata in the zod schemas, ensuring consistency between validation and documentation.

Utility Functions

The library provides utility functions for creating zod schemas with metadata:

import { utils } from '@capibox/bridge-interface';

// Create a string schema with metadata
const nameSchema = utils.createStringSchema({
  description: 'User name',
  example: 'John Doe',
  required: true,
});

// Create an optional schema
const bioSchema = utils.createOptionalSchema(
  utils.createStringSchema({
    description: 'User biography',
    example: 'Software developer with 5 years of experience',
  })
);

// Create a boolean schema
const activeSchema = utils.createBooleanSchema({
  description: 'User active status',
  example: true,
});

// Add metadata to any zod schema
const customSchema = utils.addMetadata(z.number().min(0).max(100), {
  description: 'Score percentage',
  example: 85,
});

Development

Building the library

npm run build

This will generate CommonJS, ESM, and TypeScript declaration files in the dist directory.