danwel - Integrations

Provider interfaces, OAuth flows, and data flow documentation for external integrations.

Table of Contents

---

Integration System

Multi-Calendar Support

interface CalendarProviderInterface

{

    // OAuth

    public function getAuthorizationUrl(string $state): string;

    public function handleCallback(string $code): TokenData;

    public function refreshToken(Integration $integration): TokenData;

    public function disconnect(Integration $integration): void;



    // Calendar discovery (for multi-calendar)

    public function getAvailableCalendars(Integration $integration): Collection;



    // Events (calendar-aware)

    public function getEvents(Integration $integration, Calendar $calendar, DateRange $range): Collection;

    public function createEvent(Integration $integration, Calendar $calendar, EventData $event): EventData;

    public function updateEvent(Integration $integration, Calendar $calendar, string $eventId, EventData $event): EventData;

    public function deleteEvent(Integration $integration, Calendar $calendar, string $eventId): void;



    // Provider info

    public function getProviderName(): string;

    public function getProviderKey(): string;

    public function getRequiredScopes(): array;

}

Integration Manager

class IntegrationManager

{

    public function __construct(

        private readonly TenantContext $tenantContext,

        private readonly array $calendarProviders = [],

        private readonly array $invoicingProviders = []

    ) {}



    // Get all active integrations for current organization

    public function getActiveCalendarIntegrations(): Collection

    {

        return Integration::where('provider_type', 'calendar')

            ->where('is_active', true)

            ->get();

    }



    // Get enabled calendars across all integrations

    public function getEnabledCalendars(): Collection

    {

        return Calendar::where('is_enabled', true)

            ->with('integration')

            ->get();

    }



    // Sync events from all enabled calendars

    public function syncAllCalendars(DateRange $range): void

    {

        foreach ($this->getEnabledCalendars() as $calendar) {

            $provider = $this->calendarProvider($calendar->integration->provider);

            $events = $provider->getEvents($calendar->integration, $calendar, $range);

            // Process events...

        }

    }

}

---

Data Ownership Strategy

Source of Truth: Local Database

The danwel database is the **source of truth** for time blocks. External services (Google Calendar, Moneybird) are mirrors that are kept in sync.

┌─────────────────────────────────────────────────────────────────┐

│                      danwel Database                            │

│                    (Source of Truth)                            │

└─────────────────────────────────────────────────────────────────┘

           │                                    │

           ▼                                    ▼

    ┌─────────────┐                      ┌─────────────┐

    │   Google    │                      │  Moneybird  │

    │  Calendar   │                      │             │

    │  (Mirror)   │                      │  (Mirror)   │

    └─────────────┘                      └─────────────┘

Benefits

Sync Flow

Sync Status States

pending   → Not yet synced to external service

syncing   → Currently being synced

synced    → Successfully mirrored to external services

error     → Sync failed (will retry)

conflict  → External change detected, needs resolution

disabled  → User disabled sync for this block

Conflict Resolution Strategy

Queue Jobs

// Sync single time block to external services

SyncTimeBlockJob::dispatch($timeBlock);



// Periodic: Pull changes from all calendars

PullCalendarChangesJob::dispatch($integration);



// Retry failed syncs

RetryPendingSyncsJob::dispatch();

---

Google Calendar Integration

OAuth Flow

https://www.googleapis.com/auth/calendar.events

**Additional Data Fetched on Connect:**

**Stored Token Data:**

Events API




**Fetch Events (Read):**

**Event Structure (from Google):**

**Create Event (Write):**

**Fields We Use from Google Calendar:**



| Field | Purpose |

|-------|---------|

| id | Unique event identifier |

| summary | Event title |

| start.dateTime | Start time with timezone |

| end.dateTime | End time with timezone |

| colorId | Google Calendar color (1-11) |

| extendedProperties.private.project | Moneybird project ID |

| extendedProperties.private.client | Moneybird contact ID |

| extendedProperties.private.weekplanner | Flag: "true" if created by us |

| extendedProperties.private.timeEntryId | Moneybird time entry ID |
---
Moneybird Integration




OAuth Flow




**Scopes Requested:**

**Token Exchange Response:**

**Additional Data Fetched on Connect:**

**Stored Token Data:**

Contacts (Clients) API




**Fetch Contacts:**

**Contact Structure (from Moneybird):**

**Fields We Use:**



| Field | Purpose |

|-------|---------|

| id | Unique contact identifier |

| company_name | Company name (preferred) |

| firstname + lastname | Fallback if no company name |

| email | Contact email |



**Create Contact:**

Projects API




**Fetch Projects:**

**Project Structure (from Moneybird):**

**Fields We Use:**



| Field | Purpose |

|-------|---------|

| id | Unique project identifier |

| name | Project name |

| state | Filter for "active" only |



**Create Project:**

Time Entries API




**Fetch User ID (Required for Time Entries):**

**Create Time Entry:**

**Response:**

**Update Time Entry:**

**Delete Time Entry:**

---



Data Flow Summary

---

Adding New Providers

Step 1: Implement Interface

// app/Services/Integrations/Calendar/Office365CalendarProvider.php

class Office365CalendarProvider implements CalendarProviderInterface

{

    // ... implement all methods

}

Step 2: Add Config

// config/integrations.php

'providers' => [

    'calendar' => [

        'google_calendar' => [

            'class' => GoogleCalendarProvider::class,

            'client_id' => env('GOOGLE_CLIENT_ID'),

            'client_secret' => env('GOOGLE_CLIENT_SECRET'),

            'scopes' => ['https://www.googleapis.com/auth/calendar'],

        ],

        'office365_calendar' => [

            'class' => Office365CalendarProvider::class,

            'client_id' => env('OFFICE365_CLIENT_ID'),

            'client_secret' => env('OFFICE365_CLIENT_SECRET'),

            'scopes' => ['Calendars.ReadWrite'],

        ],

    ],

    'invoicing' => [

        'moneybird' => [...],

        'harvest' => [...],

    ],

],

Step 3: Register (Automatic via Config)

// IntegrationServiceProvider boots all configured providers