Generate /action_attempts route, add special handling for AA resource

Author: andrii-balitskyi

src/data/paths.yaml

@@ -80,3 +80,8 @@
   title: Enrollment Automations
   resources:
     - enrollment_automation
+
+/action_attempts:
+  title: Action Attempts
+  resources:
+    - action_attempt

src/lib/layout/action-attempt-resource.ts

@@ -0,0 +1,93 @@
+import type { Blueprint } from '@seamapi/blueprint'
+
+import {
+  type ApiError,
+  type ApiRouteEvent,
+  type ApiRouteProperty,
+  type ApiRouteResource,
+  type ApiWarning,
+  mapBlueprintPropertyToRouteProperty,
+  type ResourceSampleContext,
+} from './api-route.js'
+
+export function processActionAttemptResource(
+  blueprint: Blueprint,
+  resources: Array<
+    ApiRouteResource & {
+      warnings: ApiWarning[]
+      errors: ApiError[]
+      resourceSamples: ResourceSampleContext[]
+    }
+  >,
+  eventsByRoutePath: Map<string, ApiRouteEvent[]>,
+): void {
+  const blueprintActionAttemptDef = blueprint.actionAttempts[0]
+  if (blueprintActionAttemptDef == null) {
+    throw new Error(
+      'Cannot process action attempt resource: blueprint.actionAttempts is empty.',
+    )
+  }
+
+  const idPropKey = 'action_attempt_id'
+  const idPropDef = blueprintActionAttemptDef.properties.find(
+    (p) => p.name === idPropKey,
+  )
+  if (idPropDef == null) {
+    throw new Error(
+      `Blueprint action attempt is missing "${idPropKey}" property.`,
+    )
+  }
+
+  const statusPropKey = 'status'
+  const statusPropDef = blueprintActionAttemptDef.properties.find(
+    (p) => p.name === statusPropKey,
+  )
+  if (statusPropDef == null) {
+    throw new Error(
+      `Blueprint action attempt is missing "${statusPropKey}" property.`,
+    )
+  }
+
+  const actionTypes = blueprint.actionAttempts.map(
+    (attempt) => attempt.actionAttemptType,
+  )
+
+  const properties: ApiRouteProperty[] = [
+    mapBlueprintPropertyToRouteProperty(idPropDef),
+    mapBlueprintPropertyToRouteProperty(statusPropDef),
+    {
+      name: 'action_type',
+      description: 'Type of the action attempt.',
+      format: 'String',
+      isDeprecated: false,
+      deprecationMessage: '',
+      enumValues: actionTypes,
+    },
+    {
+      name: 'error',
+      description:
+        'Errors associated with the action attempt. Null for pending action attempts.',
+      format: 'Object',
+      isDeprecated: false,
+      deprecationMessage: '',
+    },
+    {
+      name: 'result',
+      description:
+        'Result of the action attempt. Null for pending action attempts.',
+      format: 'Object',
+      isDeprecated: false,
+      deprecationMessage: '',
+    },
+  ]
+
+  resources.push({
+    name: 'action_attempt',
+    description: 'Represents an attempt to perform an action against a device.',
+    properties,
+    errors: [],
+    warnings: [],
+    events: eventsByRoutePath.get('/action_attempts') ?? [],
+    resourceSamples: [],
+  })
+}

src/lib/layout/api-route.ts

@@ -15,6 +15,8 @@ import type { ResourceSample } from 'node_modules/@seamapi/blueprint/lib/samples
 
 import type { PathMetadata } from 'lib/path-metadata.js'
 
+import { processActionAttemptResource } from './action-attempt-resource.js'
+
 export interface ApiRouteLayoutContext {
   title: string
   description: string
@@ -30,19 +32,19 @@ export interface ApiRouteLayoutContext {
   events: ApiRouteEvent[]
 }
 
-interface ApiRouteEvent {
+export interface ApiRouteEvent {
   name: string
   description: string
   properties: ApiRouteProperty[]
 }
 
-interface ResourceSampleContext {
+export interface ResourceSampleContext {
   title: string
   resourceData: string
   resourceDataSyntax: SyntaxName
 }
 
-type ApiRouteProperty = Pick<
+export type ApiRouteProperty = Pick<
   Property,
   'name' | 'description' | 'isDeprecated' | 'deprecationMessage'
 > & {
@@ -68,11 +70,12 @@ export interface ApiRouteResource {
   events: ApiRouteEvent[]
 }
 
-interface ApiWarning {
+export interface ApiWarning {
   name: string
   description: string
 }
-interface ApiError {
+
+export interface ApiError {
   name: string
   description: string
 }
@@ -108,6 +111,11 @@ export function setApiRouteLayoutContext(
 
   file.resources = []
   for (const resourceType of metadata.resources) {
+    if (resourceType === 'action_attempt') {
+      processActionAttemptResource(blueprint, file.resources, eventsByRoutePath)
+      continue
+    }
+
     const resource = blueprint.resources[resourceType]
 
     if (resource == null) {
@@ -150,8 +158,6 @@ const groupEventsByRoutePath = (
   const eventsByRoutePath = new Map<string, ApiRouteEvent[]>()
 
   for (const event of events) {
-    if (event.routePath == null) continue
-
     const routeEvents = eventsByRoutePath.get(event.routePath) ?? []
     routeEvents.push({
       name: event.eventType,

src/lib/reference.ts

@@ -57,7 +57,8 @@ export const reference = (
       !route.path.startsWith('/acs') &&
       !route.path.startsWith('/thermostats') &&
       !route.path.startsWith('/phones') &&
-      !route.path.startsWith('/user_identities')
+      !route.path.startsWith('/user_identities') &&
+      !route.path.startsWith('/action_attempts')
     ) {
       continue
     }