guesty-cli 1.0.0

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+export declare function invalidateToken(): void;
+export declare function getToken(): Promise<string>;

package/dist/auth.js

@@ -0,0 +1,156 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const CONFIG_DIR = join(homedir(), ".guesty-cli");
+const TOKEN_FILE = join(CONFIG_DIR, "token.json");
+const MAX_TOKENS_PER_DAY = 5;
+const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+let cached = { token: null, issued_timestamps: [] };
+let diskLoaded = false;
+function loadFromDisk() {
+    if (diskLoaded)
+        return;
+    try {
+        if (existsSync(TOKEN_FILE)) {
+            cached = JSON.parse(readFileSync(TOKEN_FILE, "utf8"));
+        }
+    }
+    catch {
+        cached = { token: null, issued_timestamps: [] };
+    }
+    diskLoaded = true;
+}
+function saveToDisk() {
+    try {
+        if (!existsSync(CONFIG_DIR)) {
+            mkdirSync(CONFIG_DIR, { recursive: true });
+        }
+        writeFileSync(TOKEN_FILE, JSON.stringify(cached, null, 2));
+    }
+    catch (e) {
+        process.stderr.write(`Warning: failed to save token cache: ${e}\n`);
+    }
+}
+function pruneOldTimestamps() {
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+    cached.issued_timestamps = cached.issued_timestamps.filter((t) => t > cutoff);
+}
+function hasSupabase() {
+    return !!(process.env.SUPABASE_URL && process.env.SUPABASE_SERVICE_ROLE_KEY);
+}
+async function getTokenFromSupabase() {
+    const url = process.env.SUPABASE_URL;
+    const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (!url || !key)
+        return null;
+    try {
+        const res = await fetch(`${url}/rest/v1/guesty_tokens?select=access_token,expires_at&order=created_at.desc&limit=1`, {
+            headers: {
+                apikey: key,
+                Authorization: `Bearer ${key}`,
+                Accept: "application/json",
+            },
+        });
+        if (!res.ok)
+            return null;
+        const rows = await res.json();
+        if (rows.length === 0)
+            return null;
+        const token = rows[0];
+        if (token.expires_at > Date.now() + REFRESH_BUFFER_MS) {
+            return token;
+        }
+    }
+    catch {
+        // Fall through to direct OAuth
+    }
+    return null;
+}
+async function saveTokenToSupabase(token) {
+    const url = process.env.SUPABASE_URL;
+    const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (!url || !key)
+        return;
+    try {
+        await fetch(`${url}/rest/v1/guesty_tokens`, {
+            method: "POST",
+            headers: {
+                apikey: key,
+                Authorization: `Bearer ${key}`,
+                "Content-Type": "application/json",
+                Prefer: "resolution=merge-duplicates",
+            },
+            body: JSON.stringify({
+                token_type: "Bearer",
+                access_token: token.access_token,
+                expires_at: token.expires_at,
+                created_at: Date.now(),
+            }),
+        });
+    }
+    catch {
+        // Non-fatal
+    }
+}
+export function invalidateToken() {
+    loadFromDisk();
+    cached.token = null;
+    saveToDisk();
+}
+export async function getToken() {
+    loadFromDisk();
+    pruneOldTimestamps();
+    // 1. Return in-memory/disk cached token if still valid
+    if (cached.token && cached.token.expires_at > Date.now() + REFRESH_BUFFER_MS) {
+        return cached.token.access_token;
+    }
+    // 2. If Supabase is configured, read shared token (avoids burning a token request)
+    if (hasSupabase()) {
+        const sbToken = await getTokenFromSupabase();
+        if (sbToken) {
+            cached.token = sbToken;
+            saveToDisk();
+            return sbToken.access_token;
+        }
+    }
+    // 3. Request new token from Guesty directly
+    if (cached.issued_timestamps.length >= MAX_TOKENS_PER_DAY) {
+        const oldest = cached.issued_timestamps[0];
+        const resetIn = Math.ceil((oldest + 24 * 60 * 60 * 1000 - Date.now()) / 60_000);
+        throw new Error(`OAuth token limit reached (${MAX_TOKENS_PER_DAY}/day). Next token available in ~${resetIn} minutes. ` +
+            `Guesty enforces a strict 5-token-per-24h limit on their OAuth endpoint.`);
+    }
+    const clientId = process.env.GUESTY_CLIENT_ID;
+    const clientSecret = process.env.GUESTY_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        throw new Error("Missing GUESTY_CLIENT_ID and/or GUESTY_CLIENT_SECRET.\n" +
+            "Set them as environment variables or in ~/.guesty-cli/.env");
+    }
+    process.stderr.write("Requesting new Guesty OAuth token...\n");
+    const res = await fetch("https://open-api.guesty.com/oauth2/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "client_credentials",
+            scope: "open-api",
+            client_id: clientId,
+            client_secret: clientSecret,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`OAuth token request failed (${res.status}): ${body}`);
+    }
+    const data = await res.json();
+    const tokenData = {
+        access_token: data.access_token,
+        expires_at: Date.now() + (data.expires_in ?? 3600) * 1000,
+    };
+    cached.token = tokenData;
+    cached.issued_timestamps.push(Date.now());
+    saveToDisk();
+    // Share with Supabase if configured
+    await saveTokenToSupabase(tokenData);
+    process.stderr.write("Token acquired and cached.\n");
+    return tokenData.access_token;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { loadEnv } from "./env.js";
+loadEnv();
+import { Command } from "commander";
+import { reservations } from "./commands/reservations.js";
+import { listings } from "./commands/listings.js";
+import { calendar } from "./commands/calendar.js";
+import { guests } from "./commands/guests.js";
+import { conversations } from "./commands/conversations.js";
+import { tasks } from "./commands/tasks.js";
+import { financials } from "./commands/financials.js";
+import { reviews } from "./commands/reviews.js";
+import { owners } from "./commands/owners.js";
+import { accounting } from "./commands/accounting.js";
+import { properties } from "./commands/properties.js";
+import { quotes } from "./commands/quotes.js";
+import { webhooks } from "./commands/webhooks.js";
+import { users } from "./commands/users.js";
+import { integrations } from "./commands/integrations.js";
+import { raw } from "./commands/raw.js";
+import { init } from "./commands/init.js";
+const program = new Command()
+    .name("guesty")
+    .version("1.0.0")
+    .description("Guesty API CLI — authenticates via OAuth with disk-cached tokens. Use 'raw' for any endpoint not covered by named commands.");
+program.addCommand(init);
+program.addCommand(reservations);
+program.addCommand(listings);
+program.addCommand(calendar);
+program.addCommand(guests);
+program.addCommand(conversations);
+program.addCommand(tasks);
+program.addCommand(financials);
+program.addCommand(reviews);
+program.addCommand(owners);
+program.addCommand(accounting);
+program.addCommand(properties);
+program.addCommand(quotes);
+program.addCommand(webhooks);
+program.addCommand(users);
+program.addCommand(integrations);
+program.addCommand(raw);
+program.parseAsync().catch((err) => {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+export interface FetchOptions {
+    method?: string;
+    body?: unknown;
+    params?: Record<string, string | number | boolean | string[]>;
+}
+export declare function guestyFetch<T = unknown>(path: string, options?: FetchOptions): Promise<T>;
+export declare function paginateAll<T = unknown>(path: string, params?: Record<string, string | number | boolean | string[]>, resultsKey?: string): Promise<T[]>;

package/dist/client.js

@@ -0,0 +1,109 @@
+import { getToken, invalidateToken } from "./auth.js";
+const BASE_URL = "https://open-api.guesty.com";
+const MAX_RETRIES = 3;
+const RATE_LIMIT_WINDOW = 60_000;
+const RATE_LIMIT_MAX = 100;
+const requestTimestamps = [];
+async function enforceRateLimit() {
+    const now = Date.now();
+    while (requestTimestamps.length > 0 && requestTimestamps[0] < now - RATE_LIMIT_WINDOW) {
+        requestTimestamps.shift();
+    }
+    if (requestTimestamps.length >= RATE_LIMIT_MAX) {
+        const waitMs = requestTimestamps[0] + RATE_LIMIT_WINDOW - now;
+        process.stderr.write(`Rate limit reached (${RATE_LIMIT_MAX}/min). Waiting ${Math.ceil(waitMs / 1000)}s...\n`);
+        await new Promise((r) => setTimeout(r, waitMs));
+        return enforceRateLimit();
+    }
+    requestTimestamps.push(now);
+}
+function buildQuery(params) {
+    const parts = [];
+    for (const [key, val] of Object.entries(params)) {
+        if (val === undefined || val === null)
+            continue;
+        if (Array.isArray(val)) {
+            val.forEach((v) => parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`));
+        }
+        else {
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(val))}`);
+        }
+    }
+    return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+export async function guestyFetch(path, options = {}) {
+    const { method = "GET", body, params } = options;
+    const token = await getToken();
+    const url = `${BASE_URL}${path}${params ? buildQuery(params) : ""}`;
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+    };
+    if (body) {
+        headers["Content-Type"] = "application/json";
+    }
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        await enforceRateLimit();
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (res.status === 204) {
+            return undefined;
+        }
+        if (res.status === 401 && attempt < MAX_RETRIES) {
+            process.stderr.write(`Token expired (401). Refreshing...\n`);
+            invalidateToken();
+            continue;
+        }
+        if (res.status === 429 && attempt < MAX_RETRIES) {
+            const retryAfter = res.headers.get("retry-after");
+            const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : attempt * 5000;
+            process.stderr.write(`Rate limited. Retrying in ${waitMs / 1000}s...\n`);
+            await new Promise((r) => setTimeout(r, waitMs));
+            continue;
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Guesty API ${method} ${path} failed: ${res.status} ${res.statusText}\n${text}`);
+        }
+        return res.json();
+    }
+    throw new Error(`Guesty API ${method} ${path} failed after ${MAX_RETRIES} retries`);
+}
+export async function paginateAll(path, params = {}, resultsKey) {
+    const limit = 100;
+    let skip = 0;
+    const all = [];
+    while (true) {
+        const res = await guestyFetch(path, {
+            params: { ...params, limit, skip },
+        });
+        let items;
+        if (resultsKey && Array.isArray(res[resultsKey])) {
+            items = res[resultsKey];
+        }
+        else if (Array.isArray(res)) {
+            items = res;
+        }
+        else if ("results" in res && Array.isArray(res.results)) {
+            items = res.results;
+        }
+        else if ("data" in res && Array.isArray(res.data)) {
+            items = res.data;
+        }
+        else {
+            break;
+        }
+        all.push(...items);
+        if (items.length < limit)
+            break;
+        if (all.length >= 10_000) {
+            process.stderr.write(`Warning: pagination capped at 10,000 results. Use filters to narrow your query.\n`);
+            break;
+        }
+        skip += limit;
+    }
+    return all;
+}

package/dist/commands/accounting.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const accounting: Command;

package/dist/commands/accounting.js

@@ -0,0 +1,102 @@
+import { Command } from "commander";
+import { guestyFetch } from "../client.js";
+import { print } from "../output.js";
+import { readStdin } from "../stdin.js";
+export const accounting = new Command("accounting")
+    .alias("acct")
+    .description("Accounting, expenses, and financial data");
+accounting
+    .command("balance <reservationId>")
+    .description("Get folio balance for a reservation")
+    .action(async (id) => {
+    const data = await guestyFetch(`/v1/accounting-api/reservations/${id}/balance`);
+    print(data);
+});
+accounting
+    .command("journal-entries")
+    .description("Get recognized journal entries")
+    .option("--limit <n>", "Max results", "100")
+    .option("--skip <n>", "Offset", "0")
+    .action(async (opts) => {
+    const data = await guestyFetch("/v1/accounting-api/journal-entries", {
+        params: { limit: parseInt(opts.limit), skip: parseInt(opts.skip) },
+    });
+    print(data);
+});
+accounting
+    .command("journal-entries-all")
+    .description("Get all journal entries (including unrecognized)")
+    .option("--limit <n>", "Max results", "100")
+    .option("--skip <n>", "Offset", "0")
+    .action(async (opts) => {
+    const data = await guestyFetch("/v1/accounting-api/journal-entries/all", {
+        params: { limit: parseInt(opts.limit), skip: parseInt(opts.skip) },
+    });
+    print(data);
+});
+accounting
+    .command("categories")
+    .description("Get accounting categories")
+    .action(async () => {
+    const data = await guestyFetch("/v1/accounting-api/categories");
+    print(data);
+});
+accounting
+    .command("working-capital <ownerId>")
+    .description("Get owner working capital")
+    .action(async (ownerId) => {
+    const data = await guestyFetch(`/v1/accounting-api/owners/${ownerId}/working-capital`);
+    print(data);
+});
+accounting
+    .command("business-models")
+    .description("Get business models")
+    .action(async () => {
+    const data = await guestyFetch("/v1/business-models-api/light-business-models");
+    print(data);
+});
+accounting
+    .command("expenses")
+    .description("List expenses")
+    .option("--limit <n>", "Max results", "25")
+    .option("--skip <n>", "Offset", "0")
+    .action(async (opts) => {
+    const data = await guestyFetch("/v1/expenses-api/expenses", {
+        params: { limit: parseInt(opts.limit), skip: parseInt(opts.skip) },
+    });
+    print(data);
+});
+accounting
+    .command("expense <id>")
+    .description("Get expense by ID")
+    .action(async (id) => {
+    const data = await guestyFetch(`/v1/expenses-api/expenses/${id}`);
+    print(data);
+});
+accounting
+    .command("create-expense")
+    .description("Create an expense (--data or stdin)")
+    .option("--data <json>", "JSON body")
+    .action(async (opts) => {
+    const body = opts.data ? JSON.parse(opts.data) : JSON.parse(await readStdin());
+    const data = await guestyFetch("/v1/expenses-api/expenses", { method: "POST", body });
+    print(data);
+});
+accounting
+    .command("vendors")
+    .description("List vendors")
+    .action(async () => {
+    const data = await guestyFetch("/v1/vendors");
+    print(data);
+});
+accounting
+    .command("payment-transactions")
+    .description("Get payment transactions from Guesty Pay")
+    .option("--limit <n>", "Max results", "25")
+    .option("--skip <n>", "Offset", "0")
+    .action(async (opts) => {
+    const data = await guestyFetch("/v1/payment-transactions/reports", {
+        params: { limit: parseInt(opts.limit), skip: parseInt(opts.skip) },
+    });
+    print(data);
+});

package/dist/commands/calendar.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const calendar: Command;

package/dist/commands/calendar.js

@@ -0,0 +1,60 @@
+import { Command } from "commander";
+import { guestyFetch } from "../client.js";
+import { print } from "../output.js";
+import { readStdin } from "../stdin.js";
+export const calendar = new Command("calendar")
+    .alias("cal")
+    .description("Calendar and availability");
+calendar
+    .command("get <listingId>")
+    .description("Get calendar for a listing")
+    .requiredOption("--from <date>", "Start date (YYYY-MM-DD)")
+    .requiredOption("--to <date>", "End date (YYYY-MM-DD)")
+    .action(async (listingId, opts) => {
+    const data = await guestyFetch(`/v1/availability-pricing/api/calendar/listings/${listingId}`, { params: { from: opts.from, to: opts.to } });
+    print(data);
+});
+calendar
+    .command("update <listingId>")
+    .description("Update calendar (--data or stdin)")
+    .option("--data <json>", "JSON body")
+    .action(async (listingId, opts) => {
+    const body = opts.data
+        ? JSON.parse(opts.data)
+        : JSON.parse(await readStdin());
+    const data = await guestyFetch(`/v1/availability-pricing/api/calendar/listings/${listingId}`, { method: "PUT", body });
+    print(data);
+});
+calendar
+    .command("block <listingId>")
+    .description("Block dates on a listing")
+    .requiredOption("--from <date>", "Start date (YYYY-MM-DD)")
+    .requiredOption("--to <date>", "End date (YYYY-MM-DD)")
+    .option("--note <text>", "Block note")
+    .action(async (listingId, opts) => {
+    const data = await guestyFetch(`/v1/availability-pricing/api/calendar/listings/${listingId}`, {
+        method: "PUT",
+        body: {
+            dateFrom: opts.from,
+            dateTo: opts.to,
+            status: "unavailable",
+            note: opts.note,
+        },
+    });
+    print(data);
+});
+calendar
+    .command("check <listingId>")
+    .description("Check availability for dates")
+    .requiredOption("--checkin <date>", "Check-in date (YYYY-MM-DD)")
+    .requiredOption("--checkout <date>", "Check-out date (YYYY-MM-DD)")
+    .action(async (listingId, opts) => {
+    const data = await guestyFetch("/v1/reservations/check-availability", {
+        params: {
+            listingId,
+            checkIn: opts.checkin,
+            checkOut: opts.checkout,
+        },
+    });
+    print(data);
+});

package/dist/commands/conversations.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const conversations: Command;

package/dist/commands/conversations.js

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import { guestyFetch } from "../client.js";
+import { print } from "../output.js";
+export const conversations = new Command("conversations")
+    .alias("conv")
+    .description("Manage conversations/messaging");
+conversations
+    .command("list")
+    .description("List conversations")
+    .option("--reservation <id>", "Filter by reservation ID")
+    .option("--limit <n>", "Max results", "25")
+    .option("--skip <n>", "Offset", "0")
+    .action(async (opts) => {
+    const params = {
+        limit: parseInt(opts.limit),
+        skip: parseInt(opts.skip),
+    };
+    if (opts.reservation)
+        params.reservationId = opts.reservation;
+    const data = await guestyFetch("/v1/communication/conversations", { params });
+    print(data);
+});
+conversations
+    .command("get <id>")
+    .description("Get a conversation and its posts")
+    .action(async (id) => {
+    const data = await guestyFetch(`/v1/communication/conversations/${id}/posts`);
+    print(data);
+});
+conversations
+    .command("send <conversationId>")
+    .description("Send a message in a conversation")
+    .requiredOption("--body <text>", "Message body")
+    .action(async (conversationId, opts) => {
+    const data = await guestyFetch(`/v1/communication/conversations/${conversationId}/send-message`, {
+        method: "POST",
+        body: { body: opts.body },
+    });
+    print(data);
+});

package/dist/commands/financials.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const financials: Command;

package/dist/commands/financials.js

@@ -0,0 +1,56 @@
+import { Command } from "commander";
+import { guestyFetch } from "../client.js";
+import { print } from "../output.js";
+export const financials = new Command("financials")
+    .alias("fin")
+    .description("Financial data and accounting");
+financials
+    .command("balance <reservationId>")
+    .description("Get folio balance for a reservation")
+    .action(async (id) => {
+    const data = await guestyFetch(`/v1/accounting-api/reservations/${id}/balance`);
+    print(data);
+});
+financials
+    .command("journal-entries")
+    .description("List journal entries")
+    .option("--from <date>", "From date (YYYY-MM-DD)")
+    .option("--to <date>", "To date (YYYY-MM-DD)")
+    .option("--listing <id>", "Filter by listing ID")
+    .option("--limit <n>", "Max results", "100")
+    .option("--skip <n>", "Offset", "0")
+    .action(async (opts) => {
+    const params = {
+        limit: parseInt(opts.limit),
+        skip: parseInt(opts.skip),
+    };
+    if (opts.from)
+        params.from = opts.from;
+    if (opts.to)
+        params.to = opts.to;
+    if (opts.listing)
+        params.listingId = opts.listing;
+    const data = await guestyFetch("/v1/accounting-api/journal-entries", { params });
+    print(data);
+});
+financials
+    .command("categories")
+    .description("List accounting categories")
+    .action(async () => {
+    const data = await guestyFetch("/v1/accounting-api/categories");
+    print(data);
+});
+financials
+    .command("owner-statement <listingId>")
+    .description("Get owner financial data for a listing")
+    .option("--from <date>", "From date (YYYY-MM-DD)")
+    .option("--to <date>", "To date (YYYY-MM-DD)")
+    .action(async (listingId, opts) => {
+    const params = {};
+    if (opts.from)
+        params.from = opts.from;
+    if (opts.to)
+        params.to = opts.to;
+    const data = await guestyFetch(`/v1/financials/listing/${listingId}`, { params });
+    print(data);
+});

package/dist/commands/guests.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const guests: Command;

package/dist/commands/guests.js

@@ -0,0 +1,57 @@
+import { Command } from "commander";
+import { guestyFetch } from "../client.js";
+import { print } from "../output.js";
+import { readStdin } from "../stdin.js";
+export const guests = new Command("guests")
+    .description("Manage guests");
+guests
+    .command("list")
+    .description("List/search guests")
+    .option("--q <query>", "Search query (name, email, phone)")
+    .option("--limit <n>", "Max results", "25")
+    .option("--skip <n>", "Offset", "0")
+    .action(async (opts) => {
+    const params = {
+        limit: parseInt(opts.limit),
+        skip: parseInt(opts.skip),
+    };
+    if (opts.q)
+        params.q = opts.q;
+    const data = await guestyFetch("/v1/guests-crud", { params });
+    print(data);
+});
+guests
+    .command("get <id>")
+    .description("Get a single guest by ID")
+    .action(async (id) => {
+    const data = await guestyFetch(`/v1/guests-crud/${id}`);
+    print(data);
+});
+guests
+    .command("create")
+    .description("Create a guest (--data or stdin)")
+    .option("--data <json>", "JSON body")
+    .action(async (opts) => {
+    const body = opts.data
+        ? JSON.parse(opts.data)
+        : JSON.parse(await readStdin());
+    const data = await guestyFetch("/v1/guests-crud", {
+        method: "POST",
+        body,
+    });
+    print(data);
+});
+guests
+    .command("update <id>")
+    .description("Update a guest (--data or stdin)")
+    .option("--data <json>", "JSON body")
+    .action(async (id, opts) => {
+    const body = opts.data
+        ? JSON.parse(opts.data)
+        : JSON.parse(await readStdin());
+    const data = await guestyFetch(`/v1/guests-crud/${id}`, {
+        method: "PUT",
+        body,
+    });
+    print(data);
+});

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const init: Command;