@dv4resi/dvss-backend-module-calendar-im

Calendar Integration Manager module for UIF. This app aggregates and bundles the internal calendar packages into a single publishable npm package that consuming microservices (e.g. dvss-backend-calendar-ms) install.

Table of Contents

• Overview
• What Gets Bundled
• How Consuming Microservices Use This
• Bundling Configuration
• Scripts
• Local Development
• Local Linking with yarn link
• Release Checklist
• Dependencies

Overview

This is the published app for the calendar integration domain. It acts as an aggregator module that:

1. Imports IntegrationLibsModule and IntegrationMicrosoftModule (microsoft already imports IntegrationOauthModule)
2. Registers thin provider handlers and adapter factories (calendar-im does not import oauth directly)
3. Bundles the internal packages into dist/ using tsup so consumers only install this single package

graph TB
    subgraph "UIF Monorepo (Internal)"
        libs["@dvss/dvss-integration-libs"]
        oauth["@dvss/dvss-integration-oauth"]
        microsoft["@dvss/dvss-integration-microsoft"]
    end

    subgraph "This Package"
        calendar["@dv4resi/dvss-backend-module-calendar-im<br/><b>CalendarIntegrationManager</b>"]
    end

    subgraph "Consuming Microservices"
        calms["dvss-backend-calendar-ms"]
    end

    libs -->|bundled into| calendar
    oauth -->|bundled into| calendar
    microsoft -->|bundled into| calendar
    oauth --> microsoft
    calendar -->|"npm install"| calms

What Gets Bundled

At build time, tsup bundles the following internal packages into dist/:

| Internal Package | What It Provides | | ---------------------------------- | --------------------------------------------------------- | | @dvss/dvss-integration-libs | Base classes, DAOs, traffic router, common utilities | | @dvss/dvss-integration-oauth | OAuth2 token lifecycle (OAuth2Provider, grant handlers) | | @dvss/dvss-integration-microsoft | Microsoft Graph calendar capability implementations |

The following are kept external (not bundled) and must be present in the consuming microservice:

• @nestjs/* packages
• @dv4resi/dvss-backend-module-datastore
• @dv4resi/dvss-backend-module-utility
• rxjs, reflect-metadata, class-transformer, class-validator
• drizzle-orm

How Consuming Microservices Use This

Installation

yarn add @dv4resi/dvss-backend-module-calendar-im

Importing CalendarIntegrationManager

The primary export is CalendarIntegrationManager -- a NestJS module that wraps libs, microsoft (and oauth via microsoft), plus calendar adapter factories. Consuming microservices only need this single import:

import { CalendarIntegrationManager } from '@dv4resi/dvss-backend-module-calendar-im';

@Module({
    imports: [
        CalendarIntegrationManager,
        // ... other modules
    ],
})
export class SomeFeatureModule {}

Once imported, adapter factories and Microsoft services are available for injection:

import {
    CalendarAuthAdapterFactory,
    CalendarBookingAdapterFactory,
    MicrosoftAuthService,
    MicrosoftCalendarBookingService,
} from '@dv4resi/dvss-backend-module-calendar-im';

What CalendarIntegrationManager provides under the hood

// apps/dvss-backend-module-calendar-im/src/app.module.ts
@Module({
    imports: [IntegrationLibsModule, IntegrationMicrosoftModule],
    providers: [...microsoftHandlers, ...adapterFactories],
    exports: [IntegrationLibsModule, IntegrationMicrosoftModule, ...microsoftHandlers, ...adapterFactories],
})
export class CalendarIntegrationManager {}

// apps/dvss-backend-module-calendar-im/src/index.ts
export { AppModule as CalendarIntegrationManager } from './app.module';
export { IntegrationLibsModule } from '@dvss/dvss-integration-libs';
export { IntegrationMicrosoftModule } from '@dvss/dvss-integration-microsoft';
export * from '@dvss/dvss-integration-libs';
export * from '@dvss/dvss-integration-microsoft';

Bundling Configuration

The tsup.config.ts handles:

• Internal package resolution - Resolves @dvss/dvss-integration-libs, @dvss/dvss-integration-oauth, and @dvss/dvss-integration-microsoft to their source files and bundles them
• Path resolution - Fixes __dirname references for .env file resolution so it works in both monorepo and installed contexts
• Output format - CommonJS (for NestJS compatibility)
• Type declarations - Generates .d.ts files for TypeScript consumers
• Source maps - Enabled for debugging
• SWC - Used for decorator metadata support
• Tree-shaking - Enabled to remove unused code

Scripts

# Start in dev mode with watch on dependent packages
# Watches: ./src, libs, oauth, microsoft
yarn run start:dev

# Build the package (tsup)
yarn run build

# Watch builds (tsup)
yarn run build:dev

# Build all local dependencies first, then build this package
yarn run build:with-deps

# Tests
yarn run test
yarn run test:watch

Local Development

From the monorepo root:

# Build this app with all its internal deps in order
yarn --cwd apps/dvss-backend-module-calendar-im run build:with-deps

# Watch mode - auto-rebuilds when libs, oauth, or microsoft source files change
yarn --cwd apps/dvss-backend-module-calendar-im run start:dev

The start:dev script uses nodemon to watch source files across:

• ./src (this app)
• ../../packages/dvss-integration-libs/src
• ../../packages/dvss-integration-oauth/src
• ../../packages/dvss-integration-microsoft/src

Any .ts file change in these directories triggers a tsup rebuild.

Local Linking with yarn link

To test local changes in a consuming microservice without publishing:

# 1. Build with deps
yarn --cwd apps/dvss-backend-module-calendar-im run build:with-deps

# 2. Register the link (from the app directory)
cd apps/dvss-backend-module-calendar-im
yarn link

# 3. Use the link in the consuming microservice
cd /path/to/dvss-backend-calendar-ms
yarn link "@dv4resi/dvss-backend-module-calendar-im"

# 4. Unlink when done
yarn unlink "@dv4resi/dvss-backend-module-calendar-im"
yarn install --force

Tip: Run start:dev in the UIF monorepo while linked so changes to libs, oauth, or microsoft automatically rebuild this package, and the consuming microservice picks them up.

Release Checklist

1. Bump the version field in this app's package.json
2. Lint and tests run automatically on commit via Husky
3. Merge to master to trigger the CI lint/build pipeline
4. After the pipeline passes, trigger the publish pipeline from the latest merged commit on master
5. Tag format: dvss-backend-module-calendar-im-vX.Y.Z
   • Version must be exactly the next patch/minor/major from npm (no skipping)
   • The tag prefix must be in the ALLOWED_NPM_PACKAGES allowlist in scripts/validate-tag-and-publish.sh

The package.json version must match the tag version.

Dependencies

Runtime (must be present in consuming microservice):

| Dependency | Purpose | | ------------------------------------------------------------ | ------------------- | | @nestjs/common, @nestjs/core, @nestjs/platform-express | NestJS framework | | rxjs | Reactive extensions | | reflect-metadata | Decorator metadata |

Dev / Bundled (bundled into dist/, not required by consumers):

| Dependency | Purpose | | ---------------------------------- | -------------------------------------------- | | @dvss/dvss-integration-libs | Internal: base classes, DAOs, traffic router | | @dvss/dvss-integration-oauth | Internal: OAuth2 token lifecycle | | @dvss/dvss-integration-microsoft | Internal: Microsoft Graph calendar |