feat: scope action-attempt error and result accessors by status

Consume the actionAttemptStatuses property annotation from
@seamapi/blueprint 1.10.0. Properties annotated with statuses are
documented as only present for those statuses, typed as nullable, and
their generated accessors return nil for any other status.

Also guard ActionAttemptFailedError against a failed action attempt
missing its error, falling back to a generic message instead of
raising NoMethodError.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EdWS7o3htQ9cNxhCWL5Frp

Author: claude

codegen/layouts/partials/resource-class.hbs

@@ -12,21 +12,27 @@
 {{#if description}}
 {{{rubyDoc description ../docIndent}}}
 {{/if}}
-{{../bodyIndent}}# @return [{{rubyResourceType this}}]{{{rubyEnumValuesDoc this ../docIndent}}}
+{{../bodyIndent}}# @return [{{rubyResourceType this}}]{{{rubyEnumValuesDoc this ../docIndent}}}{{{rubyActionAttemptStatusesDoc this ../docIndent}}}
 {{../bodyIndent}}resource_accessor :{{name}}, {{className}}
+{{#if actionAttemptStatuses}}
+{{../bodyIndent}}available_only_for_statuses :{{name}}, {{rubyStringArray actionAttemptStatuses}}
+{{/if}}
 {{/each}}
 {{#each resourceListAccessors}}
 {{#if description}}
 {{{rubyDoc description ../docIndent}}}
 {{/if}}
-{{../bodyIndent}}# @return [{{rubyResourceType this}}]{{{rubyEnumValuesDoc this ../docIndent}}}
+{{../bodyIndent}}# @return [{{rubyResourceType this}}]{{{rubyEnumValuesDoc this ../docIndent}}}{{{rubyActionAttemptStatusesDoc this ../docIndent}}}
 {{../bodyIndent}}resource_list_accessor :{{name}}, {{className}}
+{{#if actionAttemptStatuses}}
+{{../bodyIndent}}available_only_for_statuses :{{name}}, {{rubyStringArray actionAttemptStatuses}}
+{{/if}}
 {{/each}}
 {{#each accessors}}
 {{#if description}}
 {{{rubyDoc description ../docIndent}}}
 {{/if}}
-{{../bodyIndent}}# @return [{{rubyPropertyType this}}]{{{rubyEnumValuesDoc this ../docIndent}}}
+{{../bodyIndent}}# @return [{{rubyPropertyType this}}]{{{rubyEnumValuesDoc this ../docIndent}}}{{{rubyActionAttemptStatusesDoc this ../docIndent}}}
 {{#if isDeprecated}}
 {{{rubyDeprecatedDoc this ../docIndent}}}
 {{/if}}
@@ -35,16 +41,22 @@
 {{else}}
 {{../bodyIndent}}attr_accessor :{{accessorName}}
 {{/if}}
+{{#if actionAttemptStatuses}}
+{{../bodyIndent}}available_only_for_statuses :{{accessorName}}, {{rubyStringArray actionAttemptStatuses}}
+{{/if}}
 {{/each}}
 {{#each dateAccessors}}
 {{#if description}}
 {{{rubyDoc description ../docIndent}}}
 {{/if}}
-{{../bodyIndent}}# @return [{{rubyPropertyType this}}]{{{rubyEnumValuesDoc this ../docIndent}}}
+{{../bodyIndent}}# @return [{{rubyPropertyType this}}]{{{rubyEnumValuesDoc this ../docIndent}}}{{{rubyActionAttemptStatusesDoc this ../docIndent}}}
 {{#if isDeprecated}}
 {{{rubyDeprecatedDoc this ../docIndent}}}
 {{/if}}
 {{../bodyIndent}}date_accessor :{{accessorName}}
+{{#if actionAttemptStatuses}}
+{{../bodyIndent}}available_only_for_statuses :{{accessorName}}, {{rubyStringArray actionAttemptStatuses}}
+{{/if}}
 {{/each}}
 {{#if discriminator}}
 

codegen/layouts/resource.hbs

@@ -19,21 +19,27 @@ module Seam
 {{#if description}}
 {{{rubyDoc description 6}}}
 {{/if}}
-      # @return [{{rubyResourceType this}}]{{{rubyEnumValuesDoc this 6}}}
+      # @return [{{rubyResourceType this}}]{{{rubyEnumValuesDoc this 6}}}{{{rubyActionAttemptStatusesDoc this 6}}}
       resource_accessor :{{name}}, {{className}}
+{{#if actionAttemptStatuses}}
+      available_only_for_statuses :{{name}}, {{rubyStringArray actionAttemptStatuses}}
+{{/if}}
 {{/each}}
 {{#each resourceListAccessors}}
 {{#if description}}
 {{{rubyDoc description 6}}}
 {{/if}}
-      # @return [{{rubyResourceType this}}]{{{rubyEnumValuesDoc this 6}}}
+      # @return [{{rubyResourceType this}}]{{{rubyEnumValuesDoc this 6}}}{{{rubyActionAttemptStatusesDoc this 6}}}
       resource_list_accessor :{{name}}, {{className}}
+{{#if actionAttemptStatuses}}
+      available_only_for_statuses :{{name}}, {{rubyStringArray actionAttemptStatuses}}
+{{/if}}
 {{/each}}
 {{#each accessors}}
 {{#if description}}
 {{{rubyDoc description 6}}}
 {{/if}}
-      # @return [{{rubyPropertyType this}}]{{{rubyEnumValuesDoc this 6}}}
+      # @return [{{rubyPropertyType this}}]{{{rubyEnumValuesDoc this 6}}}{{{rubyActionAttemptStatusesDoc this 6}}}
 {{#if isDeprecated}}
 {{{rubyDeprecatedDoc this 6}}}
 {{/if}}
@@ -42,17 +48,23 @@ module Seam
 {{else}}
       attr_accessor :{{accessorName}}
 {{/if}}
+{{#if actionAttemptStatuses}}
+      available_only_for_statuses :{{accessorName}}, {{rubyStringArray actionAttemptStatuses}}
+{{/if}}
 {{/each}}
 {{#each dateAccessors}}
 
 {{#if description}}
 {{{rubyDoc description 6}}}
 {{/if}}
-      # @return [{{rubyPropertyType this}}]{{{rubyEnumValuesDoc this 6}}}
+      # @return [{{rubyPropertyType this}}]{{{rubyEnumValuesDoc this 6}}}{{{rubyActionAttemptStatusesDoc this 6}}}
 {{#if isDeprecated}}
 {{{rubyDeprecatedDoc this 6}}}
 {{/if}}
       date_accessor :{{accessorName}}
+{{#if actionAttemptStatuses}}
+      available_only_for_statuses :{{accessorName}}, {{rubyStringArray actionAttemptStatuses}}
+{{/if}}
 {{/each}}
 {{#if discriminator}}
 

codegen/lib/handlebars-helpers.ts

@@ -49,6 +49,33 @@ export const rubyEnumValuesDoc = (
       )}`
 }
 
+const humanizeList = (items: string[], conjunction: string): string => {
+  if (items.length <= 1) return items[0] ?? ''
+  if (items.length === 2) return items.join(` ${conjunction} `)
+  return `${items.slice(0, -1).join(', ')}, ${conjunction} ${items.at(-1)}`
+}
+
+// Documents a property scoped to specific action-attempt statuses; a property
+// without the annotation has the same value for every status.
+export const rubyActionAttemptStatusesDoc = (
+  property: Property,
+  indentation: number,
+): string => {
+  const statuses = property.actionAttemptStatuses
+  if (statuses == null || statuses.length === 0) return ''
+  const list = humanizeList(
+    statuses.map((status) => `\`${status}\``),
+    'or',
+  )
+  return `\n${comment(
+    [`Only present when \`status\` is ${list}; \`nil\` otherwise.`],
+    indentation,
+  )}`
+}
+
+export const rubyStringArray = (values: string[]): string =>
+  `[${values.map((value) => JSON.stringify(value)).join(', ')}]`
+
 const nullable = (
   type: string,
   value: { isOptional: boolean; isNullable: boolean },

codegen/lib/layouts/resource.ts

@@ -1,7 +1,11 @@
 // Builds the template context for resource files
 // (lib/seam/resources/{snake_name}.rb).
 
-import type { DiscriminatedListProperty, Property } from '@seamapi/blueprint'
+import type {
+  ActionAttemptStatus,
+  DiscriminatedListProperty,
+  Property,
+} from '@seamapi/blueprint'
 import { pascalCase } from 'change-case'
 
 import { convertCustomResourceName } from '../custom-resource-name-conversions.js'
@@ -82,7 +86,7 @@ const isErrorOrWarningList = (
   property.itemFormat === 'discriminated_object' &&
   ['error_code', 'warning_code'].includes(property.discriminator)
 
-const sameDescription = (properties: Property[]): string => {
+export const sameDescription = (properties: Property[]): string => {
   const descriptions = new Set(properties.map(({ description }) => description))
   return descriptions.size === 1 ? (properties[0]?.description ?? '') : ''
 }
@@ -154,6 +158,21 @@ export const getCommonScalarProperties = (
   return result
 }
 
+// An action-attempt property annotated with actionAttemptStatuses only holds a
+// value for the listed statuses and is null for the others. An annotation that
+// covers every known status is equivalent to no annotation at all.
+const getScopedStatuses = (
+  property: Property,
+  allStatuses: string[] | undefined,
+): ActionAttemptStatus[] | undefined => {
+  const statuses: string[] | undefined = property.actionAttemptStatuses
+  if (statuses == null || statuses.length === 0) return undefined
+  if (allStatuses != null && allStatuses.every((s) => statuses.includes(s))) {
+    return undefined
+  }
+  return property.actionAttemptStatuses
+}
+
 const getDiscriminatorValue = (
   properties: Property[],
   discriminator: string,
@@ -242,6 +261,27 @@ const buildClass = (
   const resourceListAccessors: ResourceAccessor[] = []
   const takenClassNames = new Set<string>()
 
+  // The status property enumerates every status the resource can be in, which
+  // reveals when an actionAttemptStatuses annotation is actually restrictive.
+  const statusProperty = classProperties.find(
+    ({ name, format }) => name === 'status' && format === 'enum',
+  )
+  const allStatuses =
+    statusProperty?.format === 'enum'
+      ? statusProperty.values.map(({ name }) => name)
+      : undefined
+
+  const scopeToStatuses = <T extends Property>(property: T): T => {
+    const statuses = getScopedStatuses(property, allStatuses)
+    if (statuses == null) {
+      if (property.actionAttemptStatuses == null) return property
+      const unscoped = { ...property }
+      delete unscoped.actionAttemptStatuses
+      return unscoped
+    }
+    return { ...property, actionAttemptStatuses: statuses, isNullable: true }
+  }
+
   for (const property of classProperties) {
     const nestedProperties = getNestedProperties(property)
     if (nestedProperties == null) continue
@@ -266,7 +306,10 @@ const buildClass = (
 
     const destination =
       property.format === 'list' ? resourceListAccessors : resourceAccessors
-    destination.push({ ...property, className: nestedClassName })
+    destination.push({
+      ...scopeToStatuses(property),
+      className: nestedClassName,
+    })
 
     const discriminated = isErrorOrWarningList(property)
     const nestedClass = buildClass(
@@ -305,7 +348,7 @@ const buildClass = (
   const toPropertyAccessor = (property: Property): PropertyAccessor => {
     const isAliased = property.name === 'method' && path.startsWith('event.')
     return {
-      ...property,
+      ...scopeToStatuses(property),
       accessorName: isAliased ? 'event_method' : property.name,
       isAliased,
     }

codegen/lib/routes.ts

@@ -7,6 +7,7 @@
 // blueprint.namespaces.
 
 import type {
+  ActionAttemptStatus,
   Blueprint,
   Endpoint,
   Property,
@@ -23,6 +24,7 @@ import { setImportsLayoutContext } from './layouts/imports.js'
 import {
   type DiscriminatedVariantSource,
   getCommonScalarProperties,
+  sameDescription,
   setResourceLayoutContext,
 } from './layouts/resource.js'
 import { setRoutesFileLayoutContext } from './layouts/routes-file.js'
@@ -94,12 +96,46 @@ interface ResourceSource extends ResourceDocumentation {
   variants?: DiscriminatedVariantSource[]
 }
 
+// The fallback class only scopes a property to statuses when every known
+// variant scopes it; the statuses are the union across the variants. If any
+// variant leaves the property unscoped, the fallback leaves it unscoped too.
+const mergeActionAttemptStatuses = (
+  occurrences: Property[],
+): ActionAttemptStatus[] | undefined => {
+  if (
+    occurrences.some(
+      ({ actionAttemptStatuses }) => actionAttemptStatuses == null,
+    )
+  ) {
+    return undefined
+  }
+  return [
+    ...new Set(
+      occurrences.flatMap(
+        ({ actionAttemptStatuses }) => actionAttemptStatuses ?? [],
+      ),
+    ),
+  ]
+}
+
 const createActionAttemptBaseProperties = (
   variants: DiscriminatedVariantSource[],
 ): Property[] => {
   const propertyLists = variants.map(({ properties }) => properties)
   const common = getCommonScalarProperties(propertyLists)
-  const nested = ['error', 'result'].flatMap((name) => {
+
+  // Nested object properties every variant carries (e.g. error and result)
+  // fall back to the scalar fields their occurrences share.
+  const nestedNames = [
+    ...new Set(
+      propertyLists.flatMap((properties) =>
+        properties
+          .filter(({ format }) => format === 'object')
+          .map(({ name }) => name),
+      ),
+    ),
+  ]
+  const nested = nestedNames.flatMap((name) => {
     const occurrences = propertyLists.map((properties) =>
       properties.find((property) => property.name === name),
     )
@@ -116,17 +152,21 @@ const createActionAttemptBaseProperties = (
     >
     const first = objects[0]
     if (first == null) return []
-    return [
-      {
-        ...first,
-        description:
-          name === 'error' ? 'Error associated with the action.' : '',
-        isNullable: true,
-        properties: getCommonScalarProperties(
-          objects.map(({ properties }) => properties),
-        ),
-      },
-    ]
+    const property: Extract<Property, { format: 'object' }> = {
+      ...first,
+      description: sameDescription(objects),
+      isNullable: objects.some(({ isNullable }) => isNullable),
+      properties: getCommonScalarProperties(
+        objects.map(({ properties }) => properties),
+      ),
+    }
+    const statuses = mergeActionAttemptStatuses(objects)
+    if (statuses == null) {
+      delete property.actionAttemptStatuses
+    } else {
+      property.actionAttemptStatuses = statuses
+    }
+    return [property]
   })
 
   return [...common, ...nested].sort((a, b) => a.name.localeCompare(b.name))
@@ -157,16 +197,13 @@ const getResources = (
   }
 
   if (blueprint.actionAttempts.length > 0) {
+    // Properties annotated with actionAttemptStatuses only hold a value for
+    // the listed statuses (e.g. error and result while pending); the resource
+    // layout turns that annotation into nullable, status-scoped accessors.
     const variants = blueprint.actionAttempts.map((actionAttempt) => ({
       discriminatorValue: actionAttempt.actionAttemptType,
       description: actionAttempt.description,
-      // Action attempts can return null for both fields while pending. The
-      // blueprint currently loses that per-status nullability upstream.
-      properties: actionAttempt.properties.map((property) =>
-        ['error', 'result'].includes(property.name)
-          ? { ...property, isNullable: true }
-          : property,
-      ),
+      properties: actionAttempt.properties,
     }))
     resources.set('action_attempt', {
       description:

lib/seam/base_resource.rb

@@ -78,6 +78,16 @@ def self.resource_list_accessor(attr, resource_class)
         end
       end
 
+      # Scopes an already defined accessor to the given resource statuses. The
+      # property only holds a value while the resource's status is one of the
+      # listed statuses, so the reader returns nil for any other status.
+      def self.available_only_for_statuses(attr, statuses)
+        unscoped = instance_method(attr)
+        define_method(attr) do
+          statuses.include?(status) ? unscoped.bind_call(self) : nil
+        end
+      end
+
       def self.resource_accessors
         @resource_accessors ||= {}
       end