TechDocsConnectorsService

Kind: Service

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

TechDocsConnectorsService manages integrations between the platform and external technical documentation providers. It handles connector lifecycle operations, enablement, removal, and both manual and scheduled synchronization of documentation content.

Methods

Dependencies

• PrismaService
• TechDocsSourcesService

Where it refuses work

• TechDocsConnectorsService stops the work with NotFoundException when !c — “Connector not found”, in 3 places.
• TechDocsConnectorsService stops the work with NotFoundException when !project — “Project not found”.
• TechDocsConnectorsService stops the work with BadRequestException when !c.subdomain || !c.email || !c.apiToken — “Zendesk connector needs subdomain, email and apiToken.”.
• TechDocsConnectorsService stops the work with BadRequestException when !c.accessToken — “Intercom connector needs an accessToken.”.
• TechDocsConnectorsService stops the work with BadRequestException when type !== 'ZENDESK' && type !== 'INTERCOM' — “type must be zendesk or intercom.”.
• TechDocsConnectorsService stops the work with an early return when !due.length.

When something fails

• TechDocsConnectorsService handles failure in 1 place: it lets it reach the caller in all 1.

Diagram

mermaid
sequenceDiagram
  participant Client
  participant Service as TechDocsConnectorsService
  participant Connector as Connector Repository
  participant Provider as External Docs Provider

  Client->>Service: create(connectorConfig)
  Service->>Connector: persist connector
  Connector-->>Service: connector
  Service-->>Client: created connector

  Client->>Service: syncNow(connectorId)
  Service->>Connector: load enabled connector
  Connector-->>Service: connector
  Service->>Provider: fetch documentation
  Provider-->>Service: documentation data
  Service->>Connector: store sync state/content
  Service-->>Client: sync result

  Service->>Service: syncDue()
  Service->>Connector: find due enabled connectors
  loop Each connector
    Service->>Service: syncOne(connector)
    Service->>Provider: fetch documentation
  end

Usage

ts
import { TechDocsConnectorsService } from './technical-docs/techdocs-connectors.service';

@Injectable()
export class DocumentationAdminService {
  constructor(
    private readonly techDocsConnectorsService: TechDocsConnectorsService,
  ) {}

  async addAndSyncConnector() {
    const connector = await this.techDocsConnectorsService.create({
      name: 'Engineering Docs',
      provider: 'github',
      enabled: true,
      // Include provider-specific repository, authentication, and sync settings.
    });

    await this.techDocsConnectorsService.syncNow(connector.id);

    return connector;
  }

  async disableConnector(connectorId: string) {
    return this.techDocsConnectorsService.setEnabled(connectorId, false);
  }
}

AI Coding Instructions

• Use create() for new connector configuration and validate provider-specific settings before attempting a sync.
• Prefer syncNow() for user-initiated synchronization; use syncDue() only from scheduled/background job integration points.
• Keep syncOne() focused on synchronizing a single connector and reuse it from both manual and scheduled sync flows.
• Check that a connector is enabled before fetching external documentation, and preserve sync status or errors for observability.
• When removing a connector with remove(), ensure related synced content, credentials, and scheduled-sync state are handled consistently.

Relationships

• DEPENDS_ON → PrismaService
• DEPENDS_ON → TechDocsSourcesService

Referenced By

• TechnicalDocsController (DEPENDS_ON)
• TechnicalDocsModule (MODULE_PROVIDES)