Skip to content

hubbyesim/camino

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
camino-bot
camino-bot
 
 
camino-partner-plugin
camino-partner-plugin
 
 
README.md
README.md
 
 

Repository files navigation

Hubby CMP Integration

Complete setup guide for the Camino Messenger Protocol (CMP) integration with Hubby eSIM API.

Overview

This repository contains two components that enable Hubby to integrate with the Camino travel network:

  1. Partner Plugin (camino-partner-plugin/) - A gRPC server that bridges Camino Messenger Bots with the Hubby API
  2. Bot Configuration (camino-bot/) - Docker configuration for running Camino Messenger Bots
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Camino Network (Matrix)                            │
│                        messenger.chain4travel.com                            │
└─────────────────────────────────────┬───────────────────────────────────────┘
                                      │
              ┌───────────────────────┼───────────────────┐
              │                       │                   │
              ▼                       ▼                   ▼
    ┌─────────────────┐     ┌─────────────────┐  ┌─────────────────┐
    │    External     │     │ Your Supplier   │  │ Your Distributor│
    │   Distributors  │     │ Bot (Docker)    │  │ Bot (Docker)    │
    └─────────────────┘     └────────┬────────┘  └─────────────────┘
                                     │
                                     │ gRPC (port 50051)
                                     ▼
                            ┌─────────────────┐
                            │ Partner Plugin  │  ◄── This repo
                            │  (Node.js)      │
                            └────────┬────────┘
                                     │
                                     │ HTTP/REST
                                     ▼
                            ┌─────────────────┐
                            │   Hubby API     │  ◄── backend-hubby
                            │   (Firebase)    │
                            └─────────────────┘

Prerequisites

  • Node.js >= 18
  • Docker and Docker Compose
  • grpcurl (for testing): brew install grpcurl
  • Access to Hubby API (Firebase emulator or deployed instance)

Repository Structure

hubby-cmp/
├── camino-partner-plugin/       # gRPC Partner Plugin
│   ├── src/                     # TypeScript source code
│   │   ├── api/                 # Hubby API client
│   │   ├── handlers/            # gRPC service handlers
│   │   ├── cache/               # Search result cache
│   │   ├── config.ts            # Configuration
│   │   └── server.ts            # gRPC server entry point
│   ├── proto/official/          # CMP protocol definitions (submodule)
│   ├── package.json
│   ├── tsconfig.json
│   ├── Dockerfile
│   └── docker-compose.yml
│
├── camino-bot/                  # Camino Messenger Bot config
│   ├── cmb-config/              # Bot configuration files
│   │   ├── supplier-config.yaml
│   │   └── distributor-config.yaml
│   ├── supplier-bot-db/         # Supplier bot database (auto-generated)
│   ├── distributor-bot-db/      # Distributor bot database (auto-generated)
│   ├── docker-compose.yml       # Bot containers
│   ├── e2e-test.sh              # End-to-end test script
│   └── TESTING.md               # Testing documentation
│
└── README.md                    # This file

Quick Start

1. Clone the Repository

git clone https://github.com/your-org/hubby-cmp.git
cd hubby-cmp

2. Start the Hubby API

The Partner Plugin requires the Hubby API to be running. If using Firebase Emulator:

cd /path/to/backend-hubby/functions
npm install
npm run serve

The API will be available at http://localhost:5001/hubby-esim-dev/europe-west4/api_v2

3. Start the Partner Plugin

cd camino-partner-plugin

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start the server
HUBBY_API_URL=http://localhost:5001/hubby-esim-dev/europe-west4/api_v2 npm run grpc:server

You should see:

═══════════════════════════════════════════════════════════════════
       CMP Partner Plugin - Standalone (v4)
═══════════════════════════════════════════════════════════════════

Hubby API URL:  http://localhost:5001/hubby-esim-dev/europe-west4/api_v2
Public API URL: http://localhost:5001/hubby-esim-dev/europe-west4/api_v2

  ✓ cmp.services.activity.v4.ActivitySearchService
  ✓ cmp.services.activity.v4.ActivityProductInfoService
  ✓ cmp.services.activity.v4.ActivityProductListService
  ✓ cmp.services.book.v4.ValidationService
  ✓ cmp.services.book.v4.MintService
  ✓ cmp.services.notification.v3.NotificationService

═══════════════════════════════════════════════════════════════════
  Server running on 0.0.0.0:50051
═══════════════════════════════════════════════════════════════════

4. Start the Supplier Bot

cd camino-bot

# Pull the latest bot image
docker-compose pull

# Start the supplier bot
docker-compose up supplier_bot

Important: Start services in this order:

  1. Hubby API (Firebase)
  2. Partner Plugin
  3. Supplier Bot (requires NotificationService on startup)

5. Verify the Setup

Test that the Partner Plugin is responding:

grpcurl -plaintext localhost:50051 list

Expected output:

cmp.services.activity.v4.ActivityProductInfoService
cmp.services.activity.v4.ActivityProductListService
cmp.services.activity.v4.ActivitySearchService
cmp.services.book.v4.MintService
cmp.services.book.v4.ValidationService
cmp.services.notification.v3.NotificationService
grpc.reflection.v1alpha.ServerReflection

Configuration

Partner Plugin Environment Variables

Variable Default Description
HUBBY_API_URL http://localhost:5001 Hubby REST API URL (internal)
PUBLIC_API_URL (falls back to HUBBY_API_URL) Public URL for NFT metadata (must be publicly accessible for blockchain)
GRPC_PORT 50051 gRPC server port
GRPC_HOST 0.0.0.0 gRPC server bind address

Example: Development with Firebase Emulator

HUBBY_API_URL=http://localhost:5001/hubby-esim-dev/europe-west4/api_v2 \
npm run grpc:server

Example: Production with ngrok (for NFT metadata)

HUBBY_API_URL=http://localhost:5001/hubby-esim-dev/europe-west4/api_v2 \
PUBLIC_API_URL=https://your-subdomain.ngrok.io/hubby-esim-dev/europe-west4/api_v2 \
npm run grpc:server

Bot Configuration

Bot configuration files are in camino-bot/cmb-config/:

supplier-config.yaml Key Settings

Setting Description
developer_mode Set to true for verbose logging
bot_key Private key for the bot (hex, no 0x prefix)
cm_account_address CM Account address on Camino Network
partner_plugin.host Partner Plugin address (use host.docker.internal:50051 in Docker)
partner_plugin.enabled Must be true if handling services
booking_token_address Booking Token smart contract address
chain_rpc_url Camino C-Chain RPC WebSocket URL

Services Implemented

The Partner Plugin implements these CMP v4 services:

Service Description
ActivitySearchService Search for eSIM products by location, dates
ActivityProductInfoService Get detailed product information
ActivityProductListService List all available products
ValidationService Validate a booking (locks price)
MintService Create a booking (mints NFT)
NotificationService Handle on-chain event notifications

Hubby API Endpoints

The Partner Plugin calls these Hubby API endpoints:

Method Endpoint Description
GET /api/partner/destinations List all destinations with bundles
GET /api/partner/destinations/:id Get single destination
POST /api/partner/validations Create a price validation
GET /api/partner/validations/:id Get validation details
POST /api/partner/bookings Create booking from validation
GET /api/partner/bookings/:id Get booking details
GET /api/partner/bookings/:id/metadata Get NFT metadata (ERC-721)

Testing

End-to-End Test Script

Run the automated e2e test:

cd camino-bot
./e2e-test.sh --verbose

Options:

--help          Show all options
--verbose       Show full JSON responses
--dry-run       Stop after validation (don't create booking)
--host HOST     Distributor host (default: 3.74.156.61:9090)

Manual Testing with grpcurl

# Search for eSIM products
grpcurl -plaintext -d '{
  "header": {"base_header": {"version": {"major": 4}}},
  "travellers": [{"traveller_id": 1, "type": "TRAVELLER_TYPE_ADULT"}]
}' localhost:50051 cmp.services.activity.v4.ActivitySearchService/ActivitySearch

# List all products
grpcurl -plaintext -d '{
  "header": {"base_header": {"version": {"major": 4}}}
}' localhost:50051 cmp.services.activity.v4.ActivityProductListService/ActivityProductList

Testing Hubby API Directly

# List destinations
curl http://localhost:5001/hubby-esim-dev/europe-west4/api_v2/api/partner/destinations

# Create validation
curl -X POST http://localhost:5001/hubby-esim-dev/europe-west4/api_v2/api/partner/validations \
  -H "Content-Type: application/json" \
  -d '{"destination_id": "ESP", "bundle_id": "DATA_LIMITED_1GB_TEST_ESP", "quantity": 1}'

Wallet Information (Columbus Testnet)

These wallets are for testing on the Columbus testnet:

Role Mnemonic
Partner eye multiply clump win seed hidden social ten menu poem shell knee valley sustain bright impact rely foam bullet orchard rough base enforce apology
Supplier quiz answer trap author innocent bar soft family layer close ocean seed tide deny exhibit enlist wealth bacon phone extend direct tower fat make
Distributor science explain kidney tip access nephew prosper rib voyage correct program hollow assault immense tray smile pudding dolphin vessel lava prepare together blind into
Entity CM Account Address
Supplier (Hubby) 0xe45ed0700e7d9c8e0cd338bfe86dd2fcd84bf2fc

Troubleshooting

Partner Plugin not starting

  • Check Node.js version: node -v (must be >= 18)
  • Verify HUBBY_API_URL is accessible
  • Check port 50051 is not in use

Bot can't connect to Partner Plugin

  • Ensure Partner Plugin is running on port 50051
  • In Docker, use host.docker.internal:50051 in partner_plugin.host
  • Verify with: grpcurl -plaintext localhost:50051 list

"NotificationService Unimplemented" error

Start the Partner Plugin before the Supplier Bot. The bot checks for pending notifications on startup.

"403 Forbidden" from external distributor

Your network may be blocked. Try from a different network or check firewall settings.

NFT metadata not showing on blockchain explorer

  • Ensure PUBLIC_API_URL is set to a publicly accessible URL
  • Use ngrok for local development: ngrok http 5001
  • Verify the metadata endpoint is accessible: curl $PUBLIC_API_URL/api/partner/bookings/{id}/metadata

Development

Partner Plugin Development

cd camino-partner-plugin

# Install dependencies
npm install

# Run in development mode (with ts-node)
npm run dev

# Build for production
npm run build

Proto Files

The CMP protocol definitions are in camino-partner-plugin/proto/official/. These are from the official CMP repository.

To update:

cd camino-partner-plugin/proto/official
git pull origin main

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages