refactor: migrate mintlify codegen to Metalsmith plugin architecture

.github/workflows/automerge.yml

@@ -31,6 +31,7 @@ jobs:
         with:
           files: |
             docs/api-reference/**
+            mintlify-docs/api/**
             mintlify-docs/openapi.json
             mintlify-docs/docs.json
             mintlify-docs/mobile-sdks/**

.github/workflows/generate.yml

@@ -55,14 +55,14 @@ jobs:
         run: gem install syntax_tree -v 6.2.0
       - name: Normalize package-lock.json
         run: npm install
-      - name: Generate docs
+      - name: Generate GitBook API reference (codegen/smith.ts)
         uses: nick-fields/retry@v3
         with:
           max_attempts: 3
           retry_wait_seconds: 1
           timeout_minutes: 2
           command: npm run generate
-      - name: Generate Mintlify docs
+      - name: Generate Mintlify API reference (mintlify-codegen/smith.ts)
         uses: nick-fields/retry@v3
         with:
           max_attempts: 3

.prettierignore

@@ -8,6 +8,7 @@
 # Prettier
 docs
 mintlify-docs
+mintlify-codegen/source
 seam-sdk-playground
 gitbook-plugin
 *.hbs
@@ -214,7 +215,7 @@ $RECYCLE.BIN/
 .LSOverride
 
 # Icon must end with two \r
-Icon
+Icon
 
 # Thumbnails
 ._*

mintlify-codegen/data/object-pages.yaml

@@ -0,0 +1,219 @@
+# Object-page metadata for the Mintlify API reference, keyed by API route path.
+# Validated by mintlify-codegen/lib/object-page-metadata.ts.
+#
+# Every route with an object page has an entry; all object pages are generated.
+#   - title: the page's frontmatter title. Also the source of the noun used in
+#     generated events/errors page titles ("The Device Object" -> "Device").
+#   - description: the page's frontmatter description.
+#   - endpoints: true renders an endpoint-listing page from the blueprint route
+#     (simulate/ and unmanaged/ routes).
+#   - namespace: true renders a resource-listing page for a namespace route.
+#   - resource_type: backs the page with a specific blueprint resource when the
+#     route has no resource of its own (e.g. /locks is a filtered view of the
+#     shared device resource).
+#   - include_groups / exclude_groups: property-group filter for the backing
+#     resource, following the codegen/data/paths.yaml idiom.
+#   - heading: overrides the section heading (default: 'The <type> Object').
+#   - intro: authored MDX rendered in place of the blueprint resource
+#     description (or above a namespace's resource list).
+
+/access_codes:
+  title: The Access Code Object
+  description: Learn how the access_code object represents a smart lock PIN code you can customize, track, and program across hundreds of supported keypad and pinpad locks.
+/access_codes/simulate:
+  title: Access Code Simulations
+  description: Use the access code simulation endpoints to create unmanaged access codes in a sandbox workspace and test your access code migration flows safely.
+  endpoints: true
+/access_codes/unmanaged:
+  title: Unmanaged Access Codes
+  description: Learn how the unmanaged_access_code object represents an existing smart lock PIN code that Seam tracks but does not manage until you convert it.
+/access_grants:
+  title: The Access Grant Object
+  description: Learn how the access_grant object grants a user identity access to spaces, entrances, and devices through mobile keys, plastic cards, and PIN codes.
+/access_grants/unmanaged:
+  title: Unmanaged
+  description: Use the unmanaged Access Grant endpoints to get, list, and update Access Grants that Seam tracks but does not manage (where is_managed is false).
+  endpoints: true
+/access_methods:
+  title: The Access Method Object
+  description: Learn how the access_method object describes the modes of access for an Access Grant, such as PIN codes, plastic cards, and mobile keys.
+/access_methods/unmanaged:
+  title: Unmanaged
+  description: Use the unmanaged access method endpoints to get and list access methods that Seam tracks but does not manage, usually filtered by Access Grant.
+  endpoints: true
+/acs/access_groups:
+  title: The Access Group Object
+  description: Learn how the acs_access_group object defines the entrances a set of access system users can reach and, in some systems, their access schedule.
+/acs/credentials:
+  title: The Credential Object
+  description: Learn how the acs_credential object represents the means—such as key cards, mobile keys, or PIN codes—by which an access system user gains entry.
+/acs/encoders:
+  title: The Encoder Object
+  description: Learn how the acs_encoder object represents a hardware device that encodes credential data onto physical key cards within an access control system.
+/acs/encoders/simulate:
+  title: Encoder Simulations
+  description: Use the encoder simulation endpoints to make the next credential encode or scan succeed or fail, so you can test card encoder flows in a sandbox.
+  endpoints: true
+/acs/entrances:
+  title: The Entrance Object
+  description: Learn how the acs_entrance object represents a secured door, gate, or zone within an access control system, and how to list its credentials.
+/acs:
+  title: Access Control Systems
+  description: Systems for managing and monitoring access to physical spaces
+  namespace: true
+  intro: |
+    Access control systems centralize access authorization for buildings, which means that you can use a single system to grant users access to one or more entrances. An access control system manages the following elements:
+
+    - Who has access
+    - The entrances to which users have access
+    - The access schedule for each user and entrance
+    - The access mechanism—PIN codes, mobile keys, or plastic cards—for each access grant
+
+    To grant access using the Seam access control system API, use the following basic process:
+
+    1. Create `acs_user`s.
+    2. Configure access for these users.
+       For some access control systems, configure the allowed entrances and access schedule. For other systems, use `acs_access_group`s. For details, see the [system integration guide](/device-and-system-integration-guides#access-control-systems) for your access control system.
+    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](/capability-guides/mobile-access/mobile-device-sdks) that pair with the Seam API to create and manage mobile keys.
+  resources_intro: 'The Access Control Systems (ACS) namespace contains the following resources:'
+/acs/systems:
+  title: The ACS System Object
+  description: Learn how the acs_system object represents an access control system in which you create users and credentials to grant them access at entrances.
+/acs/users:
+  title: The ACS User Object
+  description: Learn how the acs_user object represents an individual—such as an employee or resident—who holds one or more credentials in an access control system.
+/action_attempts:
+  title: The Action Attempt Object
+  description: Learn how the action_attempt object tracks an attempt to perform an action against a device, letting you monitor its status and final result.
+  resource_type: action_attempt
+  legacy: true
+/client_sessions:
+  title: The Client Session Object
+  description: Learn how the client_session object restricts your users to their own devices using a custom user_identifier_key that scopes Seam API results.
+/connect_webviews:
+  title: The Connect Webview Object
+  description: Learn how the connect_webview object embeds a client-side flow that walks your users through linking their device or system accounts to Seam.
+/connected_accounts:
+  title: The Connected Account Object
+  description: Learn how the connected_account object represents an external third-party account your user has authorized Seam to access, such as an August account.
+/connected_accounts/simulate:
+  title: Simulate
+  description: Use the connected account simulation endpoint to disconnect an account from Seam in a sandbox workspace and test how your app handles disconnections.
+  endpoints: true
+/customers:
+  title: The Customer Object
+  description: Learn how the customer_portal object provides a hosted, customizable interface for managing device access that you can share or embed in your product.
+/devices:
+  title: The Device Object
+  description: Learn how the device object represents a smart lock, thermostat, sensor, or other device connected to Seam, including its properties and events.
+/devices/simulate:
+  title: Device Simulations
+  description: Use the device simulation endpoints to connect, disconnect, and remove sandbox devices so you can test how your app handles device state changes.
+  endpoints: true
+/devices/unmanaged:
+  title: Unmanaged Devices
+  description: Learn how the unmanaged_device object exposes a limited set of properties and events for a device you cannot control until you convert it to managed.
+/events:
+  title: The Event Object
+  description: Learn how the event object represents an occurrence in your workspace, such as a device action or status change, that you can list and react to.
+/instant_keys:
+  title: The Instant Key Object
+  description: Learn how the instant_key object lets you issue a Bluetooth mobile key with one API call and share it by link, text, or email—no app install required.
+/locks:
+  title: The Lock Object
+  description: Learn how the device object represents a smart lock connected to Seam, including its lock-specific properties, capabilities, errors, and events.
+  resource_type: device
+  legacy: true
+  include_groups:
+    - locks
+    - access_codes
+  heading: The device Object for Locks
+  intro: |
+    Represents a [lock](/low-level-apis/smart-locks).
+
+    The Seam API enables you to control connected smart locks from a wide variety of manufacturers, including locks that provide online and offline [access code](/low-level-apis/smart-locks/access-codes) programming.
+
+    Depending on the smart lock brand and model, actions that you can perform include remote unlock, remote lock, and programming access codes. You can also view a lock's properties, capabilities, and status. Further, you can monitor for unlock and lock events.
+
+    See also [Webhooks](/developer-tools/webhooks).
+/locks/simulate:
+  title: Lock Simulations
+  description: Use the lock simulation endpoints to mimic keypad code entry and manual locking on sandbox August devices so you can test your smart lock app.
+  endpoints: true
+/noise_sensors/noise_thresholds:
+  title: Noise Thresholds
+  description: Learn how the noise_threshold object sets the limits of noise tolerated at a property, customizable for each hour of the day on a noise sensor.
+/noise_sensors:
+  title: The Noise Sensor Object
+  description: Learn how the device object represents a noise sensor that measures sound levels, lets you configure thresholds, and emits disturbance events.
+  # TODO: consider a full device-view page (resource_type: device,
+  # include_groups: [noise_sensors]) like /locks and /thermostats; the migrated
+  # page only ever had an intro and an endpoint listing, so that shape is kept.
+  endpoints: true
+  heading: The device Object for Noise Sensors
+  intro: |
+    Represents a [noise sensor](/capability-guides/noise-sensors).
+
+    Noise sensors are devices that measure that sound level in a given area. You can use noise sensors to monitor noise levels remotely and receive notifications when the noise volume is too loud. The Seam API enables you to configure the [noise thresholds](/capability-guides/noise-sensors/configure-noise-threshold-settings) of a noise sensor and receive events when a disturbance is detected. You can also [simulate triggering a noise threshold](/api/noise_sensors/simulate/trigger_noise_threshold).
+
+    The Seam API represents a noise sensor as a `device` resource that includes both basic device properties and noise sensor-specific properties.
+/noise_sensors/simulate:
+  title: Noise Sensor Simulations
+  description: Use the noise sensor simulation endpoint to trigger a noise threshold in a sandbox workspace so you can test how your app responds to disturbances.
+  endpoints: true
+/phones:
+  title: The Phone Object
+  description: Learn how the phone object represents an app user mobile phone that holds mobile credentials, including its properties and lifecycle events.
+/phones/simulate:
+  title: Phone Simulations
+  description: Use the phone simulation endpoint to create a simulated phone in a sandbox workspace so you can test mobile access flows for a user identity.
+  endpoints: true
+/spaces:
+  title: The Space Object
+  description: Learn how the space object groups devices and entrances together so you can assign access to an entire space and grant access more efficiently.
+/thermostats/daily_programs:
+  title: Daily Programs
+  description: Learn how the thermostat_daily_program object defines periods that each apply a climate preset at a starting time to automate a thermostat day.
+/thermostats:
+  title: The Thermostat Object
+  description: Learn how the device object represents a thermostat connected to Seam, including its climate properties, capabilities, errors, warnings, and events.
+  resource_type: device
+  legacy: true
+  include_groups:
+    - thermostats
+  heading: The device Object for Thermostats
+  intro: |
+    Represents a [thermostat](/capability-guides/thermostats).
+
+    You can use the Seam API to perform the following management and monitoring actions for thermostats:
+
+    - Monitor current thermostat settings and readings.
+    - Configure [temperature thresholds](/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds). If the thermostat reports a temperature outside these thresholds, Seam automatically alerts you.
+    - Make immediate changes to [thermostat climate settings](/capability-guides/thermostats/configure-current-climate-settings), such as the HVAC mode and fan mode.
+    - [Create](/capability-guides/thermostats/creating-and-managing-climate-presets) and [schedule](/capability-guides/thermostats/creating-and-managing-thermostat-schedules) climate presets, including a fallback climate preset.
+    - Create daily and weekly [thermostat programs](/capability-guides/thermostats/creating-and-managing-thermostat-programs).
+
+    The Seam API represents a thermostat as a `device` resource that includes both basic device properties and thermostat-specific properties.
+
+    ---
+/thermostats/schedules:
+  title: Thermostat Schedules
+  description: Learn how the thermostat_schedule object activates a climate preset on a thermostat at a starting time and deactivates it at a specified ending time.
+/thermostats/simulate:
+  title: Thermostat Simulations
+  description: Use the thermostat simulation endpoints to mimic HVAC mode changes and reaching a target temperature on sandbox devices to test your thermostat app.
+  endpoints: true
+/user_identities:
+  title: The User Identity Object
+  description: Learn how the user_identity object links a person to their application user account so you can manage their mobile credentials and access in Seam.
+/user_identities/unmanaged:
+  title: Unmanaged
+  description: Use the unmanaged user identity endpoints to get, list, and update user identities that Seam tracks but does not manage (where is_managed is false).
+  endpoints: true
+/webhooks:
+  title: The Webhook Object
+  description: Learn how the webhook object lets you receive event notifications at an endpoint URL you specify, for the set of event types you choose to subscribe to.
+/workspaces:
+  title: The Workspace Object
+  description: Learn how the workspace object represents an isolated Seam environment that holds your devices, connected accounts, and resources, with sandbox support.