feat: Allow access to undocumented API (#349)

* Generate undocumented endpoints

* Add isUndocumented to context

* Add isUndocumentedApiEnabled option

* ci: Generate code

* Add test for undocumented flag

* Fix isUndocumentedApiEnabled generation

* ci: Generate code

---------

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

Author: razor-x

README.md

@@ -524,6 +524,19 @@ const seam = new SeamHttpEndpoints()
 const devices = await seam['/devices/list']()
 ```
 
+#### Enable undocumented API
+
+Pass the `isUndocumentedApiEnabled` option to allow using the undocumented API.
+This API is used internally and is not directly supported.
+Do not use the undocumented API in production environments.
+Seam is not responsible for any issues you may encounter with the undocumented API.
+
+```ts
+import { SeamHttp } from '@seamapi/http/connect'
+
+const seam = new SeamHttp({ isUndocumentedApiEnabled: true })
+```
+
 #### Inspecting the Request
 
 All client methods return an instance of `SeamHttpRequest`.

codegen/layouts/endpoints.hbs

@@ -21,6 +21,11 @@ export class SeamHttpEndpoints {
   get['{{path}}'](): {{className}}['{{methodName}}']
   {
   const { client, defaults } = this
+  {{#if isUndocumented}}
+  if (!this.defaults.isUndocumentedApiEnabled) {
+    throw new Error('Cannot use undocumented API without isUndocumentedApiEnabled')
+  }
+  {{/if}}
   return function {{functionName}} (...args: Parameters<{{className}}['{{methodName}}']>): ReturnType<{{className}}['{{methodName}}']>
     {
       const seam = {{className}}.fromClient(client, defaults)

codegen/layouts/partials/route-class-endpoint.hbs

@@ -3,6 +3,11 @@
   {{#if hasOptions}}options: {{optionsTypeName}} = {},{{/if}}
   ): SeamHttpRequest<{{#if returnsVoid}}void, undefined{{else}}{{responseTypeName}}, '{{responseKey}}'{{/if}}>
 {
+  {{#if isUndocumented}}
+  if (!this.defaults.isUndocumentedApiEnabled) {
+    throw new Error('Cannot use undocumented API without isUndocumentedApiEnabled')
+  }
+  {{/if}}
   return new SeamHttpRequest(this, {
     pathname: '{{path}}',
     method: '{{method}}',

codegen/layouts/partials/route-class-methods.hbs

@@ -5,6 +5,11 @@ static ltsVersion = seamApiLtsVersion
 
 constructor(apiKeyOrOptions: string | SeamHttpOptions = {}) {
   const options = parseOptions(apiKeyOrOptions)
+  {{#if isUndocumented}}
+  if (!options.isUndocumentedApiEnabled) {
+    throw new Error('Cannot use undocumented API without isUndocumentedApiEnabled')
+  }
+  {{/if}}
   this.client = 'client' in options ? options.client : createClient(options)
   this.defaults = limitToSeamHttpRequestOptions(options)
 }

codegen/lib/connect.ts

@@ -28,14 +28,9 @@ export const connect = (
   metalsmith: Metalsmith,
 ): void => {
   const metadata = metalsmith.metadata() as Metadata
-  const { blueprint } = metadata
-
-  const namespaces = blueprint.namespaces.filter(
-    ({ isUndocumented }) => !isUndocumented,
-  )
-  const routes = blueprint.routes.filter(
-    ({ isUndocumented }) => !isUndocumented,
-  )
+  const {
+    blueprint: { namespaces, routes },
+  } = metadata
 
   const nodes = [...namespaces, ...routes]
 

codegen/lib/layouts/endpoints.ts

@@ -22,9 +22,9 @@ export const setEndpointsLayoutContext = (
   file.className = getClassName('Endpoints')
   file.skipClientSessionImport = true
   file.endpoints = routes.flatMap((route) =>
-    route.endpoints
-      .filter(({ isUndocumented }) => !isUndocumented)
-      .map((endpoint) => getEndpointLayoutContext(endpoint, route)),
+    route.endpoints.map((endpoint) =>
+      getEndpointLayoutContext(endpoint, route),
+    ),
   )
   file.routeImports = routes.map((route) => {
     return {

codegen/lib/layouts/route.ts

@@ -4,6 +4,7 @@ import { camelCase, kebabCase, pascalCase } from 'change-case'
 
 export interface RouteLayoutContext {
   className: string
+  isUndocumented: boolean
   endpoints: EndpointLayoutContext[]
   subroutes: SubrouteLayoutContext[]
   skipClientSessionImport: boolean
@@ -30,6 +31,7 @@ export interface EndpointLayoutContext {
   returnsActionAttempt: boolean
   returnsVoid: boolean
   isOptionalParamsOk: boolean
+  isUndocumented: boolean
 }
 
 export interface SubrouteLayoutContext {
@@ -44,15 +46,13 @@ export const setRouteLayoutContext = (
   nodes: Array<Route | Namespace>,
 ): void => {
   file.className = getClassName(node?.path ?? null)
+  file.isUndocumented = node?.isUndocumented ?? false
   file.skipClientSessionImport =
     node == null || node?.path === '/client_sessions'
 
   file.endpoints = []
   if (node != null && 'endpoints' in node) {
-    const endpoints = node.endpoints.filter(
-      ({ isUndocumented }) => !isUndocumented,
-    )
-    file.endpoints = endpoints.map((endpoint) =>
+    file.endpoints = node.endpoints.map((endpoint) =>
       getEndpointLayoutContext(endpoint, node),
     )
   }
@@ -64,7 +64,7 @@ export const setRouteLayoutContext = (
 }
 
 const getSubrouteLayoutContext = (
-  route: Pick<Route, 'path' | 'name'>,
+  route: Pick<Route, 'path' | 'name' | 'isUndocumented'>,
 ): SubrouteLayoutContext => {
   return {
     fileName: `${kebabCase(route.name)}/index.js`,
@@ -116,6 +116,7 @@ export const getEndpointLayoutContext = (
     // UPSTREAM: Needs support in blueprint, fallback to true for now.
     // https://github.com/seamapi/blueprint/issues/205
     isOptionalParamsOk: true,
+    isUndocumented: endpoint.isUndocumented,
     ...getResponseContext(endpoint),
   }
 }

src/lib/seam/connect/options.ts

@@ -22,6 +22,7 @@ interface SeamHttpCommonOptions extends ClientOptions, SeamHttpRequestOptions {
 
 export interface SeamHttpRequestOptions {
   waitForActionAttempt?: boolean | ResolveActionAttemptOptions
+  isUndocumentedApiEnabled?: boolean
 }
 
 export interface SeamHttpFromPublishableKeyOptions
@@ -33,7 +34,7 @@ export interface SeamHttpMultiWorkspaceOptionsFromEnv
   extends SeamHttpCommonOptions {}
 
 export interface SeamHttpMultiWorkspaceOptionsWithClient
-  extends SeamHttpRequestOptions {
+  extends SeamHttpCommonOptions {
   client: Client
 }
 

src/lib/seam/connect/parse-options.ts

@@ -64,6 +64,7 @@ const getNormalizedOptions = (
       : apiKeyOrOptions
 
   const requestOptions = {
+    isUndocumentedApiEnabled: options.isUndocumentedApiEnabled ?? false,
     waitForActionAttempt: options.waitForActionAttempt ?? true,
   }
 
@@ -181,6 +182,7 @@ export const isSeamHttpRequestOption = (
   key: string,
 ): key is keyof SeamHttpRequestOptions => {
   const keys: Record<keyof SeamHttpRequestOptions, true> = {
+    isUndocumentedApiEnabled: true,
     waitForActionAttempt: true,
   }
   return Object.keys(keys).includes(key)