feat: Add support for resource samples (#575)

* Update blueprint

* Load resourceSampleDefinitions

* Add resource sample

* Add resourceSamples to resource layout context

Author: razor-x

.github/CODEOWNERS

@@ -1,3 +1,3 @@
 * @seamapi/sdk
 /docs/ @seamapi/docs
-/src/data/code-sample-definitions @seamapi/docs
+/src/data @seamapi/docs

package-lock.json

@@ -33,7 +33,7 @@
     "@metalsmith/metadata": "^0.3.0",
     "@prettier/plugin-php": "^0.22.2",
     "@prettier/plugin-ruby": "^4.0.4",
-    "@seamapi/blueprint": "^0.40.2",
+    "@seamapi/blueprint": "^0.41.0",
     "@seamapi/types": "1.392.1",
     "change-case": "^5.4.4",
     "command-exists": "^1.2.9",

package.json

@@ -0,0 +1,6 @@
+---
+- title: ACS System
+  description: A basic system.
+  resource_type: acs_system
+  properties:
+    acs_system_id: 'bbcea306-7201-4d85-b527-3abc55277203'

src/data/resource-sample-definitions/acs-system.yaml

@@ -12,9 +12,15 @@ export const blueprint =
     const codeSampleDefinitions =
       'codeSampleDefinitions' in metadata ? metadata.codeSampleDefinitions : []
 
+    const resourceSampleDefinitions =
+      'resourceSampleDefinitions' in metadata
+        ? metadata.resourceSampleDefinitions
+        : []
+
     const typesModule = TypesModuleSchema.parse({
       ...types,
       codeSampleDefinitions,
+      resourceSampleDefinitions,
     })
 
     const blueprint = await createBlueprint(typesModule, {

src/lib/blueprint.ts

@@ -1,21 +1,21 @@
 import * as prettierPluginPhp from '@prettier/plugin-php/standalone'
 import * as prettierPluginRuby from '@prettier/plugin-ruby'
-import type { CodeSampleSyntax } from '@seamapi/blueprint'
+import type { SyntaxName } from '@seamapi/blueprint'
 import commandExists from 'command-exists'
 import { execa } from 'execa'
 import { format as prettier } from 'prettier'
 
 export const formatCode = async (
   content: string,
-  syntax: CodeSampleSyntax,
+  syntax: SyntaxName,
 ): Promise<string> => {
   const output = await formatCodeForSyntax(content, syntax)
   return output.trim()
 }
 
 const formatCodeForSyntax = async (
   content: string,
-  syntax: CodeSampleSyntax,
+  syntax: SyntaxName,
 ): Promise<string> => {
   switch (syntax) {
     case 'javascript':

src/lib/format-code.ts

@@ -1,8 +1,8 @@
 import type {
   ActionAttempt,
-  CodeSampleSdk,
   Endpoint,
   Parameter,
+  SdkName,
   SeamAuthMethod,
   SeamWorkspaceScope,
 } from '@seamapi/blueprint'
@@ -14,7 +14,7 @@ import {
   normalizePropertyFormatForDocs,
 } from './api-route.js'
 
-const supportedSdks: CodeSampleSdk[] = [
+const supportedSdks: SdkName[] = [
   'javascript',
   'python',
   'php',
@@ -195,7 +195,7 @@ const mapBlueprintParamToEndpointParam = (
 
 const mapCodeSample = (sample: CodeSample): CodeSampleContext => {
   const codeEntries = Object.entries(sample.code).filter(([k]) =>
-    supportedSdks.includes(k as CodeSampleSdk),
+    supportedSdks.includes(k as SdkName),
   )
   return {
     title: sample.title,

src/lib/layout/api-endpoint.ts

@@ -7,6 +7,11 @@ import type {
   Route,
 } from '@seamapi/blueprint'
 import { pascalCase } from 'change-case'
+import type {
+  SdkName,
+  SyntaxName,
+} from 'node_modules/@seamapi/blueprint/dist/index.cjs'
+import type { ResourceSample } from 'node_modules/@seamapi/blueprint/lib/samples/resource-sample.js'
 
 import type { PathMetadata } from 'lib/path-metadata.js'
 
@@ -18,6 +23,7 @@ export interface ApiRouteLayoutContext {
     ApiRouteResource & {
       warnings: ApiWarning[]
       errors: ApiError[]
+      resourceSamples: ResourceSampleContext[]
     }
   >
   endpoints: ApiRouteEndpoint[]
@@ -30,6 +36,12 @@ interface ApiRouteEvent {
   properties: ApiRouteProperty[]
 }
 
+interface ResourceSampleContext {
+  title: string
+  resourceData: string
+  resourceDataSyntax: SyntaxName
+}
+
 type ApiRouteProperty = Pick<
   Property,
   'name' | 'description' | 'isDeprecated' | 'deprecationMessage'
@@ -144,6 +156,7 @@ export function setApiRouteLayoutContext(
       errors: resourceErrors,
       warnings: resourceWarnings,
       events: resourceEvents,
+      resourceSamples: resource.resourceSamples.map(mapResourceSample),
     })
   }
 }
@@ -337,3 +350,21 @@ function addLinkTargetsToProperties(
     }
   }
 }
+
+const mapResourceSample = (sample: ResourceSample): ResourceSampleContext => {
+  const jsonSample = Object.entries(sample.resource).find(
+    ([k]) => (k as SdkName) === 'seam_cli',
+  )?.[1]
+
+  if (jsonSample == null) {
+    throw new Error(
+      `Missing seam_cli for ${sample.resource_type} resource sample: ${sample.title}`,
+    )
+  }
+
+  return {
+    title: sample.title,
+    resourceData: jsonSample.resource_data,
+    resourceDataSyntax: jsonSample.resource_data_syntax,
+  }
+}

src/lib/layout/api-route.ts

@@ -29,6 +29,7 @@ Metalsmith(rootDir)
   .use(
     metadata({
       codeSampleDefinitions: './data/code-sample-definitions',
+      resourceSampleDefinitions: './data/resource-sample-definitions',
       pathMetadata: './data/paths.yaml',
     }),
   )