jachty.pkmp.com.pl/.paul/codebase/integrations.md

External Integrations

Analysis Date: 2026-05-05

Google Calendar API v3

Purpose: Bidirectional sync — bookings push to Google Calendar as events; Google Calendar events pull back as availability blocks.

Implementation: Native PHP, no SDK. Uses WordPress HTTP API (wp_remote_post, wp_remote_get, wp_remote_request).

Files:

• integrations/google-calendar/class-gcal-service.php — API calls
• integrations/google-calendar/class-oauth-handler.php — OAuth 2.0 token management
• integrations/google-calendar/class-sync-controller.php — Cron orchestration (Singleton)

Authentication: OAuth 2.0 with offline access (refresh token).

• Auth endpoint: https://accounts.google.com/o/oauth2/v2/auth
• Token endpoint: https://oauth2.googleapis.com/token
• Scope: https://www.googleapis.com/auth/calendar
• Credentials stored in wp_options key yacht_booking_gcal_credentials
• Tokens stored in wp_options key yacht_booking_gcal_tokens
• Calendar ID stored in yacht_booking_gcal_calendar_id (defaults to 'primary')
• OAuth redirect URI hardcoded: https://jachty.pagedev.pl/wp-admin/admin.php?page=yacht-bookings-settings&tab=google-calendar&gcal_callback=1

Outbound API calls:

Method	URL	Purpose
POST	.../calendars/{id}/events	Create event
PATCH	.../calendars/{id}/events/{eventId}	Update event
DELETE	.../calendars/{id}/events/{eventId}	Delete event
GET	.../calendars/{id}/events	List events (pull sync)
GET	.../users/me/calendarList	List calendars
POST	https://oauth2.googleapis.com/token	Token exchange/refresh
GET	https://www.googleapis.com/oauth2/v2/userinfo	Get connected email

Sync model: Pull-only for external → local (hourly WP Cron yacht_booking_pull_from_gcal). Push for local → GCal on yacht_booking_created / yacht_booking_status_changed (scheduled single cron events).

Limitations:

• Single shared calendar for all yachts — GCal events apply to every yacht, not per-yacht
• No incoming webhooks — polling model only
• No retry logic on API failure

iCal Integration

Export (Feed)

Purpose: Generate .ics file per yacht for subscription by external clients (other booking systems, personal calendars).

File: integrations/ical/class-ical-feed.php

URL pattern: {home_url}/yacht-ical/{yacht_id}/{token}.ics

• Token stored in _yacht_ical_token post meta (24-char alphanumeric, auto-generated)
• Verified with hash_equals() — timing-safe
• Returns text/calendar with all non-cancelled bookings for that yacht
• Regenerate token: ICal_Feed::regenerate_token($yacht_id)

Import (Subscribe)

Purpose: Subscribe to external iCal URLs per yacht; import events as availability blocks (hourly cron).

File: integrations/ical/class-ical-import.php

Config: Per-yacht _yacht_ical_import_url post meta (set via ICal_Import::set_import_url())

Behavior: Fetches URL via wp_remote_get() (30-second timeout, SSL verification), parses VEVENT components, creates yacht_booking posts with _booking_source = 'ical_import', marks dates as blocked via Availability::mark_as_blocked().

Limitation: Does not check VEVENT STATUS property — cancelled events in the feed are imported as blocks.

jsDelivr CDN

Purpose: FullCalendar library loaded from CDN (no local copy).

Asset	URL
FullCalendar JS	https://cdn.jsdelivr.net/npm/fullcalendar@6.1.10/index.global.min.js
FullCalendar CSS	https://cdn.jsdelivr.net/npm/fullcalendar@6.1.10/index.global.min.css
Polish locale	https://cdn.jsdelivr.net/npm/@fullcalendar/core@6.1.10/locales/pl.global.min.js

Enqueued in Yacht_Booking::enqueue_frontend_assets(), conditional on page content.

Email

Provider: WordPress wp_mail() only — no Mailgun, SendGrid, or other transactional service.

Templates: includes/class-email-templates.php — templates stored in wp_options as tagged strings, compiled with get_booking_template_data().

When sent:

• On booking creation: admin notification via Rest_Controller::send_booking_notification() (hooked on yacht_booking_created)
• On status change: customer notification via Admin::send_customer_notification() (hooked on yacht_booking_status_changed)
• On inquiry create: admin + customer emails via Inquiry::send_emails() (built inline, not using Email_Templates)

Headers: From: pulled from yacht_booking_email_from option; Reply-To: set explicitly.

REST API (Internal)

Namespace: yacht-booking/v1 — base: /wp-json/yacht-booking/v1/

Method	Endpoint	Auth	Handler
GET	/yachts	Public	get_yachts()
GET	/yachts/{id}	Public	get_yacht()
GET	/availability/{yacht_id}?start=Y-m-d&end=Y-m-d	Public	get_availability()
POST	/bookings	Public + X-WP-Nonce	create_booking()
POST	/inquiries	Public + X-WP-Nonce	create_inquiry()
GET	/bookings	Admin cap	get_bookings()
PUT	/bookings/{id}/status	Admin cap	update_booking_status()

All registered in api/class-rest-controller.php.

Monitoring & Observability

• No error tracking service (no Sentry, Bugsnag)
• error_log() used with prefixes: [Yacht Booking - GCal], [Yacht Booking - GCal Sync], [Yacht Booking - iCal]
• Logging only fires when WP_DEBUG === true — silent in production

Deployment

• Method: FTP via VS Code ftp-kr extension (.vscode/ftp-kr.json)
• CI/CD: None — fully manual
• Production URL: https://jachty.pagedev.pl (hardcoded in GCal OAuth redirect)