Hospitable Ops

---

name: hospitable-ops description: Operate, debug, and automate Hospitable via Public API with a safe read-first workflow and non-price calendar controls. Use when working with Hospitable properties, reservations, calendar reads, write verification, blocking/unblocking dates, check-in/check-out restrictions, property mapping, or cross-channel automation logic around Airbnb/Booking/Hospitable. Especially use for: (1) verifying Hospitable API auth and endpoints, (2) exporting properties/reservations/calendar, (3) testing or applying non-price calendar writes, (4) building Hospitable-based automation/reporting, (5) debugging delayed sync or write semantics.

---

Hospitable Ops

Use Hospitable as the unified operational base. Prefer read-first, then safe write verification, then controlled non-price writes.

Core rules

Treat Hospitable as the system of operational judgment, especially for unified property UUIDs, calendar state, reservations, and parent/child exclusion logic.

Never expose tokens in chat, logs, screenshots, or shared files.

Use Hospitable Public API v2 as the only active execution path for reads and automation in this workspace.

MCP has been removed from the current Hospitable operating path; do not route or describe Hospitable work through MCP.

Use persistent config or local scripts; avoid session-only ad hoc setup when building repeatable workflows.

Default to non-price actions only. Price, currency, and money-related changes must be discussed first and then changed manually by the human.

Assume write effects may be asynchronous. Do not judge failure from an immediate readback alone.

In this workspace, do not rely on OpenClaw runtime inheriting shell env automatically; prefer script-level loading from /Users/admin-ai/.openclaw/workspace-qiang/.env.local for repeatable Hospitable execution.

HOSPITABLE_TOKEN must contain the token body only; never include a leading Bearer prefix in the env value.

Standard workflow

1. Verify HOSPITABLE_TOKEN is available in the current execution environment without printing it. 2. If runtime inheritance is uncertain, use local script loading from .env.local instead of re-debugging shell/profile inheritance. 3. Read data first: - properties - reservations - calendar 4. Save JSON with statusCode and body envelope. 5. Build operational judgments from Hospitable first; layer Booking/Airbnb exceptions after. 6. For writes, probe safely: - identify method - identify minimal body - test on low-risk future date - re-read after delay 7. Only after semantics are clear, apply controlled non-price changes.

Known API behavior

Read

Use bearer auth plus Accept: application/json.

Current workspace rule:

default to the current validated token

treat older/previous Hospitable tokens as deprecated unless the human explicitly restores one

prefer local env file loading over shell-history fallback or session-only manual export

Common read paths:

properties

reservations?properties[]=

properties//calendar?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

Runtime inheritance readback (validated)

Validated facts in this workspace:

host-side token is valid and can return statusCode: 200 on properties

OpenClaw agent runtime did not automatically inherit HOSPITABLE_TOKEN

repeatable workaround: load /Users/admin-ai/.openclaw/workspace-qiang/.env.local directly inside Hospitable scripts

after enabling script-level env loading, node scripts/hospitable-read.js properties --per-page 1 returned statusCode: 200

Current script CLI contract

/Users/admin-ai/.openclaw/workspace-qiang/scripts/hospitable-read.js

Supported commands:

properties [--per-page N]

reservations --property [--per-page N]

calendar --property --start YYYY-MM-DD --end YYYY-MM-DD

Important:

calendar uses --start and --end

do not use --start-date / --end-date with this script

keep #!/usr/bin/env node on line 1 if editing the script header

Write

For calendar writes:

route: properties//calendar

supported method: PUT

PATCH is not supported

request body must include dates

minimal accepted structure:

{
  "dates": [
    { "date": "YYYY-MM-DD" }
  ]
}

Verified non-price semantics

#### Block a whole date

{
  "dates": [
    { "date": "YYYY-MM-DD", "available": false }
  ]
}

Expected eventual readback:

status.reason = BLOCKED

status.source = api

status.source_type = VENDOR

status.available = false

#### Restrict check-in / check-out

{
  "dates": [
    {
      "date": "YYYY-MM-DD",
      "closed_for_checkin": true,
      "closed_for_checkout": true
    }
  ]
}

Expected eventual readback:

closed_for_checkin = true

closed_for_checkout = true

day may still remain AVAILABLE

Operational boundaries

Allowed direct actions

non-price calendar block/unblock

check-in/check-out restrictions

non-price operational lock windows

parent/child exclusion enforcement

cross-channel conflict prevention using non-price controls

one-time cleanup of legacy order occupancy when the business rule is already confirmed

Human-only actions

price

currency

money-related changes

pricing strategy decisions

Long-term operating model

Reduce the property system into three stable forms whenever possible: 1. Airbnb-only 2. dual-channel managed by Hospitable native mechanisms 3. main-house gate open/closed

Treat legacy exceptions as temporary cleanup layers, not permanent structure.

Current NXM cleanup model

mute(booking) is a historical order source only and should not take new sales.

206 -> 201 is a temporary operational occupancy transfer caused by legacy mute orders.

customer-visible order display can remain original while operational occupancy moves internally for anti-overbooking control.

after cleanup, return to the three stable forms above.

Recommended local files

scripts/hospitable-read.js

scripts/hospitable-write-probe.js

exported JSON snapshots with statusCode/body

rule config files for object tiers and lock windows

Delay-aware verification

After a write returns 202 accepted: 1. wait before declaring failure 2. re-read the same date window 3. compare operational fields, not only high-level availability 4. check whether the change is semantic (blocked vs closed_for_checkin/checkout)

Good output pattern

Report in this order: 1. current status 2. exact object/date tested 3. request accepted or rejected 4. delayed readback result 5. operational conclusion 6. single biggest remaining gap