hospitable 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,390 @@
+interface RetryConfig {
+    maxAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    onRateLimit?: (info: {
+        retryAfter: number;
+        endpoint: string;
+        attempt: number;
+    }) => void;
+}
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+interface RequestOptions {
+    method?: HttpMethod;
+    params?: Record<string, string | number | boolean | string[] | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+interface HttpClientConfig {
+    baseURL: string;
+    getAuthHeader: () => Promise<string>;
+    onUnauthorized?: () => Promise<void>;
+    debug?: boolean;
+    retryConfig?: RetryConfig;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, params?: RequestOptions['params']): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+interface PriceAmount {
+    amount: number;
+    currency: string;
+}
+interface CalendarDay {
+    date: string;
+    available: boolean;
+    price: PriceAmount;
+    minStay: number;
+    maxStay: number | null;
+    notes: string | null;
+    blockedReason: string | null;
+}
+interface CalendarUpdate {
+    date: string;
+    price?: {
+        amount: number;
+    };
+    available?: boolean;
+    minStay?: number;
+    maxStay?: number | null;
+    notes?: string | null;
+}
+interface CalendarGetParams {
+    startDate: string;
+    endDate: string;
+}
+
+interface PaginatedResponse<T> {
+    data: T[];
+    meta: {
+        nextCursor: string | null;
+        total: number;
+        perPage: number;
+    };
+}
+
+declare class CalendarResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    get(propertyId: string, startDate: string, endDate: string): Promise<PaginatedResponse<CalendarDay>>;
+    update(propertyId: string, updates: CalendarUpdate[]): Promise<void>;
+    block(propertyId: string, startDate: string, endDate: string, reason?: string): Promise<void>;
+    unblock(propertyId: string, startDate: string, endDate: string): Promise<void>;
+}
+
+type MessageDirection = 'outbound' | 'inbound';
+interface Message {
+    id: string;
+    reservationId: string;
+    direction: MessageDirection;
+    body: string;
+    sentAt: string;
+    readAt: string | null;
+    senderName: string;
+}
+interface MessageThread {
+    reservationId: string;
+    messages: Message[];
+    unreadCount: number;
+}
+interface SendMessageRequest {
+    body: string;
+}
+interface MessageTemplate {
+    id: string;
+    name: string;
+    body: string;
+    variables: string[];
+}
+
+declare class MessagesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(reservationId: string): Promise<MessageThread>;
+    send(reservationId: string, body: string): Promise<Message>;
+    listTemplates(): Promise<MessageTemplate[]>;
+    sendTemplate(reservationId: string, templateId: string, variables?: Record<string, string>): Promise<Message>;
+}
+
+type PropertyPlatform = 'airbnb' | 'vrbo' | 'booking_com' | 'direct' | string;
+interface PropertyTag {
+    id: string;
+    name: string;
+}
+interface Property {
+    id: string;
+    name: string;
+    platform: PropertyPlatform;
+    platformId: string;
+    active: boolean;
+    timezone: string;
+    currency: string;
+    address: {
+        street: string;
+        city: string;
+        state: string;
+        country: string;
+        zipCode: string;
+    };
+    tags: PropertyTag[];
+    createdAt: string;
+    updatedAt: string;
+}
+type PropertyList = PaginatedResponse<Property>;
+
+interface PropertyListParams {
+    cursor?: string;
+    perPage?: number;
+    tags?: string[];
+}
+declare class PropertiesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(params?: PropertyListParams): Promise<PropertyList>;
+    get(id: string): Promise<Property>;
+    listTags(id: string): Promise<PropertyTag[]>;
+    getCalendar(id: string, startDate: string, endDate: string): Promise<PaginatedResponse<CalendarDay>>;
+    updateCalendar(id: string, updates: CalendarUpdate[]): Promise<void>;
+    iter(params?: Omit<PropertyListParams, 'cursor'>): AsyncGenerator<Property>;
+}
+
+type ReservationStatus = 'confirmed' | 'pending' | 'cancelled' | 'inquiry' | 'declined' | 'expired';
+type ReservationPlatform = 'airbnb' | 'vrbo' | 'booking_com' | 'direct' | string;
+interface Guest {
+    id: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone: string;
+    avatarUrl: string | null;
+    verified: boolean;
+}
+interface ReservationMoney {
+    amount: number;
+    currency: string;
+}
+interface Reservation {
+    id: string;
+    propertyId: string;
+    platform: ReservationPlatform;
+    platformId: string;
+    status: ReservationStatus;
+    checkinDate: string;
+    checkoutDate: string;
+    nights: number;
+    guestCount: number;
+    guest?: Guest;
+    totalAmount: ReservationMoney;
+    cleaningFee: ReservationMoney;
+    platformFee: ReservationMoney;
+    createdAt: string;
+    updatedAt: string;
+}
+type ReservationList = PaginatedResponse<Reservation>;
+interface ReservationListParams {
+    properties?: string[];
+    startDate?: string;
+    endDate?: string;
+    status?: ReservationStatus | ReservationStatus[];
+    include?: string;
+    cursor?: string;
+    perPage?: number;
+}
+
+declare class ReservationsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(params?: ReservationListParams): Promise<ReservationList>;
+    get(id: string, include?: string): Promise<Reservation>;
+    getUpcoming(propertyIds: string[], options?: {
+        include?: string;
+    }): Promise<ReservationList>;
+    iter(params?: Omit<ReservationListParams, 'cursor'>): AsyncGenerator<Reservation>;
+}
+
+interface ReviewRatings {
+    overall: number;
+    cleanliness: number | null;
+    communication: number | null;
+    checkIn: number | null;
+    accuracy: number | null;
+    location: number | null;
+    value: number | null;
+}
+interface Review {
+    id: string;
+    reservationId: string;
+    propertyId: string;
+    guestName: string;
+    ratings: ReviewRatings;
+    body: string;
+    response: string | null;
+    submittedAt: string;
+    respondedAt: string | null;
+}
+type ReviewList = PaginatedResponse<Review>;
+interface ReviewListParams {
+    propertyId?: string;
+    responded?: boolean;
+    cursor?: string;
+    perPage?: number;
+}
+
+declare class ReviewsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(params?: ReviewListParams): Promise<ReviewList>;
+    get(id: string): Promise<Review>;
+    respond(id: string, responseText: string): Promise<Review>;
+    iter(params?: Omit<ReviewListParams, 'cursor'>): AsyncGenerator<Review>;
+}
+
+interface HospitableClientConfig {
+    /** Personal Access Token. Also read from HOSPITABLE_PAT env var. */
+    token?: string;
+    /** OAuth2 refresh token */
+    refreshToken?: string;
+    /** OAuth2 client ID */
+    clientId?: string;
+    /** OAuth2 client secret */
+    clientSecret?: string;
+    /** API base URL. Defaults to https://api.hospitable.com */
+    baseURL?: string;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+declare class HospitableClient {
+    readonly properties: PropertiesResource;
+    readonly reservations: ReservationsResource;
+    readonly calendar: CalendarResource;
+    readonly messages: MessagesResource;
+    readonly reviews: ReviewsResource;
+    constructor(config?: HospitableClientConfig);
+}
+
+declare class HospitableError extends Error {
+    readonly statusCode: number;
+    readonly requestId: string | undefined;
+    constructor(message: string, statusCode: number, requestId?: string);
+}
+declare class AuthenticationError extends HospitableError {
+    constructor(message?: string, requestId?: string);
+}
+declare class RateLimitError extends HospitableError {
+    readonly retryAfter: number;
+    constructor(retryAfter: number, requestId?: string);
+}
+declare class NotFoundError extends HospitableError {
+    readonly resource: string | undefined;
+    constructor(message?: string, requestId?: string, resource?: string);
+}
+declare class ValidationError extends HospitableError {
+    readonly fields: Record<string, string[]>;
+    constructor(message: string, fields?: Record<string, string[]>, requestId?: string);
+}
+declare class ForbiddenError extends HospitableError {
+    constructor(message?: string, requestId?: string);
+}
+declare class ServerError extends HospitableError {
+    readonly attempts: number;
+    constructor(message: string, statusCode: number, attempts: number, requestId?: string);
+}
+declare function createErrorFromResponse(statusCode: number, body: Record<string, unknown>, requestId?: string, attempts?: number): HospitableError;
+
+interface ClientConfig {
+    token?: string;
+    refreshToken?: string;
+    clientId?: string;
+    clientSecret?: string;
+    baseURL?: string;
+    onRateLimit?: (info: RateLimitInfo) => void;
+    debug?: boolean;
+}
+interface TokenResponse {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    tokenType: string;
+}
+interface RateLimitInfo {
+    retryAfter: number;
+    endpoint: string;
+    attempt: number;
+}
+
+interface TokenManagerConfig {
+    token?: string;
+    refreshToken?: string;
+    clientId?: string;
+    clientSecret?: string;
+    baseURL: string;
+}
+declare class TokenManager {
+    private readonly config;
+    private accessToken;
+    private refreshToken;
+    private expiresAt;
+    private refreshPromise;
+    constructor(config: TokenManagerConfig);
+    getAuthHeader(): Promise<string>;
+    private needsRefresh;
+    private ensureRefreshed;
+    private doRefresh;
+    handleUnauthorized(): Promise<void>;
+}
+
+interface PageFetcher<T, P extends {
+    cursor?: string;
+    perPage?: number;
+}> {
+    (params: P): Promise<PaginatedResponse<T>>;
+}
+declare function paginate<T, P extends {
+    cursor?: string;
+    perPage?: number;
+}>(fetcher: PageFetcher<T, P>, params: Omit<P, 'cursor'>, perPage?: number): AsyncGenerator<T>;
+declare function collectAll<T, P extends {
+    cursor?: string;
+    perPage?: number;
+}>(fetcher: PageFetcher<T, P>, params: Omit<P, 'cursor'>, perPage?: number): Promise<T[]>;
+
+/**
+ * Recursively masks PII and sensitive fields in an object for safe logging.
+ * Does NOT mutate the original — returns a new object with masked values.
+ * Only affects log output; never called on actual API payloads.
+ */
+declare function sanitize(value: unknown, depth?: number): unknown;
+
+declare class ReservationFilter {
+    private readonly params;
+    constructor(params?: ReservationListParams);
+    checkinAfter(date: string): ReservationFilter;
+    checkinBefore(date: string): ReservationFilter;
+    status(status: ReservationStatus | ReservationStatus[]): ReservationFilter;
+    properties(ids: string[]): ReservationFilter;
+    include(...fields: string[]): ReservationFilter;
+    perPage(n: number): ReservationFilter;
+    toParams(): ReservationListParams;
+}
+
+declare class PropertyFilter {
+    private readonly params;
+    constructor(params?: PropertyListParams);
+    tags(tagIds: string[]): PropertyFilter;
+    perPage(n: number): PropertyFilter;
+    toParams(): PropertyListParams;
+}
+
+declare const VERSION = "0.1.0";
+
+export { AuthenticationError, type CalendarDay, type CalendarGetParams, CalendarResource, type CalendarUpdate, type ClientConfig, ForbiddenError, type Guest, HospitableClient, type HospitableClientConfig, HospitableError, type Message, type MessageDirection, type MessageTemplate, type MessageThread, MessagesResource, NotFoundError, type PageFetcher, type PaginatedResponse, type PriceAmount, PropertiesResource, type Property, PropertyFilter, type PropertyList, type PropertyListParams, type PropertyPlatform, type PropertyTag, RateLimitError, type RateLimitInfo, type Reservation, ReservationFilter, type ReservationList, type ReservationListParams, type ReservationMoney, type ReservationPlatform, type ReservationStatus, ReservationsResource, type Review, type ReviewList, type ReviewListParams, type ReviewRatings, ReviewsResource, type SendMessageRequest, ServerError, TokenManager, type TokenManagerConfig, type TokenResponse, VERSION, ValidationError, collectAll, createErrorFromResponse, paginate, sanitize };