Add default title for all paths (#748)

razor-x · seambot · web-flow · commit 6722b5a6cf6b · 2025-07-24T13:54:49.000-07:00
* Rename codegen script to generate

* Add default path title for all paths

* ci: Generate docs

* ci: Generate docs

* Remove untitled namespaces and routes from report

* Fix linter error

* ci: Generate docs

* Fix type error

* ci: Generate docs

---------

Co-authored-by: Seam Bot &lt;seambot@getseam.com&gt;
diff --git a/.github/workflows/generate.yml b/.github/workflows/generate.yml
@@ -58,7 +58,7 @@ jobs:
           max_attempts: 3
           retry_wait_seconds: 1
           timeout_minutes: 2
-          command: npm run codegen
+          command: npm run generate
       - name: Commit
         uses: stefanzweifel/git-auto-commit-action@v5
         with:
diff --git a/README.md b/README.md
@@ -67,7 +67,7 @@ $ git clone https://github.com/seamapi/docs.git
 $ cd docs
 $ nvm install
 $ npm install
-$ npm run codegen
+$ npm run generate
 ```
 
 Primary development tasks are defined under `scripts` in `package.json`
diff --git a/codegen/data/paths.yaml b/codegen/data/paths.yaml
@@ -18,30 +18,12 @@
     3. Create `acs_credential`s, which are the digital means of granting access to users, such as PIN codes, mobile keys, and plastic (RFID) cards.
        If you are developing a mobile app to provide access for your users, you can also use [Seam's iOS and Android SDKs](https://docs.seam.co/latest/capability-guides/mobile-access/mobile-device-sdks) that pair with the Seam API to create and manage mobile keys.
 
-/acs/systems:
-  title: Systems
-
 /acs/users:
   title: ACS Users
 
-/acs/entrances:
-  title: Entrances
-
-/acs/access_groups:
-  title: Access Groups
-
-/acs/credentials:
-  title: Credentials
-
-/acs/encoders:
-  title: Encoders
-
 /acs/encoders/simulate:
   title: Encoder Simulations
 
-/phones:
-  title: Phones
-
 /phones/simulate:
   title: Phone Simulations
 
@@ -99,15 +81,9 @@
 
     ---
 
-/noise_sensors/noise_thresholds:
-  title: Noise Thresholds
-
 /noise_sensors/simulate:
   title: Noise Sensor Simulations
 
-/user_identities:
-  title: User Identities
-
 /access_codes:
   title: Access Codes
   include_groups:
@@ -135,28 +111,10 @@
   title: Spaces
   alpha: "**Early Access Preview.** The spaces API is currently in Alpha. We're actively developing it and seeking early feedback at [support@seam.co](mailto:support@seam.co). Expect breaking changes as we refine the design."
 
-/connected_accounts:
-  title: Connected Accounts
-
 /customers:
   title: Customers
   alpha: "**Early Access Preview.** The customers API is currently in Alpha. We're actively developing it and seeking early feedback at [support@seam.co](mailto:support@seam.co). Expect breaking changes as we refine the design."
 
-/client_sessions:
-  title: Client Sessions
-
-/connect_webviews:
-  title: Connect Webviews
-
-/webhooks:
-  title: Webhooks
-
-/workspaces:
-  title: Workspaces
-
-/devices:
-  title: Devices
-
 /devices/unmanaged:
   title: Unmanaged Devices
 
@@ -200,6 +158,3 @@
 
 /locks/simulate:
   title: Lock Simulations
-
-/instant_keys:
-  title: Instant Keys
diff --git a/codegen/layouts/report.hbs b/codegen/layouts/report.hbs
@@ -2,22 +2,6 @@
 {{#if (or noTitle.routes.length noTitle.endpoints.length noTitle.namespaces.length )}}
 
 ## Untitled
-{{#if noTitle.namespaces.length }}
-
-### Namespaces
-
-{{#each noTitle.namespaces}}
-- `{{name}}`
-{{/each}}
-{{/if}}
-{{#if noTitle.routes.length }}
-
-### Routes
-
-{{#each noTitle.routes}}
-- `{{name}}`
-{{/each}}
-{{/if}}
 {{#if noTitle.endpoints.length }}
 
 ### Endpoints
diff --git a/codegen/lib/reference.ts b/codegen/lib/reference.ts
@@ -1,6 +1,8 @@
 import type { Blueprint, Endpoint } from '@seamapi/blueprint'
 import type Metalsmith from 'metalsmith'
 
+import { toCapitalCase } from 'lib/handlebars/helpers.js'
+
 import {
   type ApiEndpointLayoutContext,
   type ApiNamespaceLayoutContext,
@@ -42,6 +44,13 @@ export const reference = (
 
   const { blueprint } = metadata
 
+  for (const { path, name } of [...blueprint.routes, ...blueprint.namespaces]) {
+    if (path in pathMetadata) continue
+    pathMetadata[path] = PathMetadataSchema.valueSchema.parse({
+      title: toCapitalCase(name),
+    })
+  }
+
   const { resources } = blueprint
 
   const namespaces = blueprint.namespaces.filter(
diff --git a/codegen/lib/report.ts b/codegen/lib/report.ts
@@ -12,8 +12,6 @@ import type {
 import { openapi } from '@seamapi/types/connect'
 import type Metalsmith from 'metalsmith'
 
-import { PathMetadataSchema } from './path-metadata.js'
-
 const defaultDeprecatedMessage = 'No deprecated message provided'
 const defaultDraftMessage = 'No draft message provided'
 const defaultUndocumentedMessage = 'No undocumented message provided'
@@ -108,24 +106,12 @@ function generateReport(metadata: Metadata): Report {
     },
   }
 
-  const pathMetadata =
-    'pathMetadata' in metadata
-      ? PathMetadataSchema.parse(metadata.pathMetadata)
-      : {}
-
   const routes = blueprint.routes ?? []
   for (const route of routes) {
-    processRoute(route, report, metadata)
+    processRoute(route, report)
   }
 
   for (const namespace of blueprint.namespaces ?? []) {
-    if (
-      !namespace.isUndocumented &&
-      pathMetadata[namespace.path]?.title == null
-    ) {
-      addUntitledNamespaceToReport(namespace.path, report)
-    }
-
     processNamespace(namespace, report)
   }
 
@@ -267,7 +253,7 @@ function processProperty(
   }
 }
 
-function processRoute(route: Route, report: Report, metadata: Metadata): void {
+function processRoute(route: Route, report: Report): void {
   if (route.isUndocumented) {
     report.undocumented.routes.push({
       name: route.path,
@@ -289,30 +275,11 @@ function processRoute(route: Route, report: Report, metadata: Metadata): void {
     })
   }
 
-  const pathMetadata =
-    'pathMetadata' in metadata
-      ? PathMetadataSchema.parse(metadata.pathMetadata)
-      : {}
-
-  if (pathMetadata[route.path]?.title == null && !route.isUndocumented) {
-    report.noTitle.routes.push({ name: route.path })
-  }
-
-  // TODO: route description
-
   for (const endpoint of route.endpoints) {
     processEndpoint(endpoint, report)
   }
 }
 
-const addUntitledNamespaceToReport = (
-  namespace: string,
-  report: Report,
-): void => {
-  if (report.noTitle.namespaces.some((n) => n.name === namespace)) return
-  report.noTitle.namespaces.push({ name: namespace })
-}
-
 function processNamespace(namespace: Namespace, report: Report): void {
   const addNamespace = (section: ReportItem[], reason: string): void => {
     if (section.some((item) => item.name === namespace.path)) return
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -326,6 +326,10 @@
   * [Set to Off Mode](api/thermostats/off.md)
   * [Update a Climate Preset](api/thermostats/update_climate_preset.md)
   * [Update the Thermostat Weekly Program](api/thermostats/update_weekly_program.md)
+  * [Daily Programs](api/thermostats/daily_programs/README.md)
+    * [Create a Thermostat Daily Program](api/thermostats/daily_programs/create.md)
+    * [Delete a Thermostat Daily Program](api/thermostats/daily_programs/delete.md)
+    * [Update a Thermostat Daily Program](api/thermostats/daily_programs/update.md)
   * [Thermostat Schedules](api/thermostats/schedules/README.md)
     * [Create a Thermostat Schedule](api/thermostats/schedules/create.md)
     * [Delete a Thermostat Schedule](api/thermostats/schedules/delete.md)
diff --git a/docs/api/_report.md b/docs/api/_report.md
@@ -1,11 +1,5 @@
 # Documentation Report
 
-## Untitled
-
-### Routes
-
-- `/thermostats/daily_programs`
-
 ## Undocumented
 
 These items are intentionally undocumented.
diff --git a/docs/api/thermostats/daily_programs/README.md b/docs/api/thermostats/daily_programs/README.md
@@ -0,0 +1,119 @@
+# Daily Programs
+
+## The thermostat_daily_program Object
+
+- [Properties](./#properties)
+- [Endpoints](./#endpoints)
+
+
+Represents a thermostat daily program, consisting of a set of periods, each of which has a starting time and the key that identifies the climate preset to apply at the starting time.
+
+{% tabs %}
+{% tab title="Thermostat Daily Program" %}
+
+A thermostat daily program resource.
+
+```json
+{
+  "created_at": "2025-06-14T16:54:17.946642Z",
+  "device_id": "58437d45-47ac-4ee6-ab27-7b2d1f2947d1",
+  "name": "Weekday Program",
+  "periods": [
+    { "starts_at_time": "07:00:00", "climate_preset_key": "Home" },
+    { "starts_at_time": "09:00:00", "climate_preset_key": "Away" },
+    { "starts_at_time": "16:00:00", "climate_preset_key": "Home" },
+    { "starts_at_time": "22:30:00", "climate_preset_key": "Sleep" }
+  ],
+  "thermostat_daily_program_id": "ab8ef74c-c7cd-4100-aa32-0ef960c0080d",
+  "workspace_id": "8da8d923-e55b-45cd-84a3-6c96b3d3d454"
+}
+```
+{% endtab %}
+{% endtabs %}
+
+---
+## Properties
+
+**`created_at`** *Datetime*
+
+Date and time at which the thermostat daily program was created.
+
+
+
+
+---
+
+**`device_id`** *UUID*
+
+ID of the thermostat device on which the thermostat daily program is configured.
+
+
+
+
+---
+
+**`name`** *String*
+
+User-friendly name to identify the thermostat daily program.
+
+
+
+
+---
+
+**`periods`** *List* *of Objects*
+
+Array of thermostat daily program periods.
+
+
+
+<details>
+  <summary>Child Object Properties</summary>
+<strong><code>climate_preset_key</code></strong> <i>String</i>
+
+  Key of the [climate preset](../../../capability-guides/thermostats/creating-and-managing-climate-presets/README.md) to activate at the `starts_at_time`.
+
+<strong><code>starts_at_time</code></strong> <i>String</i>
+
+  Time at which the thermostat daily program period starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
+
+</details>
+
+---
+
+**`thermostat_daily_program_id`** *UUID*
+
+ID of the thermostat daily program.
+
+
+
+
+---
+
+**`workspace_id`** *UUID*
+
+ID of the [workspace](../../../core-concepts/workspaces/README.md) that contains the thermostat daily program.
+
+
+
+
+---
+
+## Endpoints
+
+
+[**`/thermostats/daily_programs/create`**](./create.md)
+
+Creates a new thermostat daily program. A daily program consists of a set of periods, where each period includes a start time and the key of a configured climate preset. Once you have defined a daily program, you can assign it to one or more days within a weekly program.
+
+
+[**`/thermostats/daily_programs/delete`**](./delete.md)
+
+Deletes a thermostat daily program.
+
+
+[**`/thermostats/daily_programs/update`**](./update.md)
+
+Updates a specified thermostat daily program. The periods that you specify overwrite any existing periods for the daily program.
+
+
diff --git a/docs/api/thermostats/daily_programs/create.md b/docs/api/thermostats/daily_programs/create.md
diff --git a/docs/api/thermostats/daily_programs/delete.md b/docs/api/thermostats/daily_programs/delete.md
diff --git a/docs/api/thermostats/daily_programs/update.md b/docs/api/thermostats/daily_programs/update.md
diff --git a/package.json b/package.json
