Merge pull request #355 from seamapi/evan/cx-411-generate-seamhttpwithoutworkspaceendpoints

Add SeamHttpEndpointsWithoutWorkspace

Author: razor-x

README.md

@@ -397,10 +397,10 @@ const pages = seam.createPaginator(
 const devices = await pages.flattenToArray()
 ```
 
-### Interacting with Multiple Workspaces
+### Requests without a Workspace in scope
 
-Some Seam API endpoints interact with multiple workspaces.
-The `SeamHttpMultiWorkspace` client is not bound to a specific workspace
+Some Seam API endpoints do not require a workspace in scope.
+The `SeamHttpWithoutWorkspace` client is not bound to a specific workspace
 and may use those endpoints with an appropriate authentication method.
 
 #### Personal Access Token
@@ -410,15 +410,15 @@ Obtain one from the Seam Console.
 
 ```ts
 // Set the `SEAM_PERSONAL_ACCESS_TOKEN` environment variable
-const seam = new SeamHttpMultiWorkspace()
+const seam = new SeamHttpWithoutWorkspace()
 
 // Pass as an option to the constructor
-const seam = new SeamHttpMultiWorkspace({
+const seam = new SeamHttpWithoutWorkspace({
   personalAccessToken: 'your-personal-access-token',
 })
 
 // Use the factory method
-const seam = SeamHttpMultiWorkspace.fromPersonalAccessToken(
+const seam = SeamHttpWithoutWorkspace.fromPersonalAccessToken(
   'some-console-session-token',
 )
 
@@ -433,12 +433,12 @@ This authentication method is only used by internal Seam applications.
 
 ```ts
 // Pass as an option to the constructor
-const seam = new SeamHttpMultiWorkspace({
+const seam = new SeamHttpWithoutWorkspace({
   consoleSessionToken: 'some-console-session-token',
 })
 
 // Use the factory method
-const seam = SeamHttpMultiWorkspace.fromConsoleSessionToken(
+const seam = SeamHttpWithoutWorkspace.fromConsoleSessionToken(
   'some-console-session-token',
 )
 

codegen/layouts/endpoints.hbs

@@ -4,6 +4,7 @@
  */
 
 {{> route-imports }}
+{{> route-imports-without-workspace }}
 
 {{#each routeImports}}
 import {
@@ -14,8 +15,12 @@ import {
 } from './{{fileName}}'
 {{/each}}
 
-export class SeamHttpEndpoints {
+export class {{className}} {
+{{#if withoutWorkspace}}
+  {{> route-class-methods-without-workspace }}
+{{else}}
   {{> route-class-methods }}
+{{/if}}
 
   {{#each endpoints}}
   get['{{path}}'](): {{> endpont-method-signature isFnType=true }}
@@ -36,8 +41,14 @@ export class SeamHttpEndpoints {
   {{/each}}
 }
 
-export type SeamHttpEndpointQueryPaths = {{#each endpointReadPaths}}'{{.}}' {{#unless @last}} | {{/unless}}{{/each}}
+{{#if endpointReadPaths.length}}
+export type {{typeNamePrefix}}QueryPaths = {{#each endpointReadPaths}}'{{.}}' {{#unless @last}} | {{/unless}}{{/each}}
+{{/if}}
 
-export type SeamHttpEndpointPaginatedQueryPaths = {{#each endpointPaginatedPaths}}'{{.}}' {{#unless @last}} | {{/unless}}{{/each}}
+{{#if endpointPaginatedPaths.length}}
+export type {{typeNamePrefix}}PaginatedQueryPaths = {{#each endpointPaginatedPaths}}'{{.}}' {{#unless @last}} | {{/unless}}{{/each}}
+{{/if}}
 
-export type SeamHttpEndpointMutationPaths = {{#each endpointWritePaths}}'{{.}}' {{#unless @last}} | {{/unless}}{{/each}}
+{{#if endpointWritePaths.length}}
+export type {{typeNamePrefix}}MutationPaths = {{#each endpointWritePaths}}'{{.}}' {{#unless @last}} | {{/unless}}{{/each}}
+{{/if}}

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

@@ -0,0 +1,61 @@
+client: Client
+readonly defaults: Required<SeamHttpRequestOptions>
+readonly ltsVersion = seamApiLtsVersion
+static ltsVersion = seamApiLtsVersion
+
+constructor(options: SeamHttpWithoutWorkspaceOptions = {}) {
+  const opts = parseOptions(options)
+  this.client = 'client' in opts ? opts.client : createClient(opts)
+  this.defaults = limitToSeamHttpRequestOptions(opts)
+}
+
+static fromClient(
+  client: SeamHttpWithoutWorkspaceOptionsWithClient['client'],
+  options: Omit<SeamHttpWithoutWorkspaceOptionsWithClient, 'client'> = {},
+): {{className}}{
+  const constructorOptions = { ...options, client }
+  if (!isSeamHttpWithoutWorkspaceOptionsWithClient(constructorOptions)) {
+    throw new SeamHttpWithoutWorkspaceInvalidOptionsError('Missing client')
+  }
+  return new {{className}}(constructorOptions)
+}
+
+static fromConsoleSessionToken(
+  consoleSessionToken: SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken['consoleSessionToken'],
+  options: Omit<
+    SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken,
+    'consoleSessionToken'
+  > = {},
+): {{className}}{
+  const constructorOptions = { ...options, consoleSessionToken }
+  if (
+    !isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken(
+      constructorOptions,
+    )
+  ) {
+    throw new SeamHttpWithoutWorkspaceInvalidOptionsError(
+      'Missing consoleSessionToken',
+    )
+  }
+  return new {{className}}(constructorOptions)
+}
+
+static fromPersonalAccessToken(
+  personalAccessToken: SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken['personalAccessToken'],
+  options: Omit<
+    SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken,
+    'personalAccessToken'
+  > = {},
+): {{className}}{
+  const constructorOptions = { ...options, personalAccessToken }
+  if (
+    !isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken(
+      constructorOptions,
+    )
+  ) {
+    throw new SeamHttpWithoutWorkspaceInvalidOptionsError(
+      'Missing personalAccessToken',
+    )
+  }
+  return new {{className}}(constructorOptions)
+}

codegen/layouts/partials/route-imports-without-workspace.hbs

@@ -0,0 +1,14 @@
+import { seamApiLtsVersion } from 'lib/lts-version.js'
+import { type Client, createClient } from 'lib/seam/connect/client.js'
+import {
+  isSeamHttpWithoutWorkspaceOptionsWithClient,
+  isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken,
+  isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken,
+  type SeamHttpRequestOptions,
+  SeamHttpWithoutWorkspaceInvalidOptionsError,
+  type SeamHttpWithoutWorkspaceOptions,
+  type SeamHttpWithoutWorkspaceOptionsWithClient,
+  type SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken,
+  type SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken,
+} from 'lib/seam/connect/options.js'
+import { limitToSeamHttpRequestOptions, parseOptions } from 'lib/seam/connect/parse-options.js'

codegen/layouts/without-workspace.hbs

@@ -0,0 +1,21 @@
+/*
+ * Automatically generated by codegen/smith.ts.
+ * Do not edit this file or add other files to this directory.
+ */
+
+{{> route-imports-without-workspace }}
+
+import { SeamHttpWorkspaces } from 'lib/seam/connect/routes/workspaces/index.js'
+
+export class SeamHttpWithoutWorkspace {
+  {{> route-class-methods-without-workspace }}
+
+  get workspaces(): Pick<SeamHttpWorkspaces, 'create' | 'list'> {
+    return SeamHttpWorkspaces.fromClient(this.client, this.defaults)
+  }
+}
+
+/**
+ * @deprecated Use SeamHttpWithoutWorkspace instead.
+ */
+export const SeamHttpMultiWorkspace = SeamHttpWithoutWorkspace

codegen/lib/connect.ts

@@ -72,6 +72,24 @@ export const connect = (
   setEndpointsLayoutContext(endpointFile, routes)
   routeIndexes['']?.add('seam-http-endpoints.js')
 
+  const withoutWorkspaceKey = `${rootPath}/seam-http-without-workspace.ts`
+  files[withoutWorkspaceKey] = { contents: Buffer.from('\n') }
+  const withoutWorkspaceFile = files[withoutWorkspaceKey] as unknown as File
+  withoutWorkspaceFile.layout = 'without-workspace.hbs'
+  withoutWorkspaceFile.className = 'SeamHttpWithoutWorkspace'
+  routeIndexes['']?.add('seam-http-without-workspace.js')
+
+  const endpointsWithoutWorkspaceKey = `${rootPath}/seam-http-endpoints-without-workspace.ts`
+  files[endpointsWithoutWorkspaceKey] = { contents: Buffer.from('\n') }
+  const endpointWithoutWorkspaceFile = files[
+    endpointsWithoutWorkspaceKey
+  ] as unknown as File
+  endpointWithoutWorkspaceFile.layout = 'endpoints.hbs'
+  setEndpointsLayoutContext(endpointWithoutWorkspaceFile, routes, {
+    withoutWorkspace: true,
+  })
+  routeIndexes['']?.add('seam-http-endpoints-without-workspace.js')
+
   for (const node of nodes) {
     const path = toFilePath(node.path)
     const name = kebabCase(node.name)

codegen/lib/layouts/endpoints.ts

@@ -1,4 +1,4 @@
-import type { Route } from '@seamapi/blueprint'
+import type { Endpoint, Route } from '@seamapi/blueprint'
 
 import {
   type EndpointLayoutContext,
@@ -9,6 +9,8 @@ import {
 
 export interface EndpointsLayoutContext {
   className: string
+  typeNamePrefix: string
+  withoutWorkspace: boolean
   endpoints: EndpointLayoutContext[]
   endpointReadPaths: string[]
   endpointPaginatedPaths: string[]
@@ -26,21 +28,33 @@ interface RouteImportLayoutContext {
 export const setEndpointsLayoutContext = (
   file: Partial<EndpointsLayoutContext>,
   routes: Route[],
+  { withoutWorkspace = false }: { withoutWorkspace?: boolean } = {},
 ): void => {
-  file.className = getClassName('Endpoints')
+  const endpointFilter = (endpoint: Endpoint): boolean =>
+    withoutWorkspace ? endpoint.workspaceScope !== 'required' : true
+
+  file.withoutWorkspace = withoutWorkspace
+  file.className = getClassName(
+    `Endpoints${withoutWorkspace ? 'WithoutWorkspace' : ''}`,
+  )
+  file.typeNamePrefix = getClassName(
+    `Endpoint${withoutWorkspace ? 'WithoutWorkspace' : ''}`,
+  )
   file.skipClientSessionImport = true
   file.endpoints = routes.flatMap((route) =>
-    route.endpoints.map((endpoint) =>
-      getEndpointLayoutContext(endpoint, route),
-    ),
+    route.endpoints
+      .filter(endpointFilter)
+      .map((endpoint) => getEndpointLayoutContext(endpoint, route)),
   )
   file.endpointReadPaths = routes.flatMap((route) =>
     route.endpoints
+      .filter(endpointFilter)
       .filter(({ request }) => request.semanticMethod === 'GET')
       .map(({ path }) => path),
   )
   file.endpointPaginatedPaths = routes.flatMap((route) =>
     route.endpoints
+      .filter(endpointFilter)
       .filter(
         ({ request, hasPagination }) =>
           request.semanticMethod === 'GET' && hasPagination,
@@ -49,21 +63,25 @@ export const setEndpointsLayoutContext = (
   )
   file.endpointWritePaths = routes.flatMap((route) =>
     route.endpoints
+      .filter(endpointFilter)
       .filter(({ request }) => request.semanticMethod !== 'GET')
       .map(({ path }) => path),
   )
-  file.routeImports = routes.map((route) => {
-    const endpoints = route.endpoints.map((endpoint) =>
-      getEndpointLayoutContext(endpoint, route),
-    )
-    return {
-      className: getClassName(route.path),
-      fileName: `${toFilePath(route.path)}/index.js`,
-      typeNames: endpoints.flatMap((endpoint) => [
-        endpoint.parametersTypeName,
-        endpoint.optionsTypeName,
-        endpoint.requestTypeName,
-      ]),
-    }
-  })
+  file.routeImports = routes
+    .filter((route) => route.endpoints.some(endpointFilter))
+    .map((route) => {
+      const endpoints = route.endpoints
+        .filter(endpointFilter)
+        .map((endpoint) => getEndpointLayoutContext(endpoint, route))
+
+      return {
+        className: getClassName(route.path),
+        fileName: `${toFilePath(route.path)}/index.js`,
+        typeNames: endpoints.flatMap((endpoint) => [
+          endpoint.parametersTypeName,
+          endpoint.optionsTypeName,
+          endpoint.requestTypeName,
+        ]),
+      }
+    })
 }

package-lock.json

@@ -98,7 +98,7 @@
     "axios-retry": "^4.4.2"
   },
   "devDependencies": {
-    "@seamapi/blueprint": "^0.51.0",
+    "@seamapi/blueprint": "^0.51.1",
     "@seamapi/fake-seam-connect": "^1.77.0",
     "@seamapi/smith": "^0.4.4",
     "@seamapi/types": "1.420.2",

package.json

@@ -1,17 +1,17 @@
 import {
-  isSeamHttpMultiWorkspaceOptionsWithConsoleSessionToken,
-  isSeamHttpMultiWorkspaceOptionsWithPersonalAccessToken,
   isSeamHttpOptionsWithApiKey,
   isSeamHttpOptionsWithClientSessionToken,
   isSeamHttpOptionsWithConsoleSessionToken,
   isSeamHttpOptionsWithPersonalAccessToken,
+  isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken,
+  isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken,
   SeamHttpInvalidOptionsError,
-  type SeamHttpMultiWorkspaceOptionsWithConsoleSessionToken,
-  type SeamHttpMultiWorkspaceOptionsWithPersonalAccessToken,
   type SeamHttpOptionsWithApiKey,
   type SeamHttpOptionsWithClientSessionToken,
   type SeamHttpOptionsWithConsoleSessionToken,
   type SeamHttpOptionsWithPersonalAccessToken,
+  type SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken,
+  type SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken,
 } from './options.js'
 import type { Options } from './parse-options.js'
 import {
@@ -43,14 +43,14 @@ export const getAuthHeaders = (options: Options): Headers => {
   }
 
   if (
-    isSeamHttpMultiWorkspaceOptionsWithConsoleSessionToken(options) ||
+    isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken(options) ||
     isSeamHttpOptionsWithConsoleSessionToken(options)
   ) {
     return getAuthHeadersForConsoleSessionToken(options)
   }
 
   if (
-    isSeamHttpMultiWorkspaceOptionsWithPersonalAccessToken(options) ||
+    isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken(options) ||
     isSeamHttpOptionsWithPersonalAccessToken(options)
   ) {
     return getAuthHeadersForPersonalAccessToken(options)
@@ -142,7 +142,7 @@ const getAuthHeadersForConsoleSessionToken = ({
   consoleSessionToken,
   ...options
 }:
-  | SeamHttpMultiWorkspaceOptionsWithConsoleSessionToken
+  | SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken
   | SeamHttpOptionsWithConsoleSessionToken): Headers => {
   const workspaceId = 'workspaceId' in options ? options.workspaceId : undefined
 
@@ -180,7 +180,7 @@ const getAuthHeadersForPersonalAccessToken = ({
   personalAccessToken,
   ...options
 }:
-  | SeamHttpMultiWorkspaceOptionsWithPersonalAccessToken
+  | SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken
   | SeamHttpOptionsWithPersonalAccessToken): Headers => {
   const workspaceId = 'workspaceId' in options ? options.workspaceId : undefined