feat(corti-api): add templates and sections endpoints with versioning support

.fern/metadata.json

@@ -1,5 +1,5 @@
 {
-    "cliVersion": "4.86.1",
+    "cliVersion": "5.23.3",
     "generatorName": "fernapi/fern-typescript-node-sdk",
     "generatorVersion": "3.54.0",
     "generatorConfig": {
@@ -15,7 +15,9 @@
         },
         "packageJson": {
             "scripts": {
-                "test:integration": "vitest --config vitest.integration.config.mts"
+                "test:integration": "pnpm test:integration:main && pnpm test:integration:empty-state",
+                "test:integration:main": "vitest run --config vitest.integration.config.mts --project integration",
+                "test:integration:empty-state": "vitest run --config vitest.integration.config.mts --project integration-empty-state"
             },
             "exports": {
                 "./utils": {
@@ -32,6 +34,6 @@
             }
         }
     },
-    "originGitCommit": "23bce53307f0836f2dcd50e82ef0aba136e7ec2f",
+    "originGitCommit": "9fb3309768e7f09a22bb6b9464f15c6091659d0f",
     "sdkVersion": "0.0.0-dev"
 }

src/api/errors/UnprocessableEntityError.ts

@@ -2,10 +2,9 @@
 
 import type * as core from "../../core/index.js";
 import * as errors from "../../errors/index.js";
-import type * as Corti from "../index.js";
 
 export class UnprocessableEntityError extends errors.CortiError {
-    constructor(body: Corti.AgentsValidationErrorResponse, rawResponse?: core.RawResponse) {
+    constructor(body?: unknown, rawResponse?: core.RawResponse) {
         super({
             message: "UnprocessableEntityError",
             statusCode: 422,

src/api/resources/agents/client/Client.ts

@@ -183,16 +183,7 @@ export class AgentsClient {
                 case 401:
                     throw new Corti.UnauthorizedError(_response.error.body, _response.rawResponse);
                 case 422:
-                    throw new Corti.UnprocessableEntityError(
-                        serializers.AgentsValidationErrorResponse.parseOrThrow(_response.error.body, {
-                            unrecognizedObjectKeys: "passthrough",
-                            allowUnrecognizedUnionMembers: true,
-                            allowUnrecognizedEnumValues: true,
-                            skipValidation: true,
-                            breadcrumbsPrefix: ["response"],
-                        }),
-                        _response.rawResponse,
-                    );
+                    throw new Corti.UnprocessableEntityError(_response.error.body, _response.rawResponse);
                 default:
                     throw new errors.CortiError({
                         statusCode: _response.error.statusCode,
@@ -429,16 +420,7 @@ export class AgentsClient {
                 case 404:
                     throw new Corti.NotFoundError(_response.error.body, _response.rawResponse);
                 case 422:
-                    throw new Corti.UnprocessableEntityError(
-                        serializers.AgentsValidationErrorResponse.parseOrThrow(_response.error.body, {
-                            unrecognizedObjectKeys: "passthrough",
-                            allowUnrecognizedUnionMembers: true,
-                            allowUnrecognizedEnumValues: true,
-                            skipValidation: true,
-                            breadcrumbsPrefix: ["response"],
-                        }),
-                        _response.rawResponse,
-                    );
+                    throw new Corti.UnprocessableEntityError(_response.error.body, _response.rawResponse);
                 default:
                     throw new errors.CortiError({
                         statusCode: _response.error.statusCode,
@@ -621,16 +603,7 @@ export class AgentsClient {
                 case 404:
                     throw new Corti.NotFoundError(_response.error.body, _response.rawResponse);
                 case 422:
-                    throw new Corti.UnprocessableEntityError(
-                        serializers.AgentsValidationErrorResponse.parseOrThrow(_response.error.body, {
-                            unrecognizedObjectKeys: "passthrough",
-                            allowUnrecognizedUnionMembers: true,
-                            allowUnrecognizedEnumValues: true,
-                            skipValidation: true,
-                            breadcrumbsPrefix: ["response"],
-                        }),
-                        _response.rawResponse,
-                    );
+                    throw new Corti.UnprocessableEntityError(_response.error.body, _response.rawResponse);
                 default:
                     throw new errors.CortiError({
                         statusCode: _response.error.statusCode,
@@ -909,16 +882,7 @@ export class AgentsClient {
                 case 401:
                     throw new Corti.UnauthorizedError(_response.error.body, _response.rawResponse);
                 case 422:
-                    throw new Corti.UnprocessableEntityError(
-                        serializers.AgentsValidationErrorResponse.parseOrThrow(_response.error.body, {
-                            unrecognizedObjectKeys: "passthrough",
-                            allowUnrecognizedUnionMembers: true,
-                            allowUnrecognizedEnumValues: true,
-                            skipValidation: true,
-                            breadcrumbsPrefix: ["response"],
-                        }),
-                        _response.rawResponse,
-                    );
+                    throw new Corti.UnprocessableEntityError(_response.error.body, _response.rawResponse);
                 default:
                     throw new errors.CortiError({
                         statusCode: _response.error.statusCode,

src/api/resources/documents/client/Client.ts

@@ -8,6 +8,8 @@ import { handleNonStatusCodeError } from "../../../../errors/handleNonStatusCode
 import * as errors from "../../../../errors/index.js";
 import * as serializers from "../../../../serialization/index.js";
 import * as Corti from "../../../index.js";
+import { SectionsClient } from "../resources/sections/client/Client.js";
+import { TemplatesClient } from "../resources/templates/client/Client.js";
 
 export declare namespace DocumentsClient {
     export type Options = BaseClientOptions;
@@ -17,12 +19,24 @@ export declare namespace DocumentsClient {
 
 export class DocumentsClient {
     protected readonly _options: NormalizedClientOptionsWithAuth<DocumentsClient.Options>;
+    protected _templates: TemplatesClient | undefined;
+    protected _sections: SectionsClient | undefined;
 
     constructor(options: DocumentsClient.Options) {
         this._options = normalizeClientOptionsWithAuth(options);
     }
 
+    public get templates(): TemplatesClient {
+        return (this._templates ??= new TemplatesClient(this._options));
+    }
+
+    public get sections(): SectionsClient {
+        return (this._sections ??= new SectionsClient(this._options));
+    }
+
     /**
+     * @deprecated
+     *
      * List Documents
      *
      * @param {Corti.Uuid} id - The unique identifier of the interaction. Must be a valid UUID.
@@ -123,6 +137,8 @@ export class DocumentsClient {
     }
 
     /**
+     * @deprecated
+     *
      * This endpoint offers different ways to generate a document. Find guides to document generation [here](/textgen/documents-standard).
      *
      * @param {Corti.Uuid} id - The unique identifier of the interaction. Must be a valid UUID.
@@ -246,6 +262,8 @@ export class DocumentsClient {
     }
 
     /**
+     * @deprecated
+     *
      * Get Document.
      *
      * @param {Corti.Uuid} id - The unique identifier of the interaction. Must be a valid UUID.
@@ -354,6 +372,8 @@ export class DocumentsClient {
     }
 
     /**
+     * @deprecated
+     *
      * @param {Corti.Uuid} id - The unique identifier of the interaction. Must be a valid UUID.
      * @param {Corti.Uuid} documentId - The document ID representing the context for the request. Must be a valid UUID.
      * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -451,6 +471,8 @@ export class DocumentsClient {
     }
 
     /**
+     * @deprecated
+     *
      * @param {Corti.Uuid} id - The unique identifier of the interaction. Must be a valid UUID.
      * @param {Corti.Uuid} documentId - The document ID representing the context for the request. Must be a valid UUID.
      * @param {Corti.DocumentsUpdateRequest} request
@@ -564,4 +586,108 @@ export class DocumentsClient {
             "/interactions/{id}/documents/{documentId}",
         );
     }
+
+    /**
+     * Generates a structured document using one of three template-supply paths: a stored template reference (optionally with runtime overrides), an ad-hoc assembly of stored sections, or a fully inline dynamic template. Exactly one of `templateRef`, `assemblyTemplate`, or `dynamicTemplate` must be provided.
+     *
+     * With the exception of the plain `templateRef` path (no overrides), every call persists a new auto-generated template aggregate that snapshots the resolved content. The snapshot is drift-proof: subsequent edits to base templates or sections do not affect previously generated documents.
+     *
+     * @param {Corti.GuidedDocumentRequest} request
+     * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Corti.BadRequestError}
+     * @throws {@link Corti.NotFoundError}
+     * @throws {@link Corti.UnprocessableEntityError}
+     * @throws {@link Corti.InternalServerError}
+     *
+     * @example
+     *     await client.documents.generate({
+     *         outputLanguage: "outputLanguage",
+     *         templateRef: {
+     *             templateId: "templateId"
+     *         }
+     *     })
+     */
+    public generate(
+        request: Corti.GuidedDocumentRequest,
+        requestOptions?: DocumentsClient.RequestOptions,
+    ): core.HttpResponsePromise<Corti.CreateEphemeralDocumentResponse> {
+        return core.HttpResponsePromise.fromPromise(this.__generate(request, requestOptions));
+    }
+
+    private async __generate(
+        request: Corti.GuidedDocumentRequest,
+        requestOptions?: DocumentsClient.RequestOptions,
+    ): Promise<core.WithRawResponse<Corti.CreateEphemeralDocumentResponse>> {
+        const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
+        const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+            _authRequest.headers,
+            this._options?.headers,
+            mergeOnlyDefinedHeaders({ "Tenant-Name": requestOptions?.tenantName ?? this._options?.tenantName }),
+            requestOptions?.headers,
+        );
+        const _response = await core.fetcher({
+            url: core.url.join(
+                (await core.Supplier.get(this._options.baseUrl)) ??
+                    (await core.Supplier.get(this._options.environment)).base,
+                "documents/",
+            ),
+            method: "POST",
+            headers: _headers,
+            contentType: "application/json",
+            queryParameters: requestOptions?.queryParams,
+            requestType: "json",
+            body: serializers.GuidedDocumentRequest.jsonOrThrow(request, {
+                unrecognizedObjectKeys: "strip",
+                omitUndefined: true,
+            }),
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+            abortSignal: requestOptions?.abortSignal,
+            fetchFn: this._options?.fetch,
+            logging: this._options.logging,
+        });
+        if (_response.ok) {
+            return {
+                data: serializers.CreateEphemeralDocumentResponse.parseOrThrow(_response.body, {
+                    unrecognizedObjectKeys: "passthrough",
+                    allowUnrecognizedUnionMembers: true,
+                    allowUnrecognizedEnumValues: true,
+                    skipValidation: true,
+                    breadcrumbsPrefix: ["response"],
+                }),
+                rawResponse: _response.rawResponse,
+            };
+        }
+
+        if (_response.error.reason === "status-code") {
+            switch (_response.error.statusCode) {
+                case 400:
+                    throw new Corti.BadRequestError(_response.error.body, _response.rawResponse);
+                case 404:
+                    throw new Corti.NotFoundError(_response.error.body, _response.rawResponse);
+                case 422:
+                    throw new Corti.UnprocessableEntityError(_response.error.body, _response.rawResponse);
+                case 500:
+                    throw new Corti.InternalServerError(
+                        serializers.ErrorResponse.parseOrThrow(_response.error.body, {
+                            unrecognizedObjectKeys: "passthrough",
+                            allowUnrecognizedUnionMembers: true,
+                            allowUnrecognizedEnumValues: true,
+                            skipValidation: true,
+                            breadcrumbsPrefix: ["response"],
+                        }),
+                        _response.rawResponse,
+                    );
+                default:
+                    throw new errors.CortiError({
+                        statusCode: _response.error.statusCode,
+                        body: _response.error.body,
+                        rawResponse: _response.rawResponse,
+                    });
+            }
+        }
+
+        return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/documents/");
+    }
 }

src/api/resources/documents/index.ts

@@ -1 +1,2 @@
 export * from "./client/index.js";
+export * from "./resources/index.js";

src/api/resources/documents/resources/index.ts

@@ -0,0 +1,4 @@
+export * from "./sections/client/requests/index.js";
+export * as sections from "./sections/index.js";
+export * from "./templates/client/requests/index.js";
+export * as templates from "./templates/index.js";