feat: Add descriptions and deprecations to SDK

.gitattributes

@@ -1 +1,2 @@
+src/lib/seam/connect/resources/** linguist-generated
 src/lib/seam/connect/routes/** linguist-generated

codegen/layouts/endpoints.hbs

@@ -23,6 +23,7 @@ export class {{className}} {
 {{/if}}
 
   {{#each endpoints}}
+  {{> doc}}
   get['{{path}}'](): {{> endpont-method-signature isFnType=true }}
   {
   const { client, defaults } = this

codegen/layouts/partials/doc.hbs

@@ -0,0 +1,12 @@
+{{#if (or (trim description) isDeprecated)}}
+/**
+{{#each (lines description)}}
+ * {{replaceAll this "*/" "*\/"}}
+{{/each}}
+{{#if isDeprecated}}
+ * @deprecated{{#with (trim deprecationMessage)}} {{replaceAll this "*/" "*\/"}}{{/with}}
+{{/if}}
+ */
+{{else}}
+{{identity " "}}
+{{/if}}

codegen/layouts/partials/request-list-item-type.hbs

@@ -1,7 +1,8 @@
 {{#if (eq itemFormat "object")}}
 {{> request-object parameters=itemParameters}}
 {{else if (eq itemFormat "discriminated_object")}}
-{{#each variants}}{{#unless @first}} | {{/unless}}{{> request-object parameters=parameters}}{{/each}}
+{{#each variants}}{{#unless @first}} | {{/unless}}{{> doc~}}
+{{> request-object parameters=parameters}}{{/each}}
 {{else}}
 {{> request-scalar-type format=itemFormat values=itemEnumValues}}
 {{/if}}

codegen/layouts/partials/request-object.hbs

@@ -1,5 +1,6 @@
 {
 {{#each parameters}}
+  {{> doc}}
   {{json name}}{{#unless isRequired}}?{{/unless}}: {{> request-parameter-type }}{{#unless isRequired}} | undefined{{/unless}}
 {{/each}}
 }

codegen/layouts/partials/request-scalar-type.hbs

@@ -1 +1,2 @@
-{{#if (eq format "boolean")}}boolean{{else if (eq format "number")}}number{{else if (eq format "record")}}Record<string, unknown>{{else if (eq format "enum")}}{{#each values}}{{#unless @first}} | {{/unless}}{{json name}}{{else}}string{{/each}}{{else}}string{{/if}}
+{{#if (eq format "boolean")}}boolean{{else if (eq format "number")}}number{{else if (eq format "record")}}Record<string, unknown>{{else if (eq format "enum")}}{{#each values}}{{#unless @first}} | {{/unless}}{{> doc}}
+{{json name}}{{else}}string{{/each}}{{else}}string{{/if}}

codegen/layouts/partials/resource-list-item-type.hbs

@@ -1,7 +1,8 @@
 {{#if (eq itemFormat "object")}}
 {{> resource-object properties=itemProperties}}
 {{else if (eq itemFormat "discriminated_object")}}
-{{#each variants}}{{#unless @first}} | {{/unless}}{{> resource-object properties=properties}}{{/each}}
+{{#each variants}}{{#unless @first}} | {{/unless}}{{> doc~}}
+{{> resource-object properties=properties}}{{/each}}
 {{else}}
 {{> resource-scalar-type format=itemFormat values=itemEnumValues}}
 {{/if}}

codegen/layouts/partials/resource-object.hbs

@@ -1,5 +1,6 @@
 {
 {{#each properties}}
+  {{> doc}}
   {{json name}}{{#if isOptional}}?{{/if}}: {{> resource-property-type }}{{#if isNullable}} | null{{/if}}{{#if isOptional}} | undefined{{/if}}
 {{/each}}
 }

codegen/layouts/partials/resource-scalar-type.hbs

@@ -1 +1,2 @@
-{{#if (eq format "boolean")}}boolean{{else if (eq format "number")}}number{{else if (eq format "record")}}Record<string, unknown>{{else if (eq format "enum")}}{{#each values}}{{#unless @first}} | {{/unless}}{{json name}}{{else}}string{{/each}}{{else}}string{{/if}}
+{{#if (eq format "boolean")}}boolean{{else if (eq format "number")}}number{{else if (eq format "record")}}Record<string, unknown>{{else if (eq format "enum")}}{{#each values}}{{#unless @first}} | {{/unless}}{{> doc}}
+{{json name}}{{else}}string{{/each}}{{else}}string{{/if}}

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

@@ -1,3 +1,4 @@
+{{> doc}}
 {{methodName}}
 {{> endpont-method-signature }}
 {

codegen/layouts/resource.hbs

@@ -14,9 +14,11 @@ interface BatchResourceMap {
 {{/each}}
 }
 
+{{> doc resources.[0]}}
 export type {{typeName}}<TKey extends keyof BatchResourceMap = keyof BatchResourceMap> = {
   [K in TKey]?: Array<BatchResourceMap[K]> | undefined
 }
 {{else}}
+{{> doc resources.[0]}}
 export type {{typeName}} = {{#each resources}}{{#unless @first}} | {{/unless}}{{> resource-object properties=properties}}{{/each}}
 {{/if}}

codegen/lib/handlebars-helpers.ts

@@ -4,3 +4,16 @@ export const json = (value: string): string => JSON.stringify(value)
 
 export const replaceExtension = (fileName: string, extension: string): string =>
   fileName.replace(/\.[^.]+$/, extension)
+
+export const trim = (value = ''): string => value.trim()
+
+export const lines = (value = ''): string[] => {
+  const trimmed = trim(value)
+  return trimmed === '' ? [] : trimmed.split('\n')
+}
+
+export const replaceAll = (
+  value: string,
+  searchValue: string,
+  replaceValue: string,
+): string => value.replaceAll(searchValue, replaceValue)

codegen/lib/layouts/route.ts

@@ -17,6 +17,9 @@ export interface RouteIndexLayoutContext {
 }
 
 export interface EndpointLayoutContext {
+  description: string
+  isDeprecated: boolean
+  deprecationMessage: string
   path: string
   methodName: string
   functionName: string
@@ -119,6 +122,9 @@ export const getEndpointLayoutContext = (
   const methodName = camelCase(endpoint.name)
 
   return {
+    description: endpoint.description,
+    isDeprecated: endpoint.isDeprecated,
+    deprecationMessage: endpoint.deprecationMessage,
     path: endpoint.path,
     methodName,
     functionName: camelCase(prefix),