feat: Add telemetry (#458)

Co-authored-by: Seam Bot <[email protected]>

Author: razor-x

README.md

@@ -246,6 +246,21 @@ When serving the CSS styles from the default CDN, extend `style-src` with
 style-src https://react.seam.co
 ```
 
+### Telemetry
+
+By default, this library reports basic usage telemetry to the Seam API.
+This may be completely disabled with `<SeamProvider disableTelemetry>`.
+
+Before disabling telemetry, please consider the following:
+
+- Telemetry is sent directly to the Seam API and is never sold to third parties.
+- Telemetry is used by Seam for the sole purpose of improving Seam Components
+  and directly enhancing the experience for your end users.
+- No data is persisted on the client beyond the lifetime of the browser session: this library does not use cookies or local browser storage.
+- Telemetry may be selectively disabled for some users to align with any existing data collection compliance requirements of your application.
+- Telemetry does not negatively impact performance and adds minimal background network overhead.
+- The implementation is small, simple to audit, and completely transparent: [src/lib/telemetry](src/lib/telemetry).
+
 ## Development and Testing
 
 ### Quickstart

package-lock.json

@@ -124,16 +124,17 @@
     "@tanstack/react-query": "^4.28.0",
     "classnames": "^2.3.2",
     "luxon": "^3.3.0",
+    "queue": "^7.0.0",
     "react-hook-form": "^7.46.1",
-    "seamapi": "^8.11.0",
+    "seamapi": "^8.12.0",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
     "@emotion/styled": "^11.10.6",
     "@mui/icons-material": "^5.11.16",
     "@mui/material": "^5.12.2",
     "@rxfork/r2wc-react-to-web-component": "^2.3.0",
-    "@seamapi/fake-seam-connect": "^1.11.0",
+    "@seamapi/fake-seam-connect": "^1.14.0",
     "@storybook/addon-designs": "^7.0.1",
     "@storybook/addon-essentials": "^7.0.2",
     "@storybook/addon-links": "^7.0.2",

package.json

@@ -1,2 +1,2 @@
-declare const elementNames: string[]
+export const elementNames: string[]
 export default elementNames

src/elements.d.ts

@@ -10,6 +10,8 @@ import {
 } from 'lib/seam/SeamProvider.js'
 
 declare global {
+  // eslint-disable-next-line no-var
+  var disableSeamTelemetry: boolean | undefined
   // eslint-disable-next-line no-var
   var disableSeamCssInjection: boolean | undefined
   // eslint-disable-next-line no-var
@@ -51,6 +53,8 @@ const providerProps: R2wcProps<ProviderProps> = {
   clientSessionToken: 'string',
   endpoint: 'string',
   queryClient: 'object',
+  telemetryClient: 'object',
+  disableTelemetry: 'boolean',
   disableCssInjection: 'boolean',
   disableFontInjection: 'boolean',
   unminifiyCss: 'boolean',
@@ -73,12 +77,15 @@ export const defineCustomElement = ({
 
 function withProvider<P extends JSX.IntrinsicAttributes>(
   Component: ComponentType<P>
-) {
-  return function ({
+): (props: ProviderProps & { container: Container } & P) => JSX.Element | null {
+  const name = Component.displayName ?? Component.name ?? 'Component'
+
+  function WithProvider({
     publishableKey,
     endpoint,
     userIdentifierKey,
     clientSessionToken,
+    disableTelemetry,
     disableCssInjection,
     disableFontInjection,
     unminifiyCss,
@@ -91,6 +98,7 @@ function withProvider<P extends JSX.IntrinsicAttributes>(
         userIdentifierKey={userIdentifierKey}
         clientSessionToken={clientSessionToken}
         endpoint={endpoint}
+        disableTelemetry={disableTelemetry ?? globalThis.disableSeamTelemetry}
         disableCssInjection={
           disableCssInjection ?? globalThis.disableSeamCssInjection
         }
@@ -103,4 +111,8 @@ function withProvider<P extends JSX.IntrinsicAttributes>(
       </SeamProvider>
     )
   }
+
+  WithProvider.displayName = `WithProvider(${name})`
+
+  return WithProvider
 }

src/lib/element.tsx

@@ -7,6 +7,12 @@ import {
 } from 'react'
 import type { Seam, SeamClientOptions } from 'seamapi'
 
+import {
+  type TelemetryClient,
+  TelemetryProvider,
+  useUserTelemetry,
+} from 'lib/telemetry/index.js'
+
 import { useSeamFont } from 'lib/seam/use-seam-font.js'
 import { useSeamStyles } from 'lib/seam/use-seam-styles.js'
 
@@ -15,6 +21,8 @@ declare global {
   var seam: SeamProviderProps | undefined
   // eslint-disable-next-line no-var
   var seamQueryClient: QueryClient | undefined
+  // eslint-disable-next-line no-var
+  var seamTelemetryClient: TelemetryClient | undefined
 }
 
 export interface SeamContext {
@@ -48,10 +56,12 @@ export interface SeamProviderPropsWithClientSessionToken
 }
 
 interface SeamProviderBaseProps extends PropsWithChildren {
+  disableTelemetry?: boolean | undefined
   disableCssInjection?: boolean | undefined
   disableFontInjection?: boolean | undefined
   unminifiyCss?: boolean | undefined
   queryClient?: QueryClient | undefined
+  telemetryClient?: TelemetryClient | undefined
 }
 
 export type SeamProviderClientOptions = Pick<SeamClientOptions, 'endpoint'>
@@ -60,10 +70,12 @@ const defaultQueryClient = new QueryClient()
 
 export function SeamProvider({
   children,
+  disableTelemetry = false,
   disableCssInjection = false,
   disableFontInjection = false,
   unminifiyCss = false,
   queryClient,
+  telemetryClient,
   ...props
 }: SeamProviderProps): JSX.Element {
   useSeamStyles({ disabled: disableCssInjection, unminified: unminifiyCss })
@@ -93,17 +105,34 @@ export function SeamProvider({
 
   const { Provider } = seamContext
 
+  const endpoint = 'endpoint' in props ? props.endpoint : undefined
+
   return (
     <div className='seam-components'>
-      <QueryClientProvider
-        client={queryClient ?? globalThis.seamQueryClient ?? defaultQueryClient}
+      <TelemetryProvider
+        client={telemetryClient ?? globalThis.seamTelemetryClient}
+        disabled={disableTelemetry}
+        endpoint={endpoint}
       >
-        <Provider value={value}>{children}</Provider>
-      </QueryClientProvider>
+        <QueryClientProvider
+          client={
+            queryClient ?? globalThis.seamQueryClient ?? defaultQueryClient
+          }
+        >
+          <Provider value={value}>
+            <Wrapper>{children}</Wrapper>
+          </Provider>
+        </QueryClientProvider>
+      </TelemetryProvider>
     </div>
   )
 }
 
+function Wrapper({ children }: PropsWithChildren): JSX.Element | null {
+  useUserTelemetry()
+  return <>{children}</>
+}
+
 const createDefaultSeamContextValue = (): SeamContext => {
   try {
     if (globalThis.seam == null) {

src/lib/seam/SeamProvider.tsx

@@ -0,0 +1,32 @@
+import { useQuery } from '@tanstack/react-query'
+import type {
+  ClientSession,
+  ClientSessionsGetResponse,
+  SeamError,
+} from 'seamapi'
+
+import { useSeamClient } from 'lib/seam/use-seam-client.js'
+import type { UseSeamQueryResult } from 'lib/seam/use-seam-query-result.js'
+
+export type UseClientSessionParams = never
+export type UseClientSessionData = ClientSession | null
+
+export function useClientSession(): UseSeamQueryResult<
+  'clientSession',
+  UseClientSessionData
+> {
+  const { client } = useSeamClient()
+  const { data, ...rest } = useQuery<
+    ClientSessionsGetResponse['client_session'] | null,
+    SeamError
+  >({
+    enabled: client != null,
+    queryKey: ['client_session', 'get'],
+    queryFn: async () => {
+      if (client == null) return null
+      return await client.clientSessions.get({})
+    },
+  })
+
+  return { ...rest, clientSession: data }
+}

src/lib/seam/client-sessions/use-client-session.ts

@@ -8,6 +8,8 @@ import type {
   DeviceError,
 } from 'seamapi'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import { CopyIcon } from 'lib/icons/Copy.js'
 import { useAccessCode } from 'lib/seam/access-codes/use-access-code.js'
 import { useDeleteAccessCode } from 'lib/seam/access-codes/use-delete-access-code.js'
@@ -42,6 +44,8 @@ export function AccessCodeDetails({
   onBack,
   className,
 }: AccessCodeDetailsProps): JSX.Element | null {
+  useComponentTelemetry('AccessCodeDetails')
+
   const { accessCode } = useAccessCode(accessCodeId)
   const [selectedDeviceId, selectDevice] = useState<string | null>(null)
   const { mutate: deleteCode, isLoading: isDeleting } = useDeleteAccessCode()

src/lib/seam/components/AccessCodeDetails/AccessCodeDetails.tsx

@@ -1,6 +1,8 @@
 import classNames from 'classnames'
 import { useCallback, useMemo, useState } from 'react'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import { compareByCreatedAtDesc } from 'lib/dates.js'
 import { AddIcon } from 'lib/icons/Add.js'
 import {
@@ -83,6 +85,8 @@ export function AccessCodeTable({
   disableLockUnlock = false,
   disableDeleteAccessCode = false,
 }: AccessCodeTableProps): JSX.Element {
+  useComponentTelemetry('AccessCodeTable')
+
   const { accessCodes } = useAccessCodes({
     device_id: deviceId,
   })

src/lib/seam/components/AccessCodeTable/AccessCodeTable.tsx

@@ -1,6 +1,8 @@
 import classNames from 'classnames'
 import { useState } from 'react'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import { formatDateAndTime } from 'lib/dates.js'
 import { ArrowRightIcon } from 'lib/icons/ArrowRight.js'
 import { ClimateSettingScheduleCard } from 'lib/seam/components/ClimateSettingScheduleDetails/ClimateSettingScheduleCard.js'
@@ -33,6 +35,8 @@ export function ClimateSettingScheduleDetails({
   disableCreateAccessCode,
   disableEditAccessCode,
 }: ClimateSettingScheduleDetailsProps): JSX.Element | null {
+  useComponentTelemetry('ClimateSettingScheduleDetails')
+
   const { climateSettingSchedule } = useClimateSettingSchedule(
     climateSettingScheduleId
   )

src/lib/seam/components/ClimateSettingScheduleDetails/ClimateSettingScheduleDetails.tsx

@@ -2,6 +2,8 @@ import classNames from 'classnames'
 import { useCallback, useMemo, useState } from 'react'
 import type { ClimateSettingSchedule } from 'seamapi'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import { compareByCreatedAtDesc } from 'lib/dates.js'
 import { NestedClimateSettingScheduleDetails } from 'lib/seam/components/ClimateSettingScheduleDetails/ClimateSettingScheduleDetails.js'
 import { ClimateSettingScheduleRow } from 'lib/seam/components/ClimateSettingScheduleTable/ClimateSettingScheduleRow.js'
@@ -66,6 +68,8 @@ export function ClimateSettingScheduleTable({
   disableCreateAccessCode,
   disableEditAccessCode,
 }: ClimateSettingScheduleTableProps): JSX.Element {
+  useComponentTelemetry('ClimateSettingScheduleTable')
+
   const { climateSettingSchedules, isLoading, isError, error } =
     useClimateSettingSchedules({
       device_id: deviceId,

src/lib/seam/components/ClimateSettingScheduleTable/ClimateSettingScheduleTable.tsx

@@ -1,5 +1,7 @@
 import { useCallback } from 'react'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import {
   type CommonProps,
   withRequiredCommonProps,
@@ -15,6 +17,8 @@ export const NestedConnectAccountButton =
 export function ConnectAccountButton({
   className,
 }: ConnectAccountButtonProps = {}): JSX.Element {
+  useComponentTelemetry('ConnectAccountButton')
+
   const { isLoading, mutate } = useCreateConnectWebview({
     willNavigateToWebview: true,
   })

src/lib/seam/components/ConnectAccountButton/ConnectAccountButton.tsx

@@ -1,6 +1,8 @@
 import { useState } from 'react'
 import type { SeamError } from 'seamapi'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import { createIsoDate } from 'lib/dates.js'
 import { useCreateAccessCode } from 'lib/seam/access-codes/use-create-access-code.js'
 import {
@@ -26,6 +28,8 @@ export function CreateAccessCodeForm({
   onBack,
   deviceId,
 }: CreateAccessCodeFormProps): JSX.Element | null {
+  useComponentTelemetry('CreateAccessCodeForm')
+
   const { device } = useDevice({
     device_id: deviceId,
   })

src/lib/seam/components/CreateAccessCodeForm/CreateAccessCodeForm.tsx

@@ -1,3 +1,5 @@
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import { createIsoDate } from 'lib/dates.js'
 import type { CommonProps } from 'lib/seam/components/common-props.js'
 import { useCreateClimateSettingSchedule } from 'lib/seam/thermostats/climate-setting-schedules/use-create-climate-setting-schedule.js'
@@ -12,6 +14,8 @@ export function CreateClimateSettingScheduleForm({
   className,
   onBack,
 }: CreateClimateSettingScheduleFormProps): JSX.Element | null {
+  useComponentTelemetry('CreateClimateSettingScheduleForm')
+
   const { submit, isSubmitting } = useSubmitCreateClimateSettingSchedule(onBack)
 
   return (

src/lib/seam/components/CreateClimateSettingScheduleForm/CreateClimateSettingScheduleForm.tsx

@@ -1,5 +1,7 @@
 import { isLockDevice, isThermostatDevice } from 'seamapi'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import {
   type CommonProps,
   withRequiredCommonProps,
@@ -21,6 +23,8 @@ export function DeviceDetails({
   onBack,
   className,
 }: DeviceDetailsProps): JSX.Element | null {
+  useComponentTelemetry('DeviceDetails')
+
   const { device } = useDevice({
     device_id: deviceId,
   })

src/lib/seam/components/DeviceDetails/DeviceDetails.tsx

@@ -2,6 +2,8 @@ import classNames from 'classnames'
 import { useCallback, useMemo, useState } from 'react'
 import { type CommonDevice, isLockDevice, isThermostatDevice } from 'seamapi'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import { compareByCreatedAtDesc } from 'lib/dates.js'
 import {
   type CommonProps,
@@ -71,6 +73,8 @@ export function DeviceTable({
   onBack,
   className,
 }: DeviceTableProps = {}): JSX.Element {
+  useComponentTelemetry('DeviceTable')
+
   const { devices, isLoading, isError, error } = useDevices({
     device_ids: deviceIds,
     connected_account_ids: connectedAccountIds,

src/lib/seam/components/DeviceTable/DeviceTable.tsx

@@ -1,6 +1,8 @@
 import { useState } from 'react'
 import type { SeamError } from 'seamapi'
 
+import { useComponentTelemetry } from 'lib/telemetry/index.js'
+
 import { createIsoDate } from 'lib/dates.js'
 import {
   useAccessCode,
@@ -30,6 +32,8 @@ export function EditAccessCodeForm({
   onBack,
   className,
 }: EditAccessCodeFormProps): JSX.Element | null {
+  useComponentTelemetry('EditAccessCodeForm')
+
   const { accessCode } = useAccessCode({
     access_code_id: accessCodeId,
   })