PSA/ee/docs/plans/2026-06-01-teams-online-meetings-interactions/SCRATCHPAD.md

SCRATCHPAD — Teams Online Meetings → Interactions

Working memory for this plan. Append decisions, discoveries, gotchas, and commands.

Source of truth

• Long-form design: .ai/teams-meetings-interactions-consolidated-plan.md (incorporates two external review rounds).
• This plan folder lives in ee/docs/plans/ (per project convention) even though some artifacts are core — most of the meaningful logic (capture, subscriptions, Graph) is EE.

Key decisions (with rationale)

• Calendar-backed creation (POST /users/{upn}/events, isOnlineMeeting:true) instead of standalone POST /onlineMeetings. Reason: Graph recordings/transcripts APIs only work reliably for calendar-backed meetings. Cost: new Calendars.ReadWrite app permission + onlineMeeting-id resolution from joinUrl + invite-behavior decision.
• Provider-agnostic "Online Meeting" interaction type (icon video), NOT "Teams Meeting" — the online_meetings.provider column allows future zoom/google_meet.
• One table, two creation paths. Appointment approval and MSP-initiated both write online_meetings
  • an interaction; differ only by appointment_request_id vs schedule_entry_id. No backfill.
• Storage: transcript → durable internal document; recording → internal proxy/download (Graph content URLs are auth-protected, not clickable), with opt-in blob download. Artifacts are a collection → online_meeting_artifacts child table (NOT singular columns).
• Single service-account organizer in v1; per-user organizer + co-organizer roles deferred.
• Retrieval: manual "Refresh recordings" (Phase 1) ships first; change-notification subscriptions (Phase 2) follow (encrypted resource data + protected/metered API approval).

Must-fix items confirmed by review (do not regress) → mapped features

1. Scope Calendars.ReadWrite to the organizer mailbox via Exchange Application Access Policy / RBAC (Teams policy does NOT scope calendar). → F051, F052, T075.
2. Update/delete use provider_event_id for new rows; legacy online_meeting_id handling preserved. → F027, T038, T039.
3. Invite behavior locked: appointment approval = no external attendees; MSP-initiated = attendees allowed. → F018, T025, T026.
4. No "co-organizer" claim unless a real Graph meeting-options step is added (deferred). → F018 (attendee only), §9 deferred.
5. All Graph create/update/delete OUTSIDE DB transactions, with create→DB-fail compensation. → F028, F029, T040, T041.

Discoveries about existing code (verified)

• approveAppointmentRequest wraps work in withTransaction; existing if (createdMeeting) block ~appointmentRequestManagementActions.ts:790-793; writes online_meeting_* columns.
• Reschedule updateAppointmentRequestDateTime calls updateTeamsMeeting inside withTransaction (~:1321) — MUST move out (F028). Cancel/delete paths (scheduleActions.ts:732, client-portal appointmentRequestActions.ts:1337) already call Graph outside the tx.
• Facade CreateTeamsMeetingResult returns only {joinWebUrl, meetingId} (teamsMeetingService.ts), EE same (createTeamsMeeting.ts:107). Must add organizer UPN + AAD id + eventId (F020).
• InteractionModel.addInteraction/getById open their own createTenantKnex connection (interactions.ts:225), so the action's withTransaction does NOT cover the model insert today — latent bug fixed by F012. Defaulting/resolution/events/revalidate live in the ACTION (interactionActions.ts:~86-150) — must be replicated in the shared helper (F013).
• uploadDocument is withAuth + FormData (documentActions.ts:2642) — unusable from a job; need an internal helper (F038). Internal users inherit folder is_client_visible (documentActions.ts:2764) — set false explicitly.
• system_interaction_types modification trigger was REMOVED by server/migrations/20250613000000_remove_system_interaction_types_trigger.cjs — no workaround needed.
• Meeting (icon users) already seeded by 20241223015715_create_system_interaction_types.cjs; we add a separate Online Meeting (icon video).
• ScheduleEntry.create stores work_item_id for non-ad_hoc (scheduleEntry.ts:407) → set to interaction id (F033).
• Calendar mapping uses entry.notes as description in BOTH server/src/utils/calendar/eventMapping.ts:82 and packages/integrations/src/utils/calendar/eventMapping.ts:80 (F036).
• EE calendar sync (ee/packages/calendar/) auto-pushes schedule_entries to the user's connected calendar via calendarSyncSubscriber — partially compensates for the service-account-organizer model (meeting still shows on the creating user's own calendar). Possible Phase-2 reuse: CalendarWebhookProcessor.ts for the encrypted subscription machinery.
• scheduleRecurringJob exists (server/src/lib/jobs/jobScheduler.ts + index.ts); there is already a MicrosoftWebhookRenewalJobData recurring job to mirror for Phase 2 (F055).
• microsoft_profiles are tenant-level service accounts; users has no AAD columns → no per-user organizer today.

Open questions

• Exact hasPermission resource/action for scheduleTeamsMeeting (verify repo catalog) — F031.
• Should MSP-initiated default to adding the contact as an attendee, or leave optional in the UI?

Phasing for the implementation loop

• Phase A (data + model): F001–F013.
• Phase B (creation, both paths): F016–F036.
• Phase C (capture Phase 1 + UI): F037–F052.
• Phase D (gating): F053.
• Phase E (Phase 2 subscriptions): F054–F057. Recommend the /loop pick the lowest-id implemented:false feature whose deps are met, implement + test, flip implemented:true, repeat.

Commands / runbooks

• Validate plan JSON: python3 ~/.claude/skills/software-planner/scripts/validate_plan.py <folder> (if present).
• Tests: npm run test:unit (unit), npm run test:integration.
• Migrations: npm run migrate.

2026-06-01 — F034-F036 / T049-T051

• Implemented QuickAddInteraction Online Meeting scheduling without adding a clients -> scheduling package dependency: added optional Teams callbacks to ClientCrossFeatureContext, supplied them in MspClientCrossFeatureProvider, and had QuickAdd call scheduleTeamsMeeting only when the Online Meeting type is selected and getTeamsMeetingCapability reports available. Rationale: keeps clients package reusable while MSP composition owns cross-feature wiring.
• Implemented direct schedule-entry Teams generation by having EntryPopup add a generate_teams_meeting save payload for new entries and ScheduleCalendar route that payload to scheduleTeamsMeeting({ createScheduleEntry: true }). Constraint: the backend requires client/contact context, so the UI requires a selected client-backed work item and shows a translated validation message otherwise.
• Tightened scheduleTeamsMeeting notes behavior: stored interaction/schedule notes now append Join Teams Meeting: <url> even when caller-supplied notes exist.
• Updated both calendar mappers (server/src/utils/calendar/eventMapping.ts and packages/integrations/src/utils/calendar/eventMapping.ts) to append the join URL from online_meetings by schedule_entry_id as a fallback/field mapping for external calendar pushes.
• Added source-contract tests for QuickAdd Teams wiring, EntryPopup/ScheduleCalendar routing, and both eventMapping copies.
• Verification:
  • npm -w @alga-psa/clients run typecheck
  • npm -w @alga-psa/scheduling run typecheck
  • npm -w @alga-psa/integrations run typecheck
  • npx vitest run ../packages/clients/src/components/interactions/QuickAddInteraction.quick-add-contact.contract.test.ts ../packages/scheduling/src/components/schedule/EntryPopup.teams-meeting.contract.test.ts src/test/unit/calendar/eventMapping.onlineMeetingDescription.contract.test.ts src/test/integration/appointmentRequests.integration.test.ts -t "Schedule Teams Meeting|quick add|EntryPopup offers|online meeting calendar" from server/
  • packages/msp-composition has no package typecheck script or tsconfig; composition compile coverage is indirect through package consumers.

2026-06-01 — F015, F037-F041 / T052-T062

• Implemented Phase-1 artifact capture in packages/clients/src/lib/onlineMeetingArtifactCapture.ts. Package-boundary decision: put the handler next to OnlineMeetingModel and dynamically load the EE Teams module instead of importing scheduling from clients, because scheduling already depends on clients and a static clients -> scheduling import would create a cycle.
• fetchAndPersistMeetingArtifacts is session-agnostic and takes explicit tenantId, meetingId, and optional actorUserId. It resolves the meeting, skips cancelled rows, calls EE fetchMeetingArtifacts, upserts recording/transcript artifacts idempotently, updates bounded fetch status (recording_ready, recording_pending, no_recording, failed), and revalidates interaction
  • linked client/contact paths.
• Transcript storage uses an internal document helper, not uploadDocument: inserts documents, document_block_content, and document_associations directly inside a transaction with explicit tenant/user metadata. Client/contact associations are resolved from the linked interaction because online_meetings intentionally stores interaction_id, not duplicate client/contact columns.
• Recording capture stores content_url by default. When download_recordings is enabled, it resolves the EE Teams Graph config, fetches an app token, downloads the Graph content URL server-side, stores the blob with StorageService.uploadFile, and sets file_id.
• refreshMeetingRecordings(meetingId) was added to packages/clients/src/actions/onlineMeetingActions.ts under withAuth, passing the authenticated user id to the shared handler.
• Exported meetings/meetingConfig from @alga-psa/ee-microsoft-teams/lib so the recording download helper can reuse the existing Graph config resolver.
• Verification:
  • npm -w @alga-psa/clients run typecheck
  • npm -w @alga-psa/scheduling run typecheck
  • npm -w @alga-psa/ee-microsoft-teams run typecheck
  • npx vitest run ../packages/clients/src/lib/onlineMeetingArtifactCapture.test.ts from server/

2026-06-01 — F042 / T063-T065

• Added internal recording proxy route: server/src/app/api/online-meetings/recordings/[artifactId]/route.ts.
• Security shape: requires getCurrentUser, uses the authenticated user's tenant to create the DB context, looks up online_meeting_artifacts joined to online_meetings by (tenant, meeting_id), and returns 404 for cross-tenant artifact ids because the query is tenant-scoped.
• Proxy behavior: fetches the raw Graph content_url server-side with the EE Teams Graph config + app token, forwards Range when present, streams graphResponse.body with content headers, and never redirects or serializes the raw Graph URL to the caller.
• Portal guard: ?portal=true is denied unless teams_integrations.expose_recordings_in_portal is true; missing column/table defaults to false until F048 lands.
• Verification:
  • npx vitest run src/test/unit/onlineMeetingRecordingProxy.contract.test.ts from server/
  • npm -w @alga-psa/ee-microsoft-teams run typecheck

2026-06-01 implementation notes

• Implemented F012/F013:
  • InteractionModel.addInteraction and getById now accept an optional Knex/transaction and use it for both the insert and follow-up read; the default path still uses createTenantKnex(tenantId).
  • Added packages/clients/src/actions/interactionCreateHelper.ts as the shared interaction creation path. It centralizes user/client/contact validation, default interaction status resolution, contact -> client resolution, INTERACTION_LOGGED, INTERACTION_CREATED, and cache revalidation.
  • addInteraction now uses the helper inside its transaction but defers the helper-provided side effects until after withTransaction returns, preserving post-commit event/revalidate behavior.
  • getInteractionById now passes its active transaction into InteractionModel.getById.
• Implemented T017-T022 with focused unit tests:
  • packages/clients/src/models/interactions.transaction.test.ts covers trx-backed insertion and no-trx back-compat.
  • packages/clients/src/actions/interactionCreateHelper.test.ts covers default status, contact-client resolution/failure, event publishing, and revalidation.
• Verification:
  • npx vitest run ../packages/clients/src/models/interactions.transaction.test.ts ../packages/clients/src/actions/interactionCreateHelper.test.ts from server/ passed 6 tests.
  • npm -w @alga-psa/clients run typecheck passed.
• Implemented F014:
  • Added packages/clients/src/actions/onlineMeetingActions.ts with getOnlineMeetingForInteraction under withAuth, delegating to OnlineMeetingModel.getByInteractionId(interactionId, tenant).
  • Exported the action from packages/clients/src/actions/index.ts.
  • Corrected T037's description: it was assigned to F014 but described cancelled refresh/list-pending behavior already covered by T014; it now describes the F014 action contract.
  • Added packages/clients/src/actions/onlineMeetingActions.test.ts covering tenant-scoped lookup, absent rows, and missing id validation.
• Implemented F016-F022:
  • createTeamsMeeting now creates calendar-backed Graph events through POST /users/{organizerUpn}/events with isOnlineMeeting: true and onlineMeetingProvider: teamsForBusiness.
  • It resolves the onlineMeeting.id from the event join URL via a URL-encoded JoinWebUrl filter, then returns joinWebUrl, meetingId, organizerUpn, organizerUserId, and eventId.
  • organizerUserId is read from teams_integrations.default_meeting_organizer_object_id when present; until F048 migration/UI lands, the config falls back to organizer UPN to preserve existing tenants/tests.
  • Appointment approval keeps the default no-attendee payload; MSP-created meetings can pass attendees explicitly.
  • updateTeamsMeeting/deleteTeamsMeeting now call /events/{eventId} (falling back to meetingId only for temporary compatibility until F027 legacy branching is implemented).
  • Added EE fetchMeetingArtifacts and facade fetchMeetingArtifacts no-op off enterprise. The EE implementation fetches recordings/transcripts collections, downloads transcript content with Accept: text/vtt, and URL-encodes organizer/meeting/artifact path segments.
  • T028's online_meetings persistence portion will become concrete in F023/F032 when creation paths write the returned facade fields into online_meetings; current coverage verifies the facade returns the fields required for persistence.
• Verification:
  • npx vitest run src/test/unit/teamsMeetingHelpers.test.ts from server/ passed 23 tests.
  • npm -w @alga-psa/scheduling run typecheck passed.
  • npm -w @alga-psa/ee-microsoft-teams run typecheck passed.

2026-06-01 implementation notes

• Completed F001-F006 in server/migrations/20260601120000_create_online_meetings.cjs: added CE/core online_meetings and online_meeting_artifacts with tenant-first PKs, PRD status/artifact type checks, provider-meeting uniqueness, tenant-leading lookup indexes, Citus transaction:false distribution on tenant, and artifact colocation with online_meetings. Chose no SQL FKs in these tables to match the PRD's Citus/application-level integrity constraint.
• Completed F007 in server/migrations/20260601120100_add_online_meeting_interaction_type.cjs: added an idempotent insert-only Online Meeting system interaction type with video icon, following the existing add_general_interaction_type guard style.
• Completed T001-T007/T009-T010 in server/src/test/unit/migrations/onlineMeetingsMigration.test.ts: tests execute the migration against mocked Knex raw calls for plain Postgres and Citus paths, assert tenant-first keys, enum checks, uniqueness/index contracts, child-table colocation, rollback order, and idempotent interaction-type insertion. T008 intentionally remains open because it covers the later OnlineMeetingModel.upsertArtifact helper, not just the unique constraint.
• Verification: npx vitest run src/test/unit/migrations/onlineMeetingsMigration.test.ts from server/ passed (8 tests). An earlier npm -w server run test:unit -- ... accidentally ran the entire unit suite due to the package script prepending src/test/unit; it was terminated after unrelated existing failures and should not be treated as signal for this batch.
• Completed F008-F009/T011 in packages/types/src/interfaces/online-meeting.interfaces.ts and packages/types/src/interfaces/interaction.interfaces.ts: added IOnlineMeetingArtifact, IOnlineMeeting, status/artifact/provider type aliases, artifacts[], and optional IInteraction.online_meeting. Exported via packages/types/src/interfaces/index.ts and added @alga-psa/types smoke imports to packages/types/src/exports.typecheck.test.ts.
• Verification: npm -w @alga-psa/types test -- src/exports.typecheck.test.ts src/interfaces/barrel.test.ts passed (2 tests).
• Completed F010-F011/T008/T012-T016 in packages/clients/src/models/onlineMeeting.ts: added session-agnostic OnlineMeetingModel using createTenantKnex, tenant guard, create/get/update/provider and interaction/appointment lookups with artifacts, pending-recording listing for ended eligible statuses, idempotent artifact upsert on (tenant, meeting_id, artifact_type, provider_artifact_id), and newest-first artifact listing. Exported from packages/clients/src/models/index.ts.
• Verification: npx vitest run ../packages/clients/src/models/onlineMeeting.test.ts from server/ passed (6 tests); npm -w @alga-psa/clients run typecheck passed.
• Completed F023-F024 in packages/scheduling/src/actions/appointmentRequestManagementActions.ts: approval now uses the shared interaction helper to create an Online Meeting interaction and inserts a linked online_meetings row when Teams creation succeeds. The row stores the Graph calendar event id, organizer UPN/object id, join URL, schedule entry id, appointment request id, interaction id, and scheduled status. The legacy appointment_requests.online_meeting_* columns remain populated for existing email/portal consumers.
• Package wiring: @alga-psa/scheduling now depends on @alga-psa/clients, and @alga-psa/clients exposes the narrow ./actions/interactionCreateHelper subpath used by scheduling. @alga-psa/licensing exports were pointed at src to make Vite resolve the workspace package in the appointment integration test environment.
• Completed T032-T034 in server/src/test/integration/appointmentRequests.integration.test.ts: the Teams approval test now asserts the interaction and online_meetings row, the capability-unavailable path asserts no row is written, and the legacy appointment request columns remain asserted. The fixture now tolerates current schemas where service_types.billing_method has been removed and seeds the staff user needed by the new interaction FK.
• Verification:
  • npx vitest run src/test/integration/appointmentRequests.integration.test.ts -t "creates and stores a Teams meeting|capability is unavailable|creation fails" from server/ passed (3 tests, 38 skipped).
  • npm -w @alga-psa/scheduling run typecheck passed.
  • A full npx vitest run src/test/integration/appointmentRequests.integration.test.ts run was attempted before the fixture compatibility fix and failed on the pre-existing service_types.billing_method fixture/schema mismatch across many unrelated tests; targeted coverage now passes.
• Completed F025-F027:
  • updateAppointmentRequestDateTime now syncs linked online_meetings start/end fields and the generated interaction's date/start/end/duration, then calls updateTeamsMeeting after the DB transaction with provider_event_id for modern rows. Legacy appointment-only meetings pass eventId: null and keep the standalone-compatible fallback path.
  • Decline, MSP schedule deletion, and client-portal cancellation now mark linked online_meetings rows as cancelled, which keeps them out of later capture/polling flows.
  • Delete paths prefer online_meetings.provider_meeting_id + provider_event_id; legacy rows without provider_event_id still pass the appointment request's existing online_meeting_id.
  • F028/F029 intentionally remain open: reschedule update is now outside the transaction, but approval Graph create/DB compensation has not been reworked yet.
• Completed T035-T036/T038-T039 in server/src/test/integration/appointmentRequests.integration.test.ts: reschedule asserts event-id updates plus local meeting/interaction time sync, legacy reschedule asserts eventId: null, and decline/cancel/delete tests assert online_meetings.status='cancelled'.
• Verification:
  • npm -w @alga-psa/scheduling run typecheck passed.
  • npm -w @alga-psa/client-portal run typecheck passed.
  • npx vitest run src/test/integration/appointmentRequests.integration.test.ts -t "should update status correctly when declined|reschedules the linked Teams meeting|reschedules a legacy Teams meeting|deletes the linked Teams meeting" from server/ passed (5 tests, 37 skipped).
  • The focused integration run still logs pre-existing non-fatal warnings in decline event publishing (requestedDate Date vs string) and client cancellation notifications (contact_id binding).
• Completed F028-F029:
  • Appointment approval now performs a read/validation preflight, calls createTeamsMeeting outside the write transaction, then consumes the prepared Graph result inside the DB transaction.
  • If the post-create DB transaction fails, the action calls deleteTeamsMeeting with the created meetingId and eventId, leaving the appointment pending and without local meeting rows/links.
  • Existing update/delete paths are now covered by source-level transaction-discipline guards: reschedule updates happen after the DB transaction returns, and schedule deletion calls Teams after the appointment cleanup transaction returns.
• Completed T040-T041:
  • Added server/src/test/unit/scheduling/appointmentRequestTeamsTransaction.test.ts to guard that create/update/delete Graph calls are outside transaction bodies.
  • Added an approval integration test that hides the Online Meeting interaction type after Graph create, forcing the DB transaction to fail and asserting the orphan Teams event is deleted.
  • Moved the requester-timezone conversion fixture from 2026-04-25 to 2026-08-25; the old date is now in the past relative to the 2026-06-02 runtime clock and fails request creation before approval.
• Verification:
  • npm -w @alga-psa/scheduling run typecheck passed.
  • npx vitest run src/test/unit/scheduling/appointmentRequestTeamsTransaction.test.ts from server/ passed (3 tests).
  • npx vitest run src/test/integration/appointmentRequests.integration.test.ts -t "creates and stores a Teams meeting|deletes the orphaned Teams event|capability is unavailable|creation fails|converts requester-local approval times" from server/ passed (5 tests, 38 skipped).
  • Gotcha: do not run two server Vitest commands with coverage in parallel; one parallel attempt hit a coverage/.tmp/coverage-0.json race even though the targeted assertions had passed.
• Completed F030/T042:
  • Confirmed the rollout remains no-backfill: a legacy approved appointment with existing appointment_requests.online_meeting_* values keeps those links, but no online_meetings row and no Online Meeting timeline interaction are created just because the new schema exists.
  • Added the coverage to server/src/test/integration/appointmentRequests.integration.test.ts.
• Verification:
  • npx vitest run src/test/integration/appointmentRequests.integration.test.ts -t "does not backfill legacy approved Teams appointment links" from server/ passed (1 test, 43 skipped).
• Completed F031-F033:
  • Added packages/scheduling/src/actions/onlineMeetingSchedulingActions.ts and exported scheduleTeamsMeeting from @alga-psa/scheduling/actions.
  • The action is withAuth and explicitly requires user_schedule:update (confirmed as the local schedule-create/update permission already used by schedule actions).
  • Teams Graph create happens before the DB write transaction; if the local transaction fails, the created calendar-backed Teams event is deleted via the facade using both meetingId and eventId.
  • The DB transaction creates the shared Online Meeting interaction, inserts the online_meetings row with organizer UPN/object id and event id, and optionally creates a schedule_entries row with work_item_type='interaction' and work_item_id=<interaction_id>, linked from online_meetings.schedule_entry_id.
  • MSP-created meetings pass through provided attendees to the facade; appointment approval remains separate and still sends no attendees.
• Completed T043-T048 in server/src/test/integration/appointmentRequests.integration.test.ts:
  • Happy path asserts Graph facade input, attendee pass-through, default organizer persistence from the facade result, interaction creation, and online_meetings persistence.
  • Permission-denied and capability-unavailable paths assert no Graph create and no local interaction.
  • Schedule-entry option asserts work_item_type='interaction', work_item_id equals the created interaction id, assignee row creation, and online_meetings.schedule_entry_id linkage.
  • Test cleanup now tracks standalone online meeting and interaction ids because these rows are not appointment-request-linked.
• Verification:
  • npm -w @alga-psa/scheduling run typecheck passed.
  • npx vitest run src/test/integration/appointmentRequests.integration.test.ts -t "Schedule Teams Meeting" from server/ passed twice (4 tests, 44 skipped). The second run includes a package-level @alga-psa/event-bus/publishers mock so the new action tests do not touch Redis.

2026-06-01 - F043-F045 / T066-T068

• Implemented interaction read enrichment: InteractionModel.getById and getForEntity attach online_meeting by calling OnlineMeetingModel.getByInteractionId, which returns artifacts newest-first via the model helper. Kept the implementation scoped to interaction reads instead of duplicating artifact aggregation SQL.
• Added the MSP InteractionDetails online meeting section with Join, status, Refresh recordings, transcript document links, and recording proxy links. Artifact links use internal routes only: /api/documents/{documentId}/download for transcripts and /api/online-meetings/recordings/{artifactId} for recordings.
• Fixed InteractionIcon fallback so online meeting maps to the video icon before the generic meeting/users fallback.
• Added source contract tests for model enrichment and UI wiring: packages/clients/src/models/interactions.onlineMeeting.contract.test.ts and packages/clients/src/components/interactions/InteractionDetails.onlineMeeting.contract.test.ts.
• Verification: npx vitest run ../packages/clients/src/models/interactions.onlineMeeting.contract.test.ts ../packages/clients/src/components/interactions/InteractionDetails.onlineMeeting.contract.test.ts from server/; npm -w @alga-psa/clients run typecheck; npm -w @alga-psa/ui run typecheck.

2026-06-01 - F046-F047 / T069-T070

• Added sanitized online meeting artifact metadata to client-portal appointment actions. Portal actions return online_meeting_artifacts only when teams_integrations.expose_recordings_in_portal=true; missing settings/columns default to hidden. Returned rows intentionally omit raw Graph content_url.
• Added MSP EntryPopup artifact metadata through getAppointmentRequestById without portal gating, so internal users can see recordings/transcripts next to the existing Join Teams Meeting action.
• Added artifact buttons to AppointmentsPage, AppointmentRequestDetailsPage, and EntryPopup. Transcript buttons use /api/documents/{documentId}/download; recording buttons use /api/online-meetings/recordings/{artifactId} with ?portal=true for portal surfaces so the proxy enforces portal visibility.
• Stable ids added for artifact actions (client-portal-appointment-artifact-*, entry-popup-online-meeting-artifact-*), and all new labels use t(...) keys with defaults.
• Verification: npx vitest run ../packages/client-portal/src/components/appointments/onlineMeetingArtifacts.contract.test.ts ../packages/scheduling/src/components/schedule/EntryPopup.onlineMeetingArtifacts.contract.test.ts from server/; npm -w @alga-psa/client-portal run typecheck; npm -w @alga-psa/scheduling run typecheck.

2026-06-01 - F048 / T071

• Added EE migration ee/server/migrations/20260601120200_add_online_meeting_capture_settings_to_teams_integrations.cjs.
• Migration is idempotent and skips cleanly if teams_integrations is absent. It adds default_meeting_organizer_object_id as nullable text, plus download_recordings and expose_recordings_in_portal as non-null booleans defaulting to false; rollback drops those columns in reverse order if present.
• Verification: npx vitest run src/test/unit/migrations/teamsIntegrationCaptureSettingsMigration.test.ts from server/.

2026-06-02 — F049/F050 Teams meeting settings UI

• Moved the Teams meeting organizer controls out of packages/scheduling/src/components/schedule/AvailabilitySettings.tsx; the scheduling dialog no longer loads getTeamsMeetingsTabState or exposes the old default-meeting-organizer-upn / save / verify controls.
• Added organizer + recording settings to the Teams integration settings page: teams-default-meeting-organizer-upn, teams-download-recordings, and teams-expose-recordings-in-portal, all using integrations.teams.settings.* i18n keys.
• Extended Teams integration contracts/actions in both shared and EE packages with defaultMeetingOrganizerUpn, defaultMeetingOrganizerObjectId, downloadRecordings, and exposeRecordingsInPortal.
• Save now resolves the organizer UPN to a Microsoft Entra object id via Graph /users/{upn} using the selected Microsoft profile app credentials, then persists default_meeting_organizer_object_id. Rationale: meeting execution can prefer object id while admins can enter a UPN.
• Added runtime coverage in packages/integrations/src/actions/integrations/teamsActions.test.ts for organizer object-id resolution and recording toggle persistence; added source contract server/src/test/unit/integrations/teamsIntegrationMeetingSettings.contract.test.ts for backend/UI placement.
• Verification: npm -w @alga-psa/integrations run typecheck, npm -w @alga-psa/ee-microsoft-teams run typecheck, npm -w @alga-psa/scheduling run typecheck, and npx vitest run src/actions/integrations/teamsActions.test.ts passed. The server source-contract Vitest assertions passed, but one parallel run ended after coverage with ENOENT ... server/coverage/.tmp; rerun before commit.
• Rerun note: source-contract test passed cleanly when run alone; the earlier coverage .tmp error was from concurrent Vitest runs.

2026-06-02 — F051/F052 recording diagnostics and setup docs

• Extended getTeamsMeetingCapability to return recordingsAvailable separately from available. Meeting creation can be available while recording capture is not ready; missing organizer object id now reports recordingReason='missing_organizer_object_id'.
• Added a Teams diagnostics step recording_permissions that surfaces recording/transcript readiness and lists required Graph application permissions (Calendars.ReadWrite, OnlineMeetingRecording.Read.All, OnlineMeetingTranscript.Read.All) plus Exchange mailbox scoping.
• Mapped the new diagnostics step and organizer remediation recommendations in TeamsIntegrationSettings so warnings render with i18n-backed copy.
• Updated docs/integrations/teams-meetings-setup.md and the browser-served server/public/docs/integrations/teams-meetings-setup.md to document calendar-backed events, protected recording/transcript API consent, and Exchange Application Access Policy/RBAC scoping. Rationale: Teams Application Access Policy scopes online meetings, not calendar/mailbox access.
• Added docs contract coverage in server/src/test/unit/docs/teamsMeetingsSetupRecordingPermissions.contract.test.ts and expanded diagnostics/capability unit coverage.
• Verification: npx vitest run src/test/unit/teamsMeetingHelpers.test.ts src/test/unit/lib/teams/actions/teamsDiagnosticsActions.test.ts src/test/unit/docs/teamsMeetingsSetupRecordingPermissions.contract.test.ts; npm -w @alga-psa/ee-microsoft-teams run typecheck; npm -w @alga-psa/scheduling run typecheck; npm -w @alga-psa/integrations run typecheck; npm -w @alga-psa/clients run typecheck all passed.

2026-06-02 — F053 edition gating

• Made recording capture truly inert in CE: fetchAndPersistMeetingArtifacts now returns the existing online meeting before loading settings, fetching Graph artifacts, upserting artifacts, incrementing recording_fetch_attempts, or changing status when isEnterprise is false. Added an injectable isEnterpriseEdition dependency so the boundary is runtime-tested.
• Gated the internal recording proxy route with isEnterprise before loading EE Teams code; CE returns a controlled 404 instead of attempting Graph token/config resolution.
• Kept online meeting records and join links edition-agnostic in InteractionDetails, but hid recording status, refresh, and artifact links unless NEXT_PUBLIC_EDITION='enterprise'. Rationale: CE must show the interaction join link without recording UI or runtime EE dependencies.
• Fixed the MSP composition adapter for client-originated Teams scheduling: client UI attendees are converted from { emailAddress: string } to the Graph attendee shape expected by the scheduling action.
• Added server/src/test/unit/onlineMeetingEditionGating.contract.test.ts for CE UI/proxy/facade contracts and expanded packages/clients/src/lib/onlineMeetingArtifactCapture.test.ts with the CE capture no-op assertion.
• Verification: npx vitest run src/lib/onlineMeetingArtifactCapture.test.ts from packages/clients/; npx vitest run src/test/unit/onlineMeetingEditionGating.contract.test.ts from server/; npm -w @alga-psa/clients run typecheck; npm -w server run typecheck all passed. npm -w @alga-psa/msp-composition run typecheck is unavailable because that workspace has no typecheck script; the server typecheck covers the composition import edge.

2026-06-02 — F054-F057 Phase 2 recording/transcript subscriptions

• Added EE migration 20260601123000_add_teams_meeting_artifact_subscription_columns.cjs with recordings_subscription_id, recordings_subscription_expires_at, transcripts_subscription_id, and transcripts_subscription_expires_at on teams_integrations. Rationale: Phase 2 needs independent Graph subscription state per collection.
• Added ee/packages/microsoft-teams/src/lib/meetings/artifactSubscriptions.ts:
  • Creates Graph subscriptions for communications/onlineMeetings/getAllRecordings and communications/onlineMeetings/getAllTranscripts.
  • Persists subscription id/expiry on teams_integrations.
  • Renews near-expiry subscriptions and recreates a subscription when Graph returns 404.
  • Uses clientState only as routing data: teams-online-meeting-artifacts:<tenant>:<recordings|transcripts>.
  • Resolves the affected meeting id from resourceData['@odata.id'], with a dependency-injected encrypted resource-data decrypt path for encrypted notifications.
• Added server job wrapper teamsMeetingArtifactWebhookHandler.ts, gated by the same Enterprise edition check as calendar webhooks. The notification job resolves the meeting, skips cancelled/missing rows, then calls the shared fetchAndPersistMeetingArtifacts handler so manual refresh and webhook refresh are idempotent.
• Added job registration/scheduling:
  • renew-teams-meeting-artifact-subscriptions recurring job, scheduled per tenant only in Enterprise.
  • process-teams-meeting-artifact-notification immediate job for webhook payloads.
  • Exported @alga-psa/clients/lib/onlineMeetingArtifactCapture so server jobs can reuse the capture helper without copying capture logic.
• Added route server/src/app/api/teams/webhooks/recordings/route.ts: echoes validationToken as text/plain, responds 202 for notifications, and enqueues one job per notification whose clientState contains tenant routing.
• Verification:
  • npx vitest run src/test/unit/teamsMeetingArtifactSubscriptions.test.ts src/test/unit/api/teamsRecordingWebhookRoute.test.ts from server/ passed.
  • npm -w @alga-psa/ee-microsoft-teams run typecheck passed.
  • npm -w @alga-psa/clients run typecheck passed.
  • npm -w server run typecheck passed.