Migrate resource classes from Objects to Resources namespace (#454)

Generate the resource classes into src/Resources under the Seam\Resources
namespace instead of src/Objects under Seam\Objects.

Each blueprint resource now gets a single file. The classes that only exist
to type a nested object property of a resource (DeviceBattery, AcsSystemLocation,
and so on) are emitted as local classes in the file of the resource that
introduced them, rather than as 213 separate files.

Since those local classes no longer live in a file matching their name, add a
classmap autoload entry for src/Resources alongside the existing PSR-4 mapping.

The generated classes themselves are unchanged: all 213 class bodies are
byte-identical to the previous output.


Claude-Session: https://claude.ai/code/session_014yfWYVy7dgifgtsFPnrkDX

Co-authored-by: Claude <noreply@anthropic.com>

Author: razor-x

codegen/layouts/object.hbs codegen/layouts/resource.hbscodegen/layouts/object.hbs renamed to codegen/layouts/resource.hbs

@@ -1,7 +1,8 @@
 <?php
 
-namespace Seam\Objects;
+namespace Seam\Resources;
 
+{{#each classes}}
 class {{className}}
 {
     public static function from_json(mixed $json): {{className}}|null
@@ -23,3 +24,5 @@ class {{className}}
     ) {
     }
 }
+
+{{/each}}

codegen/layouts/seam-client.hbs

@@ -3,7 +3,7 @@
 namespace Seam;
 
 {{#each useStatements}}
-use Seam\Objects\\{{this}};
+use Seam\Resources\\{{this}};
 {{/each}}
 use Seam\Utils\PackageVersion;
 

codegen/lib/layouts/object.ts codegen/lib/layouts/resource.tscodegen/lib/layouts/object.ts renamed to codegen/lib/layouts/resource.ts

@@ -1,22 +1,29 @@
-// Builds the template context for resource object files (src/Objects/{Name}.php):
-// the from_json body lines and the constructor parameter lines.
+// Builds the template context for resource files (src/Resources/{Name}.php):
+// the resource class followed by the local classes for its object properties.
+// Each class contributes its from_json body lines and constructor parameter
+// lines.
 //
 // The blueprint does not track which resource properties are required, so
 // every property is optional: from_json falls back to null for missing values
 // and the constructor parameters are nullable.
 
 import type {
-  ResourceObjectProperty,
-  ResourceObjectSchema,
+  ResourceClassProperty,
+  ResourceClassSchema,
+  ResourceSchema,
 } from '../resource-model.js'
 
-export interface ObjectLayoutContext {
+export interface ClassLayoutContext {
   className: string
   fromJsonProps: string[]
   constructorParams: string[]
 }
 
-const generateFromJsonProp = (property: ResourceObjectProperty): string => {
+export interface ResourceLayoutContext {
+  classes: ClassLayoutContext[]
+}
+
+const generateFromJsonProp = (property: ResourceClassProperty): string => {
   const { name } = property
 
   switch (property.kind) {
@@ -31,9 +38,7 @@ const generateFromJsonProp = (property: ResourceObjectProperty): string => {
   }
 }
 
-const generateConstructorParam = (
-  property: ResourceObjectProperty,
-): string => {
+const generateConstructorParam = (property: ResourceClassProperty): string => {
   switch (property.kind) {
     case 'objectReference':
       return `public ${property.referenceName}|null $${property.name},`
@@ -49,9 +54,9 @@ const generateConstructorParam = (
   }
 }
 
-export const setObjectLayoutContext = (
-  schema: ResourceObjectSchema,
-): ObjectLayoutContext => {
+const getClassLayoutContext = (
+  schema: ResourceClassSchema,
+): ClassLayoutContext => {
   const sorted = [...schema.properties].sort((a, b) =>
     a.name.localeCompare(b.name),
   )
@@ -62,3 +67,11 @@ export const setObjectLayoutContext = (
     constructorParams: sorted.map(generateConstructorParam),
   }
 }
+
+export const setResourceLayoutContext = (
+  resource: ResourceSchema,
+): ResourceLayoutContext => ({
+  classes: [resource.resourceClass, ...resource.localClasses].map(
+    getClassLayoutContext,
+  ),
+})

codegen/lib/layouts/seam-client.ts

@@ -83,9 +83,9 @@ const getMethodLayoutContext = (
 
 export const setSeamClientLayoutContext = (
   clients: PhpClient[],
-  baseResourceObjectNames: string[],
+  resourceNames: string[],
 ): SeamClientLayoutContext => ({
-  useStatements: baseResourceObjectNames,
+  useStatements: resourceNames,
   parentClients: clients
     .filter((c) => c.isParentClient)
     .map((c) => ({ clientName: c.clientName, namespace: c.namespace })),

codegen/lib/resource-model.ts

@@ -1,9 +1,11 @@
-// Builds the resource object class model for src/Objects from the blueprint.
+// Builds the resource class model for src/Resources from the blueprint.
 //
-// Each blueprint resource becomes a PHP class. Nested object properties and
-// lists of objects are split into their own classes named after the base
-// resource and the property, e.g. the device battery property becomes
-// DeviceBattery. Discriminated unions (events, action attempts, and
+// Each blueprint resource becomes a PHP class in its own file. Nested object
+// properties and lists of objects are split into their own classes, named
+// after the base resource and the property, e.g. the device battery property
+// becomes DeviceBattery. Those classes only exist to type a resource
+// property, so they are emitted as local classes in the file of the resource
+// that introduced them. Discriminated unions (events, action attempts, and
 // discriminated object lists) are flattened into a single class with the
 // union of the variant properties.
 
@@ -12,24 +14,28 @@ import { pascalCase } from 'change-case'
 
 import { getPhpType } from './map-php-type.js'
 
-export type ResourceObjectProperty =
+export type ResourceClassProperty =
   | { name: string; kind: 'value'; phpType: string }
   | { name: string; kind: 'objectReference'; referenceName: string }
   | { name: string; kind: 'listReference'; referenceName: string }
 
-export interface ResourceObjectSchema {
+export interface ResourceClassSchema {
   name: string
-  properties: ResourceObjectProperty[]
+  properties: ResourceClassProperty[]
 }
 
-export interface ResourceObjectModel {
-  baseResourceNames: string[]
-  schemas: ResourceObjectSchema[]
+export interface ResourceSchema {
+  name: string
+  resourceClass: ResourceClassSchema
+  localClasses: ResourceClassSchema[]
+}
+
+export interface ResourceModel {
+  resourceNames: string[]
+  resources: ResourceSchema[]
 }
 
-export const createResourceObjectModel = (
-  blueprint: Blueprint,
-): ResourceObjectModel => {
+export const createResourceModel = (blueprint: Blueprint): ResourceModel => {
   const baseResources = new Map<string, Property[]>()
 
   for (const resource of blueprint.resources) {
@@ -57,50 +63,74 @@ export const createResourceObjectModel = (
     )
   }
 
-  const schemas = new Map<string, ResourceObjectSchema>()
+  const classes = new Map<string, ResourceClassSchema>()
+  const localClassNames = new Map<string, string[]>()
 
-  const addSchema = (
+  let currentResourceName = ''
+
+  const addClass = (
     name: string,
     properties: Property[],
     baseName: string,
   ): void => {
-    if (schemas.has(name)) return
-    const schema: ResourceObjectSchema = { name, properties: [] }
-    schemas.set(name, schema)
+    if (classes.has(name)) return
+    const schema: ResourceClassSchema = { name, properties: [] }
+    classes.set(name, schema)
+    if (name !== currentResourceName) {
+      localClassNames.get(currentResourceName)?.push(name)
+    }
     schema.properties = properties.map((property) =>
-      createResourceObjectProperty(property, baseName, addSchema),
+      createResourceClassProperty(property, baseName, addClass),
     )
   }
 
   const baseResourceTypes = [...baseResources.keys()].sort()
-  for (const resourceType of baseResourceTypes) {
-    addSchema(
-      pascalCase(resourceType),
-      baseResources.get(resourceType) ?? [],
-      resourceType,
-    )
-  }
+  const resources = baseResourceTypes.map((resourceType) => {
+    const name = pascalCase(resourceType)
+    currentResourceName = name
+    localClassNames.set(name, [])
+    addClass(name, baseResources.get(resourceType) ?? [], resourceType)
+
+    const resourceClass = classes.get(name)
+    if (resourceClass == null) {
+      throw new Error(
+        `Missing class for resource ${resourceType}: ${name} is already used by a property class of another resource`,
+      )
+    }
+
+    return {
+      name,
+      resourceClass,
+      localClasses: (localClassNames.get(name) ?? [])
+        .map((localClassName) => {
+          const localClass = classes.get(localClassName)
+          if (localClass == null) {
+            throw new Error(`Missing local class ${localClassName}`)
+          }
+          return localClass
+        })
+        .sort((a, b) => a.name.localeCompare(b.name)),
+    }
+  })
 
   return {
-    baseResourceNames: baseResourceTypes.map((resourceType) =>
-      pascalCase(resourceType),
-    ),
-    schemas: [...schemas.values()],
+    resourceNames: resources.map((resource) => resource.name),
+    resources,
   }
 }
 
-const createResourceObjectProperty = (
+const createResourceClassProperty = (
   property: Property,
   baseName: string,
-  addSchema: (name: string, properties: Property[], baseName: string) => void,
-): ResourceObjectProperty => {
+  addClass: (name: string, properties: Property[], baseName: string) => void,
+): ResourceClassProperty => {
   const referenceName = pascalCase(`${baseName}_${property.name}`)
 
   if (property.format === 'object') {
     const { properties } = property
 
     if (properties.length > 0) {
-      addSchema(referenceName, properties, baseName)
+      addClass(referenceName, properties, baseName)
       return { name: property.name, kind: 'objectReference', referenceName }
     }
   }
@@ -116,7 +146,7 @@ const createResourceObjectProperty = (
           : []
 
     if (itemProperties.length > 0) {
-      addSchema(referenceName, itemProperties, baseName)
+      addClass(referenceName, itemProperties, baseName)
       return { name: property.name, kind: 'listReference', referenceName }
     }
   }

codegen/lib/routes.ts

@@ -1,24 +1,24 @@
 // The Metalsmith plugin that generates the PHP SDK source files.
 //
 // The blueprint from @seamapi/blueprint is the only input: it drives the
-// resource object classes written to src/Objects, and the resource client
+// resource classes written to src/Resources, and the resource client
 // classes serialized into src/SeamClient.php.
 
 import type { Blueprint, Endpoint } from '@seamapi/blueprint'
 import { pascalCase } from 'change-case'
 import type Metalsmith from 'metalsmith'
 
 import type { PhpClient, PhpClientMethod } from './class-model.js'
-import { setObjectLayoutContext } from './layouts/object.js'
+import { setResourceLayoutContext } from './layouts/resource.js'
 import { setSeamClientLayoutContext } from './layouts/seam-client.js'
 import { getPhpType } from './map-php-type.js'
-import { createResourceObjectModel } from './resource-model.js'
+import { createResourceModel } from './resource-model.js'
 
 interface Metadata {
   blueprint: Blueprint
 }
 
-const objectsPath = 'src/Objects'
+const resourcesPath = 'src/Resources'
 const seamClientPath = 'src/SeamClient.php'
 
 export const routes = (
@@ -28,15 +28,16 @@ export const routes = (
   const metadata = metalsmith.metadata() as Metadata
   const { blueprint } = metadata
 
-  // Resource object classes, one file per (deeply extracted) schema. The base
-  // resource names drive the SeamClient use statements.
-  const { baseResourceNames, schemas } = createResourceObjectModel(blueprint)
+  // Resource classes, one file per resource holding the resource class and
+  // the local classes for its object properties. The resource names drive the
+  // SeamClient use statements.
+  const { resourceNames, resources } = createResourceModel(blueprint)
 
-  for (const schema of schemas) {
-    files[`${objectsPath}/${schema.name}.php`] = {
+  for (const resource of resources) {
+    files[`${resourcesPath}/${resource.name}.php`] = {
       contents: Buffer.from('\n'),
-      layout: 'object.hbs',
-      ...setObjectLayoutContext(schema),
+      layout: 'resource.hbs',
+      ...setResourceLayoutContext(resource),
     }
   }
 
@@ -83,7 +84,7 @@ export const routes = (
   files[seamClientPath] = {
     contents: Buffer.from('\n'),
     layout: 'seam-client.hbs',
-    ...setSeamClientLayoutContext([...classMap.values()], baseResourceNames),
+    ...setSeamClientLayoutContext([...classMap.values()], resourceNames),
   }
 }
 
@@ -93,9 +94,9 @@ const createClientMethod = (endpoint: Endpoint): PhpClientMethod => {
   const responseKey = response.responseType === 'void' ? '' : response.responseKey
 
   // Batch responses have no single resource type; they deserialize into the
-  // Batch resource object. A response whose resource type the blueprint
-  // cannot resolve ('unknown') has no resource object class to deserialize
-  // into, so the method is generated as returning void.
+  // Batch resource. A response whose resource type the blueprint cannot
+  // resolve ('unknown') has no resource class to deserialize into, so the
+  // method is generated as returning void.
   const resourceType =
     response.responseType === 'void'
       ? ''

codegen/smith.ts

@@ -11,7 +11,7 @@ import { helpers, routes } from './lib/index.js'
 
 const rootDir = dirname(fileURLToPath(import.meta.url))
 
-await Promise.all([deleteAsync(['./src/Objects', './src/SeamClient.php'])])
+await Promise.all([deleteAsync(['./src/Resources', './src/SeamClient.php'])])
 
 const partials = await getHandlebarsPartials(`${rootDir}/layouts/partials`)
 

composer.json

@@ -8,7 +8,8 @@
     "psr-4": {
       "Seam\\": ["src/", "src/Exceptions/"],
       "Tests\\": "tests/"
-    }
+    },
+    "classmap": ["src/Resources/"]
   },
   "authors": [
     {

src/Exceptions/ActionAttemptError.php

@@ -2,7 +2,7 @@
 
 namespace Seam;
 
-use Seam\Objects\ActionAttempt;
+use Seam\Resources\ActionAttempt;
 
 class ActionAttemptError extends \Exception
 {

src/Exceptions/ActionAttemptFailedError.php

@@ -2,7 +2,7 @@
 
 namespace Seam;
 
-use Seam\Objects\ActionAttempt;
+use Seam\Resources\ActionAttempt;
 
 class ActionAttemptFailedError extends ActionAttemptError
 {