# Building a plugin

RatesSpot does rates, availability and bookings, the same way for every business. Everything else, from housekeeping and guest registration to invoices, reports, loyalty and channel managers, is a plugin: your own service that works through the public API and webhooks. Our own plugins follow the same rules.

## The rules

1. **Only the public API, webhooks and metadata.** There is no database access and no private hook, so whatever you build works on any RatesSpot business, hosted or self-hosted.
2. **Keep your own data.** Store your records (a guest's ID details, an invoice, a cleaning log) in your own database. On the RatesSpot object, keep only a reference in `metadata`.
3. **React to events instead of polling.** Subscribe to webhooks, and use `GET /v1/events` to catch up after downtime.
4. **Ask for the fewest scopes.** A report needs `payments:read`, not `bookings:list`.
5. **Removing your plugin never breaks bookings.** RatesSpot never waits on a plugin.

## Building blocks

| You need | Use |
|---|---|
| To hear when things happen | Your app's own [webhook](https://www.ratesspot.com/docs/webhooks.md) (`webhook` when you register it): one address for every business that installs you, filtered by each install's scopes. `booking.confirmed`, `booking.checked_in`, `booking.completed`, `payment.succeeded`, `refund.created`, `catalog.changed`, `customer.updated`… |
| To set up and clean up | `app.installed` when a business installs you; `app.uninstalled` (with `reason`) when its last connection to you ends, as your last delivery: stop, and delete that business's data within 30 days |
| To forget a person | `customer.erased`: delete everything you hold about that customer |
| To link your record to ours | `metadata` on bookings, customers, listings, units, rates, courses and the business: 50 string keys, set with `PATCH`, and an empty string removes a key |
| To find "your" objects again | `GET /v1/bookings?metadata=key:value`, `GET /v1/customers?metadata=key:value` |
| Guests | `GET /v1/customers` (search, with booking counts), `GET /v1/customers/{id}`, `GET /v1/bookings?customerId=` for their history |
| Units (rooms, desks…) | `GET /v1/catalog`: every listing's units with their metadata; `PATCH /v1/catalog/units/{id}` to set yours |
| Money | `GET /v1/payments?from=&to=`: every charge and refund with its method (card provider, cash, POS, transfer) |
| Credentials | An API key the business creates for you, or an [OAuth app](https://www.ratesspot.com/docs/oauth-apps.md) businesses install and can uninstall |

Prefix your metadata keys with your plugin's name (`acme_cleaning`), so two plugins never collide. The core never reads metadata, so availability and prices are unaffected by anything you store there.

## Pages in the dashboard

Staff shouldn't have to leave the dashboard to use your plugin. Declare **places** when you register your app (or later, `PATCH /v1/developer/apps/{id}`):

```json
"places": [
  { "kind": "page", "label": "Reports", "url": "https://reports.example.com/app", "roles": ["OWNER", "MANAGER"] },
  { "kind": "booking_panel", "label": "Notes", "url": "https://reports.example.com/panel" }
]
```

- At most one **page** (an item in the dashboard's Apps group; put your other screens in tabs inside it) and two **booking panels**. `roles` limits who sees each; omit it for everyone. Don't name a business in a label: the same app serves many.
- The dashboard shows your URL in a sandboxed frame with `?ratesspot_context=…`: which business, which staff member and role, which place, and the booking for a panel. Check it before showing anything:

```ts
import { verifyAppContext } from "@ratesspot/sdk";

const context = await verifyAppContext(url.searchParams.get("ratesspot_context"), { clientId: process.env.RATESSPOT_CLIENT_ID!, seen: (jti) => usedOnce(jti) });
if (!context) return new Response("Open this from the RatesSpot dashboard.", { status: 401 });
// Then call the API with your own install token for context.merchantId.
```

- A context is signed by RatesSpot for your app only and lasts 5 minutes; accept each `jti` once. Set your own session cookie after the first check, and send `Referrer-Policy: no-referrer` so the token doesn't leak in links.
- **Fit the frame.** The frame starts 480 pixels tall. Tell the dashboard your page's height, and again whenever it changes and whenever the dashboard asks (it sends `{ type: "ratesspot:measure" }` once it's listening, because a report sent before then is lost):

```js
const report = () => parent.postMessage({ type: "ratesspot:resize", height: document.documentElement.scrollHeight }, "https://app.ratesspot.com");
new ResizeObserver(report).observe(document.body);
addEventListener("message", (e) => { if (e.origin === "https://app.ratesspot.com" && e.data?.type === "ratesspot:measure") report(); });
```

## Telling staff something

An installed app can put a notification under the dashboard's bell: `POST /v1/staff-notifications` with your app token and `{ "title": "Studio 2 is ready", "body": "…", "bookingId": "…", "roles": ["FRONT_DESK"] }`. It links to the booking if you give one, otherwise to your app's page. Keep it to what needs a person: there's a limit of 50 a day per business. Our Housekeeping app does this when a unit someone arrives in today becomes ready.

## Listing your app

Once it works, list it in the app directory so any business can find it: open **Apps → Apps you've built → Directory listing** in the dashboard (or `PATCH /v1/developer/apps/{id}/listing`), add an icon, screenshots, a description, the permissions it asks for and an **install address** (yours, which starts your OAuth flow), then submit it. RatesSpot reviews every listing, and every change to one, before it's shown at ratesspot.com/apps and in the dashboard. Once listed, the consent screen refuses requests for more permissions than the listing says, so ask for exactly what you need. Listing is free; if you charge, link to your own pricing page (RatesSpot doesn't bill for apps).

## Three patterns

**Guest registration** (ID documents, nationality, emergency contact). On `booking.confirmed`, send the guest your own form. Store what they submit in your own database, then `PATCH /v1/customers/{id}` with `{ "metadata": { "acme_registration": "reg_123" } }`. When staff check the guest in (`booking.checked_in`), check that the registration exists. Personal details stay with you. If the business erases a customer you get `customer.erased` (just the `customerId`): you **must** delete your copy of their details then.

**Housekeeping.** On `booking.completed` (checkout), mark the booking's units dirty: `PATCH /v1/catalog/units/{unitId}` with `{ "metadata": { "acme_cleaning": "dirty" } }`. Your cleaners' app sets the unit back to `clean`. A unit out of service for repairs is a closure (`POST /v1/closures`), which RatesSpot itself respects.

**Reports and accounting.** Backfill with `GET /v1/payments` and `GET /v1/bookings?from=&to=`, then keep your ledger current from `payment.succeeded`, `refund.created` and `refund.sent`. Occupancy comes from `GET /v1/calendar`. Exports (PDF, spreadsheets) are yours to render. With only `payments:read` you see amounts and booking references, never guests' details, but you don't get payment events (they carry the booking, which needs `bookings:read`): read `GET /v1/payments` when you need it.

## Rules for your code

- Verify every webhook signature (`verifyWebhook` in `@ratesspot/sdk`), and skip an event `id` you've already handled.
- Amounts are integers in minor units next to a currency. Dates without a time are local to the business.
- If something can't be done with the API, that's a gap in RatesSpot, not something to work around. Open an issue describing what you're building.
