@echovisionlab/geul-event 0.1.0

package/LICENSE.md

@@ -0,0 +1,6 @@
+Required Notice: Copyright 2026 Echo Vision Lab. All rights reserved.
+
+Licensed under the PolyForm Noncommercial License 1.0.0:
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+Commercial use requires a separate license from Echo Vision Lab.

package/README.md

@@ -0,0 +1,6 @@
+# @echovisionlab/geul-event
+
+Typed event names and helpers for Geul.
+
+See the [source repository](https://github.com/echovisionlab/geul-event-contracts)
+for contract sources, development instructions, and licensing.

package/dist/index.js

@@ -0,0 +1,358 @@
+// src/generated.ts
+var Signals = {
+  transcodeProgress: "transcode.progress",
+  transcodeCancel: "transcode.cancel",
+  waveformProgress: "waveform.progress",
+  waveformCancel: "waveform.cancel",
+  meshOptimizationProgress: "mesh.optimization.progress",
+  mediaProcessingLifecycle: "media.processing.lifecycle",
+  ogLifecycle: "og.lifecycle",
+  mailAdapterChanged: "mail_adapter.changed",
+  contentUpdated: "content.updated",
+  fileIngest: "file.ingest",
+  translationLifecycle: "translation.lifecycle"
+};
+var Queues = {
+  ogGenerate: "og.generate",
+  transcoderAudio: "transcoder.audio",
+  transcoderVideo: "transcoder.video",
+  waveformGenerate: "waveform.generate",
+  assetOptimizerMesh: "asset_optimizer.mesh",
+  fileDelete: "file.delete",
+  emailSend: "email.send",
+  emailAuth: "email.auth",
+  emailCampaign: "email.campaign",
+  userDeleteIdentity: "user.delete.identity",
+  userDeleteAvatar: "user.delete.avatar",
+  aiMetadataGenerate: "ai.metadata.generate",
+  translationGenerate: "translation.generate",
+  transcodeResult: "transcode.result",
+  waveformResult: "waveform.result",
+  meshOptimizationResult: "mesh.optimization.result",
+  releaseTrackOriginalAudioProjection: "release.track_original_audio.projection"
+};
+var FileIngestSignalTypes = {
+  upload: "upload",
+  download: "download",
+  finalized: "finalized",
+  attached: "attached",
+  failed: "failed"
+};
+var ContentType = {
+  protobuf: "application/x-protobuf",
+  json: "application/json"
+};
+
+// src/pgmq.ts
+var PGMQ_ENVELOPE_SCHEMA_VERSION = 1;
+function encodeBase64(payload) {
+  return Buffer.from(payload).toString("base64");
+}
+function decodeBase64(payload) {
+  return new Uint8Array(Buffer.from(payload, "base64"));
+}
+function createPgmqEnvelope(input) {
+  const envelope = {
+    message_id: input.messageId,
+    message_type: input.messageType,
+    schema_version: PGMQ_ENVELOPE_SCHEMA_VERSION,
+    created_at: (input.createdAt ?? /* @__PURE__ */ new Date()).toISOString(),
+    payload_base64: encodeBase64(input.payload),
+    ...input.correlationId ? { correlation_id: input.correlationId } : {},
+    ...input.causationId ? { causation_id: input.causationId } : {}
+  };
+  assertPgmqEnvelope(envelope);
+  return envelope;
+}
+function assertPgmqEnvelope(value) {
+  if (!value || typeof value !== "object") {
+    throw new Error("PGMQ envelope must be an object");
+  }
+  const envelope = value;
+  if (!envelope.message_id || typeof envelope.message_id !== "string") {
+    throw new Error("PGMQ envelope message_id is required");
+  }
+  if (!envelope.message_type || typeof envelope.message_type !== "string") {
+    throw new Error("PGMQ envelope message_type is required");
+  }
+  if (envelope.schema_version !== PGMQ_ENVELOPE_SCHEMA_VERSION) {
+    throw new Error(
+      `Unsupported PGMQ envelope schema ${envelope.schema_version}`
+    );
+  }
+  if (typeof envelope.created_at !== "string" || Number.isNaN(Date.parse(envelope.created_at))) {
+    throw new Error("PGMQ envelope created_at must be an ISO timestamp");
+  }
+  if (typeof envelope.payload_base64 !== "string") {
+    throw new Error("PGMQ envelope payload_base64 is required");
+  }
+  const normalized = Buffer.from(envelope.payload_base64, "base64").toString(
+    "base64"
+  );
+  if (normalized !== envelope.payload_base64) {
+    throw new Error("PGMQ envelope payload_base64 is invalid");
+  }
+}
+function pgmqEnvelopePayload(envelope) {
+  assertPgmqEnvelope(envelope);
+  return decodeBase64(envelope.payload_base64);
+}
+var PgmqClient = class {
+  async enqueue(executor, queue, envelope, options = {}) {
+    assertPgmqEnvelope(envelope);
+    if (!queue) throw new Error("PGMQ queue is required");
+    const delaySeconds = Math.max(0, Math.trunc(options.delaySeconds ?? 0));
+    const result = await executor.query(
+      "SELECT pgmq.send($1, $2::jsonb, $3::jsonb, $4::integer) AS msg_id",
+      [queue, envelope, options.headers ?? {}, delaySeconds]
+    );
+    const row = result.rows[0];
+    if (!row) throw new Error(`PGMQ send returned no message for ${queue}`);
+    return BigInt(row.msg_id);
+  }
+  async read(executor, queue, options) {
+    if (!queue) throw new Error("PGMQ queue is required");
+    const visibilityTimeoutSeconds = Math.trunc(
+      options.visibilityTimeoutSeconds
+    );
+    const batch = Math.trunc(options.batch ?? 1);
+    if (visibilityTimeoutSeconds <= 0) {
+      throw new Error("PGMQ visibility timeout must be positive");
+    }
+    if (batch <= 0) throw new Error("PGMQ batch must be positive");
+    const result = await executor.query(
+      "SELECT msg_id, read_ct, enqueued_at, vt, message, headers FROM pgmq.read($1, $2::integer, $3::integer, '{}'::jsonb)",
+      [queue, visibilityTimeoutSeconds, batch]
+    );
+    return result.rows.map((row) => {
+      const message = {
+        transportId: BigInt(row.msg_id),
+        readCount: row.read_ct,
+        enqueuedAt: new Date(row.enqueued_at),
+        visibleAt: new Date(row.vt),
+        headers: row.headers ?? {}
+      };
+      try {
+        assertPgmqEnvelope(row.message);
+        return { ...message, envelope: row.message };
+      } catch (error) {
+        return {
+          ...message,
+          contractError: error instanceof Error ? error.message : "Invalid PGMQ envelope"
+        };
+      }
+    });
+  }
+  async complete(executor, queue, transportId) {
+    await this.booleanOperation(executor, "delete", queue, transportId);
+  }
+  async retry(executor, queue, transportId, delaySeconds) {
+    const result = await executor.query(
+      "SELECT msg_id FROM pgmq.set_vt($1, $2::bigint, $3::integer)",
+      [queue, transportId.toString(), Math.max(0, Math.trunc(delaySeconds))]
+    );
+    if (BigInt(result.rows[0]?.msg_id ?? -1) !== transportId) {
+      throw new Error(`PGMQ retry did not update ${queue}/${transportId}`);
+    }
+  }
+  async deadLetter(executor, queue, transportId) {
+    await this.booleanOperation(executor, "archive", queue, transportId);
+  }
+  async booleanOperation(executor, operation, queue, transportId) {
+    const result = await executor.query(
+      `SELECT pgmq.${operation}($1, $2::bigint) AS succeeded`,
+      [queue, transportId.toString()]
+    );
+    if (result.rows[0]?.succeeded !== true) {
+      throw new Error(
+        `PGMQ ${operation} did not update ${queue}/${transportId}`
+      );
+    }
+  }
+};
+
+// src/interactive-mutation.ts
+import { AIDocumentDomain } from "@echovisionlab/geul-proto/secure/ai_pb.ts";
+import {
+  InteractiveAIDocumentMutationOrigin
+} from "@echovisionlab/geul-proto/intra/collaboration_pb.ts";
+var activeDocumentDomains = new Set(
+  Object.values(AIDocumentDomain).filter(
+    (value) => typeof value === "number" && value !== AIDocumentDomain.AI_DOCUMENT_DOMAIN_UNSPECIFIED
+  )
+);
+function requireNonBlank(value, name) {
+  if (value.trim() === "") {
+    throw new Error(`interactive AI document mutation ${name} is required`);
+  }
+}
+function assertRelayInteractiveAIDocumentMutationRequest(event) {
+  requireNonBlank(event.mutationId, "id");
+  switch (event.origin) {
+    case InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_IN_EDITOR_AI:
+    case InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_MCP:
+      break;
+    case InteractiveAIDocumentMutationOrigin.INTERACTIVE_AI_DOCUMENT_MUTATION_ORIGIN_UNSPECIFIED:
+    default:
+      throw new Error(
+        `unsupported interactive AI document mutation origin: ${event.origin}`
+      );
+  }
+  if (event.document === void 0) {
+    throw new Error("interactive AI document mutation document is required");
+  }
+  if (!activeDocumentDomains.has(event.document.domain)) {
+    throw new Error(
+      `unsupported interactive AI document mutation domain: ${event.document.domain}`
+    );
+  }
+  requireNonBlank(event.document.reference, "reference");
+  if (event.locale === void 0) {
+    throw new Error("interactive AI document mutation locale is required");
+  }
+  requireNonBlank(event.locale.code, "locale");
+  requireNonBlank(event.expectedDocumentRevision, "expected document revision");
+  requireNonBlank(event.acceptedDocumentRevision, "accepted document revision");
+  if (event.operations.length === 0) {
+    throw new Error("interactive AI document mutation operations are required");
+  }
+  event.operations.forEach((operation, index) => {
+    if (operation.operation.case === void 0) {
+      throw new Error(
+        `interactive AI document mutation operation ${index} is required`
+      );
+    }
+  });
+  if (event.operations.length !== 1 && event.operations.some(
+    (operation) => operation.operation.case === "createTranslation" || operation.operation.case === "deleteTranslation"
+  )) {
+    throw new Error(
+      "interactive AI document mutation locale lifecycle operation must be exclusive"
+    );
+  }
+  if (event.expectedTargetRevision !== void 0) {
+    requireNonBlank(event.expectedTargetRevision, "expected target revision");
+  }
+  if (event.acceptedTargetRevision !== void 0) {
+    requireNonBlank(event.acceptedTargetRevision, "accepted target revision");
+  }
+  const isTargetMutation = event.expectedTargetRevision !== void 0 || event.acceptedTargetRevision !== void 0;
+  if (isTargetMutation) {
+    if (event.acceptedDocumentRevision !== event.expectedDocumentRevision) {
+      throw new Error(
+        "interactive AI document target mutation must preserve the document revision"
+      );
+    }
+  } else {
+    if (event.expectedTargetRevision === void 0 && event.acceptedTargetRevision === void 0 && event.acceptedDocumentRevision === event.expectedDocumentRevision) {
+      throw new Error(
+        "interactive AI document source mutation must advance the document revision"
+      );
+    }
+  }
+  const onlyOperation = event.operations.length === 1 ? event.operations[0] : void 0;
+  if (onlyOperation?.operation.case === "createTranslation") {
+    if (event.expectedTargetRevision !== void 0 || event.acceptedTargetRevision === void 0) {
+      throw new Error(
+        "interactive AI document mutation create translation revisions are invalid"
+      );
+    }
+  } else if (onlyOperation?.operation.case === "deleteTranslation") {
+    if (event.expectedTargetRevision === void 0 || event.acceptedTargetRevision !== void 0) {
+      throw new Error(
+        "interactive AI document mutation delete translation revisions are invalid"
+      );
+    }
+  } else if (event.expectedTargetRevision !== void 0 && event.acceptedTargetRevision === void 0) {
+    throw new Error(
+      "interactive AI document mutation target revision cannot disappear"
+    );
+  }
+  requireNonBlank(event.actorMemberId, "actor member id");
+}
+
+// src/index.ts
+import {
+  InternalOgService,
+  OgGenerationClaimResult
+} from "@echovisionlab/geul-proto/intra/og_pb.ts";
+
+// src/proto-helpers.ts
+import { fromBinary } from "@bufbuild/protobuf";
+import {
+  AssetDisposition,
+  MediaProcessingStatus
+} from "@echovisionlab/geul-proto/common/media_pb.ts";
+import {
+  FileIngestAttachedEventSchema,
+  FileIngestDownloadEventSchema,
+  FileIngestFailedEventSchema,
+  FileIngestFailureReason,
+  FileIngestFinalizedEventSchema,
+  FileIngestIdentitySchema,
+  FileIngestMediaKind,
+  FileIngestSource,
+  FileIngestUploadEventSchema,
+  MediaProcessingLifecycleEventSchema,
+  MeshOptimizationResultEventSchema,
+  OgEntityType,
+  OgGenerationJobSchema,
+  OgGenerationLifecycleEventSchema,
+  OgGenerationStatus,
+  OgGenerationTargetSchema,
+  TranscodeCompleteEventSchema,
+  TranscodeEntityType,
+  TranslationLifecycleEventSchema,
+  WaveformResultEventSchema
+} from "@echovisionlab/geul-proto/secure/events_pb.ts";
+function deserializeProto(schema, data) {
+  return fromBinary(schema, data);
+}
+
+// src/translation-source.ts
+function assertTranslationJobRequestArtifact(job) {
+  if (job.target === void 0) {
+    throw new Error("translation job target is required");
+  }
+  if (job.requestArtifactDigest.trim().length === 0) {
+    throw new Error("translation job request artifact digest is required");
+  }
+}
+export {
+  AssetDisposition,
+  ContentType,
+  FileIngestAttachedEventSchema,
+  FileIngestDownloadEventSchema,
+  FileIngestFailedEventSchema,
+  FileIngestFailureReason,
+  FileIngestFinalizedEventSchema,
+  FileIngestIdentitySchema,
+  FileIngestMediaKind,
+  FileIngestSignalTypes,
+  FileIngestSource,
+  FileIngestUploadEventSchema,
+  InternalOgService,
+  MediaProcessingLifecycleEventSchema,
+  MediaProcessingStatus,
+  MeshOptimizationResultEventSchema,
+  OgEntityType,
+  OgGenerationClaimResult,
+  OgGenerationJobSchema,
+  OgGenerationLifecycleEventSchema,
+  OgGenerationStatus,
+  OgGenerationTargetSchema,
+  PGMQ_ENVELOPE_SCHEMA_VERSION,
+  PgmqClient,
+  Queues,
+  Signals,
+  TranscodeCompleteEventSchema,
+  TranscodeEntityType,
+  TranslationLifecycleEventSchema,
+  WaveformResultEventSchema,
+  assertPgmqEnvelope,
+  assertRelayInteractiveAIDocumentMutationRequest,
+  assertTranslationJobRequestArtifact,
+  createPgmqEnvelope,
+  deserializeProto,
+  pgmqEnvelopePayload
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@echovisionlab/geul-event",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint --cache .",
+    "lint-fix": "eslint --cache . --fix"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.14.0"
+  },
+  "peerDependencies": {
+    "@echovisionlab/geul-proto": "^0.1.0"
+  },
+  "devDependencies": {
+    "@echovisionlab/geul-proto": "workspace:*",
+    "@types/node": "^24.13.3",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "eslint": "^10.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "typescript-eslint": "^8.67.0"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/echovisionlab/geul-event-contracts.git"
+  },
+  "homepage": "https://github.com/echovisionlab/geul-event-contracts#readme",
+  "bugs": {
+    "url": "https://github.com/echovisionlab/geul-event-contracts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}