Google Maps Booking (integrations/google-maps-booking)

Server-side API client for Google Maps Booking (Google Business Profile), enabling merchant/service feed management, booking server callbacks, waitlist, and channel orders.

Overview

The Google Maps Booking workspace provides a TypeScript SDK for interacting with Google's Maps Booking API. It supports merchant/service feed management, availability slots, booking server callbacks (9 endpoints), waitlist operations, and channel orders. Authentication uses Google service account JWT signing via jose.

Tech Stack

Layer	Technology	Version
Runtime	Bun	>= 1.3.0
Language	TypeScript	^6.0.3
Validation	Zod	^4.4.3
JWT Auth	jose	^6.2.3
Bundling	bunup	^0.16.32
Testing	Vitest	^4.1.10
Linting	Biome	^2.5.4

API

• Sandbox endpoint: https://partnerdev-mapsbooking.googleapis.com
• Production endpoint: https://mapsbooking.googleapis.com
• Auth endpoint: https://oauth2.googleapis.com/token
• Scope: https://www.googleapis.com/auth/mapsbooking

Booking Server Endpoints

Endpoint	Description
/v3/HealthCheck	Health check
/v3/BatchAvailabilityLookup	Check availability across merchants/services
/v3/CreateBooking	Create a booking
/v3/UpdateBooking	Update booking status
/v3/JoinWaitlist	Join waitlist with party size
/v3/GetWaitlistInfo	Get waitlist entry status
/v3/LeaveWaitlist	Leave waitlist
/v3/CreateOrder	Create channel order with items
/v3/UpdateOrder	Update channel order status

Channel Orders (New Feature)

Channel orders enable product/service orders from external channels via channel_orders and channel_order_items database tables (migration 0040-channel-orders.ts).

Function	Description
importChannelOrder(input)	Insert order with items in transaction
fetchChannelOrderByExternalId(id)	Fetch order by external ID
fetchChannelOrderById(id)	Fetch order by internal ID
updateChannelOrderStatus(id, status)	Update order status
findChannelOrderItemByInventoryId(orderId, itemId)	Find item by inventory ID

Order status mapping: PENDING → pending, CONFIRMED → confirmed, CANCELLED → cancelled, FULFILLED → fulfilled

External order ID format: gmo-{connection_id}-{service_id}-{timestamp}

Webhook Security

Feature	Implementation
Signature	HMAC-SHA256 with X-Booking-Webhook-Signature header (lowercase hex)
Secret	GOOGLE_MAPS_BOOKING_WEBHOOK_SECRET env var (min 16 characters)
Replay prevention	X-Booking-Webhook-Timestamp with 5-minute window
Idempotency	X-Booking-Webhook-Event-ID or SHA-256 body hash fallback
Comparison	Constant-time to prevent timing attacks

Configuration

Variable	Required	Description
GOOGLE_MAPS_BOOKING_PARTNER_ID	Yes	Google partner ID
GOOGLE_MAPS_BOOKING_CLIENT_EMAIL	Yes	Service account email
GOOGLE_MAPS_BOOKING_PRIVATE_KEY	Yes	Service account private key
GOOGLE_MAPS_BOOKING_PROJECT_ID	No	Google Cloud project ID
GOOGLE_MAPS_BOOKING_SYSTEM_USER_ID	No	System user UUID (has fallback)
GOOGLE_MAPS_BOOKING_SANDBOX	No	Sandbox mode (default: false)
GOOGLE_MAPS_BOOKING_WEBHOOK_SECRET	No	Webhook signing secret (min 16 chars)

Exports

Export	Description
GoogleMapsBookingClient	API client for Google Maps Booking
getAccessToken	OAuth2 service account token acquisition
BookingServerRouter	Router for Google Booking Server callbacks
createBookingServerRouter	Create a booking server router instance
createMerchant / createMerchantList	Merchant feed builders
createService / createServiceList	Service feed builders
createAvailabilitySlot / createAvailabilityList	Availability feed builders

Key Scripts

# Build
moon run integrations-google-maps-booking:build

# Quality
moon run integrations-google-maps-booking:lint
moon run integrations-google-maps-booking:typecheck
moon run integrations-google-maps-booking:verify

Architecture

integrations/google-maps-booking/
├── src/
│   ├── index.ts          # Package entry point
│   ├── auth.ts           # OAuth2 service account JWT auth
│   ├── client.ts         # Google Maps Booking API client
│   ├── booking-server.ts # Booking Server callback router
│   ├── feeds.ts          # Merchant, service, and availability feed builders
│   ├── types.ts          # TypeScript types and Zod schemas
│   └── client.test.ts    # Client unit tests
├── bunup.config.ts       # Bundler configuration
├── biome.jsonc           # Workspace-specific lint config
├── AGENTS.md
└── package.json

Platform Adapter

The platform adapter (apps/website/src/server/integrations/google-maps-booking/platform-adapter.ts) implements ExtendedBookingAdapter with:

• healthCheck() — Returns { pong: true }
• batchAvailabilityLookup() — Maps merchant/service to platform entities, checks capacity
• createBooking() — Creates booking with idempotency key gmb-{merchant_id}-{service_id}-{start_sec}
• updateBooking() — Maps Google status to platform status (CONFIRMED→confirmed, CANCELED→cancelled)
• createOrder() — Creates channel order with user lookup and inventory item matching
• updateOrder() — Updates channel order status
• joinWaitlist() — Adds to waitlist with user creation/lookup
• getWaitlistInfo() — Returns waitlist status (WAITING/SEATED/CANCELLED)
• leaveWaitlist() — Removes from waitlist

Important

• This package is server-side only. Never import into client-side components.
• Uses jose for Google service account JWT signing.
• All Google Maps Booking API callbacks (Booking Server) must be implemented by the consuming application.
• Store GOOGLE_MAPS_BOOKING_PRIVATE_KEY via Infisical or environment variables.

Related

• Apple Business Connect
• Integrations Shared
• Health CLI