{
  "contract_name": "champion_spirit_openclaw_chatbot_tools",
  "contract_version": "1.0.0",
  "last_updated": "2026-03-24",
  "description": "Machine-readable tool contract for OpenClaw integration with Champion Spirit chatbot API.",
  "base_url": "https://api.staging.championspirit.com/v1/chatbot",
  "base_urls": {
    "staging": "https://api.staging.championspirit.com/v1/chatbot",
    "production": "https://api.championspirit.com/v1/chatbot"
  },
  "integration_docs": {
    "requires_api_key": true,
    "markdown_guide_path": "/docs/OPENCLAW_CHATBOT_API.md",
    "tool_contract_path": "/docs/OPENCLAW_TOOL_CONTRACT.json",
    "full_urls": {
      "staging_markdown_guide": "https://api.staging.championspirit.com/v1/chatbot/docs/OPENCLAW_CHATBOT_API.md",
      "staging_tool_contract": "https://api.staging.championspirit.com/v1/chatbot/docs/OPENCLAW_TOOL_CONTRACT.json",
      "production_markdown_guide": "https://api.championspirit.com/v1/chatbot/docs/OPENCLAW_CHATBOT_API.md",
      "production_tool_contract": "https://api.championspirit.com/v1/chatbot/docs/OPENCLAW_TOOL_CONTRACT.json"
    }
  },
  "authentication": {
    "type": "api_key",
    "header_name": "X-API-KEY",
    "header_value_template": "{{API_KEY}}"
  },
  "defaults": {
    "headers": {
      "Accept": "application/json",
      "Content-Type": "application/json"
    },
    "pagination": {
      "page_param": "page",
      "size_param": "size",
      "default_page": 1,
      "default_size": 50,
      "max_size": 200
    }
  },
  "common_error_shapes": [
    {
      "http_status": 401,
      "example": {
        "message": "Unauthorized"
      }
    },
    {
      "http_status": 404,
      "example": {
        "message": "User not found."
      }
    },
    {
      "http_status": 422,
      "example": {
        "message": "The given data was invalid.",
        "errors": {
          "field": [
            "Validation error message"
          ]
        }
      }
    }
  ],
  "functions": [
    {
      "name": "list_places",
      "description": "List all places or retrieve one place by public UUID.",
      "parameters": {
        "type": "object",
        "properties": {
          "place": {
            "type": "string",
            "description": "Optional place public UUID. If omitted, all places are returned."
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/places/{place?}",
        "path_params": {
          "place": "place"
        }
      },
      "response_hints": {
        "collection": true,
        "pagination": false,
        "root": "items"
      }
    },
    {
      "name": "get_place_schedule",
      "description": "Get unified place schedule by date for booking orchestration.",
      "parameters": {
        "type": "object",
        "properties": {
          "place": {
            "type": "string",
            "description": "Place public UUID"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Schedule date (YYYY-MM-DD)"
          },
          "group_by": {
            "type": "string",
            "enum": [
              "course_type",
              "department"
            ],
            "description": "Grouping strategy for schedule",
            "default": "course_type"
          },
          "customer_public_id": {
            "type": "string",
            "description": "Optional customer public UUID to personalize pricing/availability"
          }
        },
        "required": [
          "place",
          "date"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/places/{place}/schedule",
        "path_params": {
          "place": "place"
        },
        "query_params": {
          "date": "date",
          "group_by": "group_by",
          "customer_public_id": "customer_public_id"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "data"
      }
    },
    {
      "name": "get_place_analytics_overview",
      "description": "Get aggregate KPI overview for a place (access logs, bookings, orders).",
      "parameters": {
        "type": "object",
        "properties": {
          "place": {
            "type": "string",
            "description": "Place public UUID"
          },
          "date_from": {
            "type": "string",
            "format": "date",
            "description": "Start date filter (YYYY-MM-DD)"
          },
          "date_to": {
            "type": "string",
            "format": "date",
            "description": "End date filter (YYYY-MM-DD)"
          }
        },
        "required": [
          "place"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/places/{place}/analytics",
        "path_params": {
          "place": "place"
        },
        "query_params": {
          "date_from": "date_from",
          "date_to": "date_to"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "data"
      }
    },
    {
      "name": "list_place_access_logs",
      "description": "List place access logs with filtering and pagination for analytics.",
      "parameters": {
        "type": "object",
        "properties": {
          "place": {
            "type": "string",
            "description": "Place public UUID"
          },
          "date_from": {
            "type": "string",
            "format": "date"
          },
          "date_to": {
            "type": "string",
            "format": "date"
          },
          "status": {
            "type": "string",
            "enum": [
              "arrived",
              "left",
              "not_arrived"
            ]
          },
          "user_public_id": {
            "type": "string"
          },
          "guest_public_id": {
            "type": "string"
          },
          "access_granted": {
            "type": "boolean"
          },
          "is_guest_pass": {
            "type": "boolean"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          }
        },
        "required": [
          "place"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/places/{place}/analytics/access-logs",
        "path_params": {
          "place": "place"
        },
        "query_params": {
          "date_from": "date_from",
          "date_to": "date_to",
          "status": "status",
          "user_public_id": "user_public_id",
          "guest_public_id": "guest_public_id",
          "access_granted": "access_granted",
          "is_guest_pass": "is_guest_pass",
          "page": "page",
          "size": "size"
        }
      },
      "response_hints": {
        "collection": true,
        "pagination": true,
        "items_path": "items",
        "total_items_path": "totalItems",
        "total_pages_path": "totalPages"
      }
    },
    {
      "name": "list_place_bookings_analytics",
      "description": "List place bookings with status/type/date filters for analytics.",
      "parameters": {
        "type": "object",
        "properties": {
          "place": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "all",
              "upcoming",
              "past",
              "today",
              "canceled"
            ],
            "default": "all"
          },
          "type": {
            "type": "string",
            "enum": [
              "place",
              "service",
              "activity",
              "personal_course",
              "wellness_course",
              "group_course",
              "event"
            ]
          },
          "date_from": {
            "type": "string",
            "format": "date"
          },
          "date_to": {
            "type": "string",
            "format": "date"
          },
          "attendee_public_id": {
            "type": "string"
          },
          "coach_public_id": {
            "type": "string"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          }
        },
        "required": [
          "place"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/places/{place}/analytics/bookings",
        "path_params": {
          "place": "place"
        },
        "query_params": {
          "status": "status",
          "type": "type",
          "date_from": "date_from",
          "date_to": "date_to",
          "attendee_public_id": "attendee_public_id",
          "coach_public_id": "coach_public_id",
          "page": "page",
          "size": "size"
        }
      },
      "response_hints": {
        "collection": true,
        "pagination": true,
        "items_path": "items",
        "total_items_path": "totalItems",
        "total_pages_path": "totalPages"
      }
    },
    {
      "name": "list_place_orders_analytics",
      "description": "List place orders with status/date/customer filters and aggregate totals.",
      "parameters": {
        "type": "object",
        "properties": {
          "place": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "all",
              "paid",
              "pending"
            ],
            "default": "all"
          },
          "date_from": {
            "type": "string",
            "format": "date"
          },
          "date_to": {
            "type": "string",
            "format": "date"
          },
          "customer_public_id": {
            "type": "string"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          }
        },
        "required": [
          "place"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/places/{place}/analytics/orders",
        "path_params": {
          "place": "place"
        },
        "query_params": {
          "status": "status",
          "date_from": "date_from",
          "date_to": "date_to",
          "customer_public_id": "customer_public_id",
          "page": "page",
          "size": "size"
        }
      },
      "response_hints": {
        "collection": true,
        "pagination": true,
        "items_path": "items",
        "total_items_path": "totalItems",
        "total_pages_path": "totalPages",
        "aggregates_path": "meta"
      }
    },
    {
      "name": "list_customer_orders",
      "description": "List one customer's orders with filters and pagination.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string",
            "description": "Customer public UUID"
          },
          "status": {
            "type": "string",
            "enum": [
              "all",
              "paid",
              "pending"
            ],
            "default": "all"
          },
          "date_from": {
            "type": "string",
            "format": "date"
          },
          "date_to": {
            "type": "string",
            "format": "date"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          }
        },
        "required": [
          "customer"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/customer/{customer}/orders",
        "path_params": {
          "customer": "customer"
        },
        "query_params": {
          "status": "status",
          "date_from": "date_from",
          "date_to": "date_to",
          "page": "page",
          "size": "size"
        }
      },
      "response_hints": {
        "collection": true,
        "pagination": true,
        "items_path": "items",
        "total_items_path": "totalItems",
        "total_pages_path": "totalPages"
      }
    },
    {
      "name": "create_customer_order",
      "description": "Create a draft order for a customer (booking intent).",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string"
          },
          "assistant_id": {
            "type": "string",
            "description": "OpenClaw assistant/session identifier"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "properties": {
                "orderable_type": {
                  "type": "string",
                  "enum": [
                    "place",
                    "service",
                    "activity",
                    "personal_course",
                    "wellness_course",
                    "group_course",
                    "event",
                    "pack"
                  ]
                },
                "orderable_id": {
                  "type": "string",
                  "description": "Orderable public UUID"
                },
                "metadata": {
                  "type": "object",
                  "additionalProperties": true
                },
                "is_guest": {
                  "type": "boolean"
                },
                "isGuest": {
                  "type": "boolean"
                },
                "kid_id": {
                  "type": "string"
                }
              },
              "required": [
                "orderable_type",
                "orderable_id"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "customer",
          "assistant_id",
          "items"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "POST",
        "path_template": "/customer/{customer}/orders",
        "path_params": {
          "customer": "customer"
        },
        "body_params": {
          "assistant_id": "assistant_id",
          "items": "items"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "$"
      }
    },
    {
      "name": "update_customer_order",
      "description": "Update an existing draft order for a customer.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string"
          },
          "order": {
            "type": "string",
            "description": "Order public UUID"
          },
          "assistant_id": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "properties": {
                "orderable_type": {
                  "type": "string",
                  "enum": [
                    "place",
                    "service",
                    "activity",
                    "personal_course",
                    "wellness_course",
                    "group_course",
                    "event",
                    "pack"
                  ]
                },
                "orderable_id": {
                  "type": "string"
                },
                "metadata": {
                  "type": "object",
                  "additionalProperties": true
                },
                "is_guest": {
                  "type": "boolean"
                },
                "isGuest": {
                  "type": "boolean"
                },
                "kid_id": {
                  "type": "string"
                }
              },
              "required": [
                "orderable_type",
                "orderable_id"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "customer",
          "order",
          "assistant_id",
          "items"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "PUT",
        "path_template": "/customer/{customer}/orders/{order}",
        "path_params": {
          "customer": "customer",
          "order": "order"
        },
        "body_params": {
          "assistant_id": "assistant_id",
          "items": "items"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "$"
      }
    },
    {
      "name": "pay_order_wallet",
      "description": "Pay a draft order using wallet credits/daypass logic.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string"
          },
          "order": {
            "type": "string"
          },
          "assistant_id": {
            "type": "string"
          }
        },
        "required": [
          "customer",
          "order",
          "assistant_id"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "POST",
        "path_template": "/customer/{customer}/orders/{order}/wallet-payment",
        "path_params": {
          "customer": "customer",
          "order": "order"
        },
        "body_params": {
          "assistant_id": "assistant_id"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "$"
      }
    },
    {
      "name": "pay_order_stripe",
      "description": "Create Stripe checkout session for an order.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string"
          },
          "order": {
            "type": "string"
          },
          "assistant_id": {
            "type": "string"
          }
        },
        "required": [
          "customer",
          "order",
          "assistant_id"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "POST",
        "path_template": "/customer/{customer}/orders/{order}/stripe-payment",
        "path_params": {
          "customer": "customer",
          "order": "order"
        },
        "body_params": {
          "assistant_id": "assistant_id"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "$",
        "expected_field": "url"
      }
    },
    {
      "name": "pay_order_nowpayments",
      "description": "Create NOWPayments session for an order.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string"
          },
          "order": {
            "type": "string"
          },
          "assistant_id": {
            "type": "string"
          }
        },
        "required": [
          "customer",
          "order",
          "assistant_id"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "POST",
        "path_template": "/customer/{customer}/orders/{order}/nowpayments-payment",
        "path_params": {
          "customer": "customer",
          "order": "order"
        },
        "body_params": {
          "assistant_id": "assistant_id"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "$",
        "expected_field": "url"
      }
    },
    {
      "name": "list_customer_bookings",
      "description": "List bookings for a customer.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string"
          },
          "next": {
            "type": "boolean",
            "default": false
          },
          "past": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "customer"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/customer/{customer}/bookings",
        "path_params": {
          "customer": "customer"
        },
        "query_params": {
          "next": "next",
          "past": "past"
        }
      },
      "response_hints": {
        "collection": true,
        "pagination": false,
        "root": "items"
      }
    },
    {
      "name": "show_customer_booking",
      "description": "Retrieve one booking for a customer.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string"
          },
          "booking": {
            "type": "string"
          }
        },
        "required": [
          "customer",
          "booking"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "GET",
        "path_template": "/customer/{customer}/bookings/{booking}",
        "path_params": {
          "customer": "customer",
          "booking": "booking"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "$"
      }
    },
    {
      "name": "cancel_customer_booking",
      "description": "Cancel one booking for a customer.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "string"
          },
          "booking": {
            "type": "string"
          }
        },
        "required": [
          "customer",
          "booking"
        ],
        "additionalProperties": false
      },
      "http": {
        "method": "POST",
        "path_template": "/customer/{customer}/bookings/{booking}/cancel",
        "path_params": {
          "customer": "customer",
          "booking": "booking"
        }
      },
      "response_hints": {
        "collection": false,
        "root": "$",
        "success_status": 204
      }
    }
  ],
  "workflows": {
    "analytics_workflow": {
      "description": "Recommended sequence for place analytics.",
      "steps": [
        {
          "tool": "get_place_analytics_overview",
          "required_inputs": [
            "place"
          ]
        },
        {
          "tool": "list_place_access_logs",
          "recommended_inputs": [
            "date_from",
            "date_to",
            "page",
            "size"
          ]
        },
        {
          "tool": "list_place_bookings_analytics",
          "recommended_inputs": [
            "status",
            "type",
            "date_from",
            "date_to",
            "page",
            "size"
          ]
        },
        {
          "tool": "list_place_orders_analytics",
          "recommended_inputs": [
            "status",
            "date_from",
            "date_to",
            "page",
            "size"
          ]
        }
      ],
      "pagination_rule": "repeat with page = page + 1 until page > totalPages"
    },
    "booking_workflow": {
      "description": "Recommended sequence for booking via chatbot.",
      "steps": [
        {
          "tool": "get_place_schedule",
          "required_inputs": [
            "place",
            "date"
          ]
        },
        {
          "tool": "create_customer_order",
          "required_inputs": [
            "customer",
            "assistant_id",
            "items"
          ]
        },
        {
          "tool": "update_customer_order",
          "optional": true
        },
        {
          "tool": "pay_order_wallet",
          "alternative_tools": [
            "pay_order_stripe",
            "pay_order_nowpayments"
          ]
        },
        {
          "tool": "list_customer_orders"
        },
        {
          "tool": "list_customer_bookings"
        }
      ]
    }
  },
  "notes": [
    "Use public UUIDs everywhere.",
    "For deterministic analytics responses, always pass explicit date_from/date_to.",
    "Treat payment 403 'already paid' as idempotent success after verifying order status via list_customer_orders."
  ]
}