Build a production chatbot with the OpenAI Responses API

{
  "name": "responses-chatbot",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "node --watch --env-file=.env src/server.mjs",
    "start": "node --env-file=.env src/server.mjs",
    "smoke": "node --env-file=.env test/smoke.mjs"
  },
  "dependencies": {
    "cookie-parser": "1.4.7",
    "express": "5.2.1",
    "express-rate-limit": "8.6.1",
    "helmet": "8.3.0",
    "openai": "7.1.0",
    "pg": "8.22.0",
    "pino": "10.3.1",
    "zod": "4.4.3"
  }
}

node -e "for (const path of ['src','public','test','ops']) require('node:fs').mkdirSync(path,{recursive:true})" && npm install

NODE_ENV=development
PORT=3000
PUBLIC_ORIGIN={{publicOrigin}}
DATABASE_URL={{databaseUrl}}
OPENAI_MODEL={{model}}
OPENAI_API_KEY=
APP_HMAC_SECRET={{appHmacSecret}}

node -e "require('node:fs').copyFileSync('.env.example','.env',require('node:fs').constants.COPYFILE_EXCL)"

BEGIN;

CREATE EXTENSION IF NOT EXISTS pgcrypto;

CREATE TABLE IF NOT EXISTS chat_sessions (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_hash text NOT NULL,
  openai_conversation_id text NOT NULL UNIQUE,
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX IF NOT EXISTS chat_sessions_user_updated_idx
  ON chat_sessions (user_hash, updated_at DESC);

CREATE TABLE IF NOT EXISTS chat_requests (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  session_id uuid NOT NULL REFERENCES chat_sessions(id) ON DELETE CASCADE,
  idempotency_key text NOT NULL,
  user_content text NOT NULL,
  assistant_content text NOT NULL DEFAULT '',
  status text NOT NULL CHECK (status IN ('streaming', 'completed', 'cancelled', 'failed')),
  openai_response_id text,
  error_code text,
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now(),
  UNIQUE (session_id, idempotency_key)
);

CREATE INDEX IF NOT EXISTS chat_requests_session_created_idx
  ON chat_requests (session_id, created_at);

COMMIT;

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f schema.sql

import crypto from "node:crypto";
import cookieParser from "cookie-parser";
import express from "express";
import { rateLimit } from "express-rate-limit";
import helmet from "helmet";
import OpenAI from "openai";
import pg from "pg";
import pino from "pino";
import { z } from "zod";

const { Pool } = pg;
const env = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  PUBLIC_ORIGIN: z.string().url(),
  DATABASE_URL: z.string().min(1),
  OPENAI_MODEL: z.string().min(1),
  OPENAI_API_KEY: z.string().min(20),
  APP_HMAC_SECRET: z.string().min(32),
}).parse(process.env);

const log = pino({
  level: env.NODE_ENV === "production" ? "info" : "debug",
  redact: ["req.headers.authorization", "req.headers.cookie", "prompt", "content"],
});
const db = new Pool({
  connectionString: env.DATABASE_URL,
  max: 10,
  idleTimeoutMillis: 30_000,
  connectionTimeoutMillis: 5_000,
});
const openai = new OpenAI({
  apiKey: env.OPENAI_API_KEY,
  maxRetries: 2,
  timeout: 45_000,
});
const app = express();

app.set("trust proxy", 1);
app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      connectSrc: ["'self'"],
      imgSrc: ["'self'", "data:"],
      objectSrc: ["'none'"],
      baseUri: ["'none'"],
      formAction: ["'self'"],
      frameAncestors: ["'none'"],
    },
  },
}));
app.use(express.json({ limit: "16kb" }));
app.use(cookieParser(env.APP_HMAC_SECRET));
app.use(express.static("public", { extensions: ["html"] }));
app.use("/api", rateLimit({
  windowMs: 60_000,
  limit: 30,
  standardHeaders: "draft-8",
  legacyHeaders: false,
}));

const messageInput = z.object({
  message: z.string().trim().min(1).max(4_000),
});
const idInput = z.string().uuid();
const keyInput = z.string().regex(/^[A-Za-z0-9_-]{16,100}$/);

function userHash(value) {
  return crypto.createHmac("sha256", env.APP_HMAC_SECRET).update(value).digest("hex");
}

function pseudonymousUser(req, res, next) {
  let id = req.signedCookies.chat_uid;
  if (!idInput.safeParse(id).success) {
    id = crypto.randomUUID();
    res.cookie("chat_uid", id, {
      signed: true,
      httpOnly: true,
      secure: env.NODE_ENV === "production",
      sameSite: "strict",
      maxAge: 30 * 24 * 60 * 60 * 1_000,
    });
  }
  req.userHash = userHash(id);
  next();
}

function sameOriginWrite(req, res, next) {
  if (!["POST", "PUT", "PATCH", "DELETE"].includes(req.method)) return next();
  if (req.get("origin") !== env.PUBLIC_ORIGIN) {
    return res.status(403).json({ error: "origin_not_allowed" });
  }
  next();
}

app.use("/api", pseudonymousUser, sameOriginWrite);

app.get("/healthz", async (_req, res) => {
  await db.query("SELECT 1");
  res.json({ status: "ok" });
});

app.post("/api/sessions", async (req, res, next) => {
  try {
    const conversation = await openai.conversations.create();
    const result = await db.query(
      "INSERT INTO chat_sessions(user_hash, openai_conversation_id) VALUES ($1, $2) RETURNING id",
      [req.userHash, conversation.id],
    );
    res.status(201).json({ id: result.rows[0].id });
  } catch (error) {
    next(error);
  }
});

app.get("/api/sessions/:id/messages", async (req, res, next) => {
  try {
    const sessionId = idInput.parse(req.params.id);
    const session = await db.query(
      "SELECT id FROM chat_sessions WHERE id = $1 AND user_hash = $2",
      [sessionId, req.userHash],
    );
    if (session.rowCount !== 1) return res.status(404).json({ error: "not_found" });

    const messages = await db.query(
      "SELECT id, user_content, assistant_content, status, created_at FROM chat_requests WHERE session_id = $1 ORDER BY created_at, id",
      [sessionId],
    );
    res.json({ messages: messages.rows });
  } catch (error) {
    next(error);
  }
});

function sendEvent(res, type, data) {
  res.write("event: " + type + "\n");
  res.write("data: " + JSON.stringify(data) + "\n\n");
}

app.post("/api/sessions/:id/messages", async (req, res, next) => {
  let requestId;
  let responseId;
  let assembled = "";
  let finished = false;
  const abortController = new AbortController();

  try {
    const sessionId = idInput.parse(req.params.id);
    const { message } = messageInput.parse(req.body);
    const idempotencyKey = keyInput.parse(req.get("idempotency-key"));
    const session = await db.query(
      "SELECT openai_conversation_id FROM chat_sessions WHERE id = $1 AND user_hash = $2",
      [sessionId, req.userHash],
    );
    if (session.rowCount !== 1) return res.status(404).json({ error: "not_found" });

    try {
      const inserted = await db.query(
        "INSERT INTO chat_requests(session_id, idempotency_key, user_content, status) VALUES ($1, $2, $3, 'streaming') RETURNING id",
        [sessionId, idempotencyKey, message],
      );
      requestId = inserted.rows[0].id;
    } catch (error) {
      if (error?.code === "23505") {
        return res.status(409).json({ error: "duplicate_request" });
      }
      throw error;
    }

    res.status(200);
    res.set({
      "Content-Type": "text/event-stream; charset=utf-8",
      "Cache-Control": "no-cache, no-transform",
      "X-Accel-Buffering": "no",
    });
    res.flushHeaders();
    req.on("close", () => {
      if (!finished && !res.writableEnded) abortController.abort();
    });

    const stream = await openai.responses.create({
      model: env.OPENAI_MODEL,
      conversation: session.rows[0].openai_conversation_id,
      input: [{ role: "user", content: message }],
      instructions:
        "Answer the user's question clearly. State uncertainty. Never claim an external action occurred unless a tool result proves it.",
      reasoning: { effort: "none" },
      safety_identifier: req.userHash,
      stream: true,
      store: true,
      max_output_tokens: 1_200,
    }, { signal: abortController.signal });

    sendEvent(res, "ready", { requestId });
    for await (const event of stream) {
      if (event.type === "response.created") {
        responseId = event.response.id;
        sendEvent(res, "response", { responseId });
      } else if (event.type === "response.output_text.delta") {
        assembled += event.delta;
        sendEvent(res, "delta", { text: event.delta });
      } else if (event.type === "response.completed") {
        responseId = event.response.id;
        finished = true;
        await db.query(
          "UPDATE chat_requests SET assistant_content = $1, status = 'completed', openai_response_id = $2, updated_at = now() WHERE id = $3",
          [assembled, responseId, requestId],
        );
        await db.query(
          "UPDATE chat_sessions SET updated_at = now() WHERE id = $1",
          [sessionId],
        );
        sendEvent(res, "completed", {
          responseId,
          usage: event.response.usage,
        });
      } else if (event.type === "response.failed") {
        throw new Error(event.response.error?.code || "response_failed");
      } else if (event.type === "error") {
        throw new Error(event.code || "stream_error");
      }
    }
    res.end();
  } catch (error) {
    const cancelled = abortController.signal.aborted;
    if (requestId) {
      await db.query(
        "UPDATE chat_requests SET assistant_content = $1, status = $2, openai_response_id = $3, error_code = $4, updated_at = now() WHERE id = $5",
        [
          assembled,
          cancelled ? "cancelled" : "failed",
          responseId ?? null,
          cancelled ? "client_cancelled" : "upstream_error",
          requestId,
        ],
      ).catch((dbError) => log.error({ err: dbError, requestId }, "status update failed"));
    }
    log.warn({ err: error, requestId, responseId, cancelled }, "chat stream ended");
    if (res.headersSent) {
      sendEvent(res, "failed", {
        code: cancelled ? "cancelled" : "upstream_error",
        retryable: !cancelled,
      });
      return res.end();
    }
    next(error);
  }
});

app.delete("/api/sessions/:id", async (req, res, next) => {
  try {
    const sessionId = idInput.parse(req.params.id);
    const session = await db.query(
      "SELECT openai_conversation_id FROM chat_sessions WHERE id = $1 AND user_hash = $2",
      [sessionId, req.userHash],
    );
    if (session.rowCount !== 1) return res.status(404).json({ error: "not_found" });

    await openai.conversations.delete(session.rows[0].openai_conversation_id);
    await db.query(
      "DELETE FROM chat_sessions WHERE id = $1 AND user_hash = $2",
      [sessionId, req.userHash],
    );
    res.status(204).end();
  } catch (error) {
    next(error);
  }
});

app.use((error, _req, res, _next) => {
  const requestId = crypto.randomUUID();
  log.error({ err: error, requestId }, "request failed");
  const status = error instanceof z.ZodError ? 400 : 500;
  res.status(status).json({
    error: status === 400 ? "invalid_request" : "internal_error",
    requestId,
  });
});

const server = app.listen(env.PORT, () => {
  log.info({ port: env.PORT, model: env.OPENAI_MODEL }, "chatbot listening");
});

async function shutdown(signal) {
  log.info({ signal }, "shutting down");
  server.close();
  await db.end();
  process.exit(0);
}
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));

node --check src/server.mjs

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <title>Responses chatbot</title>
  <style>
    :root { color-scheme: dark; font: 16px/1.5 system-ui; background: #0d1117; color: #e6edf3; }
    body { margin: 0; }
    main { width: min(760px, calc(100% - 32px)); margin: 32px auto; }
    header, form { display: flex; gap: 12px; align-items: center; }
    header { justify-content: space-between; }
    #messages { min-height: 50vh; display: grid; align-content: start; gap: 12px; margin: 24px 0; }
    .message { padding: 12px 14px; border: 1px solid #30363d; border-radius: 8px; white-space: pre-wrap; }
    .user { background: #161b22; }
    .assistant { border-color: #238636; }
    .interrupted { border-color: #d29922; }
    textarea { flex: 1; min-height: 72px; resize: vertical; background: #161b22; color: inherit; border: 1px solid #30363d; padding: 10px; }
    button { background: #238636; color: white; border: 0; border-radius: 6px; padding: 10px 14px; cursor: pointer; }
    button[disabled] { opacity: .5; cursor: not-allowed; }
    #status { min-height: 24px; color: #8b949e; }
  </style>
</head>
<body>
<main>
  <header>
    <div><h1>Responses chatbot</h1><p id="status" role="status">Loading conversation…</p></div>
    <button id="new" type="button">New conversation</button>
  </header>
  <section id="messages" aria-live="polite"></section>
  <form id="composer">
    <label for="prompt" hidden>Message</label>
    <textarea id="prompt" maxlength="4000" required placeholder="Ask a question"></textarea>
    <button id="send" type="submit">Send</button>
    <button id="stop" type="button" disabled>Stop</button>
  </form>
</main>
<script type="module">
  const messages = document.querySelector("#messages");
  const form = document.querySelector("#composer");
  const prompt = document.querySelector("#prompt");
  const send = document.querySelector("#send");
  const stop = document.querySelector("#stop");
  const status = document.querySelector("#status");
  let sessionId = localStorage.getItem("chat_session");
  let controller;

  function bubble(role, text, state = "") {
    const node = document.createElement("article");
    node.className = "message " + role + (state ? " " + state : "");
    node.textContent = text;
    messages.append(node);
    node.scrollIntoView({ block: "end", behavior: "smooth" });
    return node;
  }

  async function createSession() {
    const response = await fetch("/api/sessions", {
      method: "POST",
    });
    if (!response.ok) throw new Error("session_create_failed");
    const body = await response.json();
    sessionId = body.id;
    localStorage.setItem("chat_session", sessionId);
    messages.replaceChildren();
    status.textContent = "New conversation ready";
  }

  async function loadMessages() {
    if (!sessionId) return createSession();
    const response = await fetch("/api/sessions/" + sessionId + "/messages");
    if (response.status === 404) return createSession();
    if (!response.ok) throw new Error("history_load_failed");
    const body = await response.json();
    messages.replaceChildren();
    for (const item of body.messages) {
      bubble("user", item.user_content);
      if (item.assistant_content) {
        bubble("assistant", item.assistant_content, item.status === "completed" ? "" : "interrupted");
      }
    }
    status.textContent = body.messages.length ? "Conversation restored" : "Ready";
  }

  function parseSseBlock(block) {
    const event = block.split("\n").find((line) => line.startsWith("event:"))?.slice(6).trim();
    const data = block.split("\n").find((line) => line.startsWith("data:"))?.slice(5).trim();
    return event && data ? { event, data: JSON.parse(data) } : null;
  }

  async function streamMessage(text) {
    controller = new AbortController();
    send.disabled = true;
    stop.disabled = false;
    bubble("user", text);
    const answer = bubble("assistant", "");
    status.textContent = "Generating…";

    const response = await fetch("/api/sessions/" + sessionId + "/messages", {
      method: "POST",
      signal: controller.signal,
      headers: {
        "Content-Type": "application/json",
        "Idempotency-Key": crypto.randomUUID().replaceAll("-", ""),
      },
      body: JSON.stringify({ message: text }),
    });
    if (!response.ok || !response.body) {
      throw new Error(response.status === 409 ? "duplicate_request" : "stream_start_failed");
    }

    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let buffer = "";
    while (true) {
      const { value, done } = await reader.read();
      buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done });
      const blocks = buffer.split("\n\n");
      buffer = blocks.pop() ?? "";
      for (const block of blocks) {
        const item = parseSseBlock(block);
        if (!item) continue;
        if (item.event === "delta") answer.textContent += item.data.text;
        if (item.event === "completed") status.textContent = "Complete";
        if (item.event === "failed") throw new Error(item.data.code);
      }
      if (done) break;
    }
  }

  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    const text = prompt.value.trim();
    if (!text) return;
    prompt.value = "";
    try {
      await streamMessage(text);
    } catch (error) {
      status.textContent = error.name === "AbortError"
        ? "Stopped. Reloading saved state…"
        : "Request failed. Reloading saved state…";
      await new Promise((resolve) => setTimeout(resolve, 500));
      await loadMessages();
    } finally {
      controller = undefined;
      send.disabled = false;
      stop.disabled = true;
      prompt.focus();
    }
  });

  stop.addEventListener("click", () => controller?.abort());
  document.querySelector("#new").addEventListener("click", async () => {
    if (sessionId) {
      const response = await fetch("/api/sessions/" + sessionId, {
        method: "DELETE",
      });
      if (!response.ok && response.status !== 404) throw new Error("session_delete_failed");
    }
    localStorage.removeItem("chat_session");
    sessionId = undefined;
    await createSession();
    prompt.focus();
  });

  loadMessages().catch(() => {
    status.textContent = "Could not load the conversation. Check the server logs.";
  });
</script>
</body>
</html>

node -e "const s=require('node:fs').readFileSync('public/index.html','utf8'); if(!s.includes('AbortController')||!s.includes('textContent')) process.exit(1); console.log('browser safety checks present')"

import assert from "node:assert/strict";

const origin = process.env.PUBLIC_ORIGIN;
const cookieJar = [];
const headers = () => ({
  Origin: origin,
  Cookie: cookieJar.join("; "),
});

const sessionResponse = await fetch(origin + "/api/sessions", {
  method: "POST",
  headers: headers(),
});
assert.equal(sessionResponse.status, 201);
for (const value of sessionResponse.headers.getSetCookie?.() ?? []) {
  cookieJar.push(value.split(";")[0]);
}
const { id } = await sessionResponse.json();
assert.match(id, /^[0-9a-f-]{36}$/);

const streamResponse = await fetch(origin + "/api/sessions/" + id + "/messages", {
  method: "POST",
  headers: {
    ...headers(),
    "Content-Type": "application/json",
    "Idempotency-Key": "smoketest0000000001",
  },
  body: JSON.stringify({ message: "Reply with exactly: STREAM_OK" }),
});
assert.equal(streamResponse.status, 200);
const streamBody = await streamResponse.text();
assert.match(streamBody, /event: delta/);
assert.match(streamBody, /STREAM_OK/);
assert.match(streamBody, /event: completed/);

const historyResponse = await fetch(origin + "/api/sessions/" + id + "/messages", {
  headers: headers(),
});
assert.equal(historyResponse.status, 200);
const history = await historyResponse.json();
assert.equal(history.messages.length, 1);
assert.equal(history.messages[0].status, "completed");
assert.match(history.messages[0].assistant_content, /STREAM_OK/);

const duplicate = await fetch(origin + "/api/sessions/" + id + "/messages", {
  method: "POST",
  headers: {
    ...headers(),
    "Content-Type": "application/json",
    "Idempotency-Key": "smoketest0000000001",
  },
  body: JSON.stringify({ message: "This must not create a second turn." }),
});
assert.equal(duplicate.status, 409);

const deleteResponse = await fetch(origin + "/api/sessions/" + id, {
  method: "DELETE",
  headers: headers(),
});
assert.equal(deleteResponse.status, 204);

console.log(JSON.stringify({
  session: "created",
  stream: "completed",
  transcript: "restored",
  duplicate: "blocked",
  deletion: "completed"
}, null, 2));

npm run smoke