Validate client timeline item createdAt handling

Author: Rieranthony

apps/api/src/rest/client-timeline-item-created-at.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import {
+	CLIENT_TIMELINE_ITEM_CREATED_AT_MAX_FUTURE_SKEW_MS,
+	ClientTimelineItemCreatedAtValidationError,
+	normalizeClientTimelineItemCreatedAt,
+} from "./client-timeline-item-created-at";
+
+describe("normalizeClientTimelineItemCreatedAt", () => {
+	const now = new Date("2026-04-17T10:00:00.000Z");
+
+	it("returns undefined when createdAt is omitted", () => {
+		expect(
+			normalizeClientTimelineItemCreatedAt({
+				field: "item.createdAt",
+				now,
+			})
+		).toBeUndefined();
+	});
+
+	it("accepts the current timestamp", () => {
+		const result = normalizeClientTimelineItemCreatedAt({
+			createdAt: "2026-04-17T10:00:00.000Z",
+			field: "item.createdAt",
+			now,
+		});
+
+		expect(result?.toISOString()).toBe("2026-04-17T10:00:00.000Z");
+	});
+
+	it("accepts historical timestamps", () => {
+		const result = normalizeClientTimelineItemCreatedAt({
+			createdAt: "2026-04-13T10:00:00.000Z",
+			field: "item.createdAt",
+			now,
+		});
+
+		expect(result?.toISOString()).toBe("2026-04-13T10:00:00.000Z");
+	});
+
+	it("accepts timestamps exactly at the future boundary", () => {
+		const result = normalizeClientTimelineItemCreatedAt({
+			createdAt: new Date(
+				now.getTime() + CLIENT_TIMELINE_ITEM_CREATED_AT_MAX_FUTURE_SKEW_MS
+			).toISOString(),
+			field: "item.createdAt",
+			now,
+		});
+
+		expect(result?.toISOString()).toBe("2026-04-17T10:05:00.000Z");
+	});
+
+	it("rejects timestamps beyond the future boundary", () => {
+		expect(() =>
+			normalizeClientTimelineItemCreatedAt({
+				createdAt: new Date(
+					now.getTime() + CLIENT_TIMELINE_ITEM_CREATED_AT_MAX_FUTURE_SKEW_MS + 1
+				).toISOString(),
+				field: "item.createdAt",
+				now,
+			})
+		).toThrow(ClientTimelineItemCreatedAtValidationError);
+	});
+});

apps/api/src/rest/client-timeline-item-created-at.ts

@@ -0,0 +1,40 @@
+export const CLIENT_TIMELINE_ITEM_CREATED_AT_MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
+
+export class ClientTimelineItemCreatedAtValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ClientTimelineItemCreatedAtValidationError";
+	}
+}
+
+export function normalizeClientTimelineItemCreatedAt(params: {
+	createdAt?: string | Date;
+	field: string;
+	now?: Date;
+}): Date | undefined {
+	const { createdAt, field, now = new Date() } = params;
+
+	if (createdAt === undefined) {
+		return;
+	}
+
+	const normalizedDate =
+		createdAt instanceof Date ? createdAt : new Date(createdAt);
+
+	if (Number.isNaN(normalizedDate.getTime())) {
+		throw new ClientTimelineItemCreatedAtValidationError(
+			`${field} must be a valid RFC 3339 / ISO 8601 timestamp.`
+		);
+	}
+
+	if (
+		normalizedDate.getTime() >
+		now.getTime() + CLIENT_TIMELINE_ITEM_CREATED_AT_MAX_FUTURE_SKEW_MS
+	) {
+		throw new ClientTimelineItemCreatedAtValidationError(
+			`${field} cannot be more than 5 minutes in the future.`
+		);
+	}
+
+	return normalizedDate;
+}

apps/api/src/rest/openapi-contract.test.ts

@@ -6,6 +6,7 @@ import {
 	createConversationRequestSchema,
 	getConversationResponseSchema,
 } from "@cossistant/types/api/conversation";
+import { sendTimelineItemRequestSchema } from "@cossistant/types/api/timeline-item";
 import { OpenAPIHono } from "@hono/zod-openapi";
 import {
 	actorUserIdHeader,
@@ -50,10 +51,13 @@ type OpenAPIMetadataSchema = {
 };
 
 type OpenAPISchemaWithProperties = {
+	type?: string | string[];
+	description?: string;
 	properties?: Record<
 		string,
 		OpenAPIMetadataSchema | OpenAPISchemaWithProperties
 	>;
+	items?: OpenAPISchemaWithProperties;
 	required?: string[];
 };
 
@@ -288,6 +292,129 @@ describe("REST OpenAPI contract guards", () => {
 		expect(responseValueTypes).toEqual(["boolean", "null", "number", "string"]);
 	});
 
+	it("documents client timeline item inputs and createdAt rules for conversation bootstrap and message sends", () => {
+		const app = new OpenAPIHono();
+
+		app.openapi(
+			{
+				method: "post",
+				path: "/conversations",
+				request: {
+					body: {
+						required: true,
+						content: {
+							"application/json": {
+								schema: createConversationRequestSchema,
+							},
+						},
+					},
+				},
+				responses: {
+					200: {
+						description: "Conversation created",
+					},
+				},
+			},
+			(() => new Response(null)) as never
+		);
+
+		app.openapi(
+			{
+				method: "post",
+				path: "/messages",
+				request: {
+					body: {
+						required: true,
+						content: {
+							"application/json": {
+								schema: sendTimelineItemRequestSchema,
+							},
+						},
+					},
+				},
+				responses: {
+					200: {
+						description: "Timeline item created",
+					},
+				},
+			},
+			(() => new Response(null)) as never
+		);
+
+		const doc = app.getOpenAPI31Document({
+			openapi: "3.1.0",
+			info: {
+				title: "OpenAPI timeline input contract test",
+				version: "1.0.0",
+			},
+		});
+
+		const createPath = doc.paths?.["/conversations"]?.post;
+		const createRequestBody = createPath?.requestBody as
+			| OpenAPIJsonContent
+			| undefined;
+		const createRequestSchema = createRequestBody?.content?.["application/json"]
+			?.schema as OpenAPISchemaWithProperties | undefined;
+		const defaultTimelineItemsSchema = createRequestSchema?.properties
+			?.defaultTimelineItems as OpenAPISchemaWithProperties | undefined;
+		const defaultTimelineItemInput = defaultTimelineItemsSchema?.items;
+		const createCreatedAtSchema = defaultTimelineItemInput?.properties
+			?.createdAt as OpenAPIMetadataSchema | undefined;
+
+		const messagesPath = doc.paths?.["/messages"]?.post;
+		const messagesRequestBody = messagesPath?.requestBody as
+			| OpenAPIJsonContent
+			| undefined;
+		const messagesRequestSchema = messagesRequestBody?.content?.[
+			"application/json"
+		]?.schema as OpenAPISchemaWithProperties | undefined;
+		const messageItemInput = messagesRequestSchema?.properties?.item as
+			| OpenAPISchemaWithProperties
+			| undefined;
+		const messageCreatedAtSchema = messageItemInput?.properties?.createdAt as
+			| OpenAPIMetadataSchema
+			| undefined;
+
+		expect(defaultTimelineItemInput?.properties).not.toHaveProperty(
+			"conversationId"
+		);
+		expect(defaultTimelineItemInput?.properties).not.toHaveProperty(
+			"organizationId"
+		);
+		expect(defaultTimelineItemInput?.properties).not.toHaveProperty(
+			"deletedAt"
+		);
+		expect(defaultTimelineItemInput?.required ?? []).not.toContain(
+			"conversationId"
+		);
+		expect(defaultTimelineItemInput?.required ?? []).not.toContain(
+			"organizationId"
+		);
+		expect(defaultTimelineItemInput?.required ?? []).not.toContain("deletedAt");
+		expect(createCreatedAtSchema?.description).toContain(
+			"server assigns the timestamp"
+		);
+		expect(createCreatedAtSchema?.description).toContain(
+			"Historical timestamps are allowed"
+		);
+		expect(createCreatedAtSchema?.description).toContain(
+			"more than 5 minutes in the future are rejected"
+		);
+
+		expect(messageItemInput?.properties).not.toHaveProperty("conversationId");
+		expect(messageItemInput?.properties).not.toHaveProperty("organizationId");
+		expect(messageItemInput?.properties).not.toHaveProperty("deletedAt");
+		expect(messageCreatedAtSchema?.description).toContain(
+			"server assigns the timestamp"
+		);
+		expect(messageCreatedAtSchema?.description).toContain(
+			"Historical timestamps are allowed"
+		);
+		expect(messageCreatedAtSchema?.description).toContain(
+			"more than 5 minutes in the future are rejected"
+		);
+	});
+
 	it("documents contact identify visitorId precedence between body and X-Visitor-Id", () => {
 		const app = new OpenAPIHono();
 

apps/api/src/rest/routers/conversation-create.test.ts

@@ -634,6 +634,96 @@ describe("POST /v1/conversations", () => {
 		expect(payload.conversation.channel).toBe("widget");
 	});
 
+	it("returns 400 when a default timeline item createdAt is more than 5 minutes in the future", async () => {
+		const dbHarness = createDbHarness({});
+		safelyExtractRequestDataMock.mockResolvedValue({
+			db: dbHarness.db,
+			website: baseWebsite,
+			organization: baseOrganization,
+			visitorIdHeader: "visitor-1",
+			body: {
+				conversationId: "conv-1",
+				visitorId: "visitor-1",
+				defaultTimelineItems: [
+					{
+						type: "message",
+						text: "hello",
+						parts: [{ type: "text", text: "hello" }],
+						visibility: "public",
+						userId: null,
+						visitorId: "visitor-1",
+						aiAgentId: null,
+						createdAt: "3026-02-26T00:00:00.000Z",
+						deletedAt: null,
+					},
+				],
+				channel: "widget",
+			},
+		});
+
+		const { conversationRouter } = await conversationRouterModulePromise;
+		const response = await conversationRouter.request(
+			createValidConversationPostRequest()
+		);
+		const payload = (await response.json()) as {
+			error: string;
+			message: string;
+		};
+
+		expect(response.status).toBe(400);
+		expect(payload).toEqual({
+			error: "BAD_REQUEST",
+			message:
+				"defaultTimelineItems[0].createdAt cannot be more than 5 minutes in the future.",
+		});
+		expect(getVisitorMock).not.toHaveBeenCalled();
+		expect(upsertConversationMock).not.toHaveBeenCalled();
+		expect(createMessageTimelineItemMock).not.toHaveBeenCalled();
+	});
+
+	it("falls back to the server timestamp when a default timeline item omits createdAt", async () => {
+		const dbHarness = createDbHarness({});
+		safelyExtractRequestDataMock.mockResolvedValue({
+			db: dbHarness.db,
+			website: baseWebsite,
+			organization: baseOrganization,
+			visitorIdHeader: "visitor-1",
+			body: {
+				conversationId: "conv-1",
+				visitorId: "visitor-1",
+				defaultTimelineItems: [
+					{
+						type: "message",
+						text: "hello",
+						parts: [{ type: "text", text: "hello" }],
+						visibility: "public",
+						userId: null,
+						visitorId: "visitor-1",
+						aiAgentId: null,
+						deletedAt: null,
+					},
+				],
+				channel: "widget",
+			},
+		});
+		upsertConversationMock.mockResolvedValue({
+			status: "created",
+			conversation: baseConversation,
+		});
+
+		const { conversationRouter } = await conversationRouterModulePromise;
+		const response = await conversationRouter.request(
+			createValidConversationPostRequest()
+		);
+
+		expect(response.status).toBe(200);
+		expect(createMessageTimelineItemMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				createdAt: undefined,
+			})
+		);
+	});
+
 	it("returns 409 when conversationId belongs to another owner tuple", async () => {
 		const dbHarness = createDbHarness({});
 		safelyExtractRequestDataMock.mockResolvedValue({