@geekmidas/constructs 10.0.0-alpha.9 → 10.0.0-alpha.91

package/dist/processAudits-BRRVVHUB.mjs

@@ -0,0 +1,131 @@
+//#region src/endpoints/optionalPeers.ts
+/**
+* The optional peers an endpoint needs only for a feature it opted into.
+*
+* `@geekmidas/audit`, `@geekmidas/rate-limit` and `@geekmidas/db` are optional
+* peers of this package: an app that audits nothing, limits nothing and sets
+* no row-level security need not install them. The adaptor every endpoint is
+* served by used to import them at the top, so serving any endpoint needed
+* them all — and a production bundle of an app without them failed to build.
+* They are loaded here, when an endpoint that uses one is served, which is
+* also when the app declaring that endpoint has installed it: an auditor's
+* storage, a rate limit's store and an RLS policy's database come from these
+* packages.
+*
+* The `try` is load-bearing beyond the error it names: a bundler leaves an
+* import it cannot resolve to run time when the import is guarded, and fails
+* the build when it is not.
+*/
+/** An endpoint uses a feature whose optional peer is not installed. */
+var OptionalPeerMissing = class extends Error {
+	packageName;
+	feature;
+	constructor(packageName, feature, cause) {
+		super(`${feature} needs '${packageName}', which could not be loaded. Add it to the dependencies of the app that serves this endpoint.`, { cause });
+		this.packageName = packageName;
+		this.feature = feature;
+		this.name = "OptionalPeerMissing";
+	}
+};
+/** `@geekmidas/audit`, for an endpoint with an auditor. */
+async function loadAudit() {
+	try {
+		return await import("@geekmidas/audit");
+	} catch (cause) {
+		throw new OptionalPeerMissing("@geekmidas/audit", "An endpoint with an auditor", cause);
+	}
+}
+/** `@geekmidas/rate-limit`, for an endpoint with a rate limit. */
+async function loadRateLimit() {
+	try {
+		return await import("@geekmidas/rate-limit");
+	} catch (cause) {
+		throw new OptionalPeerMissing("@geekmidas/rate-limit", "An endpoint with a rate limit", cause);
+	}
+}
+/** `@geekmidas/db/rls`, for an endpoint with row-level security. */
+async function loadRls() {
+	try {
+		return await import("@geekmidas/db/rls");
+	} catch (cause) {
+		throw new OptionalPeerMissing("@geekmidas/db", "An endpoint with row-level security", cause);
+	}
+}
+//#endregion
+//#region src/endpoints/processAudits.ts
+/**
+* Create audit context for handler execution.
+* Returns the auditor and storage for use in the handler.
+*
+* @param endpoint - The endpoint with audit configuration
+* @param serviceDiscovery - Service discovery for getting audit storage
+* @param logger - Logger for debug/error messages
+* @param ctx - Request context for actor extraction
+* @returns Audit context with auditor and storage, or undefined if not configured
+*/
+async function createAuditContext(endpoint, serviceDiscovery, logger, ctx) {
+	if (!endpoint.auditorStorageService) return;
+	const storage = (await serviceDiscovery.register([endpoint.auditorStorageService]))[endpoint.auditorStorageService.serviceName];
+	let actor = {
+		id: "system",
+		type: "system"
+	};
+	if (endpoint.actorExtractor) try {
+		actor = await endpoint.actorExtractor({
+			services: ctx.services,
+			session: ctx.session,
+			header: ctx.header,
+			cookie: ctx.cookie,
+			logger
+		});
+	} catch (error) {
+		logger.error(error, "Failed to extract actor for audits");
+	}
+	const { DefaultAuditor } = await loadAudit();
+	return {
+		auditor: new DefaultAuditor({
+			actor,
+			storage,
+			metadata: {
+				endpoint: endpoint.route,
+				method: endpoint.method
+			}
+		}),
+		storage
+	};
+}
+/**
+* Execute a handler with automatic audit transaction support.
+* If the audit storage provides a withTransaction method, wraps execution
+* in a transaction so audits are atomic with handler's database operations.
+*
+* This is database-agnostic - each storage implementation provides its own
+* transaction handling based on the underlying database (Kysely, Drizzle, etc.).
+*
+* If the db parameter is provided and is already a transaction, the storage
+* will reuse it instead of creating a nested transaction (similar to
+* packages/db/src/kysely.ts#withTransaction).
+*
+* @param auditContext - The audit context from createAuditContext
+* @param handler - The handler function to execute (receives auditor)
+* @param onComplete - Called after handler with response, to process declarative audits
+* @param options - Optional configuration including database connection
+* @returns The handler result
+*/
+async function executeWithAuditTransaction(auditContext, handler, onComplete, options) {
+	if (!auditContext) return handler(void 0);
+	const { auditor, storage } = auditContext;
+	if (storage.withTransaction) return storage.withTransaction(auditor, async () => {
+		const response = await handler(auditor);
+		if (onComplete) await onComplete(response, auditor);
+		return response;
+	}, options?.db);
+	const response = await handler(auditor);
+	if (onComplete) await onComplete(response, auditor);
+	await auditor.flush();
+	return response;
+}
+//#endregion
+export { loadRls as i, executeWithAuditTransaction as n, loadRateLimit as r, createAuditContext as t };
+
+//# sourceMappingURL=processAudits-BRRVVHUB.mjs.map

package/dist/processAudits-BRRVVHUB.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processAudits-BRRVVHUB.mjs","names":[],"sources":["../src/endpoints/optionalPeers.ts","../src/endpoints/processAudits.ts"],"sourcesContent":["/**\n * The optional peers an endpoint needs only for a feature it opted into.\n *\n * `@geekmidas/audit`, `@geekmidas/rate-limit` and `@geekmidas/db` are optional\n * peers of this package: an app that audits nothing, limits nothing and sets\n * no row-level security need not install them. The adaptor every endpoint is\n * served by used to import them at the top, so serving any endpoint needed\n * them all — and a production bundle of an app without them failed to build.\n * They are loaded here, when an endpoint that uses one is served, which is\n * also when the app declaring that endpoint has installed it: an auditor's\n * storage, a rate limit's store and an RLS policy's database come from these\n * packages.\n *\n * The `try` is load-bearing beyond the error it names: a bundler leaves an\n * import it cannot resolve to run time when the import is guarded, and fails\n * the build when it is not.\n */\n\n/** An endpoint uses a feature whose optional peer is not installed. */\nexport class OptionalPeerMissing extends Error {\n\tconstructor(\n\t\treadonly packageName: string,\n\t\treadonly feature: string,\n\t\tcause: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${feature} needs '${packageName}', which could not be loaded. ` +\n\t\t\t\t`Add it to the dependencies of the app that serves this endpoint.`,\n\t\t\t{ cause },\n\t\t);\n\t\tthis.name = 'OptionalPeerMissing';\n\t}\n}\n\n/** `@geekmidas/audit`, for an endpoint with an auditor. */\nexport async function loadAudit(): Promise<typeof import('@geekmidas/audit')> {\n\ttry {\n\t\treturn await import('@geekmidas/audit');\n\t} catch (cause) {\n\t\tthrow new OptionalPeerMissing(\n\t\t\t'@geekmidas/audit',\n\t\t\t'An endpoint with an auditor',\n\t\t\tcause,\n\t\t);\n\t}\n}\n\n/** `@geekmidas/rate-limit`, for an endpoint with a rate limit. */\nexport async function loadRateLimit(): Promise<\n\ttypeof import('@geekmidas/rate-limit')\n> {\n\ttry {\n\t\treturn await import('@geekmidas/rate-limit');\n\t} catch (cause) {\n\t\tthrow new OptionalPeerMissing(\n\t\t\t'@geekmidas/rate-limit',\n\t\t\t'An endpoint with a rate limit',\n\t\t\tcause,\n\t\t);\n\t}\n}\n\n/** `@geekmidas/db/rls`, for an endpoint with row-level security. */\nexport async function loadRls(): Promise<typeof import('@geekmidas/db/rls')> {\n\ttry {\n\t\treturn await import('@geekmidas/db/rls');\n\t} catch (cause) {\n\t\tthrow new OptionalPeerMissing(\n\t\t\t'@geekmidas/db',\n\t\t\t'An endpoint with row-level security',\n\t\t\tcause,\n\t\t);\n\t}\n}\n","import type {\n\tAuditActor,\n\tAuditableAction,\n\tAuditor,\n\tAuditStorage,\n} from '@geekmidas/audit';\nimport type { Logger } from '@geekmidas/logger';\nimport type { InferStandardSchema } from '@geekmidas/schema';\nimport type { Service, ServiceDiscovery } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { ActorExtractor, MappedAudit } from './audit';\nimport type { CookieFn, Endpoint, HeaderFn } from './Endpoint';\nimport { loadAudit } from './optionalPeers';\n\n/**\n * Process declarative audit definitions after successful endpoint execution.\n * Similar to publishConstructEvents for events.\n *\n * @param endpoint - The endpoint with audit configuration\n * @param response - The handler response to generate audit payloads from\n * @param serviceDiscovery - Service discovery for registering audit storage\n * @param logger - Logger for debug/error messages\n * @param ctx - Request context (session, headers, cookies, services)\n * @param existingAuditor - Optional existing auditor instance (e.g., from handler context).\n *                          If provided, uses this auditor (with its stored transaction).\n *                          If not provided, creates a new auditor.\n */\nexport async function processEndpointAudits<\n\tTServices extends Service[] = [],\n\tTSession = unknown,\n\tTLogger extends Logger = Logger,\n\tOutSchema extends StandardSchemaV1 | undefined = undefined,\n\tTAuditStorage extends AuditStorage | undefined = undefined,\n\tTAuditStorageServiceName extends string = string,\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n>(\n\tendpoint: Endpoint<\n\t\tany,\n\t\tany,\n\t\tany,\n\t\tOutSchema,\n\t\tTServices,\n\t\tTLogger,\n\t\tTSession,\n\t\tTAuditStorage,\n\t\tTAuditStorageServiceName,\n\t\tTAuditAction\n\t>,\n\tresponse: InferStandardSchema<OutSchema>,\n\tserviceDiscovery: ServiceDiscovery<any>,\n\tlogger: TLogger,\n\tctx: {\n\t\tsession: TSession;\n\t\theader: HeaderFn;\n\t\tcookie: CookieFn;\n\t\tservices: Record<string, unknown>;\n\t},\n\texistingAuditor?: Auditor<TAuditAction>,\n): Promise<void> {\n\ttry {\n\t\tconst audits = endpoint.audits as MappedAudit<TAuditAction, OutSchema>[];\n\n\t\t// If we have an existing auditor (from handler context), we need to flush\n\t\t// any manual audits it collected, even if there are no declarative audits\n\t\tconst hasExistingRecords =\n\t\t\texistingAuditor && existingAuditor.getRecords().length > 0;\n\n\t\t// Skip if no declarative audits and no existing records to flush\n\t\tif (!audits?.length && !hasExistingRecords) {\n\t\t\tlogger.debug('No audits to process');\n\t\t\treturn;\n\t\t}\n\n\t\t// If no auditor storage service and we have things to process, warn\n\t\tif (!endpoint.auditorStorageService) {\n\t\t\tif (hasExistingRecords || audits?.length) {\n\t\t\t\tlogger.warn('No auditor storage service available');\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\t// Get or create auditor\n\t\tlet auditor: Auditor<TAuditAction>;\n\n\t\tif (existingAuditor) {\n\t\t\t// Use existing auditor (preserves stored transaction and manual audits)\n\t\t\tauditor = existingAuditor;\n\t\t\tlogger.debug('Using existing auditor from handler context');\n\t\t} else {\n\t\t\t// Create new auditor (backward compatibility)\n\t\t\tconst services = await serviceDiscovery.register([\n\t\t\t\tendpoint.auditorStorageService,\n\t\t\t]);\n\t\t\tconst storage = services[\n\t\t\t\tendpoint.auditorStorageService.serviceName\n\t\t\t] as AuditStorage;\n\n\t\t\t// Extract actor if configured\n\t\t\tlet actor: AuditActor = { id: 'system', type: 'system' };\n\t\t\tif (endpoint.actorExtractor) {\n\t\t\t\ttry {\n\t\t\t\t\tactor = await (\n\t\t\t\t\t\tendpoint.actorExtractor as ActorExtractor<\n\t\t\t\t\t\t\tTServices,\n\t\t\t\t\t\t\tTSession,\n\t\t\t\t\t\t\tTLogger\n\t\t\t\t\t\t>\n\t\t\t\t\t)({\n\t\t\t\t\t\tservices: ctx.services as any,\n\t\t\t\t\t\tsession: ctx.session,\n\t\t\t\t\t\theader: ctx.header,\n\t\t\t\t\t\tcookie: ctx.cookie,\n\t\t\t\t\t\tlogger,\n\t\t\t\t\t});\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlogger.error(error as Error, 'Failed to extract actor for audits');\n\t\t\t\t\t// Continue with system actor\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst { DefaultAuditor } = await loadAudit();\n\t\t\tauditor = new DefaultAuditor<TAuditAction>({\n\t\t\t\tactor,\n\t\t\t\tstorage,\n\t\t\t\tmetadata: {\n\t\t\t\t\tendpoint: endpoint.route,\n\t\t\t\t\tmethod: endpoint.method,\n\t\t\t\t},\n\t\t\t});\n\t\t}\n\n\t\t// Process each declarative audit\n\t\tif (audits?.length) {\n\t\t\tfor (const audit of audits) {\n\t\t\t\tlogger.debug({ audit: audit.type }, 'Processing declarative audit');\n\n\t\t\t\t// Check when condition\n\t\t\t\tif (audit.when && !audit.when(response as any)) {\n\t\t\t\t\tlogger.debug(\n\t\t\t\t\t\t{ audit: audit.type },\n\t\t\t\t\t\t'Audit skipped due to when condition',\n\t\t\t\t\t);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\n\t\t\t\t// Extract payload\n\t\t\t\tconst payload = audit.payload(response as any);\n\n\t\t\t\t// Extract entityId if configured\n\t\t\t\tconst entityId = audit.entityId?.(response as any);\n\n\t\t\t\t// Record the audit\n\t\t\t\tauditor.audit(audit.type as any, payload as any, {\n\t\t\t\t\ttable: audit.table,\n\t\t\t\t\tentityId,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\t// Flush audits to storage\n\t\t// Note: If existingAuditor has a stored transaction (via setTransaction),\n\t\t// flush() will use it automatically\n\t\tconst recordCount = auditor.getRecords().length;\n\t\tif (recordCount > 0) {\n\t\t\t// Check if auditor has a stored transaction (for logging purposes)\n\t\t\tconst trx =\n\t\t\t\t'getTransaction' in auditor\n\t\t\t\t\t? (auditor as { getTransaction(): unknown }).getTransaction()\n\t\t\t\t\t: undefined;\n\t\t\tlogger.debug(\n\t\t\t\t{ auditCount: recordCount, hasTransaction: !!trx },\n\t\t\t\t'Flushing audits',\n\t\t\t);\n\t\t\tawait auditor.flush();\n\t\t}\n\t} catch (error) {\n\t\tlogger.error(error as Error, 'Failed to process audits');\n\t\t// Don't rethrow - audit failures shouldn't fail the request\n\t}\n}\n\n/**\n * Context for audit-aware handler execution.\n */\nexport interface AuditExecutionContext<\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n> {\n\t/** The auditor instance for recording audits */\n\tauditor: Auditor<TAuditAction>;\n\t/** The audit storage instance */\n\tstorage: AuditStorage;\n}\n\n/**\n * Create audit context for handler execution.\n * Returns the auditor and storage for use in the handler.\n *\n * @param endpoint - The endpoint with audit configuration\n * @param serviceDiscovery - Service discovery for getting audit storage\n * @param logger - Logger for debug/error messages\n * @param ctx - Request context for actor extraction\n * @returns Audit context with auditor and storage, or undefined if not configured\n */\nexport async function createAuditContext<\n\tTServices extends Service[] = [],\n\tTSession = unknown,\n\tTLogger extends Logger = Logger,\n\tTAuditStorage extends AuditStorage | undefined = undefined,\n\tTAuditStorageServiceName extends string = string,\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n\tTDatabase = undefined,\n\tTDatabaseServiceName extends string = string,\n>(\n\tendpoint: Endpoint<\n\t\tany,\n\t\tany,\n\t\tany,\n\t\tany,\n\t\tTServices,\n\t\tTLogger,\n\t\tTSession,\n\t\tTAuditStorage,\n\t\tTAuditStorageServiceName,\n\t\tTAuditAction,\n\t\tTDatabase,\n\t\tTDatabaseServiceName\n\t>,\n\tserviceDiscovery: ServiceDiscovery<any>,\n\tlogger: TLogger,\n\tctx: {\n\t\tsession: TSession;\n\t\theader: HeaderFn;\n\t\tcookie: CookieFn;\n\t\tservices: Record<string, unknown>;\n\t},\n): Promise<AuditExecutionContext<TAuditAction> | undefined> {\n\tif (!endpoint.auditorStorageService) {\n\t\treturn undefined;\n\t}\n\n\tconst services = await serviceDiscovery.register([\n\t\tendpoint.auditorStorageService,\n\t]);\n\tconst storage = services[\n\t\tendpoint.auditorStorageService.serviceName\n\t] as AuditStorage;\n\n\t// Extract actor if configured\n\tlet actor: AuditActor = { id: 'system', type: 'system' };\n\tif (endpoint.actorExtractor) {\n\t\ttry {\n\t\t\tactor = await (\n\t\t\t\tendpoint.actorExtractor as ActorExtractor<TServices, TSession, TLogger>\n\t\t\t)({\n\t\t\t\tservices: ctx.services as any,\n\t\t\t\tsession: ctx.session,\n\t\t\t\theader: ctx.header,\n\t\t\t\tcookie: ctx.cookie,\n\t\t\t\tlogger,\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tlogger.error(error as Error, 'Failed to extract actor for audits');\n\t\t}\n\t}\n\n\tconst { DefaultAuditor } = await loadAudit();\n\tconst auditor = new DefaultAuditor<TAuditAction>({\n\t\tactor,\n\t\tstorage,\n\t\tmetadata: {\n\t\t\tendpoint: endpoint.route,\n\t\t\tmethod: endpoint.method,\n\t\t},\n\t});\n\n\treturn { auditor, storage };\n}\n\n/**\n * Options for executeWithAuditTransaction.\n */\nexport interface ExecuteWithAuditTransactionOptions {\n\t/**\n\t * Database connection to use for the transaction.\n\t * If this is already a transaction, it will be reused instead of creating a nested one.\n\t * If not provided, the storage's internal database is used.\n\t */\n\tdb?: unknown;\n}\n\n/**\n * Execute a handler with automatic audit transaction support.\n * If the audit storage provides a withTransaction method, wraps execution\n * in a transaction so audits are atomic with handler's database operations.\n *\n * This is database-agnostic - each storage implementation provides its own\n * transaction handling based on the underlying database (Kysely, Drizzle, etc.).\n *\n * If the db parameter is provided and is already a transaction, the storage\n * will reuse it instead of creating a nested transaction (similar to\n * packages/db/src/kysely.ts#withTransaction).\n *\n * @param auditContext - The audit context from createAuditContext\n * @param handler - The handler function to execute (receives auditor)\n * @param onComplete - Called after handler with response, to process declarative audits\n * @param options - Optional configuration including database connection\n * @returns The handler result\n */\nexport async function executeWithAuditTransaction<\n\tT,\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n>(\n\tauditContext: AuditExecutionContext<TAuditAction> | undefined,\n\thandler: (auditor?: Auditor<TAuditAction>) => Promise<T>,\n\tonComplete?: (response: T, auditor: Auditor<TAuditAction>) => Promise<void>,\n\toptions?: ExecuteWithAuditTransactionOptions,\n): Promise<T> {\n\t// No audit context - just run handler\n\tif (!auditContext) {\n\t\treturn handler(undefined);\n\t}\n\n\tconst { auditor, storage } = auditContext;\n\n\t// Check if storage provides a transaction wrapper\n\tif (storage.withTransaction) {\n\t\t// Wrap in transaction - audits are atomic with handler operations\n\t\t// The storage's withTransaction handles setTransaction and flush\n\t\t// Pass db so existing transactions are reused\n\t\treturn storage.withTransaction(\n\t\t\tauditor,\n\t\t\tasync () => {\n\t\t\t\tconst response = await handler(auditor);\n\n\t\t\t\t// Process declarative audits within the transaction\n\t\t\t\tif (onComplete) {\n\t\t\t\t\tawait onComplete(response, auditor);\n\t\t\t\t}\n\n\t\t\t\treturn response;\n\t\t\t},\n\t\t\toptions?.db,\n\t\t);\n\t}\n\n\t// No transaction support - run handler and flush audits after\n\tconst response = await handler(auditor);\n\n\tif (onComplete) {\n\t\tawait onComplete(response, auditor);\n\t}\n\n\t// Flush audits (no transaction)\n\tawait auditor.flush();\n\n\treturn response;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,IAAa,sBAAb,cAAyC,MAAM;CAEpC;CACA;CAFV,YACC,aACA,SACA,OACC;EACD,MACC,GAAG,QAAQ,UAAU,YAAY,iGAEjC,EAAE,MAAM,CACT;EARS,KAAA,cAAA;EACA,KAAA,UAAA;EAQT,KAAK,OAAO;CACb;AACD;;AAGA,eAAsB,YAAwD;CAC7E,IAAI;EACH,OAAO,MAAM,OAAO;CACrB,SAAS,OAAO;EACf,MAAM,IAAI,oBACT,oBACA,+BACA,KACD;CACD;AACD;;AAGA,eAAsB,gBAEpB;CACD,IAAI;EACH,OAAO,MAAM,OAAO;CACrB,SAAS,OAAO;EACf,MAAM,IAAI,oBACT,yBACA,iCACA,KACD;CACD;AACD;;AAGA,eAAsB,UAAuD;CAC5E,IAAI;EACH,OAAO,MAAM,OAAO;CACrB,SAAS,OAAO;EACf,MAAM,IAAI,oBACT,iBACA,uCACA,KACD;CACD;AACD;;;;;;;;;;;;;ACwIA,eAAsB,mBAarB,UAcA,kBACA,QACA,KAM2D;CAC3D,IAAI,CAAC,SAAS,uBACb;CAMD,MAAM,WAAU,MAHO,iBAAiB,SAAS,CAChD,SAAS,qBACV,CAAC,EAAA,CAEA,SAAS,sBAAsB;CAIhC,IAAI,QAAoB;EAAE,IAAI;EAAU,MAAM;CAAS;CACvD,IAAI,SAAS,gBACZ,IAAI;EACH,QAAQ,MACP,SAAS,eACR;GACD,UAAU,IAAI;GACd,SAAS,IAAI;GACb,QAAQ,IAAI;GACZ,QAAQ,IAAI;GACZ;EACD,CAAC;CACF,SAAS,OAAO;EACf,OAAO,MAAM,OAAgB,oCAAoC;CAClE;CAGD,MAAM,EAAE,mBAAmB,MAAM,UAAU;CAU3C,OAAO;EAAE,SAAA,IATW,eAA6B;GAChD;GACA;GACA,UAAU;IACT,UAAU,SAAS;IACnB,QAAQ,SAAS;GAClB;EACD,CAEe;EAAG;CAAQ;AAC3B;;;;;;;;;;;;;;;;;;;AAgCA,eAAsB,4BAOrB,cACA,SACA,YACA,SACa;CAEb,IAAI,CAAC,cACJ,OAAO,QAAQ,KAAA,CAAS;CAGzB,MAAM,EAAE,SAAS,YAAY;CAG7B,IAAI,QAAQ,iBAIX,OAAO,QAAQ,gBACd,SACA,YAAY;EACX,MAAM,WAAW,MAAM,QAAQ,OAAO;EAGtC,IAAI,YACH,MAAM,WAAW,UAAU,OAAO;EAGnC,OAAO;CACR,GACA,SAAS,EACV;CAID,MAAM,WAAW,MAAM,QAAQ,OAAO;CAEtC,IAAI,YACH,MAAM,WAAW,UAAU,OAAO;CAInC,MAAM,QAAQ,MAAM;CAEpB,OAAO;AACR"}

package/dist/processAudits-DasOZjPl.cjs

@@ -0,0 +1,154 @@
+//#region src/endpoints/optionalPeers.ts
+/**
+* The optional peers an endpoint needs only for a feature it opted into.
+*
+* `@geekmidas/audit`, `@geekmidas/rate-limit` and `@geekmidas/db` are optional
+* peers of this package: an app that audits nothing, limits nothing and sets
+* no row-level security need not install them. The adaptor every endpoint is
+* served by used to import them at the top, so serving any endpoint needed
+* them all — and a production bundle of an app without them failed to build.
+* They are loaded here, when an endpoint that uses one is served, which is
+* also when the app declaring that endpoint has installed it: an auditor's
+* storage, a rate limit's store and an RLS policy's database come from these
+* packages.
+*
+* The `try` is load-bearing beyond the error it names: a bundler leaves an
+* import it cannot resolve to run time when the import is guarded, and fails
+* the build when it is not.
+*/
+/** An endpoint uses a feature whose optional peer is not installed. */
+var OptionalPeerMissing = class extends Error {
+	packageName;
+	feature;
+	constructor(packageName, feature, cause) {
+		super(`${feature} needs '${packageName}', which could not be loaded. Add it to the dependencies of the app that serves this endpoint.`, { cause });
+		this.packageName = packageName;
+		this.feature = feature;
+		this.name = "OptionalPeerMissing";
+	}
+};
+/** `@geekmidas/audit`, for an endpoint with an auditor. */
+async function loadAudit() {
+	try {
+		return await import("@geekmidas/audit");
+	} catch (cause) {
+		throw new OptionalPeerMissing("@geekmidas/audit", "An endpoint with an auditor", cause);
+	}
+}
+/** `@geekmidas/rate-limit`, for an endpoint with a rate limit. */
+async function loadRateLimit() {
+	try {
+		return await import("@geekmidas/rate-limit");
+	} catch (cause) {
+		throw new OptionalPeerMissing("@geekmidas/rate-limit", "An endpoint with a rate limit", cause);
+	}
+}
+/** `@geekmidas/db/rls`, for an endpoint with row-level security. */
+async function loadRls() {
+	try {
+		return await import("@geekmidas/db/rls");
+	} catch (cause) {
+		throw new OptionalPeerMissing("@geekmidas/db", "An endpoint with row-level security", cause);
+	}
+}
+//#endregion
+//#region src/endpoints/processAudits.ts
+/**
+* Create audit context for handler execution.
+* Returns the auditor and storage for use in the handler.
+*
+* @param endpoint - The endpoint with audit configuration
+* @param serviceDiscovery - Service discovery for getting audit storage
+* @param logger - Logger for debug/error messages
+* @param ctx - Request context for actor extraction
+* @returns Audit context with auditor and storage, or undefined if not configured
+*/
+async function createAuditContext(endpoint, serviceDiscovery, logger, ctx) {
+	if (!endpoint.auditorStorageService) return;
+	const storage = (await serviceDiscovery.register([endpoint.auditorStorageService]))[endpoint.auditorStorageService.serviceName];
+	let actor = {
+		id: "system",
+		type: "system"
+	};
+	if (endpoint.actorExtractor) try {
+		actor = await endpoint.actorExtractor({
+			services: ctx.services,
+			session: ctx.session,
+			header: ctx.header,
+			cookie: ctx.cookie,
+			logger
+		});
+	} catch (error) {
+		logger.error(error, "Failed to extract actor for audits");
+	}
+	const { DefaultAuditor } = await loadAudit();
+	return {
+		auditor: new DefaultAuditor({
+			actor,
+			storage,
+			metadata: {
+				endpoint: endpoint.route,
+				method: endpoint.method
+			}
+		}),
+		storage
+	};
+}
+/**
+* Execute a handler with automatic audit transaction support.
+* If the audit storage provides a withTransaction method, wraps execution
+* in a transaction so audits are atomic with handler's database operations.
+*
+* This is database-agnostic - each storage implementation provides its own
+* transaction handling based on the underlying database (Kysely, Drizzle, etc.).
+*
+* If the db parameter is provided and is already a transaction, the storage
+* will reuse it instead of creating a nested transaction (similar to
+* packages/db/src/kysely.ts#withTransaction).
+*
+* @param auditContext - The audit context from createAuditContext
+* @param handler - The handler function to execute (receives auditor)
+* @param onComplete - Called after handler with response, to process declarative audits
+* @param options - Optional configuration including database connection
+* @returns The handler result
+*/
+async function executeWithAuditTransaction(auditContext, handler, onComplete, options) {
+	if (!auditContext) return handler(void 0);
+	const { auditor, storage } = auditContext;
+	if (storage.withTransaction) return storage.withTransaction(auditor, async () => {
+		const response = await handler(auditor);
+		if (onComplete) await onComplete(response, auditor);
+		return response;
+	}, options?.db);
+	const response = await handler(auditor);
+	if (onComplete) await onComplete(response, auditor);
+	await auditor.flush();
+	return response;
+}
+//#endregion
+Object.defineProperty(exports, "createAuditContext", {
+	enumerable: true,
+	get: function() {
+		return createAuditContext;
+	}
+});
+Object.defineProperty(exports, "executeWithAuditTransaction", {
+	enumerable: true,
+	get: function() {
+		return executeWithAuditTransaction;
+	}
+});
+Object.defineProperty(exports, "loadRateLimit", {
+	enumerable: true,
+	get: function() {
+		return loadRateLimit;
+	}
+});
+Object.defineProperty(exports, "loadRls", {
+	enumerable: true,
+	get: function() {
+		return loadRls;
+	}
+});
+
+//# sourceMappingURL=processAudits-DasOZjPl.cjs.map

package/dist/processAudits-DasOZjPl.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processAudits-DasOZjPl.cjs","names":[],"sources":["../src/endpoints/optionalPeers.ts","../src/endpoints/processAudits.ts"],"sourcesContent":["/**\n * The optional peers an endpoint needs only for a feature it opted into.\n *\n * `@geekmidas/audit`, `@geekmidas/rate-limit` and `@geekmidas/db` are optional\n * peers of this package: an app that audits nothing, limits nothing and sets\n * no row-level security need not install them. The adaptor every endpoint is\n * served by used to import them at the top, so serving any endpoint needed\n * them all — and a production bundle of an app without them failed to build.\n * They are loaded here, when an endpoint that uses one is served, which is\n * also when the app declaring that endpoint has installed it: an auditor's\n * storage, a rate limit's store and an RLS policy's database come from these\n * packages.\n *\n * The `try` is load-bearing beyond the error it names: a bundler leaves an\n * import it cannot resolve to run time when the import is guarded, and fails\n * the build when it is not.\n */\n\n/** An endpoint uses a feature whose optional peer is not installed. */\nexport class OptionalPeerMissing extends Error {\n\tconstructor(\n\t\treadonly packageName: string,\n\t\treadonly feature: string,\n\t\tcause: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${feature} needs '${packageName}', which could not be loaded. ` +\n\t\t\t\t`Add it to the dependencies of the app that serves this endpoint.`,\n\t\t\t{ cause },\n\t\t);\n\t\tthis.name = 'OptionalPeerMissing';\n\t}\n}\n\n/** `@geekmidas/audit`, for an endpoint with an auditor. */\nexport async function loadAudit(): Promise<typeof import('@geekmidas/audit')> {\n\ttry {\n\t\treturn await import('@geekmidas/audit');\n\t} catch (cause) {\n\t\tthrow new OptionalPeerMissing(\n\t\t\t'@geekmidas/audit',\n\t\t\t'An endpoint with an auditor',\n\t\t\tcause,\n\t\t);\n\t}\n}\n\n/** `@geekmidas/rate-limit`, for an endpoint with a rate limit. */\nexport async function loadRateLimit(): Promise<\n\ttypeof import('@geekmidas/rate-limit')\n> {\n\ttry {\n\t\treturn await import('@geekmidas/rate-limit');\n\t} catch (cause) {\n\t\tthrow new OptionalPeerMissing(\n\t\t\t'@geekmidas/rate-limit',\n\t\t\t'An endpoint with a rate limit',\n\t\t\tcause,\n\t\t);\n\t}\n}\n\n/** `@geekmidas/db/rls`, for an endpoint with row-level security. */\nexport async function loadRls(): Promise<typeof import('@geekmidas/db/rls')> {\n\ttry {\n\t\treturn await import('@geekmidas/db/rls');\n\t} catch (cause) {\n\t\tthrow new OptionalPeerMissing(\n\t\t\t'@geekmidas/db',\n\t\t\t'An endpoint with row-level security',\n\t\t\tcause,\n\t\t);\n\t}\n}\n","import type {\n\tAuditActor,\n\tAuditableAction,\n\tAuditor,\n\tAuditStorage,\n} from '@geekmidas/audit';\nimport type { Logger } from '@geekmidas/logger';\nimport type { InferStandardSchema } from '@geekmidas/schema';\nimport type { Service, ServiceDiscovery } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { ActorExtractor, MappedAudit } from './audit';\nimport type { CookieFn, Endpoint, HeaderFn } from './Endpoint';\nimport { loadAudit } from './optionalPeers';\n\n/**\n * Process declarative audit definitions after successful endpoint execution.\n * Similar to publishConstructEvents for events.\n *\n * @param endpoint - The endpoint with audit configuration\n * @param response - The handler response to generate audit payloads from\n * @param serviceDiscovery - Service discovery for registering audit storage\n * @param logger - Logger for debug/error messages\n * @param ctx - Request context (session, headers, cookies, services)\n * @param existingAuditor - Optional existing auditor instance (e.g., from handler context).\n *                          If provided, uses this auditor (with its stored transaction).\n *                          If not provided, creates a new auditor.\n */\nexport async function processEndpointAudits<\n\tTServices extends Service[] = [],\n\tTSession = unknown,\n\tTLogger extends Logger = Logger,\n\tOutSchema extends StandardSchemaV1 | undefined = undefined,\n\tTAuditStorage extends AuditStorage | undefined = undefined,\n\tTAuditStorageServiceName extends string = string,\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n>(\n\tendpoint: Endpoint<\n\t\tany,\n\t\tany,\n\t\tany,\n\t\tOutSchema,\n\t\tTServices,\n\t\tTLogger,\n\t\tTSession,\n\t\tTAuditStorage,\n\t\tTAuditStorageServiceName,\n\t\tTAuditAction\n\t>,\n\tresponse: InferStandardSchema<OutSchema>,\n\tserviceDiscovery: ServiceDiscovery<any>,\n\tlogger: TLogger,\n\tctx: {\n\t\tsession: TSession;\n\t\theader: HeaderFn;\n\t\tcookie: CookieFn;\n\t\tservices: Record<string, unknown>;\n\t},\n\texistingAuditor?: Auditor<TAuditAction>,\n): Promise<void> {\n\ttry {\n\t\tconst audits = endpoint.audits as MappedAudit<TAuditAction, OutSchema>[];\n\n\t\t// If we have an existing auditor (from handler context), we need to flush\n\t\t// any manual audits it collected, even if there are no declarative audits\n\t\tconst hasExistingRecords =\n\t\t\texistingAuditor && existingAuditor.getRecords().length > 0;\n\n\t\t// Skip if no declarative audits and no existing records to flush\n\t\tif (!audits?.length && !hasExistingRecords) {\n\t\t\tlogger.debug('No audits to process');\n\t\t\treturn;\n\t\t}\n\n\t\t// If no auditor storage service and we have things to process, warn\n\t\tif (!endpoint.auditorStorageService) {\n\t\t\tif (hasExistingRecords || audits?.length) {\n\t\t\t\tlogger.warn('No auditor storage service available');\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\t// Get or create auditor\n\t\tlet auditor: Auditor<TAuditAction>;\n\n\t\tif (existingAuditor) {\n\t\t\t// Use existing auditor (preserves stored transaction and manual audits)\n\t\t\tauditor = existingAuditor;\n\t\t\tlogger.debug('Using existing auditor from handler context');\n\t\t} else {\n\t\t\t// Create new auditor (backward compatibility)\n\t\t\tconst services = await serviceDiscovery.register([\n\t\t\t\tendpoint.auditorStorageService,\n\t\t\t]);\n\t\t\tconst storage = services[\n\t\t\t\tendpoint.auditorStorageService.serviceName\n\t\t\t] as AuditStorage;\n\n\t\t\t// Extract actor if configured\n\t\t\tlet actor: AuditActor = { id: 'system', type: 'system' };\n\t\t\tif (endpoint.actorExtractor) {\n\t\t\t\ttry {\n\t\t\t\t\tactor = await (\n\t\t\t\t\t\tendpoint.actorExtractor as ActorExtractor<\n\t\t\t\t\t\t\tTServices,\n\t\t\t\t\t\t\tTSession,\n\t\t\t\t\t\t\tTLogger\n\t\t\t\t\t\t>\n\t\t\t\t\t)({\n\t\t\t\t\t\tservices: ctx.services as any,\n\t\t\t\t\t\tsession: ctx.session,\n\t\t\t\t\t\theader: ctx.header,\n\t\t\t\t\t\tcookie: ctx.cookie,\n\t\t\t\t\t\tlogger,\n\t\t\t\t\t});\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlogger.error(error as Error, 'Failed to extract actor for audits');\n\t\t\t\t\t// Continue with system actor\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst { DefaultAuditor } = await loadAudit();\n\t\t\tauditor = new DefaultAuditor<TAuditAction>({\n\t\t\t\tactor,\n\t\t\t\tstorage,\n\t\t\t\tmetadata: {\n\t\t\t\t\tendpoint: endpoint.route,\n\t\t\t\t\tmethod: endpoint.method,\n\t\t\t\t},\n\t\t\t});\n\t\t}\n\n\t\t// Process each declarative audit\n\t\tif (audits?.length) {\n\t\t\tfor (const audit of audits) {\n\t\t\t\tlogger.debug({ audit: audit.type }, 'Processing declarative audit');\n\n\t\t\t\t// Check when condition\n\t\t\t\tif (audit.when && !audit.when(response as any)) {\n\t\t\t\t\tlogger.debug(\n\t\t\t\t\t\t{ audit: audit.type },\n\t\t\t\t\t\t'Audit skipped due to when condition',\n\t\t\t\t\t);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\n\t\t\t\t// Extract payload\n\t\t\t\tconst payload = audit.payload(response as any);\n\n\t\t\t\t// Extract entityId if configured\n\t\t\t\tconst entityId = audit.entityId?.(response as any);\n\n\t\t\t\t// Record the audit\n\t\t\t\tauditor.audit(audit.type as any, payload as any, {\n\t\t\t\t\ttable: audit.table,\n\t\t\t\t\tentityId,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\t// Flush audits to storage\n\t\t// Note: If existingAuditor has a stored transaction (via setTransaction),\n\t\t// flush() will use it automatically\n\t\tconst recordCount = auditor.getRecords().length;\n\t\tif (recordCount > 0) {\n\t\t\t// Check if auditor has a stored transaction (for logging purposes)\n\t\t\tconst trx =\n\t\t\t\t'getTransaction' in auditor\n\t\t\t\t\t? (auditor as { getTransaction(): unknown }).getTransaction()\n\t\t\t\t\t: undefined;\n\t\t\tlogger.debug(\n\t\t\t\t{ auditCount: recordCount, hasTransaction: !!trx },\n\t\t\t\t'Flushing audits',\n\t\t\t);\n\t\t\tawait auditor.flush();\n\t\t}\n\t} catch (error) {\n\t\tlogger.error(error as Error, 'Failed to process audits');\n\t\t// Don't rethrow - audit failures shouldn't fail the request\n\t}\n}\n\n/**\n * Context for audit-aware handler execution.\n */\nexport interface AuditExecutionContext<\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n> {\n\t/** The auditor instance for recording audits */\n\tauditor: Auditor<TAuditAction>;\n\t/** The audit storage instance */\n\tstorage: AuditStorage;\n}\n\n/**\n * Create audit context for handler execution.\n * Returns the auditor and storage for use in the handler.\n *\n * @param endpoint - The endpoint with audit configuration\n * @param serviceDiscovery - Service discovery for getting audit storage\n * @param logger - Logger for debug/error messages\n * @param ctx - Request context for actor extraction\n * @returns Audit context with auditor and storage, or undefined if not configured\n */\nexport async function createAuditContext<\n\tTServices extends Service[] = [],\n\tTSession = unknown,\n\tTLogger extends Logger = Logger,\n\tTAuditStorage extends AuditStorage | undefined = undefined,\n\tTAuditStorageServiceName extends string = string,\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n\tTDatabase = undefined,\n\tTDatabaseServiceName extends string = string,\n>(\n\tendpoint: Endpoint<\n\t\tany,\n\t\tany,\n\t\tany,\n\t\tany,\n\t\tTServices,\n\t\tTLogger,\n\t\tTSession,\n\t\tTAuditStorage,\n\t\tTAuditStorageServiceName,\n\t\tTAuditAction,\n\t\tTDatabase,\n\t\tTDatabaseServiceName\n\t>,\n\tserviceDiscovery: ServiceDiscovery<any>,\n\tlogger: TLogger,\n\tctx: {\n\t\tsession: TSession;\n\t\theader: HeaderFn;\n\t\tcookie: CookieFn;\n\t\tservices: Record<string, unknown>;\n\t},\n): Promise<AuditExecutionContext<TAuditAction> | undefined> {\n\tif (!endpoint.auditorStorageService) {\n\t\treturn undefined;\n\t}\n\n\tconst services = await serviceDiscovery.register([\n\t\tendpoint.auditorStorageService,\n\t]);\n\tconst storage = services[\n\t\tendpoint.auditorStorageService.serviceName\n\t] as AuditStorage;\n\n\t// Extract actor if configured\n\tlet actor: AuditActor = { id: 'system', type: 'system' };\n\tif (endpoint.actorExtractor) {\n\t\ttry {\n\t\t\tactor = await (\n\t\t\t\tendpoint.actorExtractor as ActorExtractor<TServices, TSession, TLogger>\n\t\t\t)({\n\t\t\t\tservices: ctx.services as any,\n\t\t\t\tsession: ctx.session,\n\t\t\t\theader: ctx.header,\n\t\t\t\tcookie: ctx.cookie,\n\t\t\t\tlogger,\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tlogger.error(error as Error, 'Failed to extract actor for audits');\n\t\t}\n\t}\n\n\tconst { DefaultAuditor } = await loadAudit();\n\tconst auditor = new DefaultAuditor<TAuditAction>({\n\t\tactor,\n\t\tstorage,\n\t\tmetadata: {\n\t\t\tendpoint: endpoint.route,\n\t\t\tmethod: endpoint.method,\n\t\t},\n\t});\n\n\treturn { auditor, storage };\n}\n\n/**\n * Options for executeWithAuditTransaction.\n */\nexport interface ExecuteWithAuditTransactionOptions {\n\t/**\n\t * Database connection to use for the transaction.\n\t * If this is already a transaction, it will be reused instead of creating a nested one.\n\t * If not provided, the storage's internal database is used.\n\t */\n\tdb?: unknown;\n}\n\n/**\n * Execute a handler with automatic audit transaction support.\n * If the audit storage provides a withTransaction method, wraps execution\n * in a transaction so audits are atomic with handler's database operations.\n *\n * This is database-agnostic - each storage implementation provides its own\n * transaction handling based on the underlying database (Kysely, Drizzle, etc.).\n *\n * If the db parameter is provided and is already a transaction, the storage\n * will reuse it instead of creating a nested transaction (similar to\n * packages/db/src/kysely.ts#withTransaction).\n *\n * @param auditContext - The audit context from createAuditContext\n * @param handler - The handler function to execute (receives auditor)\n * @param onComplete - Called after handler with response, to process declarative audits\n * @param options - Optional configuration including database connection\n * @returns The handler result\n */\nexport async function executeWithAuditTransaction<\n\tT,\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n>(\n\tauditContext: AuditExecutionContext<TAuditAction> | undefined,\n\thandler: (auditor?: Auditor<TAuditAction>) => Promise<T>,\n\tonComplete?: (response: T, auditor: Auditor<TAuditAction>) => Promise<void>,\n\toptions?: ExecuteWithAuditTransactionOptions,\n): Promise<T> {\n\t// No audit context - just run handler\n\tif (!auditContext) {\n\t\treturn handler(undefined);\n\t}\n\n\tconst { auditor, storage } = auditContext;\n\n\t// Check if storage provides a transaction wrapper\n\tif (storage.withTransaction) {\n\t\t// Wrap in transaction - audits are atomic with handler operations\n\t\t// The storage's withTransaction handles setTransaction and flush\n\t\t// Pass db so existing transactions are reused\n\t\treturn storage.withTransaction(\n\t\t\tauditor,\n\t\t\tasync () => {\n\t\t\t\tconst response = await handler(auditor);\n\n\t\t\t\t// Process declarative audits within the transaction\n\t\t\t\tif (onComplete) {\n\t\t\t\t\tawait onComplete(response, auditor);\n\t\t\t\t}\n\n\t\t\t\treturn response;\n\t\t\t},\n\t\t\toptions?.db,\n\t\t);\n\t}\n\n\t// No transaction support - run handler and flush audits after\n\tconst response = await handler(auditor);\n\n\tif (onComplete) {\n\t\tawait onComplete(response, auditor);\n\t}\n\n\t// Flush audits (no transaction)\n\tawait auditor.flush();\n\n\treturn response;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAmBA,IAAa,sBAAb,cAAyC,MAAM;CAEpC;CACA;CAFV,YACC,aACA,SACA,OACC;EACD,MACC,GAAG,QAAQ,UAAU,YAAY,iGAEjC,EAAE,MAAM,CACT;EARS,KAAA,cAAA;EACA,KAAA,UAAA;EAQT,KAAK,OAAO;CACb;AACD;;AAGA,eAAsB,YAAwD;CAC7E,IAAI;EACH,OAAO,MAAM,OAAO;CACrB,SAAS,OAAO;EACf,MAAM,IAAI,oBACT,oBACA,+BACA,KACD;CACD;AACD;;AAGA,eAAsB,gBAEpB;CACD,IAAI;EACH,OAAO,MAAM,OAAO;CACrB,SAAS,OAAO;EACf,MAAM,IAAI,oBACT,yBACA,iCACA,KACD;CACD;AACD;;AAGA,eAAsB,UAAuD;CAC5E,IAAI;EACH,OAAO,MAAM,OAAO;CACrB,SAAS,OAAO;EACf,MAAM,IAAI,oBACT,iBACA,uCACA,KACD;CACD;AACD;;;;;;;;;;;;;ACwIA,eAAsB,mBAarB,UAcA,kBACA,QACA,KAM2D;CAC3D,IAAI,CAAC,SAAS,uBACb;CAMD,MAAM,WAAU,MAHO,iBAAiB,SAAS,CAChD,SAAS,qBACV,CAAC,EAAA,CAEA,SAAS,sBAAsB;CAIhC,IAAI,QAAoB;EAAE,IAAI;EAAU,MAAM;CAAS;CACvD,IAAI,SAAS,gBACZ,IAAI;EACH,QAAQ,MACP,SAAS,eACR;GACD,UAAU,IAAI;GACd,SAAS,IAAI;GACb,QAAQ,IAAI;GACZ,QAAQ,IAAI;GACZ;EACD,CAAC;CACF,SAAS,OAAO;EACf,OAAO,MAAM,OAAgB,oCAAoC;CAClE;CAGD,MAAM,EAAE,mBAAmB,MAAM,UAAU;CAU3C,OAAO;EAAE,SAAA,IATW,eAA6B;GAChD;GACA;GACA,UAAU;IACT,UAAU,SAAS;IACnB,QAAQ,SAAS;GAClB;EACD,CAEe;EAAG;CAAQ;AAC3B;;;;;;;;;;;;;;;;;;;AAgCA,eAAsB,4BAOrB,cACA,SACA,YACA,SACa;CAEb,IAAI,CAAC,cACJ,OAAO,QAAQ,KAAA,CAAS;CAGzB,MAAM,EAAE,SAAS,YAAY;CAG7B,IAAI,QAAQ,iBAIX,OAAO,QAAQ,gBACd,SACA,YAAY;EACX,MAAM,WAAW,MAAM,QAAQ,OAAO;EAGtC,IAAI,YACH,MAAM,WAAW,UAAU,OAAO;EAGnC,OAAO;CACR,GACA,SAAS,EACV;CAID,MAAM,WAAW,MAAM,QAAQ,OAAO;CAEtC,IAAI,YACH,MAAM,WAAW,UAAU,OAAO;CAInC,MAAM,QAAQ,MAAM;CAEpB,OAAO;AACR"}

package/dist/queue/index.cjs

@@ -1,189 +1,6 @@
-const require_chunk = require('../chunk-DWy1uDak.cjs');
-const require_construct_interface = require('../construct-interface-BfjcOD_E.cjs');
-const require_Construct = require('../Construct-CyS3RpTL.cjs');
-const require_clone = require('../clone-Dy0cR2SZ.cjs');
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const __geekmidas_logger_console = require_chunk.__toESM(require("@geekmidas/logger/console"));
-const __geekmidas_events = require_chunk.__toESM(require("@geekmidas/events"));
-
-//#region src/queue/Queue.ts
-/**
-* A queue worker — a point-to-point SQS-style queue and its single consumer.
-* Unlike a `Subscriber` (topic fan-out, filtered by `subscribedEvents`), a queue
-* drains every message of its one `message` type. Build one with `q` (see
-* `QueueBuilder`); `gkm build` discovers it into the manifest's `queues` field.
-*
-* The producer side is {@link Queue.publisher} — a ready-to-inject `Service`
-* that any endpoint/function drops into `.services([...])` to send messages.
-*/
-var Queue = class extends require_Construct.Construct {
-	__IS_QUEUE__ = true;
-	static isQueue(obj) {
-		return Boolean(obj && obj.__IS_QUEUE__ === true && obj.type === require_Construct.ConstructType.Queue);
-	}
-	/**
-	* The canonical id this queue is declared under.
-	*
-	* Derived from the name rather than given separately, so `emails` and
-	* `Emails` are one queue. The name stays what it was: it is the wire `type`
-	* a producer sends and the worker subscribes to, and changing that would
-	* silently orphan in-flight messages.
-	*/
-	id;
-	/**
-	* The producer's env key. Read by both {@link declare} and
-	* {@link publisher}, so what the target publishes and what the producer
-	* looks up cannot drift.
-	*/
-	connectionKey;
-	constructor(name, handler, messageSchema, timeout = 3e4, services = [], logger = __geekmidas_logger_console.DEFAULT_LOGGER, batchSize, fifo, constructs = []) {
-		super(require_Construct.ConstructType.Queue, logger, services, [], void 0, void 0, timeout, void 0, void 0, constructs);
-		this.name = name;
-		this.handler = handler;
-		this.messageSchema = messageSchema;
-		this.timeout = timeout;
-		this.services = services;
-		this.logger = logger;
-		this.batchSize = batchSize;
-		this.fifo = fifo;
-		this.id = (0, __geekmidas_manifest.canonicalId)(name);
-		this.connectionKey = (0, __geekmidas_manifest.provideKey)(this.id, "publisherConnectionString");
-	}
-	/**
-	* What this queue is in the manifest.
-	*
-	* A queue is a resource, not a handler: the worker is reached *through* it,
-	* so the declaration carries the producer's key and nothing about the code
-	* that drains it. The local target reads this to know which broker has to be
-	* running and what connection string to inject.
-	*/
-	declare() {
-		return [{
-			kind: "queue",
-			id: this.id,
-			provides: [this.connectionKey],
-			...this.fifo ? { fifo: true } : {},
-			worker: {
-				id: `${this.id}Worker`,
-				handler: `${this.id}.handler`,
-				dependencies: []
-			}
-		}];
-	}
-	/**
-	* The producer side — a `Service` exposing an `EventPublisher` typed to this
-	* queue's message. Inject it via `.services([queue.publisher])`; the handler
-	* then calls `services.<name>Publisher.publish([{ type, payload }])`.
-	*
-	* It reads `<NAME>_PUBLISHER_CONNECTION_STRING` and builds the transport from
-	* the URL protocol — `pgboss://` locally, `sqs://` deployed — so the same
-	* code publishes to Postgres in dev and SQS in prod. Because it's a `Service`,
-	* `Construct.getEnvironment()` sniffs it, so the env requirement flows into
-	* the manifest and infra links exactly this queue with least privilege.
-	*/
-	/**
-	* The queue as a dependency — what `.dependsOn([emailsQueue])` dissolves
-	* into, reachable as `services.emails`.
-	*
-	* It is the producer: a consumer is the worker written right here, so the
-	* only thing another construct can want from a queue is the ability to send
-	* to it. {@link publisher} is the same service under its older
-	* `<name>Publisher` key, kept for `.services([queue.publisher])`.
-	*/
-	get service() {
-		const { register } = this.publisher;
-		return {
-			serviceName: (0, __geekmidas_manifest.serviceKey)(this.id),
-			register
-		};
-	}
-	get publisher() {
-		const envVar = this.connectionKey;
-		return {
-			serviceName: `${this.name}Publisher`,
-			async register({ envParser }) {
-				const { connectionString } = envParser.create((get) => ({ connectionString: get(envVar).string() })).parse();
-				return __geekmidas_events.Publisher.fromConnectionString(connectionString);
-			}
-		};
-	}
-};
-
-//#endregion
-//#region src/queue/QueueBuilder.ts
-/**
-* Builds a {@link Queue} worker — `q.queue('orders').services([db]).message(schema).handle(fn)`.
-* Services are an array (sniffed for required env vars); `message` is the typed
-* job payload; `handle` is the single consumer. The queue name is captured as a
-* literal so `queue.publisher` is typed to `{ type: '<name>', payload }`.
-*/
-var QueueBuilder = class {
-	_name;
-	_messageSchema;
-	_timeout = 3e4;
-	_batchSize;
-	_fifo;
-	_services = [];
-	/** The construct ids `.dependsOn()` named — what the manifest records. */
-	_constructs = [];
-	_logger = __geekmidas_logger_console.DEFAULT_LOGGER;
-	/** The queue name — drives the infra queue and its `<NAME>_*` env vars. */
-	queue(name) {
-		return require_clone.cloneWith(this, { _name: name });
-	}
-	timeout(timeout) {
-		return require_clone.cloneWith(this, { _timeout: timeout });
-	}
-	/** SQS event-source batch size (deployed). */
-	batchSize(batchSize) {
-		return require_clone.cloneWith(this, { _batchSize: batchSize });
-	}
-	/** Mark the queue as FIFO (deployed). */
-	fifo(fifo = true) {
-		return require_clone.cloneWith(this, { _fifo: fifo });
-	}
-	/**
-	* Depend on constructs — a database, a bucket, a mail sender, a queue, a
-	* topic.
-	*
-	* It records the edge and dissolves each construct's client into the
-	* handler's service record under the construct's own id, so
-	* `.dependsOn([uploads])` is what makes `services.uploads` exist and type.
-	*
-	* Constructs only. A `Service` does not match the shape, which is what keeps
-	* env sniffing confined to `.services()` and the explicit lift.
-	*/
-	dependsOn(constructs) {
-		const services = require_construct_interface.servicesOf(constructs);
-		return require_clone.cloneWith(this, {
-			_services: [...this._services, ...services],
-			_constructs: require_construct_interface.idsOf(constructs, this._constructs)
-		});
-	}
-	services(services) {
-		return require_clone.cloneWith(this, { _services: [...this._services, ...services] });
-	}
-	logger(logger) {
-		return require_clone.cloneWith(this, { _logger: logger });
-	}
-	/** The typed message (job) payload the queue carries. */
-	message(schema) {
-		return require_clone.cloneWith(this, { _messageSchema: schema });
-	}
-	handle(fn) {
-		if (!this._name) throw new Error("Queue requires a name — call .queue(name) before .handle().");
-		if (!this._messageSchema) throw new Error("Queue requires a message schema — call .message(schema) before .handle().");
-		const queue = new Queue(this._name, fn, this._messageSchema, this._timeout, this._services, this._logger, this._batchSize, this._fifo, this._constructs);
-		return queue;
-	}
-};
-
-//#endregion
-//#region src/queue/index.ts
-const q = new QueueBuilder();
-
-//#endregion
-exports.Queue = Queue;
-exports.QueueBuilder = QueueBuilder;
-exports.q = q;
-//# sourceMappingURL=index.cjs.map
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_Queue = require("../Queue-A3wfD0it.cjs");
+const require_QueueBuilder = require("../QueueBuilder-BjuF0UBl.cjs");
+exports.Queue = require_Queue.Queue;
+exports.QueueNeedsMessage = require_QueueBuilder.QueueNeedsMessage;
+exports.QueueNeedsName = require_QueueBuilder.QueueNeedsName;

package/dist/queue/index.d.cts

@@ -1,60 +1,3 @@
-import "../Construct-C0ijr2qp.cjs";
-import { Consumable, ServicesOf } from "../construct-interface-D9d4Gm4p.cjs";
-import { Queue, QueueContext, QueueHandler, QueueMessage } from "../Queue-D7ZuwBhy.cjs";
-import * as _geekmidas_logger24 from "@geekmidas/logger";
-import { Logger } from "@geekmidas/logger";
-import { Service } from "@geekmidas/services";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-
-//#region src/queue/QueueBuilder.d.ts
-
-/**
- * Builds a {@link Queue} worker — `q.queue('orders').services([db]).message(schema).handle(fn)`.
- * Services are an array (sniffed for required env vars); `message` is the typed
- * job payload; `handle` is the single consumer. The queue name is captured as a
- * literal so `queue.publisher` is typed to `{ type: '<name>', payload }`.
- */
-declare class QueueBuilder<TName extends string = string, TMessage extends StandardSchemaV1 | undefined = undefined, TServices extends Service[] = [], TLogger extends Logger = Logger> {
-  private _name?;
-  private _messageSchema?;
-  private _timeout;
-  private _batchSize?;
-  private _fifo?;
-  private _services;
-  /** The construct ids `.dependsOn()` named — what the manifest records. */
-  _constructs: string[];
-  private _logger;
-  /** The queue name — drives the infra queue and its `<NAME>_*` env vars. */
-  queue<T extends string>(name: T): QueueBuilder<T, TMessage, TServices, TLogger>;
-  timeout(timeout: number): this;
-  /** SQS event-source batch size (deployed). */
-  batchSize(batchSize: number): this;
-  /** Mark the queue as FIFO (deployed). */
-  fifo(fifo?: boolean): this;
-  /**
-   * Depend on constructs — a database, a bucket, a mail sender, a queue, a
-   * topic.
-   *
-   * It records the edge and dissolves each construct's client into the
-   * handler's service record under the construct's own id, so
-   * `.dependsOn([uploads])` is what makes `services.uploads` exist and type.
-   *
-   * Constructs only. A `Service` does not match the shape, which is what keeps
-   * env sniffing confined to `.services()` and the explicit lift.
-   */
-  dependsOn<const T extends readonly Consumable[]>(constructs: T): QueueBuilder<TName, TMessage, [...TServices, ...ServicesOf<T>], TLogger>;
-  services<T extends Service[]>(services: T): QueueBuilder<TName, TMessage, [...TServices, ...T], TLogger>;
-  logger<T extends Logger>(logger: T): QueueBuilder<TName, TMessage, TServices, T>;
-  /** The typed message (job) payload the queue carries. */
-  message<T extends StandardSchemaV1>(schema: T): QueueBuilder<TName, T, TServices, TLogger>;
-  handle(fn: QueueHandler<NonNullable<TMessage>, TServices, TLogger>): Queue<TName, NonNullable<TMessage>, TServices, TLogger>;
-}
-//# sourceMappingURL=QueueBuilder.d.ts.map
-//#endregion
-//#region src/queue/index.d.ts
-declare const q: QueueBuilder<string, undefined, [], _geekmidas_logger24.Logger>;
-//# sourceMappingURL=index.d.ts.map
-
-//#endregion
-export { Queue, QueueBuilder, QueueContext, QueueHandler, QueueMessage, q };
-//# sourceMappingURL=index.d.cts.map
+import { i as QueueMessage, n as QueueContext, r as QueueHandler, t as Queue } from "../Queue-HPyi0e1i.cjs";
+import { n as QueueNeedsMessage, r as QueueNeedsName } from "../QueueBuilder-OSi6LkV9.cjs";
+export { Queue, type QueueContext, type QueueHandler, type QueueMessage, QueueNeedsMessage, QueueNeedsName };