@guestcraft/react

Private, unpublished MIT helpers for GuestCraft’s React clients. Hey API generates TanStack Query factories from the OpenAPI contract; the handwritten entry point manages a caller’s workspace-scoped cache and cancellation lifetime. React and TanStack Query are peers. This package supplies data access helpers; screens and persisted workflows live in the app and server packages.

Public API

Entry point	Exports and behavior
@guestcraft/react	createGuestCraftQueries(options), with SDK GuestCraftOptions plus a required workspaceId. Options include baseUrl, injected fetch, headers and an optional GuestCraft API key.
@guestcraft/react/query/<tag>	Generated query keys, read options, infinite-query options and mutation options for the operations of one OpenAPI tag, in kebab case (reservations, room-types, …). Pass the caller’s transport client and workspace header.
@guestcraft/react/query	Every tag’s factories; a bundle that imports it carries them all.

The handwritten helper returns:

Methods	Purpose
listProperties(signal, cursor?), getProperty(id, signal)	Read local workspace properties; lists use pages of 20.
createProperty(input, signal), updateProperty(id, input, signal)	Write local properties through the SDK and clear the helper’s read cache.
connection(signal), properties(signal)	Read the Channex connection and discover upstream properties. The Channex operations load on the first of these calls (or connect), so a page that only reads local properties carries none of them.
connect(apiKey, signal)	Replace the Channex credential directly through the SDK, outside query keys/data and mutation caches; cancel/remove previous upstream-property reads.
close()	Clear the helper’s cache at the end of its caller/workspace lifetime. Abort outstanding caller work before closing.

This helper owns one short-lived cache. In a component, keep it for that caller/workspace, abort requests on cleanup and call close() on unmount or before switching identity or workspace. Server requests must each get their own instance. This function illustrates a single operation with guaranteed cleanup; callers supply the instance URL, workspace and request cancellation signal.

import { createGuestCraftQueries } from "@guestcraft/react";
import type { GuestCraftOptions } from "@guestcraft/sdk";

export async function listWorkspaceProperties(
  options: GuestCraftOptions & { readonly workspaceId: string },
  signal: AbortSignal,
) {
  const queries = createGuestCraftQueries(options);
  try {
    return await queries.listProperties(signal);
  } finally {
    queries.close();
  }
}

Generated operations and cache ownership

The generated API reference groups endpoints by tag; the API README links their workflow contracts. Factories cover properties, inventory, guests (including duplicate review, merge, consent history and owning-property reassignment), reservations and stay transitions, planning, rates/quotes, folios, policies, room blocks and maintenance tickets, reports, team/access, night audits, Channex booking/ARI/messages, devices/workspaces, API keys and webhooks. They do not broaden server-side permissions.

Generated options take client from createGuestCraftTransport (or transport from createGuestCraft) and headers: { "GuestCraft-Workspace-Id": workspaceId }. Scope both the SDK and QueryClient to the current caller/workspace; never share authenticated clients or caches across sessions. The handwritten helper disables read retries and gives queries zero stale/garbage-collection time. When consuming generated factories directly, configure retry/caching explicitly and invalidate affected read models after mutations. Do not automatically retry writes whose outcome is unknown.

Keep credentials and one-time API-key/webhook secrets out of query keys and mutation caches. Use the SDK directly for those writes. A Channex credential passed to connect authorizes GuestCraft’s upstream calls; the SDK’s apiKey option authenticates a GuestCraft integration. See the integration contract.

Generation and tests

pnpm --filter @guestcraft/react test
pnpm --filter @guestcraft/react typecheck
pnpm --filter @guestcraft/sdk generate:check
pnpm --filter @guestcraft/scripts test:integration test/integration/readme-examples.integration.test.ts

Unit tests use injected transports to verify workspace/cache isolation, cancellation, credential replacement and local property operations without network credentials. The README example check compiles the actual TypeScript fence. Generation and drift checks run through the SDK’s Hey API pipeline; generated files are not edited by hand. ADR 0022 records the package boundary and generation design.

Guest review factories include guestsContactNoticesOptions and guestsDismissContactNoticeMutation under @guestcraft/react/query/guests. The mutation requires the guest ETag plus snapshot revision and expected field value. Invalidate the guest and contact-notice queries after a decision; fetch them again after a version or snapshot conflict before offering another decision. Notice contacts contain only actionable fields and never operator notes.