@v-office/website-sdk

Website-facing SDK facade for vOffice backends.

The current SDK includes catalog-backed custom attributes and v9 built-in attributes, backend-aware search, localized search discount details, and quote booking-card modifier output. See instructions/CHANGELOG.md for the complete release history.

Install

pnpm add @v-office/website-sdk

The package is ESM-only and exposes:

• @v-office/website-sdk
• @v-office/website-sdk/cli
• @v-office/website-sdk/package.json

Create a SDK

import { createWebsiteSDK, defineWebsiteSDKOptions } from "@v-office/website-sdk";

const sdk = createWebsiteSDK({
  config: {
    backend: "v10",
    apiEndpoint: "https://api.example.com/graphql",
    searchEndpoint: "https://search.example.com/search",
    accessToken: "...",
    imageBaseUrl: "https://images.example.com",
  },
  options: defineWebsiteSDKOptions({
    rentalScope: {
      propertyId: "property-1",
    },
  }),
});

try {
  const rentals = await sdk.static.rentals.getRentals({ locale: "de-DE" });
  console.log(rentals);
} finally {
  await sdk.dispose();
}

For v9:

const sdk = createWebsiteSDK({
  config: {
    backend: "v9",
    graphqlUrl: "https://example.com/graphql",
    apiKey: "...",
    imageProxyBaseUrl: "https://images.example.com",
    v1ApiBaseUrl: "https://example.com/api/v1",
    v0ApiBaseUrl: "https://example.com/api/v0",
    // Optional: associate facilities through a facility p_* object-group field.
    facilityObjectGroupRelationAttributeId: 18962,
  },
});

To expose newline-separated facility text such as p_18963 through the existing v9 property.highlights, define a stable source and select its key:

import { defineV9PropertyHighlightSources } from "@v-office/website-sdk";

const v9PropertyHighlightSources = defineV9PropertyHighlightSources({
  facilityHighlights: { v9: "p_18963", type: "line-list" },
});

const options = defineWebsiteSDKOptions({
  v9PropertyHighlightSources,
  rentalPropertyHighlightPrioritization: [v9PropertyHighlightSources.keys.facilityHighlights],
});

SDK Surface

The facade exposes Promise-based static and live APIs:

sdk.static.rentals.getRentals(input);
sdk.static.filter.getFilters(input);
// v10 only:
sdk.static.documents.getTermsAndPrivacyPolicy(input);

sdk.live.search.search(input);
// v9 only:
sdk.live.rentals.getRentalsByIds(input);
sdk.live.voucher.validate(input);
sdk.live.availability.getInitialAvailability(input);
sdk.live.availability.getStartDateSelectedAvailability(input);
sdk.live.quote.quote(input);
sdk.live.booking.book(input);
sdk.live.contact.submit(input);

await sdk.dispose();

Both backends support fixed start/end search periods. Flexible-period query keys (month, dates, nights, and weekend) are v10-only and are rejected before transport by the v9 facade. An empty v9 query browses the scoped searchable inventory without requiring a dummy occupancy value.

Quote mutation helpers are available under sdk.live.quote:

• addAdditionalService
• removeAdditionalService
• clearAdditionalServices
• selectCancellationPolicy
• selectInsurance
• createInsurancePreContract
• selectInsurancePayment
• bookInsurance

CLI

website-sdk --backend v10 rentals --locale de-DE
website-sdk --backend v9 filters --locale en-US
website-sdk --backend v10 search --locale de-DE --query "adults=2"
website-sdk --backend v9 rentals-by-ids --locale de-DE --rental-ids 12,34
website-sdk --backend v9 voucher validate --code SUMMER26
website-sdk --backend v9 hub-filters request --object-group

The CLI can read config from environment variables or from JSON files:

website-sdk --backend v10 --config ./website-sdk-config.json --options ./website-sdk-options.json rentals --locale de-DE

For v10, environment configuration uses:

• VOFFICE_API_ENDPOINT
• VOFFICE_SEARCH_ENDPOINT
• VOFFICE_LOCAL_DEV_ACCESS_TOKEN
• VOFFICE_IMAGE_BASE_URL

For v9, environment configuration uses:

• HUB_GRAPHQL_URL
• HUB_V1_API_BASE_URL
• HUB_API_KEY
• IMAGE_PROXY_BASE_URL
• HUB_V0_API_BASE_URL optional
• HUB_RENTAL_SCOPE_PROPERTY_KIND optional, facility or objectGroup
• HUB_RENTAL_IDS_SEARCH optional, true or false

Migration From Legacy

The 2.0.0 line was the breaking migration from the legacy SDK API. If you are still migrating from legacy, the largest changes are:

• createCMSSDKFromParsedConfig(...) was replaced by createWebsiteSDK({ config, options }).
• Config moved from nested { backend, v9: {...} } / { backend, v10: {...} } objects to flat WebsiteSDKConfig objects.
• Public type names moved from CMS naming to Website naming.
• The error model now comes from @v-office/sdk-core.
• CLI config JSON uses the new flat config shape.

Custom attributes are configured by joining a v10 catalog with authored site policy:

import { defineCustomAttributes } from "@v-office/website-sdk";

const customAttributes = defineCustomAttributes({
  catalog,
  select: {
    region: {
      label: { "de-DE": "Region", "en-US": "Region" },
      filter: true,
      optionLabels: {
        north: { "de-DE": "Norden", "en-US": "North" },
      },
    },
  },
});

See instructions/custom-attributes.md before migrating an older customAttributeDefinitionManifest configuration.

See instructions/ for the full consumer documentation. Version-specific release notes and migration details live under instructions/versions/, with indexes at instructions/CHANGELOG.md and instructions/MIGRATION.md.