# PreviewLit

PreviewLit shows a homeowner their own house lit for the holidays, live, on their phone. You
send us the address of a house you are quoting. We build that house, and you get back a
private link to send the homeowner and a tag that puts the same house on your website.

This page is the whole setup. Everything below is an HTTP call or an HTML tag, so an AI
assistant given this page's address can do every step.

## 1. Send an address

```http
POST https://previewlit.com/api/houses
Content-Type: application/json

{"address": "1418 Maple St, Houston, TX 77006", "email": "you@your-company.com"}
```

- `address`: the street address you are quoting.
- `email`: where we can reach you about this house. It is never shown to anyone.

The answer is `202` with a request id:

```json
{"ok": true, "request": "3f9c…", "state": "queued", "status": "https://previewlit.com/api/houses/3f9c…"}
```

Each POST is a new request, so send an address once. We take 20 requests a day across everyone. Past that, the answer is `429` with
`"code": "DAILY_CAP"`; send it again the next day (UTC). A field that is wrong answers `422`
and says which.

## 2. Ask until it is a house

```http
GET https://previewlit.com/api/houses/<request>
```

An id we do not know answers `404`. Asking is the only way to hear: we send nothing when a
house is ready.

`state` is one of:

- `queued`: we have it and have not started.
- `building`: we are building the house.
- `refused`: we cannot build it; `reason` says why.
- `ready`: the house is live. The answer carries `project`, `link` and `embed`.

We build each house by hand, so there is no promised time. Ask every few hours, not every
few seconds.

```json
{"request": "3f9c…", "state": "ready", "project": "r-k7q2xm",
 "link": "https://previewlit.com/h/r-k7q2xm",
 "embed": "<script src=\"https://previewlit.com/embed.js\" data-project=\"r-k7q2xm\" async></script>"}
```

## 3. Send the homeowner the link

`link` opens the house lit, on a phone or a computer. The homeowner can switch between the
looks and change the colour and effect of each light. Everyone viewing a house sees the same
lights at once, so a change the homeowner makes shows for you too.

The link is private: no page lists it, and its id cannot be guessed. Anyone who has the link
can open it.

## 4. Put the house on your website

Paste `embed` where the house should appear. Good places are the page after a quote request
and your gallery.

```html
<script src="https://previewlit.com/embed.js" data-project="r-k7q2xm" async></script>
```

The tag puts the house where the tag is, full width at 4:3. Any website may show it.

## Events

The tag's frame emits these as DOM events, which bubble up to `document`. Each event's
`detail` is the message itself.

- `gl:ready`: the house has loaded. `detail.groups` lists its lights.
- `gl:built`: the live view is drawn.
- `gl:tap`: someone tapped a light. `detail.key` names its group, or is `null`.
- `gl:error`: the house could not load. `detail.message` says why.

```js
document.addEventListener("gl:ready", (e) => console.log(e.detail.groups.length, "lights"));
```

This page is also plain Markdown at https://previewlit.com/setup.md.