🧠 chatgpt-dto - DTO-first GPT Integration

A lightweight wrapper around the OpenAI GPT API with first-class support for DTO-based JSON output validation using class-validator and class-transformer. Ideal for TypeScript-based server applications (e.g., NestJS, routing-controllers) that require structured and type-safe responses from ChatGPT.

✨ Features

• ✅ Seamless integration with class-validator & class-transformer
• 🧩 Converts DTOs to JSON Schema using class-validator-jsonschema
• 🧠 Utilizes OpenAI's JSON Schema output format (response_format: json_schema)
• 🔄 Automatically parses and validates GPT responses into typed DTO instances
• ⚙️ Minimal setup, with lazy singleton provider initialization
• 🪄 Supports $ref schema expansion for complex/nested DTOs

📦 Installation

npm install chatgpt-dto

🚀 Quick Start

import { getGPTProvider } from "chatgpt-dto";
import { IsString, IsEmail } from "class-validator";
import { Expose } from "class-transformer";

class UserDTO {
  @IsString()
  @Expose()
  name: string;

  @IsEmail()
  @Expose()
  email: string;
}

async function run() {
  const gpt = getGPTProvider({
    apiKey: "your-openai-api-key", // Required
    model: "gpt-4o-mini",          // Optional (default: gpt-4o-mini)
  });

  const response = await gpt.jsonDTO("Generate a random user", UserDTO);
  console.log(response?.result); // typed UserDTO instance
}

🧩 API

getGPTProvider(options?: PluginOptions): GPTProvider

Initializes (once) and returns a GPTProvider instance.

Options

| Option | Type | Required | Description | |----------|----------|----------|--------------------------------------| | apiKey | string | ✅ | Your OpenAI API key | | model | string | ❌ | Model name (default: gpt-4o-mini) |

gpt.jsonDTO<T>(prompt: string, dtoClass: new () => T, model?: string): Promise<GptResponse<T> | null>

Sends a prompt and expects a structured JSON response that matches the given DTO class.

• Automatically generates JSON Schema from the DTO
• Expands $ref properties for compatibility with OpenAI

Returns:

type GptResponse<T> = {
  result: T; // typed DTO instance
  usage: OpenAI.Completions.CompletionUsage;
  message: OpenAI.Chat.Completions.ChatCompletionMessage;
}

gpt.chat(prompt: string, model?: string): Promise<GptResponse<string> | null>

Standard ChatGPT interaction that returns a raw string message.

gpt.chatString(prompt: string, model?: string): Promise<string>

Convenience wrapper for simple string responses.

gpt.JsonString<T>(prompt: string, jsonSchema: any, model?: string): Promise<T | null>

Advanced method for validating GPT output against a manually provided JSON Schema.

📘 Use Case: Schema Expansion with $ref

This plugin automatically expands $ref references in generated schemas. That means you can safely use nested DTOs, and the schema sent to OpenAI will be fully inlined and self-contained.

📌 Requirements

• Node.js >= 18
• OpenAI API Key
• DTOs must use class-validator decorators for schema generation
• reflect-metadata must be imported globally

import "reflect-metadata";

📄 License

MIT © unbywyd