@rentaltide/cli 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @rentaltide/cli
+
+Build apps for RentalTide without the deploy-paste-reinstall cycle.
+
+```bash
+npm install -g @rentaltide/cli
+
+rentaltide init my-app
+cd my-app && npm install
+rentaltide login
+rentaltide link
+npm run dev            # your app on localhost
+rentaltide dev         # your sandbox now renders it
+```
+
+## Why `dev` needs no tunnel
+
+Your app is an iframe on a RentalTide page, rendered by **your** browser — so
+`http://localhost:5173` resolves fine. `rentaltide dev` changes your app's embed
+URL to your local one, prints the sandbox links, and changes it back when you
+stop it.
+
+It refuses to do this to an **approved** app: repointing one that merchants have
+installed points all of them at your laptop.
+
+## Commands
+
+|                                |                                                                        |
+| ------------------------------ | ---------------------------------------------------------------------- |
+| `init [dir]`                   | Scaffold an app that already runs                                      |
+| `login` / `logout` / `whoami`  | Partner account, stored in `~/.rentaltide/credentials.json` (mode 600) |
+| `link`                         | Attach this directory to one of your apps                              |
+| `dev [--url <url>]`            | Point your sandbox at your local app                                   |
+| `push [--yes]`                 | Apply `rentaltide.app.json` to the app record, with a diff             |
+| `pull`                         | Write the app record back into `rentaltide.app.json`                   |
+| `webhook trigger <event>`      | Send yourself a signed webhook                                         |
+| `open [booking\|portal\|docs]` | Open a sandbox surface                                                 |
+
+## `rentaltide.app.json`
+
+Scopes and embed locations decide what your app may read and where it renders.
+In a web form they are invisible to review and the only record of a change is
+that it happened. In your repo they diff.
+
+```json
+{
+  "appId": "…",
+  "name": "Dock Weather",
+  "slug": "dock-weather",
+  "scopes": ["read:bookings", "read:customers"],
+  "embedLocations": ["order-details"],
+  "urls": { "embed": "https://dock-weather.example.com/embed" },
+  "dev": { "embedUrl": "http://localhost:5173" }
+}
+```
+
+`dev` is local and is never pushed.
+
+## Environment
+
+- `RENTALTIDE_API_URL` — defaults to `https://v3.api.rentaltide.com`
+- `RENTALTIDE_APP_URL` — defaults to `https://app.rentaltide.com`
+- `NO_COLOR` — honoured
+
+Docs: <https://docs.rentaltide.com/developers/>

package/dist/api.js

@@ -0,0 +1,101 @@
+/**
+ * The partner API, as the CLI sees it.
+ *
+ * One wrapper so every command reports a failure the same way, and so an
+ * expired token says "run rentaltide login" rather than "401".
+ */
+import { readCredentials, DEFAULT_API } from './config.js';
+import { fail } from './ui.js';
+export function apiUrl() {
+    return process.env.RENTALTIDE_API_URL || readCredentials()?.apiUrl || DEFAULT_API;
+}
+function token() {
+    const credentials = readCredentials();
+    if (!credentials?.token) {
+        fail('You are not signed in.', 'Run `rentaltide login`.');
+    }
+    return credentials.token;
+}
+export async function request(path, init = {}) {
+    const headers = { 'content-type': 'application/json' };
+    if (!init.anonymous)
+        headers.authorization = `Bearer ${token()}`;
+    let response;
+    try {
+        response = await fetch(`${apiUrl()}${path}`, {
+            method: init.method || 'GET',
+            headers,
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        });
+    }
+    catch (err) {
+        return fail(`Could not reach ${apiUrl()}.`, err instanceof Error ? err.message : 'Check your connection.');
+    }
+    const text = await response.text();
+    const data = text ? safeJson(text) : null;
+    if (response.status === 401) {
+        fail('Your session has expired.', 'Run `rentaltide login` again.');
+    }
+    if (!response.ok) {
+        const message = data?.message ||
+            data?.error ||
+            `${response.status} ${response.statusText}`;
+        fail(message);
+    }
+    return data;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text.slice(0, 300) };
+    }
+}
+/** Project config → the field names the API expects. */
+export function configToAppPayload(config) {
+    return {
+        appName: config.name,
+        appSlug: config.slug,
+        developerName: config.developerName,
+        description: config.description,
+        category: config.category,
+        requiredScopes: config.scopes,
+        embedLocations: config.embedLocations,
+        embedUrl: config.urls?.embed,
+        redirectUris: config.urls?.redirect,
+        webhookUrl: config.urls?.webhook,
+        settingsUrl: config.urls?.settings,
+        supportUrl: config.urls?.support,
+        privacyPolicyUrl: config.urls?.privacy,
+        termsUrl: config.urls?.terms,
+        documentationUrl: config.urls?.documentation,
+        apiUrl: config.urls?.api,
+    };
+}
+/** The API's shape → project config, for `pull`. */
+export function appToConfig(app, existing) {
+    return {
+        appId: app.appId,
+        name: app.appName,
+        slug: app.appSlug,
+        developerName: app.developerName,
+        description: app.description,
+        category: app.category,
+        scopes: app.requiredScopes || [],
+        embedLocations: app.embedLocations || [],
+        urls: {
+            embed: app.embedUrl,
+            redirect: app.redirectUris,
+            webhook: app.webhookUrl,
+            settings: app.settingsUrl,
+            support: app.supportUrl,
+            privacy: app.privacyPolicyUrl,
+            terms: app.termsUrl,
+            documentation: app.documentationUrl,
+            api: app.apiUrl,
+        },
+        // `dev` is local and is never pushed, so a pull must not erase it.
+        ...(existing?.dev ? { dev: existing.dev } : {}),
+    };
+}

package/dist/commands/auth.js

@@ -0,0 +1,37 @@
+/** login / logout / whoami. */
+import { apiUrl, request } from '../api.js';
+import { clearCredentials, readCredentials, writeCredentials } from '../config.js';
+import { ask, bold, dim, ok, say } from '../ui.js';
+export async function login() {
+    say(`Sign in to ${bold('partners.rentaltide.com')}`);
+    const email = await ask('Email:');
+    // Masked, and never written anywhere: the token it returns is what we keep.
+    const password = await ask('Password:', { mask: true });
+    const result = await request('/partners/login', {
+        method: 'POST',
+        body: { email, password },
+        anonymous: true,
+    });
+    writeCredentials({
+        token: result.token,
+        email: result.partner?.email || email,
+        partnerId: result.partner?.id,
+        apiUrl: apiUrl(),
+        savedAt: new Date().toISOString(),
+    });
+    ok(`Signed in as ${result.partner?.name || email}`);
+    say(dim('Token saved to ~/.rentaltide/credentials.json (readable only by you).'));
+}
+export async function logout() {
+    clearCredentials();
+    ok('Signed out.');
+}
+export async function whoami() {
+    const credentials = readCredentials();
+    if (!credentials) {
+        say('Not signed in. Run `rentaltide login`.');
+        return;
+    }
+    say(`${bold(credentials.email)}`);
+    say(dim(`partner ${credentials.partnerId || 'unknown'} · ${credentials.apiUrl}`));
+}

package/dist/commands/dev.js

@@ -0,0 +1,82 @@
+/**
+ * Point your sandbox at the app running on your laptop.
+ *
+ * The embed is an iframe rendered in YOUR browser, so a `http://localhost` URL
+ * resolves perfectly well — there is no tunnel here and none is needed. What
+ * was needed was somebody to change the app's embed URL and change it back,
+ * which is why this exists: before it, seeing a code change meant deploying
+ * somewhere public, pasting the URL into a form, and reinstalling.
+ *
+ * Two safety rules:
+ *
+ *  - It refuses on an APPROVED app. Repointing one of those at a laptop points
+ *    every merchant who installed it at a laptop.
+ *  - It restores the previous embed URL on exit, including Ctrl-C, and says so
+ *    if it could not.
+ */
+import { request } from '../api.js';
+import { requireAppConfig } from '../config.js';
+import { bold, cyan, dim, fail, ok, say, step, warn, yellow } from '../ui.js';
+const DEFAULT_DEV_URL = 'http://localhost:5173';
+export async function dev(args) {
+    const config = requireAppConfig();
+    if (!config.appId)
+        fail('This project is not linked yet.', 'Run `rentaltide link`.');
+    const flagIndex = args.findIndex((a) => a === '--url');
+    const devUrl = (flagIndex >= 0 ? args[flagIndex + 1] : undefined) || config.dev?.embedUrl || DEFAULT_DEV_URL;
+    const app = await request(`/developer/apps/${config.appId}`);
+    if (app.status === 'approved') {
+        fail(`${app.appName} is approved and installed by real merchants.`, 'Repointing its embed URL would point all of them at your laptop. Work on a draft copy instead.');
+    }
+    const previousEmbedUrl = app.embedUrl || '';
+    // A sandbox to install into. Both calls are idempotent.
+    step('Preparing your sandbox…');
+    const sandboxResponse = await request('/developer/sandbox', {
+        method: 'POST',
+    });
+    const sandbox = sandboxResponse.sandbox;
+    if (!sandbox)
+        fail('Could not create your sandbox.');
+    await request(`/developer/apps/${config.appId}/sandbox-install`, { method: 'POST' }).catch(() => undefined);
+    step(`Pointing ${app.appName} at ${bold(devUrl)}`);
+    await request(`/developer/apps/${config.appId}`, {
+        method: 'PUT',
+        body: { embedUrl: devUrl },
+    });
+    let restored = false;
+    const restore = async () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            await request(`/developer/apps/${config.appId}`, {
+                method: 'PUT',
+                body: { embedUrl: previousEmbedUrl },
+            });
+            say(`\n${dim(`Restored embed URL to ${previousEmbedUrl || '(empty)'}.`)}`);
+        }
+        catch {
+            // Said loudly: an app left pointing at a laptop renders nothing for
+            // anyone else, and the cause is invisible from the portal.
+            warn(`Could not restore the embed URL. Set it back to ${previousEmbedUrl || '(empty)'} in the portal.`);
+        }
+    };
+    process.on('SIGINT', () => void restore().then(() => process.exit(0)));
+    process.on('SIGTERM', () => void restore().then(() => process.exit(0)));
+    const appUrl = (process.env.RENTALTIDE_APP_URL || 'https://app.rentaltide.com').replace(/\/$/, '');
+    say();
+    ok(`${app.appName} is live in your sandbox.`);
+    say();
+    say(`  ${bold('Console')}      ${cyan(`${appUrl}`)}`);
+    say(`  ${bold('Booking page')} ${cyan(`${appUrl}/booking/customerId/${sandbox.customerId}`)}`);
+    say(`  ${bold('Embedding')}    ${devUrl}`);
+    say(`  ${bold('Locations')}    ${config.embedLocations.join(', ') || dim('(none declared)')}`);
+    say();
+    say(dim('Open the console from the partner portal → App Sandbox → Open sandbox console.'));
+    say(dim('Edit your app and refresh the page. No redeploy, no reinstall.'));
+    say();
+    say(yellow('Leave this running.') + dim(' Ctrl-C restores the embed URL.'));
+    // Nothing to poll: the page reloads from the developer's own dev server.
+    // This process exists to hold the restore handler.
+    await new Promise(() => { });
+}

package/dist/commands/init.js

@@ -0,0 +1,75 @@
+/**
+ * Scaffold an app that already runs.
+ *
+ * The template is deliberately small — one page, the SDK wired to the host,
+ * a live context readout and one API call — because the thing a developer
+ * needs on minute one is proof that the handshake works, not a framework.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeAppConfig } from '../config.js';
+import { ask, bold, dim, fail, ok, say } from '../ui.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+function templateDir() {
+    // dist/commands/init.js → package root → templates
+    const candidates = [
+        path.resolve(here, '../../templates/starter'),
+        path.resolve(here, '../templates/starter'),
+    ];
+    for (const dir of candidates)
+        if (fs.existsSync(dir))
+            return dir;
+    return fail('The starter template is missing from this install of the CLI.');
+}
+function copyTree(from, to, replace) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+        const source = path.join(from, entry.name);
+        // `_gitignore` ships under a name npm will not strip from the package.
+        const target = path.join(to, entry.name === '_gitignore' ? '.gitignore' : entry.name);
+        if (entry.isDirectory()) {
+            copyTree(source, target, replace);
+            continue;
+        }
+        const body = fs.readFileSync(source, 'utf8');
+        fs.writeFileSync(target, replace(body));
+    }
+}
+export async function init(args) {
+    const target = args.find((a) => !a.startsWith('-'));
+    const name = (await ask(`App name: ${dim('(e.g. Dock Weather)')}`)) || 'My RentalTide App';
+    const slug = (await ask(`Slug: ${dim(slugify(name))}`)) || slugify(name);
+    const dir = path.resolve(process.cwd(), target || slug);
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length > 0) {
+        fail(`${dir} already exists and is not empty.`);
+    }
+    copyTree(templateDir(), dir, (body) => body.replaceAll('__APP_NAME__', name).replaceAll('__APP_SLUG__', slug));
+    const config = {
+        name,
+        slug,
+        description: '',
+        category: 'Operations & Logistics',
+        scopes: ['read:bookings', 'read:customers'],
+        embedLocations: ['order-details'],
+        urls: { embed: 'https://example.com/embed' },
+        dev: { embedUrl: 'http://localhost:5173' },
+    };
+    writeAppConfig(config, dir);
+    ok(`Created ${bold(path.relative(process.cwd(), dir) || '.')}`);
+    say();
+    say('Next:');
+    say(`  ${bold(`cd ${path.relative(process.cwd(), dir) || '.'}`)}`);
+    say(`  ${bold('npm install')}`);
+    say(`  ${bold('rentaltide login')}      ${dim('once per machine')}`);
+    say(`  ${bold('rentaltide link')}       ${dim('pick the app this belongs to')}`);
+    say(`  ${bold('npm run dev')}           ${dim('in one terminal')}`);
+    say(`  ${bold('rentaltide dev')}        ${dim('in another — points your sandbox at it')}`);
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 60);
+}

package/dist/commands/link.js

@@ -0,0 +1,33 @@
+/** Attach this directory to one of your apps, and pull its config down. */
+import { appToConfig, request } from '../api.js';
+import { readAppConfig, requireAppConfig, writeAppConfig, CONFIG_FILENAME } from '../config.js';
+import { ask, bold, dim, fail, ok, say } from '../ui.js';
+async function listApps() {
+    const data = await request('/developer/apps');
+    return data.apps || [];
+}
+export async function link() {
+    const apps = await listApps();
+    if (apps.length === 0) {
+        fail('You have no apps yet.', 'Create one at partners.rentaltide.com → Developer → Apps.');
+    }
+    say('Your apps:');
+    apps.forEach((app, index) => {
+        say(`  ${bold(String(index + 1))}. ${app.appName} ${dim(`(${app.appSlug} · ${app.status})`)}`);
+    });
+    const answer = await ask(`Which one? ${dim('1-' + apps.length)}`);
+    const chosen = apps[Number(answer) - 1];
+    if (!chosen)
+        fail('That is not one of the options.');
+    const existing = readAppConfig();
+    writeAppConfig(appToConfig(chosen, existing));
+    ok(`Linked to ${chosen.appName}. Wrote ${CONFIG_FILENAME}.`);
+}
+export async function pull() {
+    const config = requireAppConfig();
+    if (!config.appId)
+        fail('This project is not linked yet.', 'Run `rentaltide link`.');
+    const app = await request(`/developer/apps/${config.appId}`);
+    writeAppConfig(appToConfig(app, config));
+    ok(`Pulled ${app.appName} into ${CONFIG_FILENAME}.`);
+}

package/dist/commands/open.js

@@ -0,0 +1,28 @@
+/** Open the sandbox surfaces without hunting for a URL. */
+import { spawn } from 'node:child_process';
+import { request } from '../api.js';
+import { bold, dim, fail, say } from '../ui.js';
+function openUrl(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    spawn(command, [url], { stdio: 'ignore', detached: true }).unref();
+}
+export async function open(args) {
+    const what = args[0] || 'booking';
+    const appUrl = (process.env.RENTALTIDE_APP_URL || 'https://app.rentaltide.com').replace(/\/$/, '');
+    if (what === 'portal') {
+        openUrl('https://partners.rentaltide.com/dashboard/developer');
+        return;
+    }
+    if (what === 'docs') {
+        openUrl('https://docs.rentaltide.com/developers/');
+        return;
+    }
+    const { sandbox } = await request('/developer/sandbox');
+    if (!sandbox) {
+        fail('You have no sandbox yet.', 'Run `rentaltide dev`, or create one in the portal.');
+    }
+    const url = `${appUrl}/booking/customerId/${sandbox.customerId}`;
+    say(`${bold('Opening')} ${url}`);
+    say(dim('The console needs a session — open it from the portal → App Sandbox.'));
+    openUrl(url);
+}

package/dist/commands/push.js

@@ -0,0 +1,59 @@
+/**
+ * Apply the project's config to the app record.
+ *
+ * Shows the diff and asks first. Scopes and embed locations decide what an app
+ * may read and where it renders; applying a change to them silently because a
+ * file moved is not a thing a tool should do.
+ */
+import { appToConfig, configToAppPayload, request } from '../api.js';
+import { requireAppConfig } from '../config.js';
+import { bold, confirm, dim, fail, green, ok, red, say } from '../ui.js';
+function flatten(value) {
+    if (Array.isArray(value))
+        return value.length ? value.join(', ') : '(none)';
+    if (value === undefined || value === null || value === '')
+        return '(none)';
+    return String(value);
+}
+export async function push(args) {
+    const config = requireAppConfig();
+    if (!config.appId)
+        fail('This project is not linked yet.', 'Run `rentaltide link`.');
+    const current = await request(`/developer/apps/${config.appId}`);
+    const before = appToConfig(current);
+    const fields = [
+        ['name', before.name, config.name],
+        ['description', before.description, config.description],
+        ['category', before.category, config.category],
+        ['scopes', before.scopes, config.scopes],
+        ['embedLocations', before.embedLocations, config.embedLocations],
+        ['urls.embed', before.urls?.embed, config.urls?.embed],
+        ['urls.webhook', before.urls?.webhook, config.urls?.webhook],
+        ['urls.settings', before.urls?.settings, config.urls?.settings],
+        ['urls.support', before.urls?.support, config.urls?.support],
+        ['urls.privacy', before.urls?.privacy, config.urls?.privacy],
+        ['urls.terms', before.urls?.terms, config.urls?.terms],
+        ['urls.redirect', before.urls?.redirect, config.urls?.redirect],
+    ];
+    const changed = fields.filter(([, a, b]) => flatten(a) !== flatten(b));
+    if (changed.length === 0) {
+        ok('Nothing to push — the app already matches this project.');
+        return;
+    }
+    say(`${bold('Changes to')} ${current.appName}:`);
+    for (const [field, a, b] of changed) {
+        say(`  ${field}`);
+        say(`    ${red('-')} ${dim(flatten(a))}`);
+        say(`    ${green('+')} ${flatten(b)}`);
+    }
+    say();
+    if (!args.includes('--yes') && !(await confirm('Apply?'))) {
+        say('Nothing pushed.');
+        return;
+    }
+    await request(`/developer/apps/${config.appId}`, {
+        method: 'PUT',
+        body: configToAppPayload(config),
+    });
+    ok('Pushed.');
+}

package/dist/commands/webhook.js

@@ -0,0 +1,29 @@
+/**
+ * Send yourself a signed webhook.
+ *
+ * Verifying a signature is the one part of a webhook integration that cannot
+ * be checked by reading the docs, and the only way to exercise it used to be
+ * to make a real booking happen.
+ */
+import { request } from '../api.js';
+import { requireAppConfig } from '../config.js';
+import { bold, dim, fail, ok, say } from '../ui.js';
+export async function webhook(args) {
+    const [sub, event] = args;
+    if (sub !== 'trigger' || !event) {
+        say(`Usage: ${bold('rentaltide webhook trigger <event>')}`);
+        say(dim('  e.g. rentaltide webhook trigger booking.created'));
+        return;
+    }
+    const config = requireAppConfig();
+    if (!config.appId)
+        fail('This project is not linked yet.', 'Run `rentaltide link`.');
+    if (!config.urls?.webhook) {
+        fail('No webhook URL in this project.', 'Add urls.webhook to rentaltide.app.json, then `rentaltide push`.');
+    }
+    const result = await request(`/developer/apps/${config.appId}/webhooks/test`, { method: 'POST', body: { event } });
+    if (result.delivered === false) {
+        fail(`Your endpoint did not accept it${result.status ? ` (${result.status})` : ''}.`, result.error);
+    }
+    ok(`Sent ${event} to ${config.urls.webhook}${result.status ? ` — ${result.status}` : ''}`);
+}

package/dist/config.js

@@ -0,0 +1,63 @@
+/**
+ * Where the CLI keeps its two kinds of state.
+ *
+ * Credentials are per MACHINE (`~/.rentaltide/credentials.json`, mode 600) and
+ * never in the project — a token committed to a repo is a partner account
+ * handed to whoever clones it.
+ *
+ * App config is per PROJECT (`rentaltide.app.json`) and belongs in the repo.
+ * Scopes and embed locations decide what an app may read and where it renders;
+ * typed into a web form they are invisible to review, and the only record of a
+ * change is that it happened. In the repo they diff.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export const CONFIG_FILENAME = 'rentaltide.app.json';
+export const DEFAULT_API = 'https://v3.api.rentaltide.com';
+const CREDENTIALS_DIR = path.join(os.homedir(), '.rentaltide');
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, 'credentials.json');
+export function readCredentials() {
+    try {
+        const raw = fs.readFileSync(CREDENTIALS_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed?.token ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCredentials(credentials) {
+    fs.mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2), { mode: 0o600 });
+}
+export function clearCredentials() {
+    try {
+        fs.unlinkSync(CREDENTIALS_FILE);
+    }
+    catch {
+        /* already gone */
+    }
+}
+export function configPath(cwd = process.cwd()) {
+    return path.join(cwd, CONFIG_FILENAME);
+}
+export function readAppConfig(cwd = process.cwd()) {
+    try {
+        return JSON.parse(fs.readFileSync(configPath(cwd), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeAppConfig(config, cwd = process.cwd()) {
+    fs.writeFileSync(configPath(cwd), `${JSON.stringify(config, null, 2)}\n`);
+}
+/** The config, or a message telling them exactly what to run. */
+export function requireAppConfig(cwd = process.cwd()) {
+    const config = readAppConfig(cwd);
+    if (!config) {
+        throw new Error(`No ${CONFIG_FILENAME} here. Run \`rentaltide init\` to start an app, or \`rentaltide link\` in an existing one.`);
+    }
+    return config;
+}

package/dist/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * The RentalTide app CLI.
+ *
+ * It exists for one reason: before it, seeing a code change in a real
+ * RentalTide meant deploying the app somewhere public, pasting the URL into a
+ * web form, and reinstalling. Every change. `rentaltide dev` makes it a file
+ * save.
+ */
+import { login, logout, whoami } from './commands/auth.js';
+import { link, pull } from './commands/link.js';
+import { push } from './commands/push.js';
+import { dev } from './commands/dev.js';
+import { init } from './commands/init.js';
+import { webhook } from './commands/webhook.js';
+import { open } from './commands/open.js';
+import { bold, dim, say } from './ui.js';
+const VERSION = '0.1.0';
+function usage() {
+    say(`${bold('rentaltide')} ${dim(VERSION)} — build apps for RentalTide`);
+    say();
+    say(bold('  Getting started'));
+    say(`    init [dir]              scaffold an app that already runs`);
+    say(`    login                   sign in to your partner account`);
+    say(`    link                    attach this directory to one of your apps`);
+    say();
+    say(bold('  Every day'));
+    say(`    dev [--url <url>]       point your sandbox at your local app`);
+    say(`    push [--yes]            apply rentaltide.app.json to the app record`);
+    say(`    pull                    write the app record into rentaltide.app.json`);
+    say(`    webhook trigger <event> send yourself a signed webhook`);
+    say(`    open [booking|portal|docs]`);
+    say();
+    say(bold('  Other'));
+    say(`    whoami                  who you are signed in as`);
+    say(`    logout`);
+    say();
+    say(dim('  Docs: https://docs.rentaltide.com/developers/cli/'));
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    switch (command) {
+        case 'init':
+            return init(args);
+        case 'login':
+            return login();
+        case 'logout':
+            return logout();
+        case 'whoami':
+            return whoami();
+        case 'link':
+            return link();
+        case 'pull':
+            return pull();
+        case 'push':
+            return push(args);
+        case 'dev':
+            return dev(args);
+        case 'webhook':
+            return webhook(args);
+        case 'open':
+            return open(args);
+        case '--version':
+        case '-v':
+            say(VERSION);
+            return;
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            return usage();
+        default:
+            say(`Unknown command: ${command}`);
+            say();
+            return usage();
+    }
+}
+main().catch((err) => {
+    // Commands report their own failures through `fail()`; anything reaching
+    // here is a bug, and a stack is more use than a friendly sentence.
+    process.stderr.write(`${err instanceof Error ? err.stack || err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/ui.js

@@ -0,0 +1,65 @@
+/**
+ * Terminal output and prompts.
+ *
+ * No dependencies: colour is four escape codes and a prompt is one readline.
+ * A CLI that pulls a tree of packages to print in green is a CLI that breaks
+ * when one of them is yanked.
+ */
+import readline from 'node:readline';
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (text) => (useColor ? `\x1b[${code}m${text}\x1b[0m` : text);
+export const bold = wrap('1');
+export const dim = wrap('2');
+export const green = wrap('32');
+export const yellow = wrap('33');
+export const red = wrap('31');
+export const cyan = wrap('36');
+export const say = (message = '') => process.stdout.write(`${message}\n`);
+export const ok = (message) => say(`${green('✓')} ${message}`);
+export const warn = (message) => say(`${yellow('!')} ${message}`);
+export const step = (message) => say(`${cyan('→')} ${message}`);
+/** Errors explain what went wrong and what to do about it, then exit 1. */
+export function fail(message, hint) {
+    process.stderr.write(`${red('✗')} ${message}\n`);
+    if (hint)
+        process.stderr.write(`  ${dim(hint)}\n`);
+    process.exit(1);
+}
+export async function ask(question, opts = {}) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    /**
+     * Resolve on EOF as well as on an answer.
+     *
+     * With piped stdin (a script, CI) the input ends and `question` never calls
+     * back. The promise then stays pending, the event loop empties, and Node
+     * exits 0 having done nothing — a command that silently succeeds at nothing
+     * is worse than one that fails.
+     */
+    const answered = (prompt) => new Promise((resolve) => {
+        rl.on('close', () => resolve(''));
+        rl.question(prompt, resolve);
+    });
+    if (!opts.mask) {
+        const answer = await answered(`${question} `);
+        rl.close();
+        return answer.trim();
+    }
+    // Masked input: readline echoes, so intercept the output stream for the
+    // duration. A password on screen is a password in a screen share.
+    const output = rl;
+    const original = output._writeToOutput.bind(output);
+    output._writeToOutput = (chunk) => {
+        if (chunk.includes(question))
+            return original(chunk);
+        return original('');
+    };
+    const answer = await answered(`${question} `);
+    output._writeToOutput = original;
+    rl.close();
+    say();
+    return answer.trim();
+}
+export async function confirm(question) {
+    const answer = await ask(`${question} ${dim('(y/N)')}`);
+    return /^y(es)?$/i.test(answer);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rentaltide/cli",
+  "version": "0.1.0",
+  "description": "Build RentalTide apps: scaffold, run against your sandbox, push config, trigger webhooks.",
+  "license": "MIT",
+  "author": "RentalTide Inc.",
+  "homepage": "https://docs.rentaltide.com/developers/cli/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RentalTide/RentalTide.git",
+    "directory": "packages/RentalTide-App-CLI"
+  },
+  "bugs": {
+    "url": "https://github.com/RentalTide/RentalTide/issues"
+  },
+  "type": "module",
+  "bin": {
+    "rentaltide": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/fix-esm-extensions.mjs && chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "rentaltide",
+    "cli",
+    "apps",
+    "developer"
+  ],
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/templates/starter/README.md

@@ -0,0 +1,21 @@
+# **APP_NAME**
+
+A RentalTide embedded app.
+
+```bash
+npm install
+npm run dev          # your app on http://localhost:5173
+
+rentaltide login     # once per machine
+rentaltide link      # attach this directory to your app
+rentaltide dev       # point your sandbox at localhost, and print where to look
+```
+
+Then open your sandbox and refresh after each change. No redeploy, no reinstall.
+
+- `rentaltide.app.json` — name, scopes, embed locations, URLs. `rentaltide push`
+  applies it; `rentaltide pull` brings the record back down.
+- `src/main.js` — the app. It reads context from the host and makes one
+  scope-checked API call.
+
+Docs: https://docs.rentaltide.com/developers/

package/templates/starter/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.DS_Store

package/templates/starter/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/templates/starter/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "__APP_SLUG__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5173",
+    "build": "vite build",
+    "preview": "vite preview --port 5173"
+  },
+  "dependencies": {
+    "@rentaltide/app-sdk": "^0.1.1"
+  },
+  "devDependencies": {
+    "vite": "^6.0.0"
+  }
+}

package/templates/starter/src/main.js

@@ -0,0 +1,65 @@
+/**
+ * __APP_NAME__ — a RentalTide embedded app.
+ *
+ * This runs inside an iframe on a RentalTide page. The SDK is how you talk to
+ * the page around you: it hands you the account, the location, the record the
+ * merchant is looking at, and the theme they are using, and it makes API calls
+ * on your behalf — scope-checked by the host, so your app never holds a
+ * credential.
+ */
+
+import { createApp } from '@rentaltide/app-sdk';
+
+const root = document.getElementById('root');
+
+async function start() {
+  // Resolves once the host has answered the handshake. If this hangs, the page
+  // is not embedding you — open it through RentalTide, not directly.
+  const app = await createApp();
+  const context = app.context;
+
+  render(context, null);
+
+  // Bookings the merchant can see. Requires the read:bookings scope, which is
+  // declared in rentaltide.app.json and granted at install.
+  try {
+    const bookings = await app.api.get('/bookings?limit=3');
+    render(context, bookings);
+  } catch (err) {
+    render(context, { error: String(err) });
+  }
+
+  // The merchant may switch location or open a different record without
+  // reloading you.
+  app.onContextChange((next) => render(next, null));
+}
+
+function render(context, data) {
+  const theme = context.theme || {};
+  document.body.style.margin = '0';
+  document.body.style.background = theme.background || '#fff';
+  document.body.style.color = theme.text || '#111';
+  document.body.style.fontFamily = theme.fontFamily || 'system-ui, sans-serif';
+
+  root.innerHTML = `
+    <div style="padding:16px">
+      <h1 style="font-size:15px;margin:0 0 12px">__APP_NAME__</h1>
+      <dl style="display:grid;grid-template-columns:auto 1fr;gap:4px 12px;font-size:13px;margin:0">
+        <dt style="opacity:.6">Account</dt><dd style="margin:0">${context.account?.businessName ?? '—'}</dd>
+        <dt style="opacity:.6">Location</dt><dd style="margin:0">${context.location?.name ?? '—'}</dd>
+        <dt style="opacity:.6">Where</dt><dd style="margin:0">${context.embedLocation ?? '—'}</dd>
+      </dl>
+      <pre style="margin:16px 0 0;padding:12px;border-radius:8px;overflow:auto;font-size:12px;background:${
+        theme.paper || 'rgba(0,0,0,.04)'
+      }">${data ? escapeHtml(JSON.stringify(data, null, 2)) : 'Loading bookings…'}</pre>
+    </div>
+  `;
+}
+
+function escapeHtml(value) {
+  return value.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
+}
+
+start().catch((err) => {
+  root.textContent = `Could not start: ${err.message}`;
+});