@seamapi/react 5.0.0 → 5.1.1

package/src/lib/seam/components/index.ts

@@ -1,8 +1,10 @@
 export * from './AccessCodeDetails/AccessCodeDetails.js'
 export * from './AccessCodeTable/AccessCodeTable.js'
 export * from './common-props.js'
+export * from './CompatibleApps/CompatibleApps.js'
 export * from './ConnectAccountButton/ConnectAccountButton.js'
 export * from './CreateAccessCodeForm/CreateAccessCodeForm.js'
 export * from './DeviceDetails/DeviceDetails.js'
 export * from './DeviceTable/DeviceTable.js'
 export * from './EditAccessCodeForm/EditAccessCodeForm.js'
+export * from './SupportedDevices/SupportedDevices.js'

package/src/lib/seam/ecosystem/EcosystemProvider.tsx

@@ -0,0 +1,133 @@
+import {
+  QueryClient,
+  QueryClientContext,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+import {
+  createContext,
+  type PropsWithChildren,
+  useContext,
+  useMemo,
+} from 'react'
+
+import { defaultEcosystemEndpoint } from 'lib/seam/ecosystem/client.js'
+import { seamComponentsClassName } from 'lib/seam/seam-components-class-name.js'
+import { useSeamFont } from 'lib/seam/use-seam-font.js'
+import { useSeamStyles } from 'lib/seam/use-seam-styles.js'
+
+export interface EcosystemContext {
+  /** The embed key sent as `X-Embed-Key`, if any. */
+  embedKey: string | undefined
+  /** The Ecosystem API endpoint, ending in `/`. */
+  endpoint: string
+}
+
+export interface EcosystemOptions {
+  /**
+   * Seam Ecosystem embed key (`eco_live_…`).
+   * Required outside seam.co: the key's allowed origins must include the page origin.
+   */
+  embedKey?: string | undefined
+  /** Seam Ecosystem API endpoint. Defaults to `https://ecosystem.seam.co/v1/`. */
+  ecosystemEndpoint?: string | undefined
+}
+
+export interface EcosystemProviderProps
+  extends EcosystemOptions,
+    PropsWithChildren {
+  queryClient?: QueryClient | undefined
+  disableCssInjection?: boolean | undefined
+  disableFontInjection?: boolean | undefined
+  unminifiyCss?: boolean | undefined
+}
+
+const defaultQueryClient = new QueryClient()
+
+/**
+ * Provides the Seam Ecosystem context for `CompatibleApps` and `SupportedDevices`.
+ *
+ * Unlike `SeamProvider`, this does not need a Seam publishable key
+ * and does not load the Seam API client, so it stays lightweight.
+ * Inside a `SeamProvider`, pass `embedKey` to the `SeamProvider` instead.
+ */
+export function EcosystemProvider({
+  children,
+  queryClient,
+  disableCssInjection = false,
+  disableFontInjection = false,
+  unminifiyCss = false,
+  ...options
+}: EcosystemProviderProps): JSX.Element {
+  useSeamStyles({ disabled: disableCssInjection, unminified: unminifiyCss })
+  useSeamFont({ disabled: disableFontInjection })
+
+  const queryClientFromContext = useContext(QueryClientContext)
+
+  return (
+    <div className={seamComponentsClassName}>
+      <QueryClientProvider
+        client={
+          queryClient ??
+          queryClientFromContext ??
+          globalThis.seamQueryClient ??
+          defaultQueryClient
+        }
+      >
+        <EcosystemContextProvider {...options}>
+          {children}
+        </EcosystemContextProvider>
+      </QueryClientProvider>
+    </div>
+  )
+}
+
+/**
+ * Provides only the Ecosystem context; used by `SeamProvider`.
+ * Unset options inherit from an enclosing provider.
+ */
+export function EcosystemContextProvider({
+  children,
+  embedKey,
+  ecosystemEndpoint,
+}: EcosystemOptions & PropsWithChildren): JSX.Element {
+  const parent = useContext(ecosystemContext)
+
+  const value = useMemo(
+    () => ({
+      embedKey: normalizeEmbedKey(embedKey) ?? parent.embedKey,
+      endpoint: normalizeEndpoint(ecosystemEndpoint) ?? parent.endpoint,
+    }),
+    [embedKey, ecosystemEndpoint, parent]
+  )
+
+  return (
+    <ecosystemContext.Provider value={value}>
+      {children}
+    </ecosystemContext.Provider>
+  )
+}
+
+export function useEcosystemContext(): EcosystemContext {
+  return useContext(ecosystemContext)
+}
+
+const normalizeEmbedKey = (
+  embedKey: string | undefined
+): string | undefined => {
+  const key = embedKey?.trim()
+  if (key == null || key.length === 0) return undefined
+  return key
+}
+
+const normalizeEndpoint = (
+  endpoint: string | undefined
+): string | undefined => {
+  const value = endpoint?.trim()
+  if (value == null || value.length === 0) return undefined
+  return value.endsWith('/') ? value : `${value}/`
+}
+
+const ecosystemContext = createContext<EcosystemContext>({
+  embedKey: undefined,
+  endpoint: defaultEcosystemEndpoint,
+})

package/src/lib/seam/ecosystem/client.ts

@@ -0,0 +1,116 @@
+import type { EcosystemErrorResponse } from './types.js'
+
+export const defaultEcosystemEndpoint = 'https://ecosystem.seam.co/v1/'
+
+export type EcosystemQueryParams = Record<
+  string,
+  string | number | boolean | string[] | null | undefined
+>
+
+export interface EcosystemRequestOptions {
+  endpoint: string
+  embedKey?: string | undefined
+  params?: EcosystemQueryParams
+  signal?: AbortSignal
+}
+
+/**
+ * An error response from the Ecosystem API.
+ * The `type` is the API error type, e.g., `embed_key_required`,
+ * `invalid_embed_key` or `origin_not_allowed`.
+ */
+export class EcosystemApiError extends Error {
+  readonly status: number
+  readonly type: string
+  readonly requestId: string | null
+
+  constructor({
+    status,
+    type,
+    message,
+    requestId = null,
+  }: {
+    status: number
+    type: string
+    message: string
+    requestId?: string | null
+  }) {
+    super(message)
+    this.name = 'EcosystemApiError'
+    this.status = status
+    this.type = type
+    this.requestId = requestId
+  }
+}
+
+/** True when the error means the embed key is missing, invalid or not allowed here. */
+export const isEmbedKeyError = (error: unknown): boolean =>
+  error instanceof EcosystemApiError &&
+  (error.status === 401 || error.status === 403)
+
+export const getEcosystemUrl = (
+  endpoint: string,
+  path: string,
+  params: EcosystemQueryParams = {}
+): URL => {
+  const base = endpoint.endsWith('/') ? endpoint : `${endpoint}/`
+  const url = new URL(path, new URL(base, globalThis.location?.href))
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null) continue
+    if (Array.isArray(value)) {
+      if (value.length === 0) continue
+      url.searchParams.set(key, value.join(','))
+      continue
+    }
+    if (typeof value === 'string' && value.length === 0) continue
+    url.searchParams.set(key, String(value))
+  }
+  return url
+}
+
+export const fetchEcosystem = async <T>(
+  path: string,
+  { endpoint, embedKey, params, signal }: EcosystemRequestOptions
+): Promise<T> => {
+  const url = getEcosystemUrl(endpoint, path, params)
+
+  const headers: Record<string, string> = { Accept: 'application/json' }
+  if (embedKey != null && embedKey.length > 0) {
+    headers['X-Embed-Key'] = embedKey
+  }
+
+  const res = await globalThis.fetch(url, {
+    headers,
+    ...(signal == null ? {} : { signal }),
+  })
+
+  const body = (await res.json().catch(() => null)) as unknown
+
+  if (!res.ok) {
+    const error = isErrorResponse(body) ? body.error : null
+    throw new EcosystemApiError({
+      status: res.status,
+      type: error?.type ?? 'unknown_error',
+      message:
+        error?.message ?? `Ecosystem request failed with status ${res.status}`,
+      requestId: error?.request_id ?? null,
+    })
+  }
+
+  if (body == null || typeof body !== 'object') {
+    throw new EcosystemApiError({
+      status: res.status,
+      type: 'invalid_response',
+      message: 'Ecosystem returned an invalid response',
+    })
+  }
+
+  return body as T
+}
+
+const isErrorResponse = (body: unknown): body is EcosystemErrorResponse =>
+  body != null &&
+  typeof body === 'object' &&
+  'error' in body &&
+  body.error != null &&
+  typeof body.error === 'object'

package/src/lib/seam/ecosystem/index.ts

@@ -0,0 +1,19 @@
+export {
+  defaultEcosystemEndpoint,
+  EcosystemApiError,
+  isEmbedKeyError,
+} from './client.js'
+export {
+  type EcosystemContext,
+  type EcosystemOptions,
+  EcosystemProvider,
+  type EcosystemProviderProps,
+  useEcosystemContext,
+} from './EcosystemProvider.js'
+export * from './types.js'
+export * from './use-compatible-partners.js'
+export * from './use-ecosystem-device-models.js'
+export * from './use-ecosystem-manufacturers.js'
+export type { UseEcosystemQueryResult } from './use-ecosystem-query-result.js'
+export * from './use-embed-key-resolution.js'
+export type { EcosystemTheme } from 'lib/ui/ecosystem/theme.js'

package/src/lib/seam/ecosystem/types.ts

@@ -0,0 +1,402 @@
+/**
+ * Response types for the public Seam Ecosystem API (PartnerDB and DeviceDB).
+ *
+ * Hand-copied from the zod schemas in `seamapi/ecosystem` `public-types/`
+ * (origin/main 055335c, 2026-10-17) to avoid a zod runtime dependency.
+ * Fields stored verbatim from the source as JSON are typed as `unknown`.
+ * Keep in sync with Ecosystem until it publishes its types as a package.
+ */
+
+// Partners (PartnerDB)
+
+export interface EcosystemIndustry {
+  industry_id: string
+  slug: string
+  display_name: string
+  short_name: string | null
+}
+
+export interface EcosystemSolution {
+  solution_id: string
+  slug: string
+  display_name: string
+  short_name: string | null
+  type: 'software' | 'service'
+}
+
+export type PartnerAssetKind =
+  | 'square_logo'
+  | 'square_logo_mono'
+  | 'horizontal_logo'
+  | 'horizontal_logo_mono'
+  | 'product_image'
+
+export interface PartnerAsset {
+  partner_asset_id: string
+  kind: PartnerAssetKind
+  url: string
+  mime: string
+  width: number | null
+  height: number | null
+  sort_order: number
+}
+
+export interface Partner {
+  partner_id: string
+  slug: string
+  display_name: string
+  website: string | null
+  description_md: string | null
+  is_live: boolean
+  is_featured: boolean
+  legacy_industry_featured: boolean
+  industries: EcosystemIndustry[]
+  solutions: EcosystemSolution[]
+  assets: PartnerAsset[]
+  created_at: string
+  updated_at: string
+}
+
+export type SupportLevel =
+  | 'device_category'
+  | 'manufacturer'
+  | 'provider'
+  | 'capability'
+
+export type ObservedStatus = 'active' | 'trace' | 'none' | 'unknown'
+
+export type DeclaredStatus = 'enabled' | 'disabled' | 'not_via_seam'
+
+export interface SupportResolution {
+  supported: boolean
+  resolved_level: SupportLevel | null
+  declared_status: DeclaredStatus | null
+  observed_status: ObservedStatus | null
+  note: string | null
+}
+
+export interface CompatiblePartner extends Partner {
+  support: SupportResolution
+}
+
+// Embed keys
+
+export type EmbedKeyOwnerKind = 'partner' | 'manufacturer' | 'seam'
+
+/** The public record of an embed key, as returned by `embed/resolve`. */
+export interface EmbedKey {
+  embed_key_id: string
+  display_name: string
+  owner_kind: EmbedKeyOwnerKind
+  partner_id: string | null
+  manufacturer_slug: string | null
+  allowed_origins: string[]
+  config: Record<string, unknown>
+  revoked_at: string | null
+  created_at: string
+}
+
+export interface EmbedCapabilityExclusion {
+  device_category: string
+  /** Empty means every manufacturer in the category. */
+  manufacturer_slug: string
+  /** Empty means every provider in the category. */
+  provider_slug: string
+}
+
+export interface EmbedExclusions {
+  excluded_manufacturers: string[]
+  excluded_device_types: string[]
+  unsupported_providers: string[]
+  capability: string
+  capability_exclusions: EmbedCapabilityExclusion[]
+}
+
+/** The manufacturer a manufacturer-owned key scopes DeviceDB widgets to (DEVDB-439). */
+export interface EmbedManufacturerContext {
+  manufacturer_slug: string
+}
+
+export interface EmbedResolution {
+  embed_key: EmbedKey
+  /** Set for manufacturer-owned keys; null for partner and Seam keys. */
+  manufacturer_context?: EmbedManufacturerContext | null
+  exclusions: EmbedExclusions
+}
+
+// Devices (DeviceDB)
+
+export interface MediaFormat {
+  object_key: string
+  url: string
+  mime: string | null
+  width: number | null
+  height: number | null
+  bytes: number | null
+  sha256: string | null
+}
+
+export type MediaFormatName = 'thumbnail' | 'small' | 'medium' | 'large'
+
+export type DeviceAssetKind =
+  | 'square_logo'
+  | 'square_logo_mono'
+  | 'horizontal_logo'
+  | 'horizontal_logo_mono'
+  | 'default_device_image'
+  | 'featured'
+  | 'variant_image'
+
+export interface DeviceAsset {
+  asset_id: string
+  kind: DeviceAssetKind
+  object_key: string
+  url: string
+  mime: string | null
+  width: number | null
+  height: number | null
+  bytes: number | null
+  sha256: string | null
+  sort_order: number
+  formats: Partial<Record<MediaFormatName, MediaFormat>>
+  created_at: string
+  updated_at: string
+}
+
+export interface DeviceTypeRef {
+  device_type_id: string
+  slug: string
+  display_name: string
+  is_accessory: boolean
+}
+
+export interface ManufacturerRef {
+  manufacturer_id: string
+  slug: string
+  display_name: string | null
+}
+
+export interface ProviderRef {
+  provider_id: string
+  slug: string
+  display_name: string | null
+}
+
+export type CapabilityName =
+  | 'device_connectivity'
+  | 'can_program_online_access_codes'
+  | 'can_program_offline_access_codes'
+  | 'can_remotely_unlock'
+  | 'can_remotely_lock'
+  | 'can_encode_plastic_cards'
+  | 'can_provision_mobile_keys'
+  | 'can_provision_wallet_keys'
+  | 'can_hvac_cool'
+  | 'can_hvac_heat'
+  | 'can_hvac_auto'
+  | 'can_hvac_fan'
+  | 'can_program_thermostat_weekly_programs'
+  | 'can_monitor'
+
+export type CapabilitySupported = 'yes' | 'no' | 'conditionally'
+
+export type IntegrationSupportLevel =
+  | 'inquire'
+  | 'unavailable'
+  | 'planned'
+  | 'in-progress'
+  | 'beta'
+  | 'stable'
+
+export interface CapabilityReport {
+  details: string
+  requirements?: Record<
+    string,
+    { message: string; device_slugs?: string[]; [key: string]: unknown }
+  >
+  dependencies?: string[]
+  [key: string]: unknown
+}
+
+export interface CapabilityDetail {
+  capability_id: string
+  name: CapabilityName
+  supported: CapabilitySupported
+  integration_support_level: IntegrationSupportLevel | null
+  report: CapabilityReport | null
+  report_raw: CapabilityReport | null
+  locale: string
+  computed_at: string
+}
+
+export interface ProviderCapabilities {
+  provider: ProviderRef
+  capabilities: CapabilityDetail[]
+}
+
+export interface DeviceModelVariant {
+  device_model_variant_id: string
+  color_name: string | null
+  style_name: string | null
+  primary_color_hex: string | null
+  manufacturer_model_id: string | null
+  asin: string | null
+  gtins: unknown
+  marketplace_listings: unknown
+  sort_order: number
+  images: DeviceAsset[]
+  created_at: string
+  updated_at: string
+}
+
+export interface DeviceModel {
+  device_model_id: string
+  slug: string
+  display_name: string | null
+  description_md: string | null
+  product_url: string | null
+  is_forbidden_to_3dparty: boolean | null
+  no_longer_sold: boolean | null
+  shop_listings: unknown
+  last_commerce_search_at: string | null
+  manufacturer: ManufacturerRef | null
+  device_type: DeviceTypeRef | null
+  device_type_properties: unknown
+  variants: DeviceModelVariant[]
+  featured_image: DeviceAsset | null
+  providers: ProviderRef[]
+  capabilities_by_provider: ProviderCapabilities[]
+  capabilities_stale: boolean
+  created_at: string
+  updated_at: string
+}
+
+// Device model summaries (`device_models/summaries/list`, DEVDB-437):
+// the same models in a slim shape, without storage internals or commerce data.
+
+export interface DeviceImageFormat {
+  url: string
+  width: number | null
+  height: number | null
+}
+
+export interface DeviceImage {
+  url: string
+  mime: string | null
+  width: number | null
+  height: number | null
+  formats: Partial<Record<MediaFormatName, DeviceImageFormat>>
+}
+
+export interface CapabilitySummary {
+  name: CapabilityName
+  supported: CapabilitySupported
+  integration_support_level: IntegrationSupportLevel | null
+  report: CapabilityReport | null
+}
+
+export interface DeviceModelSummaryVariant {
+  device_model_variant_id: string
+  color_name: string | null
+  style_name: string | null
+  primary_color_hex: string | null
+  manufacturer_model_id: string | null
+  images: DeviceImage[]
+  /** Only with `include=commerce`. */
+  asin?: string | null
+  /** Only with `include=commerce`. */
+  gtins?: unknown
+  /** Only with `include=commerce`. */
+  marketplace_listings?: unknown
+}
+
+export interface DeviceModelSummary {
+  device_model_id: string
+  slug: string
+  display_name: string | null
+  description_md: string | null
+  product_url: string | null
+  no_longer_sold: boolean | null
+  is_forbidden_to_3dparty: boolean | null
+  manufacturer: ManufacturerRef | null
+  device_type: DeviceTypeRef | null
+  device_type_properties: unknown
+  featured_image: DeviceImage | null
+  variants: DeviceModelSummaryVariant[]
+  providers: ProviderRef[]
+  capabilities_by_provider: Array<{
+    provider: ProviderRef
+    capabilities: CapabilitySummary[]
+  }>
+  capabilities_stale: boolean
+  /** Only with `include=commerce`. */
+  shop_listings?: unknown
+  /** Only with `include=commerce`. */
+  last_commerce_search_at?: string | null
+  updated_at: string
+}
+
+export interface ManufacturerDefaultDeviceImage {
+  device_type: DeviceTypeRef
+  asset: DeviceAsset
+}
+
+export interface Manufacturer {
+  manufacturer_id: string
+  slug: string
+  display_name: string | null
+  website: string | null
+  headquarters: string | null
+  country_of_origin: string | null
+  parent_org: string | null
+  inc_date: string | null
+  customer_support_phone: string | null
+  customer_support_email: string | null
+  customer_support_url: string | null
+  description_md: string | null
+  seam_api_guide: string | null
+  commerce_footprint: unknown
+  last_commerce_search_at: string | null
+  logos: DeviceAsset[]
+  default_device_images: ManufacturerDefaultDeviceImage[]
+  providers: ProviderRef[]
+  device_model_count: number
+  created_at: string
+  updated_at: string
+}
+
+export interface Pagination {
+  has_next_page: boolean
+  next_page_cursor: string | null
+}
+
+// Responses
+
+export interface CompatibilityResponse {
+  partners: CompatiblePartner[]
+}
+
+export interface DeviceModelsListResponse {
+  device_models: DeviceModel[]
+  pagination: Pagination
+}
+
+export interface DeviceModelSummariesListResponse {
+  device_models: DeviceModelSummary[]
+  pagination: Pagination
+}
+
+export interface ManufacturersListResponse {
+  manufacturers: Manufacturer[]
+  pagination: Pagination
+}
+
+export interface EcosystemErrorResponse {
+  ok: false
+  error: {
+    type: string
+    message: string
+    data?: Record<string, unknown>
+    request_id?: string
+  }
+}