Add description for /acs/systems

docs/api/acs/systems/README.md

@@ -1,3 +1,10 @@
+---
+description: Access Control Systems
+---
+```
+/acs/systems
+```
+
 # `acs_system`
 
 Represents an [access control system](https://docs.seam.co/latest/capability-guides/access-systems).

docs/api/acs/systems/get.md

@@ -1,3 +1,6 @@
+---
+description: Get an ACS System
+---
 # Get an ACS System
 
 ```

docs/api/acs/systems/list.md

@@ -1,3 +1,6 @@
+---
+description: List ACS Systems
+---
 # List ACS Systems
 
 ```

docs/api/acs/systems/list_compatible_credential_manager_acs_systems.md

@@ -1,3 +1,6 @@
+---
+description: List Compatible Credential Manager ACS Systems
+---
 # List Compatible Credential Manager ACS Systems
 
 ```

package.json

@@ -40,7 +40,8 @@
  "execa": "^9.3.1",
  "jstransformer-handlebars": "^1.2.0",
  "metalsmith": "^2.6.3",
- "prettier": "^3.0.0"
+ "prettier": "^3.0.0",
+ "zod": "^3.23.8"
  },
  "devDependencies": {
  "@types/command-exists": "^1.2.3",

src/data/paths.yaml

@@ -1,3 +1,20 @@
 ---
 /acs/systems:
- description: null
+ page:
+ title: Systems
+ description: Access Control Systems
+
+/acs/systems/get:
+ page:
+ title: Get an ACS System
+ description: Get an ACS System
+
+/acs/systems/list:
+ page:
+ title: List ACS Systems
+ description: List ACS Systems
+
+/acs/systems/list_compatible_credential_manager_acs_systems:
+ page:
+ title: List Compatible Credential Manager ACS Systems
+ description: List Compatible Credential Manager ACS Systems

src/layouts/api-endpoint.hbs

@@ -1,3 +1,6 @@
+---
+description: {{page.description}}
+---
 # {{title}}
 
 ```

src/layouts/api-route.hbs

@@ -1,3 +1,10 @@
+---
+description: {{page.description}}
+---
+```
+{{path}}
+```
+
 {{#each resources}}
 # `{{name}}`
 {{#if description}}

src/lib/blueprint.ts

@@ -13,14 +13,11 @@ export const blueprint = async (
  const codeSampleDefinitions =
  'codeSampleDefinitions' in metadata ? metadata.codeSampleDefinitions : []
 
- // UPSTREAM: Ideally, path metadata would be unnecessary and contained inside the blueprint.
- const pathMetadata = 'pathMetadata' in metadata ? metadata.pathMetadata : {}
-
  const typesModule = TypesModuleSchema.parse({
  ...types,
  codeSampleDefinitions,
  })
 
  const blueprint = await createBlueprint(typesModule, { formatCode })
- Object.assign(metadata, { ...blueprint, pathMetadata })
+ Object.assign(metadata, blueprint)
 }

src/lib/layout-context.ts

@@ -7,7 +7,7 @@ import type {
 } from '@seamapi/blueprint'
 import { pascalCase } from 'change-case'
 
-import type { PathMetadata } from './reference.js'
+import type { PathMetadata } from './path-metadata.js'
 
 const supportedSdks: CodeSampleSdk[] = [
  'javascript',
@@ -21,6 +21,10 @@ export interface EndpointLayoutContext {
  description: string
  title: string
  path: string
+ page: {
+ title: string
+ description: string
+ }
  request: {
  preferredMethod: string
  parameters: Array<{
@@ -54,10 +58,16 @@ export interface EndpointLayoutContext {
 export function setEndpointLayoutContext(
  file: Partial<EndpointLayoutContext>,
  endpoint: Endpoint,
+ pathMetadata: PathMetadata,
 ): void {
  file.description = endpoint.description
  file.title = endpoint.title
  file.path = endpoint.path
+ const page = pathMetadata[endpoint.path]?.page
+ if (page == null) {
+ throw new Error(`Missing page metadata for ${endpoint.path}`)
+ }
+ file.page = page
 
  file.request = {
  preferredMethod: endpoint.request?.preferredMethod ?? '',
@@ -115,7 +125,12 @@ interface ContextResource {
 type ContextEndpoint = Pick<Endpoint, 'path' | 'description'>
 
 export interface RouteLayoutContext {
- description: string | null
+ page: {
+ title: string
+ description: string
+ }
+ description: string
+ path: string
  resources: ContextResource[]
  endpoints: ContextEndpoint[]
 }
@@ -126,7 +141,12 @@ export function setApiRouteLayoutContext(
  blueprint: Blueprint,
  pathMetadata: PathMetadata,
 ): void {
- file.description = pathMetadata[route.path]?.description ?? null
+ const page = pathMetadata[route.path]?.page
+ if (page == null) {
+ throw new Error(`Missing page metadata for ${route.path}`)
+ }
+ file.page = page
+ file.path = route.path
  file.endpoints = route.endpoints.map(({ path, name, description }) => ({
  path,
  name,

src/lib/path-metadata.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+export const PathMetadataSchema = z.record(
+ z.string(),
+ z.object({
+ page: z.object({
+ title: z.string().trim().min(1),
+ description: z.string().trim().min(1),
+ }),
+ }),
+)
+
+export type PathMetadata = z.infer<typeof PathMetadataSchema>

src/lib/reference.ts

@@ -7,26 +7,25 @@ import {
  setApiRouteLayoutContext,
  setEndpointLayoutContext,
 } from './layout-context.js'
+import { PathMetadataSchema } from './path-metadata.js'
 
 const sdks: Array<'javascript'> = []
 
 type Metadata = Partial<Pick<Blueprint, 'routes' | 'resources'>>
 
 type File = EndpointLayoutContext & RouteLayoutContext & { layout: string }
 
-export type PathMetadata = Record<
- string,
- {
- description?: string | null
- }
->
-
 export const reference = (
  files: Metalsmith.Files,
  metalsmith: Metalsmith,
 ): void => {
- const { pathMetadata = {}, ...metadata } =
- metalsmith.metadata() as Metadata & { pathMetadata: PathMetadata }
+ const metadata = metalsmith.metadata() as Metadata
+
+ // UPSTREAM: Ideally, path metadata would be unnecessary and contained inside the blueprint.
+ const pathMetadata =
+ 'pathMetadata' in metadata
+ ? PathMetadataSchema.parse(metadata.pathMetadata)
+ : {}
 
  const blueprint = {
  title: '',
@@ -59,7 +58,7 @@ export const reference = (
  }
  const file = files[k] as unknown as File
  file.layout = 'api-endpoint.hbs'
- setEndpointLayoutContext(file, endpoint)
+ setEndpointLayoutContext(file, endpoint, pathMetadata)
 
  for (const sdk of sdks) {
  const k = `sdk/${sdk}${endpoint.path}.md`
@@ -68,7 +67,7 @@ export const reference = (
  }
  const file = files[k] as unknown as File
  file.layout = 'sdk-reference.hbs'
- setEndpointLayoutContext(file, endpoint)
+ setEndpointLayoutContext(file, endpoint, pathMetadata)
  }
  }
  }