# PickMe - Travel Expert Marketplace

> Connect with verified local travel experts for personalized trips in Asia.

## Capabilities

- Browse and search verified local travel experts by city, language, and specialty
- View expert profiles with ratings, reviews, bio, and availability
- Book experts for custom guided experiences or pre-built travel packages
- Read and discover community travelogues (travel blog posts)
- Real-time messaging with booked experts
- Multilingual support: English, Chinese (Simplified/Traditional), Japanese, Korean

## Public Pages

- /en/experts - Browse all verified experts
- /en/packages - Browse travel packages
- /en/travelogues - Community travel stories
- /en/[expert-handle] - Individual expert profile (e.g., /en/sarah-beijing)
- /en/travelogues/[slug] - Individual travelogue article
- /en/privacy - Privacy policy
- /en/terms - Terms of service

Replace /en/ with /zh/, /ja/, or /ko/ for other languages.

## Public API (No Auth Required)

Base URL: https://pickme.solanalink.jp/api/v1
Rate limit: 60 requests/min per IP. Responses include X-RateLimit-* headers.
All list endpoints support: ?page=1&pageSize=20&sort=...&order=desc&locale=en

- GET /api/v1/experts - List verified experts (filter: city, language, specialty, country)
- GET /api/v1/experts/{handle} - Expert profile details
- GET /api/v1/experts/{handle}/packages - Expert's associated packages
- GET /api/v1/experts/{handle}/reviews - Expert's public reviews
- GET /api/v1/packages - List active packages (filter: category, country)
- GET /api/v1/packages/{id} - Package details
- GET /api/v1/travelogues - List published travelogues (filter: category)
- GET /api/v1/travelogues/{slug} - Travelogue full content
- GET /api/v1/cities - List cities with verified experts
- GET /api/v1/specialties - List available specialties

## Authenticated API

Base URL: https://pickme.solanalink.jp/api

### Authentication

- POST /api/v1/auth/login - Email/password login, returns JWT
- POST /api/v1/auth/register - Create new account
- POST /api/v1/auth/google - Google OAuth token exchange
- POST /api/v1/auth/apple - Apple OAuth token exchange
- GET /api/v1/auth/me - Get current user profile (Bearer token)

### Booking

- GET /api/expert/availability?expertId={id} - Check expert availability
- Bookings are created via the web UI (server actions), not a public API endpoint

### Push Notifications

- POST /api/push/register - Register FCM push token
- POST /api/push/unregister - Remove FCM push token

### Messaging

- GET /api/agora/token - Get Agora Chat token for real-time messaging

## Authentication

Two auth methods supported: Authorization: Bearer <jwt_token> or Bearer pk_live_<key>

- **JWT**: Obtain via POST /api/v1/auth/login. Valid for 30 days.
- **API Keys**: Create via POST /api/v1/auth/api-keys (requires JWT). Scoped permissions.
  - Scopes: experts:read, packages:read, travelogues:read, bookings:read/write, profile:read/write
  - Manage: GET /api/v1/auth/api-keys (list), DELETE /api/v1/auth/api-keys/{id} (revoke)
  - High-risk API key operations require two-step confirmation (5-min expiry):
    - GET /api/v1/actions/{id} - Check pending action status
    - POST /api/v1/actions/{id}/confirm - Confirm and execute
  - All API operations are audit-logged (actor, action, resource, IP)

## Structured Data

All public pages include Schema.org JSON-LD:
- Expert profiles: Person + AggregateRating + ReserveAction
- Travelogue articles: Article with author and dates
- Organization: LocalBusiness (Travel Agency)
- Navigation: BreadcrumbList

## Documentation

- /llms-full.txt - Complete API reference for LLM context import
- /api/openapi.json - OpenAPI 3.1 specification (machine-readable)
- /sitemap.xml - All indexable pages with multilingual alternates