TechDocsNotionExportService

Kind: Service

Source: atloria-monorepo/apps/api/src/technical-docs/techdocs-notion-export.service.ts

TechDocsNotionExportService is a NestJS backend service responsible for exporting technical documentation content to Notion. It coordinates the transformation and delivery of generated TechDocs data to the configured Notion workspace, acting as the integration boundary between the technical documentation module and Notion APIs.

Methods

Dependencies

• PrismaService
• TechnicalDocsMaterializerService

Where it refuses work

• TechDocsNotionExportService stops the work with NotFoundException when !member — “Project not found”.
• TechDocsNotionExportService stops the work with BadRequestException when !pages.length.
• TechDocsNotionExportService stops the work with BadRequestException when !integrationToken || !parentPageId — “integrationToken and parentPageId are required (or pass dryRun: true).”.
• TechDocsNotionExportService stops the work with BadRequestException when !container.ok.
• TechDocsNotionExportService stops the work with an early return when dto?.dryRun.
• TechDocsNotionExportService stops the work with an early return when !res.ok.

When something fails

• TechDocsNotionExportService handles failure in 2 places: it turns it into a return value in all 2.

Diagram

mermaid
sequenceDiagram
  participant Client as API Controller / Job
  participant ExportService as TechDocsNotionExportService
  participant TechDocs as Technical Docs Source
  participant Notion as Notion API

  Client->>ExportService: exportToNotion()
  ExportService->>TechDocs: Load documentation content
  TechDocs-->>ExportService: Documentation data
  ExportService->>ExportService: Transform content for Notion blocks
  ExportService->>Notion: Create or update Notion pages
  Notion-->>ExportService: Export result
  ExportService-->>Client: Return export status/result

Usage

ts
import { Injectable } from '@nestjs/common';
import { TechDocsNotionExportService } from './techdocs-notion-export.service';

@Injectable()
export class TechDocsExportJob {
  constructor(
    private readonly notionExportService: TechDocsNotionExportService,
  ) {}

  async run() {
    const result = await this.notionExportService.exportToNotion();

    return {
      success: true,
      result,
    };
  }
}

AI Coding Instructions

• Inject TechDocsNotionExportService through NestJS dependency injection; do not instantiate it directly with new.
• Keep Notion-specific API calls and block/page transformation logic inside this service or dedicated Notion client helpers.
• Ensure exported documentation is validated and normalized before creating Notion blocks, especially for headings, code blocks, and nested content.
• Handle Notion API failures, rate limits, and partial exports explicitly so callers receive actionable error information.
• Preserve idempotency where possible by updating existing Notion pages instead of creating duplicate pages on repeated exports.

Relationships

• DEPENDS_ON → PrismaService
• DEPENDS_ON → TechnicalDocsMaterializerService

Referenced By

• TechnicalDocsController (DEPENDS_ON)
• TechnicalDocsModule (MODULE_PROVIDES)