more-apartments-astro-integration 1.0.1

package/README.md

@@ -0,0 +1,982 @@
+# More Apartments Astro Integration
+
+A fully-typed Astro integration for the More Apartments REST API, providing easy access to property listings, availability, bookings, and content management.
+
+## Features
+
+- 🚀 **Full TypeScript Support** - Complete type definitions for all API responses
+- 🔄 **Built-in Retry Logic** - Automatic retry with exponential backoff
+- 💾 **Response Caching** - Configurable caching to reduce API calls
+- 🎯 **Zod Validation** - Runtime validation of API responses
+- 🔌 **Virtual Modules** - Easy importing in Astro components
+- 🛣️ **Optional API Routes** - Proxy API calls through your Astro server
+- ⚡ **Optimized for Astro** - Follows Astro integration best practices
+
+## Installation
+
+```bash
+bun add @shelfwood/more-apartments-astro-integration
+# or
+npm install @shelfwood/more-apartments-astro-integration
+# or
+yarn add @shelfwood/more-apartments-astro-integration
+# or
+bun add @shelfwood/more-apartments-astro-integration
+```
+
+## CLI Usage
+
+The package includes a powerful CLI for interacting with the More Apartments API directly from the command line.
+
+### CLI Installation
+
+The CLI is automatically available after installing the package:
+
+```bash
+npx more-apartments --help
+# or with bun
+bunx more-apartments --help
+```
+
+### CLI Configuration
+
+The CLI reads configuration from environment variables or command-line options:
+
+```bash
+# .env file
+MORE_APARTMENTS_BASE_URL=http://prj-more-apartments.test
+MORE_APARTMENTS_API_KEY=your-api-key
+MORE_APARTMENTS_INSTANCE=your-instance-name
+```
+
+Or provide options directly:
+
+```bash
+more-apartments --base-url http://prj-more-apartments.test \
+                --api-key your-api-key \
+                --instance your-instance-name \
+                properties list
+```
+
+### CLI Commands
+
+#### Properties
+
+```bash
+# List properties with pagination
+more-apartments properties list --page 1 --limit 10
+
+# Show specific property
+more-apartments properties show adipisci-voluptas-maiores
+
+# Search properties with filters
+more-apartments properties search \
+  --city "The Hague" \
+  --bedrooms 2 \
+  --guests 4 \
+  --arrival 2024-06-01 \
+  --departure 2024-06-07
+
+# Advanced search with amenities
+more-apartments properties search \
+  --city Amsterdam \
+  --parking \
+  --balcony \
+  --elevator
+
+# Get property availability
+more-apartments properties availability <property-slug> \
+  --start 2024-06-01 \
+  --end 2024-06-30
+```
+
+#### Content Management
+
+```bash
+# List all pages
+more-apartments content pages list
+
+# Show specific page
+more-apartments content pages show about-us
+
+# List posts with filters
+more-apartments content posts list --page 1 --limit 5 --tag news
+
+# Show specific post
+more-apartments content posts show welcome-to-our-blog
+
+# List categories
+more-apartments content categories list
+
+# Show category with segments
+more-apartments content categories show locations
+more-apartments content categories segments locations
+
+# Show specific segment
+more-apartments content categories segment locations the-hague
+
+# List all locations
+more-apartments content locations
+```
+
+#### Settings
+
+```bash
+# Get main site settings
+more-apartments settings main
+
+# Get theme settings
+more-apartments settings theme
+
+# Get property settings
+more-apartments settings properties
+
+# Get booking settings
+more-apartments settings booking
+
+# Get all settings at once
+more-apartments settings all
+```
+
+#### Bookings
+
+```bash
+# Create booking from JSON file
+more-apartments bookings create --file booking.json
+
+# Show booking details
+more-apartments bookings show <booking-id>
+
+# Generate example booking JSON
+more-apartments bookings example > booking.json
+```
+
+### Output Formats
+
+The CLI supports multiple output formats:
+
+```bash
+# JSON format (default)
+more-apartments properties list --format json
+
+# Table format (great for quick viewing)
+more-apartments properties list --format table
+
+# YAML format (human-readable)
+more-apartments properties list --format yaml
+```
+
+### CLI Examples
+
+**Find available 2-bedroom apartments in The Hague for a specific week:**
+
+```bash
+more-apartments properties search \
+  --city "The Hague" \
+  --bedrooms 2 \
+  --arrival 2024-07-15 \
+  --departure 2024-07-22 \
+  --format table
+```
+
+**Get property details and availability in one command:**
+
+```bash
+# First get property details
+more-apartments properties show my-apartment-slug --format yaml
+
+# Then check availability
+more-apartments properties availability my-apartment-slug \
+  --start 2024-06-01 \
+  --end 2024-06-30 \
+  --format json
+```
+
+**Export all properties to JSON file:**
+
+```bash
+more-apartments properties list --limit 100 --format json > properties.json
+```
+
+**Get site configuration:**
+
+```bash
+more-apartments settings all --format yaml > config.yaml
+```
+
+## Configuration
+
+Add the integration to your `astro.config.mjs`:
+
+```js
+import { defineConfig } from 'astro/config';
+import moreApartments from '@shelfwood/more-apartments-astro-integration';
+
+export default defineConfig({
+  integrations: [
+    moreApartments({
+      baseUrl: 'http://prj-more-apartments.test', // Your API base URL
+      apiKey: process.env.MORE_APARTMENTS_API_KEY, // Optional API key
+      instance: 'cheap-gotham-apartments', // Optional instance identifier
+      
+      // Optional configuration
+      timeout: 30000, // Request timeout in ms (default: 30000)
+      retry: {
+        attempts: 3, // Number of retry attempts (default: 3)
+        delay: 1000, // Initial retry delay in ms (default: 1000)
+      },
+      cache: {
+        enabled: true, // Enable response caching (default: true)
+        ttl: 300000, // Cache TTL in ms (default: 5 minutes)
+      },
+      
+      // Integration features
+      virtualModules: true, // Enable virtual module imports (default: true)
+      injectClient: true, // Inject global client (default: true)
+      addApiRoutes: true, // Add proxy API routes for security (default: true, recommended)
+      apiRoutePrefix: '/api/apartments', // API route prefix when addApiRoutes is true
+    })
+  ]
+});
+```
+
+**Environment Variables (.env):**
+
+```bash
+# API Configuration (required)
+MORE_APARTMENTS_BASE_URL=https://api.moreapartments.com
+MORE_APARTMENTS_API_KEY=your-api-key-here
+MORE_APARTMENTS_INSTANCE=your-instance-name
+```
+
+## Usage
+
+### Hybrid Booking Flow (Phase 1)
+
+The integration includes a **Hybrid Booking Flow** that allows you to display properties in your Astro frontend while redirecting users to the Laravel backend for the booking process. This provides a fast time-to-market solution.
+
+#### PropertyBookingWidget Component
+
+```astro
+---
+// src/pages/property/[id].astro
+import client from 'virtual:more-apartments/client';
+import PropertyBookingWidget from '@shelfwood/more-apartments-astro-integration/components/PropertyBookingWidget.astro';
+import { generateBookingUrl } from '@shelfwood/more-apartments-astro-integration';
+
+const { id } = Astro.params;
+const property = await client.getProperty(id);
+
+// Example search parameters (these would typically come from URL params or form state)
+const searchParams = {
+  arrival: '2024-03-15',
+  departure: '2024-03-20', 
+  guests: 2
+};
+---
+
+<PropertyBookingWidget
+  propertyExternalId={property.external_id}
+  propertyName={property.name}
+  basePrice={property.base_price}
+  arrival={searchParams.arrival}
+  departure={searchParams.departure}
+  guests={searchParams.guests}
+  buttonText="Reserve Now"
+/>
+```
+
+#### Manual Booking URL Generation
+
+```typescript
+import { generateBookingUrl } from '@shelfwood/more-apartments-astro-integration';
+
+// Generate booking URL for Laravel backend
+const bookingUrl = generateBookingUrl(
+  property.external_id,  // Property's external_id
+  '2024-03-15',         // Arrival date (YYYY-MM-DD)
+  '2024-03-20',         // Departure date (YYYY-MM-DD)
+  2                     // Number of guests
+);
+
+// Use in a regular HTML anchor tag
+// <a href={bookingUrl}>Book This Property</a>
+```
+
+#### Booking Complete Page
+
+Copy the example booking complete page to your project:
+
+```bash
+# Copy the example page to your Astro project
+cp node_modules/@shelfwood/more-apartments-astro-integration/src/pages/booking-complete.astro src/pages/
+```
+
+#### Environment Configuration
+
+```bash
+# .env
+PUBLIC_LARAVEL_BOOKING_URL=http://prj-more-apartments.test/booking/initiate
+```
+
+### Advanced Property Search (Phase 2)
+
+The integration now includes powerful property search functionality that leverages the backend's PropertySearchService for rich filtering capabilities.
+
+#### PropertySearchGrid Component
+
+```astro
+---
+// src/pages/search.astro
+import PropertySearchGrid from '@shelfwood/more-apartments-astro-integration/components/PropertySearchGrid.astro';
+
+// Get search parameters from URL or form
+const url = new URL(Astro.request.url);
+const searchParams = {
+  destination: url.searchParams.get('destination') || undefined,
+  arrival: url.searchParams.get('arrival') || undefined,
+  departure: url.searchParams.get('departure') || undefined,
+  guests: url.searchParams.get('guests') ? parseInt(url.searchParams.get('guests')) : undefined,
+};
+---
+
+<PropertySearchGrid
+  destination={searchParams.destination}
+  arrival={searchParams.arrival}
+  departure={searchParams.departure}
+  guests={searchParams.guests}
+  showBookingWidgets={true}
+  maxResults={20}
+/>
+```
+
+#### Manual Property Search
+
+```typescript
+import { searchProperties } from '@shelfwood/more-apartments-astro-integration';
+import client from 'virtual:more-apartments/client';
+
+// Search with various filters
+const properties = await searchProperties(client, {
+  destination: 'Amsterdam',
+  arrival: '2024-03-15',
+  departure: '2024-03-20',
+  guests: 2,
+  segment: 'luxury-apartments' // Optional segment filter
+});
+```
+
+#### Search Parameters
+
+- **destination**: Free-text search across city, country, and area fields
+- **arrival/departure**: Date range filtering with availability checking
+- **guests**: Minimum occupancy requirements
+- **segment**: Filter by property segments/categories
+
+### Building Custom Components
+
+While the integration provides ready-to-use components, you can also build custom components using the image utilities and helper functions.
+
+#### Custom Property Card Example
+
+```astro
+---
+// src/components/CustomPropertyCard.astro
+import type { Property } from '@shelfwood/more-apartments-astro-integration';
+import { getPrimaryImageUrl, getImageCount } from '@shelfwood/more-apartments-astro-integration';
+
+interface Props {
+  property: Property;
+  class?: string;
+}
+
+const { property, class: className } = Astro.props;
+
+// Use image utilities for consistent fallback handling
+const imageUrl = getPrimaryImageUrl(property, '/images/default-property.jpg');
+const imageCount = getImageCount(property);
+---
+
+<article class:list={['property-card', className]}>
+  <div class="property-image">
+    <img
+      src={imageUrl}
+      alt={property.name}
+      loading="lazy"
+      width="400"
+      height="300"
+    />
+    {imageCount > 1 && (
+      <span class="image-count">{imageCount} photos</span>
+    )}
+  </div>
+
+  <div class="property-details">
+    <h3>{property.name}</h3>
+    <p class="location">{property.area}, {property.city}</p>
+    <p class="description">{property.short_description}</p>
+
+    <div class="property-features">
+      {property.bedrooms && (
+        <span>{property.bedrooms} bed{property.bedrooms > 1 ? 's' : ''}</span>
+      )}
+      {property.max_persons && (
+        <span>Up to {property.max_persons} guests</span>
+      )}
+      {property.size && (
+        <span>{property.size}m²</span>
+      )}
+    </div>
+
+    {property.min_rate && (
+      <div class="pricing">
+        <span class="price">€{property.min_rate}</span>
+        <span class="price-label">per night</span>
+      </div>
+    )}
+  </div>
+</article>
+
+<style>
+  .property-card {
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    overflow: hidden;
+    transition: shadow 0.3s ease;
+  }
+
+  .property-card:hover {
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+  }
+
+  .property-image {
+    position: relative;
+  }
+
+  .image-count {
+    position: absolute;
+    bottom: 8px;
+    right: 8px;
+    background: rgba(0, 0, 0, 0.7);
+    color: white;
+    padding: 4px 8px;
+    border-radius: 4px;
+    font-size: 12px;
+  }
+
+  /* Additional styling... */
+</style>
+```
+
+#### Custom Property Gallery Example
+
+```astro
+---
+// src/components/PropertyGallery.astro
+import type { Property } from '@shelfwood/more-apartments-astro-integration';
+import {
+  getAllImageUrls,
+  getAllThumbnailUrls,
+  getImageWithAlt
+} from '@shelfwood/more-apartments-astro-integration';
+
+interface Props {
+  property: Property;
+}
+
+const { property } = Astro.props;
+
+// Get all images for the gallery
+const images = getAllImageUrls(property);
+const thumbnails = getAllThumbnailUrls(property);
+
+// Get primary image with alt text for main display
+const { url: primaryUrl, alt: primaryAlt } = getImageWithAlt(property, 0);
+---
+
+<div class="gallery">
+  {images.length > 0 ? (
+    <>
+      <div class="gallery-main">
+        <img
+          src={primaryUrl}
+          alt={primaryAlt}
+          class="main-image"
+        />
+      </div>
+
+      {images.length > 1 && (
+        <div class="gallery-thumbnails">
+          {images.map((imageUrl, index) => {
+            const { alt } = getImageWithAlt(property, index);
+            return (
+              <button
+                class="thumbnail"
+                data-image={imageUrl}
+                aria-label={`View ${alt}`}
+              >
+                <img
+                  src={thumbnails[index] || imageUrl}
+                  alt={alt}
+                  loading="lazy"
+                />
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </>
+  ) : (
+    <div class="no-images">
+      <p>No images available for this property</p>
+    </div>
+  )}
+</div>
+
+<script>
+  // Add client-side gallery interactivity
+  document.querySelectorAll('.thumbnail').forEach(thumb => {
+    thumb.addEventListener('click', (e) => {
+      const imageUrl = (e.currentTarget as HTMLElement).dataset.image;
+      const mainImage = document.querySelector('.main-image') as HTMLImageElement;
+      if (mainImage && imageUrl) {
+        mainImage.src = imageUrl;
+      }
+    });
+  });
+</script>
+
+<style>
+  .gallery {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+  }
+
+  .gallery-main {
+    width: 100%;
+    aspect-ratio: 16 / 9;
+    overflow: hidden;
+    border-radius: 8px;
+  }
+
+  .main-image {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+
+  .gallery-thumbnails {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(80px, 1fr));
+    gap: 0.5rem;
+  }
+
+  .thumbnail {
+    aspect-ratio: 1;
+    border: 2px solid transparent;
+    border-radius: 4px;
+    overflow: hidden;
+    cursor: pointer;
+    transition: border-color 0.2s;
+  }
+
+  .thumbnail:hover {
+    border-color: #3b82f6;
+  }
+
+  .thumbnail img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+</style>
+```
+
+### Using Virtual Modules (Recommended)
+
+The integration provides virtual modules for easy importing:
+
+```astro
+---
+// In any .astro component
+import client from 'virtual:more-apartments/client';
+
+// Fetch properties with full type safety
+const propertiesResponse = await client.getProperties({ 
+  page: 1, 
+  per_page: 10 
+});
+const properties = propertiesResponse.data;
+
+// Fetch a single property
+const property = await client.getProperty('luxury-apartment-1');
+
+// Get availability
+const availability = await client.getAvailability(
+  property.id,
+  '2024-03-01',
+  '2024-03-15'
+);
+---
+
+<div>
+  {properties.map(property => (
+    <article>
+      <h2>{property.name}</h2>
+      <p>{property.description}</p>
+      <p>Max occupancy: {property.max_occupancy}</p>
+    </article>
+  ))}
+</div>
+```
+
+### Direct Client Import
+
+You can also import and instantiate the client directly:
+
+```ts
+import { MoreApartmentsClient } from '@shelfwood/more-apartments-astro-integration';
+
+const client = new MoreApartmentsClient({
+  baseUrl: 'http://prj-more-apartments.test',
+  apiKey: 'your-api-key',
+});
+
+const properties = await client.getProperties();
+```
+
+### Using Helper Functions
+
+The integration exports helper functions with built-in error handling:
+
+```astro
+---
+import client from 'virtual:more-apartments/client';
+import { 
+  fetchProperties, 
+  fetchProperty,
+  fetchAvailability,
+  fetchPages,
+  fetchPosts 
+} from '@shelfwood/more-apartments-astro-integration';
+
+// These helpers return null or empty arrays on error
+const properties = await fetchProperties(client, { page: 1 });
+const property = await fetchProperty(client, 'apartment-slug');
+const pages = await fetchPages(client);
+---
+```
+
+### Image Utilities
+
+The integration provides type-safe image utility functions for handling property images. These utilities simplify image handling and provide consistent fallback behavior.
+
+> **⚠️ Server-Side Only**: Image utilities are designed for use in Astro component frontmatter (server-side). They cannot be used in `<script>` tags, framework components with `client:` directives, or browser console.
+
+```astro
+---
+import type { Property } from '@shelfwood/more-apartments-astro-integration';
+import {
+  getPrimaryImageUrl,
+  getThumbnailUrl,
+  getAllImageUrls,
+  getImageWithAlt,
+  hasImages,
+  getImageCount
+} from '@shelfwood/more-apartments-astro-integration';
+
+const { property } = Astro.props;
+
+// Get primary image with optional fallback
+const imageUrl = getPrimaryImageUrl(property, '/images/default.jpg');
+
+// Get thumbnail image
+const thumbUrl = getThumbnailUrl(property, '/images/default-thumb.jpg');
+
+// Get all image URLs for gallery
+const allImages = getAllImageUrls(property);
+
+// Get image with alt text for accessibility
+const { url, alt } = getImageWithAlt(property, 0);
+
+// Check if property has images
+if (hasImages(property)) {
+  const count = getImageCount(property);
+  // property has {count} images
+}
+---
+
+<img src={imageUrl} alt={alt} loading="lazy" />
+
+<!-- Image gallery -->
+{allImages.map((imgUrl) => (
+  <img src={imgUrl} alt={property.name} />
+))}
+```
+
+#### Available Image Functions
+
+- **`getPrimaryImageUrl(property, fallbackUrl?)`** - Get the first image URL, returns fallback if no images
+- **`getThumbnailUrl(property, fallbackUrl?)`** - Get the first thumbnail URL, returns fallback if no images
+- **`getAllImageUrls(property)`** - Get array of all image URLs (empty array if none)
+- **`getAllThumbnailUrls(property)`** - Get array of all thumbnail URLs (empty array if none)
+- **`getImageWithAlt(property, index?)`** - Get image URL and alt text (defaults to property name)
+- **`getImage(property, index?)`** - Get complete PropertyImage object or null
+- **`hasImages(property)`** - Returns true if property has at least one image
+- **`getImageCount(property)`** - Returns number of images (0 if none)
+
+#### Migration from Local Implementations
+
+If you previously had custom image handling functions:
+
+```diff
+---
+- function getPrimaryImageUrl(property) {
+-   if (property.images?.[0]) {
+-     return property.images[0].url;
+-   }
+-   return '/placeholder.jpg';
+- }
++ import { getPrimaryImageUrl } from '@shelfwood/more-apartments-astro-integration';
+
+- const imageUrl = getPrimaryImageUrl(property);
++ const imageUrl = getPrimaryImageUrl(property, '/placeholder.jpg');
+---
+```
+
+## API Methods
+
+### Properties
+
+```ts
+// Get paginated properties
+const properties = await client.getProperties({
+  page: 1,
+  per_page: 15
+});
+
+// Get single property by ID or slug
+const property = await client.getProperty(123);
+// or
+const property = await client.getProperty('property-slug');
+```
+
+### Availability
+
+```ts
+// Get availability for date range
+const availability = await client.getAvailability(
+  propertyId,
+  '2024-03-01',
+  '2024-03-15'
+);
+```
+
+### Content Management
+
+```ts
+// Get all pages
+const pages = await client.getPages();
+
+// Get single page
+const page = await client.getPage('about-us');
+
+// Get paginated posts
+const posts = await client.getPosts({
+  page: 1,
+  per_page: 10,
+  tag: 'news'
+});
+
+// Get single post
+const post = await client.getPost('latest-update');
+```
+
+### Settings
+
+```ts
+// Get various settings
+const mainSettings = await client.getMainSettings();
+const themeSettings = await client.getThemeSettings();
+const propertySettings = await client.getPropertySettings();
+const bookingSettings = await client.getBookingSettings();
+```
+
+### Bookings
+
+```ts
+// Create a booking
+const booking = await client.createBooking({
+  property_id: 123,
+  check_in: '2024-03-01',
+  check_out: '2024-03-07',
+  guests: 2,
+  first_name: 'John',
+  last_name: 'Doe',
+  email: 'john@example.com',
+  phone: '+1234567890',
+  notes: 'Late arrival',
+  total_amount: 1500,
+  payment_method: 'stripe'
+});
+
+// Get booking details
+const bookingDetails = await client.getBooking('booking-id');
+```
+
+## TypeScript Types
+
+All response types are fully typed and exported:
+
+```ts
+import type {
+  Property,
+  Page,
+  Post,
+  Availability,
+  BookingRequest,
+  BookingResponse,
+  MainSettings,
+  ThemeSettings,
+  PropertySettings,
+  BookingSettings,
+  PaginatedResponse,
+  ApiError
+} from '@shelfwood/more-apartments-astro-integration';
+```
+
+## Cache Management
+
+The client includes built-in caching for GET requests:
+
+```ts
+// Clear all cached data
+client.clearCache();
+
+// Get cache statistics
+const stats = client.getCacheStats();
+console.log(`Cache has ${stats.entries} entries`);
+```
+
+## Error Handling
+
+The client includes comprehensive error handling with retry logic:
+
+```ts
+try {
+  const property = await client.getProperty('non-existent');
+} catch (error) {
+  // Error will be thrown after all retry attempts fail
+  console.error('Failed to fetch property:', error.message);
+}
+```
+
+## Environment Variables
+
+For security, store sensitive configuration in environment variables:
+
+```bash
+# .env
+MORE_APARTMENTS_BASE_URL=http://prj-more-apartments.test
+MORE_APARTMENTS_API_KEY=your-api-key-here
+MORE_APARTMENTS_INSTANCE=cheap-gotham-apartments
+```
+
+Then use in your config:
+
+```js
+moreApartments({
+  baseUrl: import.meta.env.MORE_APARTMENTS_BASE_URL,
+  apiKey: import.meta.env.MORE_APARTMENTS_API_KEY,
+  instance: import.meta.env.MORE_APARTMENTS_INSTANCE,
+})
+```
+
+## Security Best Practices
+
+### ⚠️ Important: API Key Security
+
+**Never expose your API key in client-side code!** The integration provides two patterns:
+
+#### 🔒 Secure Pattern (Recommended - Default)
+Use the API proxy routes to keep your API key secure on the server:
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  integrations: [
+    moreApartments({
+      // For client-side modules: point to your own API routes
+      baseUrl: '/api/apartments',
+      instance: import.meta.env.MORE_APARTMENTS_INSTANCE,
+      // Don't include apiKey here - it would be exposed!
+      
+      // Enable server-side proxy routes (default: true)
+      addApiRoutes: true,
+      apiRoutePrefix: '/api/apartments'
+    })
+  ]
+});
+```
+
+```bash
+# .env (server-side only)
+MORE_APARTMENTS_BASE_URL=http://prj-more-apartments.test
+MORE_APARTMENTS_API_KEY=your-secret-api-key
+MORE_APARTMENTS_INSTANCE=your-instance
+```
+
+#### ❌ Insecure Pattern (Avoid)
+Never do this - it exposes your API key in the browser:
+
+```js
+// DON'T DO THIS
+moreApartments({
+  baseUrl: 'http://prj-more-apartments.test', // Direct backend URL
+  apiKey: 'your-secret-key', // ❌ EXPOSED IN BROWSER!
+  addApiRoutes: false
+})
+```
+
+### How API Proxying Works
+
+When `addApiRoutes: true` (default), the integration creates secure server-side routes:
+
+```
+Browser → /api/apartments/properties → Your Astro Server → Your Laravel API
+                                     (with secret API key)
+```
+
+This creates proxy routes like:
+- `/api/apartments/properties`
+- `/api/apartments/properties/[id]`
+- `/api/apartments/pages`
+- etc.
+
+The API routes automatically read these server-side environment variables:
+- `MORE_APARTMENTS_BASE_URL` - Your actual backend URL
+- `MORE_APARTMENTS_API_KEY` - Your secret API key
+- `MORE_APARTMENTS_INSTANCE` - Your instance identifier
+
+## Advanced Features
+
+### Global Client Access
+
+When `injectClient` is enabled, a global object is available in the browser:
+
+```js
+// In client-side scripts
+if (window.__moreApartments) {
+  console.log('API Base URL:', window.__moreApartments.baseUrl);
+  console.log('Instance:', window.__moreApartments.instance);
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT