Add typedoc (#439)

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

.github/workflows/publish.yml

@@ -93,3 +93,30 @@ jobs:
           AWS_S3_ENDPOINT: https://${{ vars.CLOUDFLARE_ACCOUNT_ID }}.r2.cloudflarestorage.com
           SOURCE_DIR: package
           DEST_DIR: v/${{ steps.version.outputs.result }}
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup
+        uses: ./.github/actions/setup
+      - name: Build docs
+        run: npm run docs:build
+      - name: Get version
+        uses: actions/github-script@v6
+        id: version
+        with:
+          result-encoding: string
+          script: return context.ref.split('/')[2].slice(1)
+      - name: Sync to R2
+        uses: jakejarvis/[email protected]
+        env:
+          AWS_S3_BUCKET: ${{ vars.CLOUDFLARE_R2_BUCKET_NAME }}
+          AWS_ACCESS_KEY_ID: ${{ vars.CLOUDFLARE_R2_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.CLOUDFLARE_R2_SECRET_ACCESS_KEY }}
+          AWS_REGION: ${{ vars.CLOUDFLARE_R2_BUCKET_REGION }}
+          AWS_S3_ENDPOINT: https://${{ vars.CLOUDFLARE_ACCOUNT_ID }}.r2.cloudflarestorage.com
+          SOURCE_DIR: docs
+          DEST_DIR: v/${{ steps.version.outputs.result }}/docs

README.md

@@ -27,6 +27,7 @@ refreshing data, and performing actions.
 - Play with the components live in the interactive [Storybook](https://react.seam.co/)!
 - See how the components work with a real Seam sandbox workspace in this [live example app](https://react.seam.co/examples/basic/).
 - Clone a [sample app in your preferred framework](https://github.com/seamapi/seam-components-sample-apps).
+- [Versioned API reference documentation generated by TypeDoc](https://react.seam.co/v/1.52.1/docs/api-docs).
 
 ### Live Examples
 

package.json

@@ -72,6 +72,7 @@
     "docs:start": "concurrently --raw --kill-others npm:examples:storybook npm:storybook:docs",
     "docs:build": "storybook build --docs --output-dir docs",
     "predocs:build": "npm run examples:build",
+    "postdocs:build": "typedoc",
     "typecheck": "tsc",
     "test": "jest --collect-coverage",
     "test:update": "jest --updateSnapshot",
@@ -182,6 +183,7 @@
     "tsc-alias": "^1.8.5",
     "tsconfig-paths-webpack-plugin": "^4.0.1",
     "tsx": "^3.12.7",
+    "typedoc": "^0.25.1",
     "typescript": "~5.1.0",
     "vite": "^4.2.1",
     "vite-tsconfig-paths": "^4.0.8",

src/lib/seam/SeamProvider.tsx

@@ -19,7 +19,7 @@ declare global {
 
 export interface SeamContext {
   client: Seam | null
-  clientOptions?: AllowedSeamClientOptions | undefined
+  clientOptions?: SeamProviderClientOptions | undefined
   publishableKey?: string | undefined
   userIdentifierKey?: string | undefined
   clientSessionToken?: string | undefined
@@ -36,14 +36,14 @@ export interface SeamProviderPropsWithClient extends SeamProviderBaseProps {
 
 export interface SeamProviderPropsWithPublishableKey
   extends SeamProviderBaseProps,
-    AllowedSeamClientOptions {
+    SeamProviderClientOptions {
   publishableKey: string
   userIdentifierKey?: string
 }
 
 export interface SeamProviderPropsWithClientSessionToken
   extends SeamProviderBaseProps,
-    AllowedSeamClientOptions {
+    SeamProviderClientOptions {
   clientSessionToken: string
 }
 
@@ -54,7 +54,7 @@ interface SeamProviderBaseProps extends PropsWithChildren {
   queryClient?: QueryClient | undefined
 }
 
-type AllowedSeamClientOptions = Pick<SeamClientOptions, 'endpoint'>
+export type SeamProviderClientOptions = Pick<SeamClientOptions, 'endpoint'>
 
 const defaultQueryClient = new QueryClient()
 
@@ -172,7 +172,7 @@ const isSeamProviderPropsWithClient = (
 
 const isSeamProviderPropsWithPublishableKey = (
   props: SeamProviderProps
-): props is SeamProviderPropsWithPublishableKey & AllowedSeamClientOptions => {
+): props is SeamProviderPropsWithPublishableKey & SeamProviderClientOptions => {
   if (!('publishableKey' in props)) return false
 
   const { publishableKey } = props
@@ -196,7 +196,7 @@ const isSeamProviderPropsWithPublishableKey = (
 const isSeamProviderPropsWithClientSessionToken = (
   props: SeamProviderProps
 ): props is SeamProviderPropsWithClientSessionToken &
-  AllowedSeamClientOptions => {
+  SeamProviderClientOptions => {
   if (!('clientSessionToken' in props)) return false
 
   const { clientSessionToken } = props

src/lib/seam/components/index.ts

@@ -2,6 +2,7 @@ export * from './AccessCodeDetails/AccessCodeDetails.js'
 export * from './AccessCodeTable/AccessCodeTable.js'
 export * from './ClimateSettingScheduleDetails/ClimateSettingScheduleDetails.js'
 export * from './ClimateSettingScheduleTable/ClimateSettingScheduleTable.js'
+export * from './common-props.js'
 export * from './ConnectAccountButton/ConnectAccountButton.js'
 export * from './DeviceDetails/DeviceDetails.js'
 export * from './DeviceTable/DeviceTable.js'

src/lib/seam/index.ts

@@ -11,3 +11,4 @@ export * from './SeamProvider.js'
 export * from './thermostats/climate-setting-schedules/use-climate-setting-schedule.js'
 export * from './thermostats/climate-setting-schedules/use-climate-setting-schedules.js'
 export * from './use-seam-client.js'
+export * from './use-seam-query-result.js'

src/stories/Introduction.mdx

@@ -44,6 +44,7 @@ refreshing data, and performing actions.
 - Play with the components live in the interactive [Storybook](https://react.seam.co/)!
 - See how the components work with a real Seam sandbox workspace in this [live example app](https://react.seam.co/examples/basic/).
 - Clone a [sample app in your preferred framework](https://github.com/seamapi/seam-components-sample-apps).
+- <a href='/api-docs/'>API reference documentation generated by TypeDoc</a>
 
 ## Live Examples
 

typedoc.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "includeVersion": true,
+  "entryPoints": ["src/index.ts", "src/hooks.ts"],
+  "out": "docs/api-docs",
+  "tsconfig": "./tsconfig.build.json",
+  "navigationLinks": {
+    "GitHub": "https://github.com/seamapi/react"
+  }
+}

vercel.json

@@ -87,6 +87,33 @@
           "value": "default-src 'self'; connect-src 'self' https://connect.getseam.com; img-src 'self' https://connect.getseam.com https://seam.co https://www.seam.co; font-src 'self' https://fonts.gstatic.com; style-src 'self' https://fonts.googleapis.com"
         }
       ]
+    },
+    {
+      "source": "/v/(.*)/docs",
+      "headers": [
+        {
+          "key": "Content-Security-Policy",
+          "value": "default-src 'self'; script-src 'self' 'nonce-storybook'; connect-src 'self' https://connect.getseam.com; img-src 'self' https://connect.getseam.com https://seam.co https://www.seam.co https://img.shields.io https://github.com; font-src 'self' https://fonts.gstatic.com; style-src 'self' 'unsafe-inline' http://fonts.googleapis.com"
+        }
+      ]
+    },
+    {
+      "source": "/v/(.*)/docs/api-docs",
+      "headers": [
+        {
+          "key": "Content-Security-Policy",
+          "value": "default-src 'self'; script-src 'self' 'unsafe-inline'; connect-src 'self' data:; img-src 'self' https://img.shields.io https://github.com; style-src 'self' 'unsafe-inline'"
+        }
+      ]
+    },
+    {
+      "source": "/api-docs/(.*)",
+      "headers": [
+        {
+          "key": "Content-Security-Policy",
+          "value": "default-src 'self'; script-src 'self' 'unsafe-inline'; connect-src 'self' data:; img-src 'self' https://img.shields.io https://github.com; style-src 'self' 'unsafe-inline'"
+        }
+      ]
     }
   ]
 }