feat(service): add support for Apps Script output types in ResponseBuilder and cleanup

MaksymStoianov · junie-agent · MaksymStoianov · commit db2f91255096 · 2026-04-15T10:59:16.000+02:00
Co-authored-by: Junie &lt;junie@jetbrains.com&gt;
diff --git a/README.md b/README.md
@@ -604,7 +604,7 @@ export class GlobalExceptionHandler {
 }
 ```
 
-## Recommended Utilities
+## Recommended
 
 For enhanced development with Google Apps Script, we recommend using [apps-script-utils](https://github.com/MaksymStoianov/apps-script-utils), a collection of utility functions and classes that complement this framework.
 
diff --git a/config/vite/types/BuildOptions.ts b/config/vite/types/BuildOptions.ts
@@ -6,7 +6,6 @@ import { BuildPaths } from "./BuildPaths";
  * Extends Vite's `ConfigEnv` with project-specific paths and flags.
  */
 export interface BuildOptions extends ConfigEnv {
-
   /**
    * Project paths.
    */
diff --git a/config/vite/types/BuildPaths.ts b/config/vite/types/BuildPaths.ts
@@ -2,7 +2,6 @@
  * Directory paths used in the build process.
  */
 export type BuildPaths = {
-
   /**
    * Project root directory.
    */
diff --git a/config/vite/types/ResolveOptions.ts b/config/vite/types/ResolveOptions.ts
@@ -4,7 +4,6 @@ import { AliasOptions, ResolveOptions as ViteResolveOptions } from "vite";
  * Vite resolve options with optional aliases.
  */
 export type ResolveOptions = ViteResolveOptions & {
-
   /**
    * Module aliases.
    */
diff --git a/src/controller/decorators/Controller.ts b/src/controller/decorators/Controller.ts
@@ -9,7 +9,6 @@ import {
  * Interface representing controller options.
  */
 export interface ControllerOptions {
-
   /**
    * The base path for all routes in the controller.
    */
diff --git a/src/controller/decorators/routing/RequestMapping.ts b/src/controller/decorators/routing/RequestMapping.ts
@@ -9,7 +9,6 @@ import { RequestMethod } from "../../../domain/enums";
  * Interface representing RequestMapping options.
  */
 export interface RequestMappingOptions {
-
   /**
    * The path for the route.
    */
diff --git a/src/domain/entities/RouteExecutionContext.ts b/src/domain/entities/RouteExecutionContext.ts
@@ -4,7 +4,6 @@ import { HttpHeaders, HttpRequest, HttpResponse, ParsedUrlQuery } from "../../do
  * Execution context for a route handler.
  */
 export interface RouteExecutionContext {
-
   /**
    * The Google Apps Script event.
    */
diff --git a/src/domain/enums/AppsScriptEventType.ts b/src/domain/enums/AppsScriptEventType.ts
@@ -4,7 +4,6 @@
  * @see https://developers.google.com/apps-script/guides/triggers
  */
 export enum AppsScriptEventType {
-
   /**
    * Triggered when an add-on is installed.
    *
diff --git a/src/domain/enums/HeaderAcceptMimeType.ts b/src/domain/enums/HeaderAcceptMimeType.ts
@@ -4,7 +4,6 @@
  * @see https://developers.google.com/apps-script/reference/content/mime-type
  */
 export enum HeaderAcceptMimeType {
-
   /**
    * Special type for returning a JSON string directly (without TextOutput).
    * Used for internal Google Apps Script purposes.
diff --git a/src/domain/enums/HttpStatus.ts b/src/domain/enums/HttpStatus.ts
@@ -2,7 +2,6 @@
  * Enum of HTTP status codes.
  */
 export enum HttpStatus {
-
   /**
    * Continue (100).
    */
diff --git a/src/domain/enums/ParamSource.ts b/src/domain/enums/ParamSource.ts
@@ -2,7 +2,6 @@
  * Enum of parameter sources for method handlers.
  */
 export enum ParamSource {
-
   /**
    * Path parameters.
    */
diff --git a/src/domain/enums/RequestMethod.ts b/src/domain/enums/RequestMethod.ts
@@ -2,7 +2,6 @@
  * Enum of HTTP request methods.
  */
 export enum RequestMethod {
-
   /**
    * GET method.
    */
diff --git a/src/domain/types/ApplicationConfig.ts b/src/domain/types/ApplicationConfig.ts
@@ -6,7 +6,6 @@ import { Provider } from "./Provider";
  * Interface representing application configuration.
  */
 export interface ApplicationConfig {
-
   /**
    * List of controller classes.
    */
diff --git a/src/domain/types/ClassProvider.ts b/src/domain/types/ClassProvider.ts
@@ -5,7 +5,6 @@ import { Newable } from "./Newable";
  * Interface representing a class provider.
  */
 export interface ClassProvider<T = unknown> {
-
   /**
    * The injection token.
    */
diff --git a/src/domain/types/ErrorResponse.ts b/src/domain/types/ErrorResponse.ts
@@ -2,7 +2,6 @@
  * Interface representing an error response.
  */
 export interface ErrorResponse {
-
   /**
    * The timestamp of the error.
    */
diff --git a/src/domain/types/ExistingProvider.ts b/src/domain/types/ExistingProvider.ts
@@ -4,7 +4,6 @@ import { InjectionToken } from "./InjectionToken";
  * Interface representing an existing provider.
  */
 export interface ExistingProvider<T = unknown> {
-
   /**
    * The injection token.
    */
diff --git a/src/domain/types/FactoryProvider.ts b/src/domain/types/FactoryProvider.ts
@@ -4,7 +4,6 @@ import { InjectionToken } from "./InjectionToken";
  * Interface representing a factory provider.
  */
 export interface FactoryProvider<T = unknown> {
-
   /**
    * The injection token.
    */
diff --git a/src/domain/types/HttpHeaders.ts b/src/domain/types/HttpHeaders.ts
@@ -2,7 +2,6 @@
  * Interface representing HTTP headers.
  */
 export interface HttpHeaders {
-
   /**
    * Header name and value pairs.
    */
diff --git a/src/domain/types/HttpRequest.ts b/src/domain/types/HttpRequest.ts
@@ -6,7 +6,6 @@ import { RequestMethod } from "../../domain/enums";
  * Interface representing an HTTP request.
  */
 export interface HttpRequest {
-
   /**
    * HTTP request headers.
    */
diff --git a/src/domain/types/HttpResponse.ts b/src/domain/types/HttpResponse.ts
@@ -5,7 +5,6 @@ import { HttpStatus } from "../../domain/enums";
  * Interface representing an HTTP response.
  */
 export interface HttpResponse {
-
   /**
    * HTTP response headers.
    */
diff --git a/src/domain/types/InjectTokenDefinition.ts b/src/domain/types/InjectTokenDefinition.ts
@@ -5,7 +5,6 @@ import { InjectionToken } from "./InjectionToken";
  * Interface representing an injection token definition.
  */
 export interface InjectTokenDefinition {
-
   /**
    * The source of the parameter (`INJECT` or `VALUE`).
    */
diff --git a/src/domain/types/ParamDefinition.ts b/src/domain/types/ParamDefinition.ts
@@ -4,7 +4,6 @@ import { ParamSource } from "../../domain/enums";
  * Interface representing a parameter definition.
  */
 export interface ParamDefinition {
-
   /**
    * The source of the parameter.
    */
diff --git a/src/domain/types/ParsedUrl.ts b/src/domain/types/ParsedUrl.ts
@@ -4,7 +4,6 @@ import { ParsedUrlQuery } from "./ParsedUrlQuery";
  * Interface representing a parsed URL.
  */
 export interface ParsedUrl {
-
   /**
    * The pathname part of the URL.
    */
diff --git a/src/domain/types/ParsedUrlQuery.ts b/src/domain/types/ParsedUrlQuery.ts
@@ -2,7 +2,6 @@
  * Interface representing parsed URL query parameters.
  */
 export interface ParsedUrlQuery {
-
   /**
    * Query parameter key and value(s).
    */
diff --git a/src/domain/types/PipeTransform.ts b/src/domain/types/PipeTransform.ts
@@ -5,7 +5,6 @@ import { Newable } from "./Newable";
  * Interface representing the argument metadata passed to the transform method.
  */
 export interface ArgumentMetadata {
-
   /**
    * Source of the parameter.
    */
@@ -26,7 +25,6 @@ export interface ArgumentMetadata {
  * Interface representing a pipe transform.
  */
 export interface PipeTransform<T = any, R = any> {
-
   /**
    * Transforms the input value.
    *
diff --git a/src/domain/types/RouteMetadata.ts b/src/domain/types/RouteMetadata.ts
@@ -5,7 +5,6 @@ import { RequestMethod } from "../../domain/enums";
  * Interface representing metadata for a route.
  */
 export interface RouteMetadata {
-
   /**
    * The controller class.
    */
diff --git a/src/domain/types/ValueProvider.ts b/src/domain/types/ValueProvider.ts
@@ -4,7 +4,6 @@ import { InjectionToken } from "./InjectionToken";
  * Interface representing a value provider.
  */
 export interface ValueProvider<T = unknown> {
-
   /**
    * The injection token.
    */
diff --git a/src/repository/createMethodDecorator.ts b/src/repository/createMethodDecorator.ts
@@ -7,7 +7,6 @@ import { APPSSCRIPT_EVENT_METADATA, APPSSCRIPT_OPTIONS_METADATA } from "../domai
  * This interface defines event-specific filters for `onEdit`, `onFormSubmit`, and `onChange` handlers.
  */
 export interface AppsScriptOptions {
-
   /**
    * The type of Apps Script event.
    */
diff --git a/src/service/ResponseBuilder.ts b/src/service/ResponseBuilder.ts
@@ -1,6 +1,6 @@
 import { HeaderAcceptMimeType, HttpStatus, RequestMethod } from "../domain/enums";
 import { HttpHeaders, HttpRequest, HttpResponse } from "../domain/types";
-import { isEmpty, isString, normalize } from "apps-script-utils";
+import { isEmpty, isHtmlOutput, isString, isTextOutput, normalize } from "apps-script-utils";
 
 /**
  * Service for building and wrapping HTTP responses.
@@ -59,7 +59,7 @@ export class ResponseBuilder {
       ok,
       status: resolvedStatus,
       statusText,
-      body: ok ? data : { error: data }
+      body: ok || isHtmlOutput(data) || isTextOutput(data) ? data : { error: data }
     };
   }
 
@@ -74,6 +74,10 @@ export class ResponseBuilder {
     request: HttpRequest,
     response: HttpResponse
   ): GoogleAppsScript.HTML.HtmlOutput | GoogleAppsScript.Content.TextOutput | string {
+    if (isHtmlOutput(response.body) || isTextOutput(response.body)) {
+      return response.body;
+    }
+
     const acceptHeader: string | undefined = request.headers?.Accept;
 
     const mimeType: HeaderAcceptMimeType =
diff --git a/test/unit/service/ResponseBuilder/ResponseBuilder.gasOutput.unit.test.ts b/test/unit/service/ResponseBuilder/ResponseBuilder.gasOutput.unit.test.ts
@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ResponseBuilder } from "src/service";
+import { HttpStatus, RequestMethod } from "src/domain/enums";
+import { HttpRequest } from "src/domain/types";
+import * as appsScriptUtils from "apps-script-utils";
+
+vi.mock("apps-script-utils", async () => {
+  const actual = await vi.importActual("apps-script-utils");
+  return {
+    ...actual,
+    isHtmlOutput: vi.fn(),
+    isTextOutput: vi.fn()
+  };
+});
+
+describe("ResponseBuilder: GasOutput", () => {
+  const builder = new ResponseBuilder();
+  const mockRequest = {
+    method: RequestMethod.GET,
+    headers: {},
+    url: { pathname: "/" }
+  } as unknown as HttpRequest;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubGlobal("ContentService", {
+      createTextOutput: vi.fn().mockReturnValue({
+        setMimeType: vi.fn().mockReturnThis()
+      }),
+      MimeType: {
+        JSON: "JSON",
+        TEXT: "TEXT"
+      }
+    });
+    vi.stubGlobal("HtmlService", {
+      createHtmlOutput: vi.fn().mockReturnValue("html-output")
+    });
+
+    vi.mocked(appsScriptUtils.isHtmlOutput).mockImplementation(
+      (val: any) => val && val.__isHtmlOutput
+    );
+    vi.mocked(appsScriptUtils.isTextOutput).mockImplementation(
+      (val: any) => val && val.__isTextOutput
+    );
+  });
+
+  it("should not wrap TextOutput in error object even if status is not 2xx", () => {
+    const textOutput = {
+      getContent: () => "content",
+      getMimeType: () => {},
+      __isTextOutput: true
+    };
+    const res = builder.create(mockRequest, HttpStatus.BAD_REQUEST, {}, textOutput);
+
+    expect(res.status).toBe(HttpStatus.BAD_REQUEST);
+    expect(res.ok).toBe(false);
+    expect(res.body).toBe(textOutput);
+  });
+
+  it("should return TextOutput directly in wrap method", () => {
+    const textOutput = {
+      getContent: () => "content",
+      getMimeType: () => {},
+      __isTextOutput: true
+    };
+    const res = builder.create(mockRequest, HttpStatus.OK, {}, textOutput);
+    const result = builder.wrap(mockRequest, res);
+
+    expect(result).toBe(textOutput);
+  });
+
+  it("should return HtmlOutput directly in wrap method", () => {
+    const htmlOutput = {
+      getContent: () => "content",
+      setTitle: () => {},
+      setXFrameOptionsMode: () => {},
+      __isHtmlOutput: true
+    };
+    const res = builder.create(mockRequest, HttpStatus.OK, {}, htmlOutput);
+    const result = builder.wrap(mockRequest, res);
+
+    expect(result).toBe(htmlOutput);
+  });
+
+  it("should return GasOutput even for API requests (should not be wrapped in JSON structure)", () => {
+    const apiBuilder = new ResponseBuilder("api");
+    const apiRequest = {
+      method: RequestMethod.GET,
+      headers: {},
+      url: { pathname: "/api/feed" }
+    } as unknown as HttpRequest;
+
+    const textOutput = {
+      getContent: () => "content",
+      getMimeType: () => {},
+      __isTextOutput: true
+    };
+    const res = apiBuilder.create(apiRequest, HttpStatus.OK, {}, textOutput);
+    const result = apiBuilder.wrap(apiRequest, res);
+
+    expect(result).toBe(textOutput);
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -604,7 +604,7 @@ export class GlobalExceptionHandler {`
`604`	`604`	`}`
`605`	`605`	```
`606`	`606`
`607`		`-## Recommended Utilities`
	`607`	`+## Recommended`
`608`	`608`
`609`	`609`	`For enhanced development with Google Apps Script, we recommend using [apps-script-utils](https://github.com/MaksymStoianov/apps-script-utils), a collection of utility functions and classes that complement this framework.`
`610`	`610`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,6 @@`
`4`	`4`	`* @see https://developers.google.com/apps-script/guides/triggers`
`5`	`5`	`*/`
`6`	`6`	`export enum AppsScriptEventType {`
`7`		`-`
`8`	`7`	`/**`
`9`	`8`	`* Triggered when an add-on is installed.`
`10`	`9`	`*`