feat: Add SeamHttpEndpoints (#347)

* feat: Generate SeamHttpEndpoints

* Use TS util types

* ci: Generate code

* Add section to README

* Add test for SeamHttpEndpoints

---------

Co-authored-by: Seam Bot <seambot@getseam.com>

Author: razor-x

README.md

@@ -512,6 +512,18 @@ const devices = await seam.client.get<DevicesListResponse>('/devices/list')
 An Axios compatible client may be provided to create a `SeamHttp` instance.
 This API is used internally and is not directly supported.
 
+#### Alternative endpoint path interface
+
+The `SeamHttpEndpoints` class offers an alternative path-based interface to every API endpoint.
+Each endpoint is exposed as simple property that returns the corresponding method from `SeamHttp`.
+
+```ts
+import { SeamHttpEndpoints } from '@seamapi/http/connect'
+
+const seam = new SeamHttpEndpoints()
+const devices = await seam['/devices/list']()
+```
+
 #### Inspecting the Request
 
 All client methods return an instance of `SeamHttpRequest`.

codegen/layouts/endpoints.hbs

@@ -0,0 +1,32 @@
+/*
+ * Automatically generated by codegen/smith.ts.
+ * Do not edit this file or add other files to this directory.
+ */
+
+{{> route-imports }}
+
+{{#each routeImports}}
+import {
+{{className}},
+{{#each typeNames}}
+  type {{.}},
+{{/each}}
+} from './{{fileName}}'
+{{/each}}
+
+export class SeamHttpEndpoints {
+  {{> route-class-methods }}
+
+  {{#each endpoints}}
+  get['{{path}}'](): {{className}}['{{methodName}}']
+  {
+  const { client, defaults } = this
+  return function {{functionName}} (...args: Parameters<{{className}}['{{methodName}}']>): ReturnType<{{className}}['{{methodName}}']>
+    {
+      const seam = {{className}}.fromClient(client, defaults)
+      return seam.{{methodName}}(...args)
+    }
+  }
+
+  {{/each}}
+}

codegen/lib/connect.ts

@@ -2,17 +2,24 @@ import type { Blueprint } from '@seamapi/blueprint'
 import { kebabCase } from 'change-case'
 import type Metalsmith from 'metalsmith'
 
+import {
+  type EndpointsLayoutContext,
+  setEndpointsLayoutContext,
+} from './layouts/endpoints.js'
 import {
   type RouteIndexLayoutContext,
   type RouteLayoutContext,
   setRouteLayoutContext,
+  toFilePath,
 } from './layouts/route.js'
 
 interface Metadata {
   blueprint: Blueprint
 }
 
-type File = RouteLayoutContext & RouteIndexLayoutContext & { layout: string }
+type File = RouteLayoutContext &
+  RouteIndexLayoutContext &
+  EndpointsLayoutContext & { layout: string }
 
 const rootPath = 'src/lib/seam/connect/routes'
 
@@ -34,15 +41,22 @@ export const connect = (
 
   const routeIndexes: Record<string, Set<string>> = {}
 
-  const rootRouteKey = `${rootPath}/seam-http.ts`
-  files[rootRouteKey] = { contents: Buffer.from('\n') }
-  const file = files[rootRouteKey] as unknown as File
+  const k = `${rootPath}/seam-http.ts`
+  files[k] = { contents: Buffer.from('\n') }
+  const file = files[k] as unknown as File
   file.layout = 'route.hbs'
   setRouteLayoutContext(file, null, nodes)
 
   routeIndexes[''] ??= new Set()
   routeIndexes['']?.add('seam-http.js')
 
+  const endpointsKey = `${rootPath}/seam-http-endpoints.ts`
+  files[endpointsKey] = { contents: Buffer.from('\n') }
+  const endpointFile = files[endpointsKey] as unknown as File
+  endpointFile.layout = 'endpoints.hbs'
+  setEndpointsLayoutContext(endpointFile, routes)
+  routeIndexes['']?.add('seam-http-endpoints.js')
+
   for (const node of nodes) {
     const path = toFilePath(node.path)
     const name = kebabCase(node.name)
@@ -75,10 +89,3 @@ export const connect = (
     file.routes = [...routes]
   }
 }
-
-const toFilePath = (path: string): string =>
-  path
-    .slice(1)
-    .split('/')
-    .map((p) => kebabCase(p))
-    .join('/')

codegen/lib/layouts/endpoints.ts

@@ -0,0 +1,35 @@
+import type { Route } from '@seamapi/blueprint'
+
+import {
+  type EndpointLayoutContext,
+  getClassName,
+  getEndpointLayoutContext,
+  type SubrouteLayoutContext,
+  toFilePath,
+} from './route.js'
+
+export interface EndpointsLayoutContext {
+  className: string
+  endpoints: EndpointLayoutContext[]
+  routeImports: Array<Pick<SubrouteLayoutContext, 'className' | 'fileName'>>
+  skipClientSessionImport: boolean
+}
+
+export const setEndpointsLayoutContext = (
+  file: Partial<EndpointsLayoutContext>,
+  routes: Route[],
+): void => {
+  file.className = getClassName('Endpoints')
+  file.skipClientSessionImport = true
+  file.endpoints = routes.flatMap((route) =>
+    route.endpoints
+      .filter(({ isUndocumented }) => !isUndocumented)
+      .map((endpoint) => getEndpointLayoutContext(endpoint, route)),
+  )
+  file.routeImports = routes.map((route) => {
+    return {
+      className: getClassName(route.path),
+      fileName: `${toFilePath(route.path)}/index.js`,
+    }
+  })
+}

codegen/lib/layouts/route.ts

@@ -13,9 +13,11 @@ export interface RouteIndexLayoutContext {
   routes: string[]
 }
 
-interface EndpointLayoutContext {
+export interface EndpointLayoutContext {
   path: string
   methodName: string
+  functionName: string
+  className: string
   method: Method
   hasOptions: boolean
   responseKey: string
@@ -30,7 +32,7 @@ interface EndpointLayoutContext {
   isOptionalParamsOk: boolean
 }
 
-interface SubrouteLayoutContext {
+export interface SubrouteLayoutContext {
   methodName: string
   className: string
   fileName: string
@@ -71,7 +73,7 @@ const getSubrouteLayoutContext = (
   }
 }
 
-const getEndpointLayoutContext = (
+export const getEndpointLayoutContext = (
   endpoint: Endpoint,
   route: Pick<Route, 'path' | 'name'>,
 ): EndpointLayoutContext => {
@@ -95,11 +97,15 @@ const getEndpointLayoutContext = (
     endpoint.response.responseType === 'resource' &&
     endpoint.response.resourceType === 'action_attempt'
 
+  const methodName = camelCase(endpoint.name)
+
   return {
     path: endpoint.path,
-    methodName: camelCase(endpoint.name),
+    methodName,
+    functionName: camelCase(prefix),
     method: endpoint.request.preferredMethod,
     hasOptions: returnsActionAttempt,
+    className: getClassName(route.path),
     methodParamName,
     requestFormat,
     requestFormatSuffix,
@@ -129,5 +135,12 @@ const getResponseContext = (
   }
 }
 
-const getClassName = (name: string | null): string =>
-  `SeamHttp${pascalCase(name ?? '')}`
+export const getClassName = (path: string | null): string =>
+  `SeamHttp${pascalCase(path ?? '')}`
+
+export const toFilePath = (path: string): string =>
+  path
+    .slice(1)
+    .split('/')
+    .map((p) => kebabCase(p))
+    .join('/')