makeEnvelope

@mineflow/contracts

---

@mineflow/contracts / makeEnvelope

Function: makeEnvelope()

function makeEnvelope<T>(input: object): object & object;

Defined in: envelope.ts:127

Собирает конверт события на стороне продюсера: подставляет occurredAt (текущее время), генерирует id и копирует остальные поля из input.

id по умолчанию — crypto.randomUUID(). Если передан deterministicId, id вычисляется детерминированно как UUIDv5(namespace, '${organizationId}:${type}:${deterministicId}') — это даёт стабильный eventId для безопасного retry (см. описание deterministicId).

Возвращаемый тип сужает data до T, поэтому продюсер не теряет типизацию нагрузки (в отличие от EventEnvelope, где data: unknown).

Type Parameters

Type Parameter	Description
T	— тип полезной нагрузки data.

Parameters

Parameter	Type	Description
input	{ causationId?: string; correlationId?: string; data: T; deterministicId?: string; organizationId: string; producedBy: string; type: string; version: string; }	— поля события без id/occurredAt (они вычисляются).
input.causationId?	string	UUID события-причины (опционально).
input.correlationId?	string	UUID цепочки корреляции (опционально).
input.data	T	Полезная нагрузка события.
input.deterministicId?	string	R10-PLAT-F5: deterministic envelope.id seed. Если задан — id вычисляется как UUIDv5(namespace, ${organizationId}:${type}:${deterministicId}). Use-case: retry-with-same-Idempotency-Key который пробил cache (5xx не кешируется). Без этого второй attempt сгенерил бы новый crypto.randomUUID() → второй envelope в outbox → дубль в Redis Streams. С deterministicId второй attempt пытается INSERT с тем же eventId и Prisma бросает P2002 (eventOutbox Unique на eventId) → caller знает что событие уже зафиксировано и retry безопасен. Producer формирует deterministicId из стабильного входа: Idempotency- Key HTTP-header'а, или sagaId+stepName для idempotent saga steps, или externalId для inbox-driven cascade'ов.
input.organizationId	string	UUID организации-владельца (ADR-0020).
input.producedBy	string	Имя продюсера.
input.type	string	Имя события <context>.<entity>.<verb-past>.
input.version	string	Версия data-схемы (major.minor).

Returns

Готовый конверт EventEnvelope с типизированным data: T.

Example

const evt = makeEnvelope({
  type: 'eam.asset.transferred',
  version: '1.0',
  data: { assetId, fromObjectId, toObjectId, performedBy },
  producedBy: 'eam-api',
  organizationId,
  deterministicId: idempotencyKey, // повторный publish → тот же id
});