@riverintel/stayfinder-plugin 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Shared TypeScript types for the StayFinder plugin.
+ *
+ * These mirror the public adapter API surface (the request/response shapes
+ * for `POST /v1/search/stays`, `POST /v1/signup`, `POST /v1/signup/verify`,
+ * `GET /v1/tenant/me`) and the on-disk credential store shape.
+ *
+ * They are deliberately a SUBSET of what the adapter returns — we only type
+ * the fields the plugin actually reads. The adapter is free to add new
+ * fields without breaking us; missing optional fields parse fine; unexpected
+ * extra fields are silently ignored at runtime.
+ *
+ * The single source of truth for the wire format is the adapter spec at
+ * docs/expedia-adapter-cloudrun-spec.md §7 (in the private operations repo).
+ */
+/** ISO-8601 timestamp string, e.g. "2026-04-15T22:32:39.436Z". */
+export type IsoTimestamp = string;
+/** YYYY-MM-DD date string. */
+export type IsoDate = string;
+export interface StayFinderPluginConfig {
+    /** Base URL of the StayFinder service. Defaults to the public hosted endpoint. */
+    adapter_url: string;
+    /** ISO-3166-1 alpha-2 country code for point-of-sale. Defaults to 'US'. */
+    default_pos_country: string;
+    /** ISO-4217 currency code. If unset, the adapter falls back to the POS default. */
+    default_currency?: string;
+    /** HTTP timeout for adapter calls, in milliseconds. Defaults to 10000. */
+    request_timeout_ms: number;
+}
+export type LodgingType = 'hotel' | 'vacation_rental' | 'any';
+export type SortOrder = 'recommended' | 'price_asc' | 'price_desc' | 'rating_desc' | 'distance';
+export interface SearchStaysFilters {
+    pet_friendly?: boolean;
+    free_cancellation?: boolean;
+    min_star_rating?: number;
+    max_star_rating?: number;
+    price_min?: number;
+    price_max?: number;
+}
+export interface SearchStaysRequest {
+    destination: string;
+    check_in: IsoDate;
+    check_out: IsoDate;
+    adults: number;
+    children_ages?: number[];
+    lodging_type?: LodgingType;
+    filters?: SearchStaysFilters;
+    sort?: SortOrder;
+    limit?: number;
+    pos_country?: string;
+    currency?: string;
+    intent?: string;
+    hotel_name?: string;
+}
+/**
+ * Free-text fields that come back wrapped in
+ * <<<EXTERNAL_UNTRUSTED_CONTENT id="..."> ... <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">
+ * sentinels by the adapter. Typed as string here; the wrapping is plain
+ * text inside the string and the model is expected to recognize it.
+ */
+export type WrappedString = string;
+export interface SearchStaysProperty {
+    property_id: string;
+    name: WrappedString;
+    property_type?: string;
+    neighborhood?: WrappedString;
+    star_rating: number | null;
+    guest_rating?: {
+        score: number | null;
+        scale: number;
+        review_count: number;
+    };
+    price: {
+        amount_per_night: number;
+        amount_total: number;
+        currency: string;
+        taxes_included: boolean;
+        fees_estimate?: number;
+    };
+    free_cancellation?: boolean;
+    pet_friendly?: boolean;
+    descriptions?: {
+        location?: WrappedString;
+        hotel?: WrappedString;
+        room?: WrappedString;
+    };
+    distance?: {
+        value: number;
+        unit: 'km' | 'mi';
+    };
+    thumbnail_url?: string;
+    redirect_link: string;
+    geo?: {
+        lat: number;
+        lng: number;
+        obfuscated?: boolean;
+    };
+}
+export interface SearchStaysResponse {
+    request_id: string;
+    trace_id?: string;
+    cached: boolean;
+    cached_at: IsoTimestamp;
+    cache_ttl_seconds: number;
+    brand?: 'expedia' | 'vrbo';
+    resolved_destination?: {
+        id: string;
+        label: string;
+        type: string;
+    };
+    check_in: IsoDate;
+    check_out: IsoDate;
+    nights: number;
+    party: {
+        adults: number;
+        children: number;
+    };
+    currency: string;
+    result_count: number;
+    total_available?: number | null;
+    warnings: Array<{
+        code: string;
+        message: string;
+    }>;
+    results: SearchStaysProperty[];
+}
+export interface SignupResponse {
+    status: 'verification_sent';
+    message: string;
+    expires_in_seconds: number;
+}
+export interface SignupVerifyResponse {
+    status: 'verified';
+    tenant_id: string;
+    /** Plaintext API token — returned ONCE; never request twice. */
+    token: string;
+    token_kind: 'ephemeral' | 'persistent';
+    expires_at: IsoTimestamp | null;
+    quota_per_hour: number;
+    default_pos: string;
+}
+export interface TenantMeResponse {
+    tenant_id: string;
+    name: string | null;
+    email: string | null;
+    quota: {
+        limit_per_hour: number;
+        remaining: number;
+        reset_at: IsoTimestamp;
+    };
+    token: {
+        kind: 'ephemeral' | 'persistent';
+        expires_at: IsoTimestamp | null;
+    };
+    default_pos: string;
+}
+/**
+ * Every known adapter error code, in one place. The plugin maps each one
+ * to a model-facing message in errors.ts. Unknown codes still parse fine
+ * (the AdapterErrorEnvelope.code field is `string`, not this union) — the
+ * union is for exhaustive switch coverage in the mapper.
+ */
+export type AdapterErrorCode = 'invalid_request' | 'missing_field' | 'invalid_email' | 'disposable_email' | 'code_invalid' | 'code_expired' | 'code_attempts_exceeded' | 'unauthorized' | 'token_expired' | 'tenant_suspended' | 'tenant_quota_exceeded' | 'global_quota_exceeded' | 'signup_rate_limited' | 'destination_not_found' | 'destination_ambiguous' | 'expedia_upstream_error' | 'upstream_timeout' | 'upstream_unavailable' | 'internal_error';
+export interface AdapterErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        request_id?: string;
+        trace_id?: string;
+        retry_after_seconds?: number;
+        attempts_remaining?: number;
+        expires_at?: string | null;
+        upstream_status?: number | null;
+        transaction_id?: string;
+        pos_country?: string;
+        details?: Record<string, unknown>;
+    };
+}
+export interface CredentialFile {
+    /** Plaintext API token, "oct_..." prefix. */
+    api_token: string;
+    /** ISO-8601 timestamp when the file was last written. */
+    saved_at: IsoTimestamp;
+    /** Tenant ID the token belongs to. */
+    tenant_id: string;
+    /** Email the tenant was registered under (used for re-auth). */
+    email: string;
+    /** Token kind: ephemeral tokens slide; persistent ones don't. */
+    token_kind: 'ephemeral' | 'persistent';
+    /** Token's current expires_at; null for persistent tokens. */
+    expires_at: IsoTimestamp | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * Shared TypeScript types for the StayFinder plugin.
+ *
+ * These mirror the public adapter API surface (the request/response shapes
+ * for `POST /v1/search/stays`, `POST /v1/signup`, `POST /v1/signup/verify`,
+ * `GET /v1/tenant/me`) and the on-disk credential store shape.
+ *
+ * They are deliberately a SUBSET of what the adapter returns — we only type
+ * the fields the plugin actually reads. The adapter is free to add new
+ * fields without breaking us; missing optional fields parse fine; unexpected
+ * extra fields are silently ignored at runtime.
+ *
+ * The single source of truth for the wire format is the adapter spec at
+ * docs/expedia-adapter-cloudrun-spec.md §7 (in the private operations repo).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/validation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pre-HTTP validation for `search_stays` parameters.
+ *
+ * The TypeBox schema in `tools/search-stays.ts` catches type and range
+ * errors that the runtime can enforce automatically (string vs number,
+ * minLength, maximum, enum membership, etc.). Anything that requires
+ * cross-field comparison or runtime computation lives here.
+ *
+ * Returning a non-null string from any of these functions means the
+ * tool's `execute` should throw with that string as the user-facing
+ * message instead of making the HTTP call. The string is phrased for
+ * the model — concrete next action, plain English, no error codes.
+ *
+ * The spec is explicit that error messages should give the model an
+ * actionable hypothesis. "check_out must be after check_in. Did you
+ * swap the dates?" is much better than "validation failed".
+ */
+import type { SearchStaysRequest } from './types.js';
+/**
+ * Run all post-schema validation checks against a `search_stays` request.
+ *
+ * Returns null if everything passes; otherwise returns the model-facing
+ * error message string. Tools call this in `execute` *before* hitting
+ * the HTTP layer so we never burn an adapter call on a request the
+ * adapter would also reject.
+ */
+export declare function validateSearchStaysRequest(req: SearchStaysRequest, now?: Date): string | null;
+/**
+ * Trim and validate an email address with a deliberately-loose check.
+ *
+ * The plugin doesn't try to be a perfect RFC 5322 validator — that's the
+ * adapter's job (it uses the same `email-validator` package and runs the
+ * disposable-domain check). All we want here is to reject things that
+ * obviously aren't emails before burning an HTTP call.
+ *
+ * Returns null on success, or a model-facing error string on failure.
+ */
+export declare function validateEmailLoose(raw: string): string | null;
+/**
+ * Strip whitespace, dashes, dots, and any non-digit characters from a
+ * pasted code, then return the result if it's exactly 6 ASCII digits.
+ *
+ * Returns null when the cleaned input isn't 6 digits — the verify tool
+ * uses this to short-circuit "the user pasted a token by mistake" or
+ * "the user pasted a phrase" without burning an HTTP call.
+ *
+ * Defensive cleanup matters because email clients sometimes paste
+ * non-breaking spaces or thin spaces around copied text.
+ */
+export declare function sanitizeAndValidateCode(raw: unknown): string | null;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwCrD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,kBAAkB,EACvB,GAAG,GAAE,IAAiB,GACrB,MAAM,GAAG,IAAI,CAyFf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoB7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKnE"}

package/dist/validation.js

@@ -0,0 +1,174 @@
+/**
+ * Pre-HTTP validation for `search_stays` parameters.
+ *
+ * The TypeBox schema in `tools/search-stays.ts` catches type and range
+ * errors that the runtime can enforce automatically (string vs number,
+ * minLength, maximum, enum membership, etc.). Anything that requires
+ * cross-field comparison or runtime computation lives here.
+ *
+ * Returning a non-null string from any of these functions means the
+ * tool's `execute` should throw with that string as the user-facing
+ * message instead of making the HTTP call. The string is phrased for
+ * the model — concrete next action, plain English, no error codes.
+ *
+ * The spec is explicit that error messages should give the model an
+ * actionable hypothesis. "check_out must be after check_in. Did you
+ * swap the dates?" is much better than "validation failed".
+ */
+const MAX_NIGHTS = 30;
+const MAX_DAYS_OUT = 500;
+const ymdRegex = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Parse a YYYY-MM-DD string as UTC midnight. Returns null if the string
+ * doesn't match the format or doesn't represent a real date.
+ *
+ * We use UTC because the adapter (and Expedia) treat the date as
+ * calendar-day-in-the-destination, not "wall clock at midnight in the
+ * user's local timezone". A user in NYC searching for a hotel in Tokyo
+ * for 2026-06-01 means 2026-06-01 in Tokyo, regardless of what time it
+ * is on their laptop.
+ */
+const parseYmdUtc = (s) => {
+    if (!ymdRegex.test(s))
+        return null;
+    const ms = Date.parse(`${s}T00:00:00Z`);
+    if (!Number.isFinite(ms))
+        return null;
+    // Reject roll-overs like "2026-02-30" — Date.parse silently rolls them
+    // forward, so we round-trip and compare to catch the difference.
+    const back = new Date(ms).toISOString().slice(0, 10);
+    if (back !== s)
+        return null;
+    return new Date(ms);
+};
+/** Today, normalized to UTC midnight, as a Date. */
+const todayUtc = () => {
+    const d = new Date();
+    d.setUTCHours(0, 0, 0, 0);
+    return d;
+};
+const daysBetween = (a, b) => {
+    const ms = b.getTime() - a.getTime();
+    return Math.round(ms / (24 * 60 * 60 * 1000));
+};
+/**
+ * Run all post-schema validation checks against a `search_stays` request.
+ *
+ * Returns null if everything passes; otherwise returns the model-facing
+ * error message string. Tools call this in `execute` *before* hitting
+ * the HTTP layer so we never burn an adapter call on a request the
+ * adapter would also reject.
+ */
+export function validateSearchStaysRequest(req, now = todayUtc()) {
+    // -----------------------------------------------------------------------
+    // Date format
+    // -----------------------------------------------------------------------
+    const checkIn = parseYmdUtc(req.check_in);
+    if (!checkIn) {
+        return (`check_in is not a valid YYYY-MM-DD date: "${req.check_in}". ` +
+            'Ask the user for the date in plain English and re-format it as YYYY-MM-DD.');
+    }
+    const checkOut = parseYmdUtc(req.check_out);
+    if (!checkOut) {
+        return (`check_out is not a valid YYYY-MM-DD date: "${req.check_out}". ` +
+            'Ask the user for the date in plain English and re-format it as YYYY-MM-DD.');
+    }
+    // -----------------------------------------------------------------------
+    // Date order — by far the most common LLM mistake
+    // -----------------------------------------------------------------------
+    if (checkOut.getTime() <= checkIn.getTime()) {
+        return (`check_out (${req.check_out}) must be after check_in (${req.check_in}). ` +
+            'Did you swap the dates? Re-check with the user and call search_stays again.');
+    }
+    // -----------------------------------------------------------------------
+    // check_in not in the past
+    // -----------------------------------------------------------------------
+    if (checkIn.getTime() < now.getTime()) {
+        return (`check_in (${req.check_in}) is in the past. ` +
+            'Confirm the dates with the user — Expedia only sells future stays.');
+    }
+    // -----------------------------------------------------------------------
+    // Stay length cap
+    // -----------------------------------------------------------------------
+    const nights = daysBetween(checkIn, checkOut);
+    if (nights > MAX_NIGHTS) {
+        return (`Stay length is ${nights} nights, which exceeds the ${MAX_NIGHTS}-night maximum per search. ` +
+            'Split the trip into multiple ≤30-night searches and combine the results yourself.');
+    }
+    // -----------------------------------------------------------------------
+    // check_in window cap (Expedia only quotes ~500 days out)
+    // -----------------------------------------------------------------------
+    const daysOut = daysBetween(now, checkIn);
+    if (daysOut > MAX_DAYS_OUT) {
+        return (`check_in (${req.check_in}) is ${daysOut} days from now, beyond the ${MAX_DAYS_OUT}-day booking window. ` +
+            'Tell the user the destination doesn\'t have inventory open that far in the future yet, and ask if they want to try a date closer to now.');
+    }
+    // -----------------------------------------------------------------------
+    // Filter sanity (only when both ends of a range are present)
+    // -----------------------------------------------------------------------
+    const filters = req.filters;
+    if (filters) {
+        if (typeof filters.min_star_rating === 'number' &&
+            typeof filters.max_star_rating === 'number' &&
+            filters.min_star_rating > filters.max_star_rating) {
+            return (`Star rating filter is inverted: min_star_rating ${filters.min_star_rating} > max_star_rating ${filters.max_star_rating}. ` +
+                'Did you swap them? Re-call search_stays with the bounds in the right order.');
+        }
+        if (typeof filters.price_min === 'number' &&
+            typeof filters.price_max === 'number' &&
+            filters.price_min > filters.price_max) {
+            return (`Price filter is inverted: price_min ${filters.price_min} > price_max ${filters.price_max}. ` +
+                'Did you swap them? Re-call search_stays with the bounds in the right order.');
+        }
+    }
+    return null;
+}
+/**
+ * Trim and validate an email address with a deliberately-loose check.
+ *
+ * The plugin doesn't try to be a perfect RFC 5322 validator — that's the
+ * adapter's job (it uses the same `email-validator` package and runs the
+ * disposable-domain check). All we want here is to reject things that
+ * obviously aren't emails before burning an HTTP call.
+ *
+ * Returns null on success, or a model-facing error string on failure.
+ */
+export function validateEmailLoose(raw) {
+    if (typeof raw !== 'string') {
+        return 'Email must be a string. Ask the user for their email address.';
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return 'Email is empty. Ask the user for their email address.';
+    }
+    if (trimmed.length > 254) {
+        return 'Email is unrealistically long. Ask the user to double-check what they typed.';
+    }
+    // One @, non-empty local and domain parts, domain has at least one dot,
+    // no whitespace anywhere. This matches the adapter's first-pass regex.
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(trimmed)) {
+        return (`"${trimmed}" doesn't look like a valid email address. ` +
+            'Ask the user to double-check the spelling.');
+    }
+    return null;
+}
+/**
+ * Strip whitespace, dashes, dots, and any non-digit characters from a
+ * pasted code, then return the result if it's exactly 6 ASCII digits.
+ *
+ * Returns null when the cleaned input isn't 6 digits — the verify tool
+ * uses this to short-circuit "the user pasted a token by mistake" or
+ * "the user pasted a phrase" without burning an HTTP call.
+ *
+ * Defensive cleanup matters because email clients sometimes paste
+ * non-breaking spaces or thin spaces around copied text.
+ */
+export function sanitizeAndValidateCode(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const cleaned = raw.replace(/[^0-9]/g, '');
+    if (cleaned.length !== 6)
+        return null;
+    return cleaned;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/openclaw.plugin.json

@@ -0,0 +1,41 @@
+{
+  "id": "stayfinder-plugin",
+  "name": "StayFinder",
+  "description": "Live hotel and vacation rental search via the StayFinder service. Returns real-time pricing, availability, and Expedia booking redirect links — never scrape, never construct booking URLs from training data.",
+  "skills": [
+    "./skills"
+  ],
+  "contracts": {
+    "tools": [
+      "search_stays",
+      "stayfinder_signup",
+      "stayfinder_verify"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "adapter_url": {
+        "type": "string",
+        "description": "Base URL of the StayFinder service. Defaults to the public hosted endpoint at https://api.stayfinder.riverintel.com if omitted."
+      },
+      "default_pos_country": {
+        "type": "string",
+        "pattern": "^[A-Z]{2}$",
+        "description": "ISO-3166-1 alpha-2 country code for point-of-sale (affects currency and pricing display). Defaults to US."
+      },
+      "default_currency": {
+        "type": "string",
+        "pattern": "^[A-Z]{3}$",
+        "description": "ISO-4217 currency code. Defaults to the POS country's primary currency."
+      },
+      "request_timeout_ms": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 60000,
+        "description": "HTTP timeout for service calls. Defaults to 10000 (10s)."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@riverintel/stayfinder-plugin",
+  "version": "0.2.0",
+  "description": "OpenClaw plugin for live hotel and vacation rental search via the StayFinder service. Returns real-time pricing, availability, and Expedia booking redirect links — no scraping, no browser automation.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "stayfinder",
+    "lodging",
+    "hotels",
+    "vacation-rental",
+    "travel",
+    "expedia",
+    "vrbo"
+  ],
+  "author": "RiverIntel",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/RiverIntel/stayfinder#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RiverIntel/stayfinder.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RiverIntel/stayfinder/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.5"
+    },
+    "build": {
+      "openclawVersion": "2026.4.5"
+    },
+    "install": {
+      "npmSpec": "@riverintel/stayfinder-plugin",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.5"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.4.5"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.33.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "openclaw": "2026.4.5",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.3"
+  }
+}