@seamapi/react 5.0.0 → 5.1.1

package/src/lib/seam/ecosystem/use-compatible-partners.ts

@@ -0,0 +1,80 @@
+import { useQuery } from '@tanstack/react-query'
+
+import {
+  type EcosystemApiError,
+  fetchEcosystem,
+} from 'lib/seam/ecosystem/client.js'
+import { useEcosystemContext } from 'lib/seam/ecosystem/EcosystemProvider.js'
+import type {
+  CompatibilityResponse,
+  CompatiblePartner,
+} from 'lib/seam/ecosystem/types.js'
+import {
+  retryEcosystemQuery,
+  type UseEcosystemQueryResult,
+} from 'lib/seam/ecosystem/use-ecosystem-query-result.js'
+
+export interface UseCompatiblePartnersParams {
+  /** Device category, e.g., `smartlock`, `thermostat`, `sensor`, `intercom`. */
+  deviceType: string
+  /** DeviceDB manufacturer slug, e.g., `schlage`. */
+  manufacturer?: string | undefined
+  /** DeviceDB provider slug, e.g., `salto-ks`. */
+  provider?: string | undefined
+  /** DeviceDB capability, e.g., `can_provision_mobile_keys`. */
+  capability?: string | undefined
+  /** Industry slug, e.g., `short-term-rental`. */
+  industry?: string | undefined
+}
+
+export type UseCompatiblePartnersData = CompatiblePartner[]
+
+/**
+ * The live partners that support a device category, manufacturer, provider
+ * or capability through Seam, from Ecosystem `GET /v1/compatibility`.
+ * Declared-first: a partner is listed only where Seam or the partner declared support.
+ */
+export function useCompatiblePartners({
+  deviceType,
+  manufacturer = '',
+  provider = '',
+  capability = '',
+  industry = '',
+}: UseCompatiblePartnersParams): UseEcosystemQueryResult<
+  'partners',
+  UseCompatiblePartnersData
+> {
+  const { embedKey, endpoint } = useEcosystemContext()
+
+  const params = {
+    device_category: deviceType.trim(),
+    manufacturer_slug: manufacturer.trim(),
+    provider_slug: provider.trim(),
+    capability: capability.trim(),
+    industry: industry.trim(),
+  }
+
+  const { data, ...rest } = useQuery<
+    UseCompatiblePartnersData,
+    EcosystemApiError
+  >({
+    enabled: params.device_category.length > 0,
+    queryKey: [
+      'ecosystem',
+      endpoint,
+      embedKey ?? null,
+      'compatibility',
+      params,
+    ],
+    queryFn: async ({ signal }) => {
+      const { partners } = await fetchEcosystem<CompatibilityResponse>(
+        'compatibility',
+        { endpoint, embedKey, params, signal }
+      )
+      return partners
+    },
+    retry: retryEcosystemQuery,
+  })
+
+  return { ...rest, partners: data }
+}

package/src/lib/seam/ecosystem/use-ecosystem-device-model-summaries.ts

@@ -0,0 +1,89 @@
+import { useQuery } from '@tanstack/react-query'
+
+import {
+  type EcosystemApiError,
+  fetchEcosystem,
+} from 'lib/seam/ecosystem/client.js'
+import { useEcosystemContext } from 'lib/seam/ecosystem/EcosystemProvider.js'
+import type {
+  DeviceModelSummariesListResponse,
+  DeviceModelSummary,
+} from 'lib/seam/ecosystem/types.js'
+import type { UseEcosystemDeviceModelsParams } from 'lib/seam/ecosystem/use-ecosystem-device-models.js'
+import {
+  retryEcosystemQuery,
+  type UseEcosystemQueryResult,
+} from 'lib/seam/ecosystem/use-ecosystem-query-result.js'
+
+export type UseEcosystemDeviceModelSummariesParams =
+  UseEcosystemDeviceModelsParams
+
+export type UseEcosystemDeviceModelSummariesData = DeviceModelSummary[]
+
+const pageSize = 500
+const maxPages = 20
+
+/**
+ * Published device models in the slim summary shape from Ecosystem
+ * `GET /v1/device_models/summaries/list` (no commerce data),
+ * following pagination to return every matching model.
+ */
+export function useEcosystemDeviceModelSummaries({
+  manufacturer = '',
+  deviceType = '',
+  provider = '',
+  capability = '',
+  enabled = true,
+}: UseEcosystemDeviceModelSummariesParams = {}): UseEcosystemQueryResult<
+  'deviceModels',
+  UseEcosystemDeviceModelSummariesData
+> {
+  const { embedKey, endpoint } = useEcosystemContext()
+
+  const params = {
+    manufacturer: manufacturer.trim(),
+    device_type: deviceType.trim(),
+    provider: provider.trim(),
+    capability: capability.trim(),
+  }
+
+  const { data, ...rest } = useQuery<
+    UseEcosystemDeviceModelSummariesData,
+    EcosystemApiError
+  >({
+    enabled,
+    queryKey: [
+      'ecosystem',
+      endpoint,
+      embedKey ?? null,
+      'device_models',
+      'summaries',
+      'list',
+      params,
+    ],
+    queryFn: async ({ signal }) => {
+      const deviceModels: DeviceModelSummary[] = []
+      let pageCursor: string | undefined
+      for (let page = 0; page < maxPages; page++) {
+        const res = await fetchEcosystem<DeviceModelSummariesListResponse>(
+          'device_models/summaries/list',
+          {
+            endpoint,
+            embedKey,
+            params: { ...params, limit: pageSize, page_cursor: pageCursor },
+            signal,
+          }
+        )
+        deviceModels.push(...res.device_models)
+        const { has_next_page: hasNextPage, next_page_cursor: nextPageCursor } =
+          res.pagination
+        if (!hasNextPage || nextPageCursor == null) break
+        pageCursor = nextPageCursor
+      }
+      return deviceModels
+    },
+    retry: retryEcosystemQuery,
+  })
+
+  return { ...rest, deviceModels: data }
+}

package/src/lib/seam/ecosystem/use-ecosystem-device-models.ts

@@ -0,0 +1,96 @@
+import { useQuery } from '@tanstack/react-query'
+
+import {
+  type EcosystemApiError,
+  fetchEcosystem,
+} from 'lib/seam/ecosystem/client.js'
+import { useEcosystemContext } from 'lib/seam/ecosystem/EcosystemProvider.js'
+import type {
+  DeviceModel,
+  DeviceModelsListResponse,
+} from 'lib/seam/ecosystem/types.js'
+import {
+  retryEcosystemQuery,
+  type UseEcosystemQueryResult,
+} from 'lib/seam/ecosystem/use-ecosystem-query-result.js'
+
+export interface UseEcosystemDeviceModelsParams {
+  /** DeviceDB manufacturer slug, e.g., `schlage`. */
+  manufacturer?: string | undefined
+  /** DeviceDB device type slug, e.g., `smartlock`. */
+  deviceType?: string | undefined
+  /** DeviceDB provider slug, e.g., `salto-ks`. */
+  provider?: string | undefined
+  /** Only device models with a computed capability of this name. */
+  capability?: string | undefined
+  /** Set to false to wait before fetching. */
+  enabled?: boolean | undefined
+}
+
+export type UseEcosystemDeviceModelsData = DeviceModel[]
+
+const pageSize = 500
+const maxPages = 20
+
+/**
+ * Published device models from Ecosystem `GET /v1/device_models/list`,
+ * following pagination to return every matching model.
+ */
+export function useEcosystemDeviceModels({
+  manufacturer = '',
+  deviceType = '',
+  provider = '',
+  capability = '',
+  enabled = true,
+}: UseEcosystemDeviceModelsParams = {}): UseEcosystemQueryResult<
+  'deviceModels',
+  UseEcosystemDeviceModelsData
+> {
+  const { embedKey, endpoint } = useEcosystemContext()
+
+  const params = {
+    manufacturer: manufacturer.trim(),
+    device_type: deviceType.trim(),
+    provider: provider.trim(),
+    capability: capability.trim(),
+  }
+
+  const { data, ...rest } = useQuery<
+    UseEcosystemDeviceModelsData,
+    EcosystemApiError
+  >({
+    enabled,
+    queryKey: [
+      'ecosystem',
+      endpoint,
+      embedKey ?? null,
+      'device_models',
+      'list',
+      params,
+    ],
+    queryFn: async ({ signal }) => {
+      const deviceModels: DeviceModel[] = []
+      let pageCursor: string | undefined
+      for (let page = 0; page < maxPages; page++) {
+        const res = await fetchEcosystem<DeviceModelsListResponse>(
+          'device_models/list',
+          {
+            endpoint,
+            embedKey,
+            params: { ...params, limit: pageSize, page_cursor: pageCursor },
+            signal,
+          }
+        )
+        deviceModels.push(...res.device_models)
+        const { has_next_page: hasNextPage, next_page_cursor: nextPageCursor } =
+          res.pagination
+        if (!hasNextPage || nextPageCursor == null) break
+        pageCursor = nextPageCursor
+      }
+      return deviceModels
+    },
+    retry: retryEcosystemQuery,
+  })
+
+  return { ...rest, deviceModels: data }
+}

package/src/lib/seam/ecosystem/use-ecosystem-manufacturers.ts

@@ -0,0 +1,86 @@
+import { useQuery } from '@tanstack/react-query'
+
+import {
+  type EcosystemApiError,
+  fetchEcosystem,
+} from 'lib/seam/ecosystem/client.js'
+import { useEcosystemContext } from 'lib/seam/ecosystem/EcosystemProvider.js'
+import type {
+  Manufacturer,
+  ManufacturersListResponse,
+} from 'lib/seam/ecosystem/types.js'
+import {
+  retryEcosystemQuery,
+  type UseEcosystemQueryResult,
+} from 'lib/seam/ecosystem/use-ecosystem-query-result.js'
+
+export interface UseEcosystemManufacturersParams {
+  /** Only manufacturers with these slugs. */
+  slugs?: string[] | undefined
+  /** Set to false to wait before fetching. */
+  enabled?: boolean | undefined
+}
+
+export type UseEcosystemManufacturersData = Manufacturer[]
+
+const pageSize = 500
+const maxPages = 10
+
+/** Published manufacturers from Ecosystem `GET /v1/manufacturers/list`. */
+export function useEcosystemManufacturers({
+  slugs,
+  enabled = true,
+}: UseEcosystemManufacturersParams = {}): UseEcosystemQueryResult<
+  'manufacturers',
+  UseEcosystemManufacturersData
+> {
+  const { embedKey, endpoint } = useEcosystemContext()
+
+  const sortedSlugs =
+    slugs == null
+      ? null
+      : [...new Set(slugs)].sort((a, b) => a.localeCompare(b))
+
+  const { data, ...rest } = useQuery<
+    UseEcosystemManufacturersData,
+    EcosystemApiError
+  >({
+    enabled: enabled && (sortedSlugs == null || sortedSlugs.length > 0),
+    queryKey: [
+      'ecosystem',
+      endpoint,
+      embedKey ?? null,
+      'manufacturers',
+      'list',
+      { slugs: sortedSlugs },
+    ],
+    queryFn: async ({ signal }) => {
+      const manufacturers: Manufacturer[] = []
+      let pageCursor: string | undefined
+      for (let page = 0; page < maxPages; page++) {
+        const res = await fetchEcosystem<ManufacturersListResponse>(
+          'manufacturers/list',
+          {
+            endpoint,
+            embedKey,
+            params: {
+              slugs: sortedSlugs ?? undefined,
+              limit: pageSize,
+              page_cursor: pageCursor,
+            },
+            signal,
+          }
+        )
+        manufacturers.push(...res.manufacturers)
+        const { has_next_page: hasNextPage, next_page_cursor: nextPageCursor } =
+          res.pagination
+        if (!hasNextPage || nextPageCursor == null) break
+        pageCursor = nextPageCursor
+      }
+      return manufacturers
+    },
+    retry: retryEcosystemQuery,
+  })
+
+  return { ...rest, manufacturers: data }
+}

package/src/lib/seam/ecosystem/use-ecosystem-query-result.ts

@@ -0,0 +1,19 @@
+import type { UseQueryResult } from '@tanstack/react-query'
+
+import type { EcosystemApiError } from 'lib/seam/ecosystem/client.js'
+
+export type UseEcosystemQueryResult<Field extends string, Data> = Omit<
+  UseQueryResult<Data, EcosystemApiError>,
+  'data'
+> & {
+  [key in Field]?: Data
+}
+
+/** Retry server and network errors, but not client errors such as an invalid embed key. */
+export const retryEcosystemQuery = (
+  failureCount: number,
+  error: EcosystemApiError
+): boolean => {
+  if (error.status >= 400 && error.status < 500) return false
+  return failureCount < 2
+}

package/src/lib/seam/ecosystem/use-embed-key-resolution.ts

@@ -0,0 +1,80 @@
+import { useQuery } from '@tanstack/react-query'
+
+import {
+  type EcosystemApiError,
+  fetchEcosystem,
+} from 'lib/seam/ecosystem/client.js'
+import { useEcosystemContext } from 'lib/seam/ecosystem/EcosystemProvider.js'
+import type { EmbedResolution } from 'lib/seam/ecosystem/types.js'
+import {
+  retryEcosystemQuery,
+  type UseEcosystemQueryResult,
+} from 'lib/seam/ecosystem/use-ecosystem-query-result.js'
+
+export interface UseEmbedKeyResolutionParams {
+  /** Resolve the partner's capability exclusions for this capability. */
+  capability?: string | undefined
+}
+
+export type UseEmbedKeyResolutionData = EmbedResolution
+
+/**
+ * Validates the provider's embed key against the page origin with
+ * Ecosystem `GET /v1/embed/resolve` and returns the key's public record
+ * and, for partner keys, what the partner's widgets must not show.
+ * Disabled when there is no embed key.
+ */
+export function useEmbedKeyResolution({
+  capability = '',
+}: UseEmbedKeyResolutionParams = {}): UseEcosystemQueryResult<
+  'embedResolution',
+  UseEmbedKeyResolutionData
+> {
+  const { embedKey, endpoint } = useEcosystemContext()
+
+  const params = { capability: capability.trim() }
+
+  const { data, ...rest } = useQuery<
+    UseEmbedKeyResolutionData,
+    EcosystemApiError
+  >({
+    enabled: embedKey != null,
+    queryKey: [
+      'ecosystem',
+      endpoint,
+      embedKey ?? null,
+      'embed',
+      'resolve',
+      params,
+    ],
+    queryFn: async ({ signal }) =>
+      await fetchEcosystem<EmbedResolution>('embed/resolve', {
+        endpoint,
+        embedKey,
+        params,
+        signal,
+      }),
+    retry: retryEcosystemQuery,
+  })
+
+  return { ...rest, embedResolution: data }
+}
+
+/**
+ * The manufacturer an embed key is scoped to, if any.
+ * Prefers the `manufacturer_context` Ecosystem returns for manufacturer keys (DEVDB-439),
+ * and falls back to the key's own `manufacturer_slug`.
+ */
+export const getEmbedKeyManufacturer = (
+  resolution: EmbedResolution | null | undefined
+): string | null => {
+  if (resolution == null) return null
+  const contextSlug = resolution.manufacturer_context?.manufacturer_slug
+  if (contextSlug != null && contextSlug.length > 0) return contextSlug
+  const { owner_kind: ownerKind, manufacturer_slug: slug } =
+    resolution.embed_key
+  if (ownerKind === 'manufacturer' && slug != null && slug.length > 0) {
+    return slug
+  }
+  return null
+}

package/src/lib/seam/index.ts

@@ -10,5 +10,6 @@ export * from './connected-accounts/use-connected-account.js'
 export * from './devices/use-device.js'
 export * from './devices/use-device-providers.js'
 export * from './devices/use-devices.js'
+export * from './ecosystem/index.js'
 export * from './SeamProvider.js'
 export * from './use-seam-query-result.js'

package/src/lib/seam/seam-components-class-name.ts

@@ -0,0 +1 @@
+export const seamComponentsClassName = 'seam-components'

package/src/lib/ui/ecosystem/SearchField.tsx

@@ -0,0 +1,32 @@
+import { SearchIcon } from 'lib/icons/Search.js'
+
+interface SearchFieldProps {
+  value: string
+  onChange: (value: string) => void
+  label: string
+  disabled?: boolean
+}
+
+export function SearchField({
+  value,
+  onChange,
+  label,
+  disabled = false,
+}: SearchFieldProps): JSX.Element {
+  return (
+    <label className='seam-ecosystem-search'>
+      <SearchIcon aria-hidden className='seam-ecosystem-search-icon' />
+      <input
+        type='search'
+        className='seam-ecosystem-search-input'
+        placeholder={label}
+        aria-label={label}
+        value={value}
+        disabled={disabled}
+        onChange={(event) => {
+          onChange(event.target.value)
+        }}
+      />
+    </label>
+  )
+}

package/src/lib/ui/ecosystem/StateMessage.tsx

@@ -0,0 +1,29 @@
+import type { PropsWithChildren } from 'react'
+
+interface StateMessageProps extends PropsWithChildren {
+  actionLabel?: string
+  onAction?: () => void
+  role?: 'status' | 'alert'
+}
+
+export function StateMessage({
+  children,
+  actionLabel,
+  onAction,
+  role = 'status',
+}: StateMessageProps): JSX.Element {
+  return (
+    <div className='seam-ecosystem-message' role={role}>
+      <p>{children}</p>
+      {actionLabel != null && onAction != null && (
+        <button
+          type='button'
+          className='seam-ecosystem-button'
+          onClick={onAction}
+        >
+          {actionLabel}
+        </button>
+      )}
+    </div>
+  )
+}

package/src/lib/ui/ecosystem/errors.ts

@@ -0,0 +1,30 @@
+import { EcosystemApiError } from 'lib/seam/ecosystem/client.js'
+
+/** A message for an Ecosystem error, and whether retrying could help. */
+export const getEcosystemErrorMessage = (
+  error: unknown,
+  fallback: string
+): { message: string; canRetry: boolean } => {
+  if (error instanceof EcosystemApiError) {
+    if (error.type === 'embed_key_required') {
+      return { message: t.embedKeyRequired, canRetry: false }
+    }
+    if (error.type === 'origin_not_allowed') {
+      return { message: t.originNotAllowed, canRetry: false }
+    }
+    if (error.status === 401) {
+      return { message: t.invalidEmbedKey, canRetry: false }
+    }
+    if (error.status === 403) {
+      return { message: t.originNotAllowed, canRetry: false }
+    }
+  }
+  return { message: fallback, canRetry: true }
+}
+
+const t = {
+  embedKeyRequired:
+    'An embed key is required to show this list on this website.',
+  invalidEmbedKey: 'The embed key is invalid or has been revoked.',
+  originNotAllowed: 'The embed key is not allowed on this website.',
+}

package/src/lib/ui/ecosystem/storybook.tsx

@@ -0,0 +1,40 @@
+import type { Decorator } from '@storybook/react'
+
+import { EcosystemProvider } from 'lib/seam/ecosystem/EcosystemProvider.js'
+
+// Embed keys accepted by the fake Ecosystem API served at /api/ecosystem
+// (.storybook/fake-ecosystem.js). The Storybook never uses a real key or production data.
+export const storybookEmbedKeys = {
+  seam: 'eco_live_storybook',
+  partner: 'eco_live_storybook_partner',
+  manufacturer: 'eco_live_storybook_schlage',
+  wrongOrigin: 'eco_live_storybook_wrong_origin',
+  invalid: 'eco_live_invalid',
+} as const
+
+export const storybookEcosystemEndpoint = '/api/ecosystem/v1/'
+
+export interface EcosystemStoryArgs {
+  embedKey?: string | undefined
+}
+
+/** Wraps a story in an EcosystemProvider pointed at the fake Ecosystem API. */
+export const withFakeEcosystem: Decorator<EcosystemStoryArgs> = (
+  Story,
+  context
+) => (
+  <EcosystemProvider
+    embedKey={context.args.embedKey}
+    ecosystemEndpoint={storybookEcosystemEndpoint}
+    disableCssInjection
+    disableFontInjection
+  >
+    <Story />
+  </EcosystemProvider>
+)
+
+export const withDarkBackground: Decorator = (Story) => (
+  <div style={{ background: '#0b0d10', padding: 24, borderRadius: 12 }}>
+    <Story />
+  </div>
+)

package/src/lib/ui/ecosystem/theme.ts

@@ -0,0 +1,14 @@
+export type EcosystemTheme = 'light' | 'dark' | 'auto'
+
+/**
+ * The class name for an Ecosystem component theme.
+ * `auto` follows the visitor's `prefers-color-scheme`.
+ */
+export const getEcosystemThemeClassName = (
+  theme: string | undefined
+): string => {
+  if (theme === 'dark' || theme === 'auto') {
+    return `seam-ecosystem-theme-${theme}`
+  }
+  return 'seam-ecosystem-theme-light'
+}

package/src/lib/version.ts

@@ -1,3 +1,3 @@
-const seamapiReactVersion = '5.0.0'
+const seamapiReactVersion = '5.1.1'
 
 export default seamapiReactVersion