feat: Add descriptions and deprecations to SDK (#947)

* Add blueprint documentation to generated types

* ci: Generate code

* Use hbs for doc

* Mark resources generated in .gitattributes

* Fix bad deprecaions

* ci: Generate code

---------

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

Author: razor-x

.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 }}
 {