@dv4resi/dvss-backend-module-calendar-im 0.0.3 → 0.0.4

package/README.md

@@ -0,0 +1,247 @@
+# @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](#overview)
+- [What Gets Bundled](#what-gets-bundled)
+- [How Consuming Microservices Use This](#how-consuming-microservices-use-this)
+- [Bundling Configuration](#bundling-configuration)
+- [Scripts](#scripts)
+- [Local Development](#local-development)
+- [Local Linking with yarn link](#local-linking-with-yarn-link)
+- [Release Checklist](#release-checklist)
+- [Dependencies](#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
+
+```mermaid
+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
+
+```bash
+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:
+
+```typescript
+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:
+
+```typescript
+import {
+    CalendarAuthAdapterFactory,
+    CalendarBookingAdapterFactory,
+    MicrosoftAuthService,
+    MicrosoftCalendarBookingService,
+} from '@dv4resi/dvss-backend-module-calendar-im';
+```
+
+### What `CalendarIntegrationManager` provides under the hood
+
+```typescript
+// 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 {}
+```
+
+```typescript
+// 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
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```bash
+# 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           |