@c15t/backend 1.8.0 → 2.0.0-rc.1

package/src/db/registry/subject.test.ts

@@ -0,0 +1,388 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Subject } from '../schema';
+import { subjectRegistry } from './subject';
+import type { Registry } from './types';
+
+// Mock generateUniqueId to return a predictable value for assertions
+vi.mock('./utils/generate-id', () => ({
+	generateUniqueId: vi.fn().mockResolvedValue('sub_test_123'),
+}));
+
+describe('subjectRegistry', () => {
+	const mockLogger = {
+		debug: vi.fn(),
+		error: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+	};
+
+	const createMockSubject = (overrides: Partial<Subject> = {}): Subject => ({
+		id: 'sub_test_123',
+		isIdentified: false,
+		externalId: null,
+		identityProvider: 'anonymous',
+		createdAt: new Date('2024-01-01T00:00:00.000Z'),
+		updatedAt: new Date('2024-01-01T00:00:00.000Z'),
+		...overrides,
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	describe('findOrCreateSubject', () => {
+		describe('when subjectId is provided', () => {
+			it('should return existing subject when found', async () => {
+				const mockSubject = createMockSubject({
+					id: 'sub_existing',
+					externalId: 'ext_123',
+					isIdentified: true,
+				});
+
+				const db = {
+					findFirst: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				const result = await registry.findOrCreateSubject({
+					subjectId: 'sub_existing',
+					externalSubjectId: 'ext_123',
+					ipAddress: '192.168.1.1',
+				});
+
+				expect(db.findFirst).toHaveBeenCalledWith('subject', {
+					where: expect.any(Function),
+				});
+
+				expect(result).toEqual(mockSubject);
+			});
+
+			it('should create new subject when subjectId not found', async () => {
+				const createdSubject = createMockSubject({
+					id: 'sub_new',
+					externalId: null,
+					identityProvider: 'anonymous',
+					isIdentified: false,
+				});
+
+				const db = {
+					findFirst: vi.fn().mockResolvedValue(null),
+					create: vi.fn().mockResolvedValue(createdSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				const result = await registry.findOrCreateSubject({
+					subjectId: 'sub_new',
+				});
+
+				expect(db.findFirst).toHaveBeenCalledWith('subject', {
+					where: expect.any(Function),
+				});
+
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_new',
+					externalId: null,
+					identityProvider: 'anonymous',
+					isIdentified: false,
+				});
+
+				expect(result).toEqual(createdSubject);
+			});
+
+			it('should create new subject with externalId when both IDs provided but subject not found', async () => {
+				const createdSubject = createMockSubject({
+					id: 'sub_new',
+					externalId: 'ext_123',
+					identityProvider: 'external',
+					isIdentified: true,
+				});
+
+				const db = {
+					findFirst: vi.fn().mockResolvedValue(null),
+					create: vi.fn().mockResolvedValue(createdSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				const result = await registry.findOrCreateSubject({
+					subjectId: 'sub_new',
+					externalSubjectId: 'ext_123',
+				});
+
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_new',
+					externalId: 'ext_123',
+					identityProvider: 'external',
+					isIdentified: true,
+				});
+
+				expect(result).toEqual(createdSubject);
+			});
+		});
+
+		describe('when only externalSubjectId is provided', () => {
+			it('should create a new subject with external ID', async () => {
+				const mockSubject = createMockSubject({
+					id: 'sub_test_123',
+					externalId: 'ext_existing',
+					identityProvider: 'external',
+					isIdentified: true,
+				});
+
+				const db = {
+					create: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				const result = await registry.findOrCreateSubject({
+					externalSubjectId: 'ext_existing',
+					ipAddress: '192.168.1.200',
+				});
+
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_test_123',
+					externalId: 'ext_existing',
+					identityProvider: 'external',
+					isIdentified: true,
+				});
+
+				expect(result).toEqual(mockSubject);
+				expect(mockLogger.debug).toHaveBeenCalledWith(
+					'Creating subject with external ID (legacy flow)',
+					{ externalSubjectId: 'ext_existing' }
+				);
+			});
+
+			it('should use custom identity provider when specified', async () => {
+				const mockSubject = createMockSubject({
+					id: 'sub_test_123',
+					externalId: 'ext_new',
+					identityProvider: 'google',
+					isIdentified: true,
+				});
+
+				const db = {
+					create: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				const result = await registry.findOrCreateSubject({
+					externalSubjectId: 'ext_new',
+					identityProvider: 'google',
+				});
+
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_test_123',
+					externalId: 'ext_new',
+					identityProvider: 'google',
+					isIdentified: true,
+				});
+
+				expect(result).toEqual(mockSubject);
+			});
+
+			it('should default identityProvider to "external"', async () => {
+				const mockSubject = createMockSubject({
+					externalId: 'ext_test',
+				});
+
+				const db = {
+					create: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				await registry.findOrCreateSubject({
+					externalSubjectId: 'ext_test',
+				});
+
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_test_123',
+					externalId: 'ext_test',
+					identityProvider: 'external',
+					isIdentified: true,
+				});
+			});
+		});
+
+		describe('when no identifiers are provided (anonymous subject)', () => {
+			it('should create a new anonymous subject', async () => {
+				const mockSubject = createMockSubject({
+					externalId: null,
+					isIdentified: false,
+				});
+
+				const db = {
+					create: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				const result = await registry.findOrCreateSubject({
+					ipAddress: '10.0.0.1',
+				});
+
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_test_123',
+					externalId: null,
+					identityProvider: 'anonymous',
+					isIdentified: false,
+				});
+
+				expect(result).toEqual(mockSubject);
+				expect(mockLogger.debug).toHaveBeenCalledWith(
+					'Creating new anonymous subject'
+				);
+			});
+
+			it('should create anonymous subject when no arguments provided', async () => {
+				const mockSubject = createMockSubject({
+					externalId: null,
+					isIdentified: false,
+				});
+
+				const db = {
+					create: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				const result = await registry.findOrCreateSubject({});
+
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_test_123',
+					externalId: null,
+					identityProvider: 'anonymous',
+					isIdentified: false,
+				});
+
+				expect(result).toEqual(mockSubject);
+			});
+		});
+
+		describe('edge cases and error handling', () => {
+			it('should handle empty string externalSubjectId as falsy', async () => {
+				const mockSubject = createMockSubject();
+
+				const db = {
+					create: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				await registry.findOrCreateSubject({
+					externalSubjectId: '',
+				});
+
+				// Should create anonymous subject since empty string is falsy
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_test_123',
+					externalId: null,
+					identityProvider: 'anonymous',
+					isIdentified: false,
+				});
+			});
+
+			it('should handle empty string subjectId as falsy', async () => {
+				const mockSubject = createMockSubject();
+
+				const db = {
+					create: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				await registry.findOrCreateSubject({
+					subjectId: '',
+				});
+
+				// Should create anonymous subject since empty string is falsy
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_test_123',
+					externalId: null,
+					identityProvider: 'anonymous',
+					isIdentified: false,
+				});
+			});
+		});
+
+		describe('database query construction', () => {
+			it('should construct correct findFirst query for subjectId lookup', async () => {
+				const mockSubject = createMockSubject();
+				const db = {
+					findFirst: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				await registry.findOrCreateSubject({
+					subjectId: 'sub_test',
+				});
+
+				expect(db.findFirst).toHaveBeenCalledWith('subject', {
+					where: expect.any(Function),
+				});
+			});
+
+			it('should construct correct create call for externalSubjectId', async () => {
+				const mockSubject = createMockSubject();
+				const db = {
+					create: vi.fn().mockResolvedValue(mockSubject),
+				};
+
+				const registry = subjectRegistry({
+					db,
+					ctx: { logger: mockLogger },
+				} as unknown as Registry);
+
+				await registry.findOrCreateSubject({
+					externalSubjectId: 'ext_test',
+				});
+
+				expect(db.create).toHaveBeenCalledWith('subject', {
+					id: 'sub_test_123',
+					externalId: 'ext_test',
+					identityProvider: 'external',
+					isIdentified: true,
+				});
+			});
+		});
+	});
+});

package/src/db/registry/subject.ts

@@ -0,0 +1,129 @@
+import { withDatabaseSpan } from '~/utils/instrumentation';
+import { getMetrics } from '~/utils/metrics';
+import type { Registry } from './types';
+import { generateUniqueId } from './utils/generate-id';
+
+export function subjectRegistry({ db, ctx }: Registry) {
+	const { logger } = ctx;
+	return {
+		/**
+		 * Finds or creates a subject.
+		 *
+		 * For the subject-centric API (v2.0):
+		 * - subjectId is required and client-generated
+		 * - Creates subject if it doesn't exist with the provided ID
+		 * - externalSubjectId can be provided at creation time
+		 * - Multiple subjects can have the same externalId (1:many relationship)
+		 *
+		 * @param subjectId - Client-generated subject ID (required for v2.0)
+		 * @param externalSubjectId - Optional external user ID from auth system
+		 * @param identityProvider - Optional identity provider name
+		 * @param ipAddress - Client IP address
+		 */
+		findOrCreateSubject: async ({
+			subjectId,
+			externalSubjectId,
+			identityProvider,
+			ipAddress = null,
+		}: {
+			subjectId?: string;
+			externalSubjectId?: string;
+			identityProvider?: string;
+			ipAddress?: string | null;
+		}) => {
+			const start = Date.now();
+			try {
+				const result = await withDatabaseSpan(
+					{ operation: 'findOrCreate', entity: 'subject' },
+					async () => {
+						// If subjectId is provided (v2.0 flow), find or create with that ID
+						if (subjectId) {
+							logger.debug(
+								'Finding/Creating subject with client-generated ID',
+								{
+									subjectId,
+								}
+							);
+
+							// Try to find existing subject
+							const existingSubject = await db.findFirst('subject', {
+								where: (b) => b('id', '=', subjectId),
+							});
+
+							if (existingSubject) {
+								logger.debug('Found existing subject', {
+									subjectId,
+								});
+								return existingSubject;
+							}
+
+							// Create new subject with client-provided ID
+							logger.debug('Creating new subject with client-generated ID', {
+								subjectId,
+							});
+
+							const newSubject = await db.create('subject', {
+								id: subjectId,
+								externalId: externalSubjectId ?? null,
+								identityProvider: externalSubjectId
+									? (identityProvider ?? 'external')
+									: 'anonymous',
+								isIdentified: !!externalSubjectId,
+							});
+
+							logger.debug('Created new subject', {
+								subject: newSubject,
+							});
+
+							return newSubject;
+						}
+
+						// Legacy flow: If only externalSubjectId provided, find or create
+						// Note: This creates a new subject for each call since we don't have a subjectId
+						// With 1:many relationship, we should not upsert by externalId anymore
+						if (externalSubjectId) {
+							logger.debug('Creating subject with external ID (legacy flow)', {
+								externalSubjectId,
+							});
+
+							const subject = await db.create('subject', {
+								id: await generateUniqueId(db, 'subject', ctx),
+								externalId: externalSubjectId,
+								identityProvider: identityProvider ?? 'external',
+								isIdentified: true,
+							});
+
+							return subject;
+						}
+
+						// If no identifiers provided, create an anonymous subject
+						logger?.debug('Creating new anonymous subject');
+						const subject = await db.create('subject', {
+							id: await generateUniqueId(db, 'subject', ctx),
+							externalId: null,
+							identityProvider: 'anonymous',
+							isIdentified: false,
+						});
+
+						logger.debug('Created new anonymous subject', {
+							subject,
+						});
+
+						return subject;
+					}
+				);
+				getMetrics()?.recordDbQuery(
+					{ operation: 'findOrCreate', entity: 'subject' },
+					Date.now() - start
+				);
+				return result;
+			} catch (error) {
+				getMetrics()?.recordDbError({
+					operation: 'findOrCreate',
+					entity: 'subject',
+				});
+				throw error;
+			}
+		},
+	};
+}

package/src/db/registry/types.ts

@@ -0,0 +1,10 @@
+import type { createLogger } from '@c15t/logger';
+import type { InferFumaDB } from 'fumadb';
+import type { LatestDB } from '~/db/schema';
+
+export interface Registry {
+	db: ReturnType<InferFumaDB<typeof LatestDB>['orm']>;
+	ctx: {
+		logger: ReturnType<typeof createLogger>;
+	};
+}