@palantir/pack.state.foundry-event 0.1.2 → 0.2.1

package/src/FoundryEventService.ts

@@ -17,12 +17,12 @@
 import type { Logger } from "@osdk/api";
 import type {
   ActivityCollaborativeUpdate,
-  ClientId,
   DocumentEditDescription,
   DocumentPublishMessage,
   DocumentUpdateMessage,
   DocumentUpdateSubscriptionRequest,
-  UserId,
+  PresenceCollaborativeUpdate,
+  PresencePublishMessage,
 } from "@osdk/foundry.pack";
 import { getAuthModule } from "@palantir/pack.auth";
 import { generateId, justOnce, type PackAppInternal } from "@palantir/pack.core";
@@ -33,10 +33,9 @@ import {
   hasMetadata,
 } from "@palantir/pack.document-schema.model-types";
 import { DocumentLoadStatus, type DocumentSyncStatus } from "@palantir/pack.state.core";
-import type { CometD } from "cometd";
 import { Base64 } from "js-base64";
 import * as y from "yjs";
-import { EventServiceCometD } from "./cometd/EventServiceCometD.js";
+import { type CometDLoader, EventServiceCometD } from "./cometd/EventServiceCometD.js";
 import type {
   EventService,
   SubscriptionId,
@@ -49,36 +48,6 @@ export interface PresenceSubscriptionOptions {
   readonly ignoreSelfUpdates?: boolean;
 }
 
-export interface PresencePublishMessageCustom {
-  readonly type: "custom";
-  readonly custom: {
-    userId: UserId;
-    clientId: ClientId;
-    eventData: any;
-  };
-}
-
-export type PresencePublishMessage = PresencePublishMessageCustom;
-
-export interface DocumentPresenceChangeEvent {
-  readonly type: "presenceChangeEvent";
-  readonly presenceChangeEvent: {
-    readonly userId: UserId;
-    readonly status: "PRESENT" | "NOT_PRESENT";
-  };
-}
-
-export interface CustomPresenceEvent {
-  readonly type: "customPresenceEvent";
-  readonly customPresenceEvent: {
-    readonly userId: UserId;
-    readonly clientId: ClientId;
-    readonly eventData: any;
-  };
-}
-
-export type PresenceCollaborativeUpdate = DocumentPresenceChangeEvent | CustomPresenceEvent;
-
 // TODO: presence api should have an eventType so we don't need extra wrapper here.
 interface PresencePublishMessageData {
   readonly eventType: string; // model name
@@ -130,16 +99,43 @@ interface SyncSessionInternal extends SyncSession {
  * This manages event subscriptions and publishing of document related events via
  * our PACK Foundry backend's cometd service.
  */
-export class FoundryEventService {
+export interface FoundryEventService {
+  publishCustomPresence(
+    documentId: DocumentId,
+    eventType: string,
+    eventData: unknown,
+  ): Promise<void>;
+
+  startDocumentSync(
+    documentId: DocumentId,
+    yDoc: y.Doc,
+    onStatusChange: (status: Partial<DocumentSyncStatus>) => void,
+  ): SyncSession;
+
+  stopDocumentSync(session: SyncSession): void;
+
+  subscribeToActivityUpdates(
+    documentId: DocumentId,
+    callback: (event: ActivityCollaborativeUpdate) => void,
+  ): Promise<SubscriptionId>;
+
+  subscribeToPresenceUpdates(
+    documentId: DocumentId,
+    callback: (update: PresenceCollaborativeUpdate) => void,
+    options?: PresenceSubscriptionOptions,
+  ): Promise<SubscriptionId>;
+}
+
+class FoundryEventServiceImpl implements FoundryEventService {
   private readonly eventService: EventService;
   private readonly logger: Logger;
   private readonly sessions = new Map<string, SyncSessionInternal>();
 
   constructor(
     private readonly app: PackAppInternal,
-    cometd?: CometD,
+    cometdLoader?: CometDLoader,
   ) {
-    this.eventService = new EventServiceCometD(app, cometd);
+    this.eventService = new EventServiceCometD(app, cometdLoader);
     this.logger = app.config.logger.child({}, {
       level: "debug",
       msgPrefix: "FoundryEventService",
@@ -311,12 +307,12 @@ export class FoundryEventService {
         if (ignoreSelfUpdates && localUserId != null) {
           switch (update.type) {
             case "presenceChangeEvent":
-              if (update.presenceChangeEvent.userId === localUserId) {
+              if (update.userId === localUserId) {
                 return;
               }
               break;
             case "customPresenceEvent":
-              if (update.customPresenceEvent.userId === localUserId) {
+              if (update.userId === localUserId) {
                 return;
               }
               break;
@@ -363,12 +359,10 @@ export class FoundryEventService {
     }
 
     return this.eventService.publish(channelId, {
-      custom: {
-        clientId: session.clientId,
-        eventData: messageData,
-        // FIXME: why do we have to send this, we are authenticated
-        userId,
-      },
+      clientId: session.clientId,
+      eventData: messageData,
+      // FIXME: why do we have to send this, we are authenticated
+      userId,
       type: "custom",
     }).catch((error: unknown) => {
       this.logger.error("Failed to publish custom presence", error, {
@@ -492,9 +486,10 @@ export class FoundryEventService {
 
 export function createFoundryEventService(
   app: PackAppInternal,
-  cometd?: CometD,
+  /** @internal */
+  cometdLoader?: CometDLoader,
 ): FoundryEventService {
-  return new FoundryEventService(app, cometd);
+  return new FoundryEventServiceImpl(app, cometdLoader);
 }
 
 function isEditDescription(obj: unknown): obj is EditDescription {

package/src/__tests__/EventServiceCometD.reconnection.test.ts

@@ -19,6 +19,7 @@ import type { Callback, CometD, ListenerHandle, SubscriptionHandle } from "comet
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { MockProxy } from "vitest-mock-extended";
 import { mock } from "vitest-mock-extended";
+import type { CometDLoader } from "../cometd/EventServiceCometD.js";
 import { EventServiceCometD } from "../cometd/EventServiceCometD.js";
 import type { TypedReceiveChannelId } from "../types/EventService.js";
 
@@ -88,7 +89,20 @@ describe("EventServiceCometD Reconnection Handling", () => {
       callback();
     });
 
-    service = new EventServiceCometD(mockApp, mockCometD);
+    const mockLoader = () => {
+      class MockAckExtension {}
+      class MockCometD {
+        constructor() {
+          return mockCometD;
+        }
+      }
+      return Promise.resolve({
+        AckExtension: MockAckExtension,
+        CometD: MockCometD,
+      });
+    };
+
+    service = new EventServiceCometD(mockApp, mockLoader as CometDLoader);
   });
 
   afterEach(() => {

package/src/cometd/EventServiceCometD.ts

@@ -17,8 +17,7 @@
 import type { Logger } from "@osdk/api";
 import { getAuthModule } from "@palantir/pack.auth";
 import type { AppConfig, PackAppInternal } from "@palantir/pack.core";
-import type { Message, SubscriptionHandle } from "cometd";
-import { AckExtension, CometD } from "cometd";
+import type { AckExtension, CometD, Message, SubscriptionHandle } from "cometd";
 import type {
   EventService,
   EventServiceLogLevel,
@@ -26,9 +25,7 @@ import type {
   TypedPublishChannelId,
   TypedReceiveChannelId,
 } from "../types/EventService.js";
-
-// side-effect shenanigans imports the class impl to cometd module
-import "cometd/AckExtension.js";
+import { lazyLoadCometD } from "./lazyLoadCometD.js";
 
 const BEARER_TOKEN_FIELD = "bearer-token";
 const EXTENSION_ACK = "AckExtension";
@@ -42,24 +39,26 @@ interface Subscription {
   readonly getSubscriptionRequest?: () => object;
 }
 
+export interface CometDLoader {
+  (): Promise<{
+    AckExtension: new() => AckExtension;
+    CometD: new() => CometD;
+  }>;
+}
+
 export class EventServiceCometD implements EventService {
   private readonly logger: Logger;
   private initializePromise: Promise<void> | undefined;
   private readonly subscriptionById: Map<SubscriptionId, Subscription> = new Map();
   private readonly tokenExtension = new TokenExtension();
   private nextSubscriptionHandle = 0;
+  private cometd?: CometD;
 
   constructor(
     private readonly app: PackAppInternal,
-    private readonly cometd: CometD = new CometD(),
+    private readonly cometdLoader: CometDLoader = lazyLoadCometD,
   ) {
     this.logger = app.config.logger.child({}, { msgPrefix: "EventServiceCometD" });
-    this.configureCometd();
-    this.cometd.registerExtension(EXTENSION_ACK, new AckExtension());
-    this.cometd.registerExtension(EXTENSION_HANDSHAKE_TOKEN, this.tokenExtension);
-
-    // TODO: Support binary messages
-    // this.cometd.registerExtension(BINARY_EXTENSION_NAME, new BinaryExtension());
 
     // Any time the token changes, update the extension so reconnection requests use the new token.
     // This will also be called on initial token set when the auth module is initialized.
@@ -68,44 +67,58 @@ export class EventServiceCometD implements EventService {
     });
   }
 
-  private initialize(): Promise<void> {
+  private async initialize(): Promise<void> {
     if (this.initializePromise != null) {
       return this.initializePromise;
     }
 
-    this.initializePromise = new Promise<void>(resolve => {
-      this.cometd.addListener(
-        META_CHANNEL_HANDSHAKE,
-        ({ clientId, connectionType, error, successful }) => {
-          if (successful) {
-            this.logger.info("CometD handshake successful", { clientId, connectionType });
-            resolve();
-
-            this.cometd.batch(() => {
-              this.subscriptionById.forEach((subscription, subscriptionId) => {
-                this.logger.debug("Resubscribing to channel", {
-                  channel: subscription.eventChannel,
-                  subscriptionId,
-                });
-                const subscribeProps = subscription.getSubscriptionRequest?.();
-                subscription.handle = this.cometd.resubscribe(subscription.handle, {
-                  ext: subscribeProps,
+    this.initializePromise = (async () => {
+      if (this.cometd == null) {
+        const { AckExtension, CometD } = await this.cometdLoader();
+        this.cometd = new CometD();
+        this.configureCometd();
+
+        this.cometd.registerExtension(EXTENSION_ACK, new AckExtension());
+        this.cometd.registerExtension(EXTENSION_HANDSHAKE_TOKEN, this.tokenExtension);
+
+        // TODO: Support binary messages
+        // this.cometd.registerExtension(BINARY_EXTENSION_NAME, new BinaryExtension());
+      }
+
+      await new Promise<void>(resolve => {
+        this.cometd!.addListener(
+          META_CHANNEL_HANDSHAKE,
+          ({ clientId, connectionType, error, successful }) => {
+            if (successful) {
+              this.logger.info("CometD handshake successful", { clientId, connectionType });
+              resolve();
+
+              this.cometd!.batch(() => {
+                this.subscriptionById.forEach((subscription, subscriptionId) => {
+                  this.logger.debug("Resubscribing to channel", {
+                    channel: subscription.eventChannel,
+                    subscriptionId,
+                  });
+                  const subscribeProps = subscription.getSubscriptionRequest?.();
+                  subscription.handle = this.cometd!.resubscribe(subscription.handle, {
+                    ext: subscribeProps,
+                  });
                 });
               });
-            });
-          } else {
-            this.logger.warn("CometD handshake failed", { clientId, error });
-          }
-        },
-      );
-
-      const authModule = getAuthModule(this.app);
-      void authModule.getToken().then(token => {
-        this.logger.info("Initializing CometD with token");
-        this.tokenExtension.setToken(token);
-        this.cometd.handshake();
+            } else {
+              this.logger.warn("CometD handshake failed", { clientId, error });
+            }
+          },
+        );
+
+        const authModule = getAuthModule(this.app);
+        void authModule.getToken().then(token => {
+          this.logger.info("Initializing CometD with token");
+          this.tokenExtension.setToken(token);
+          this.cometd!.handshake();
+        });
       });
-    });
+    })();
 
     return this.initializePromise;
   }
@@ -116,6 +129,11 @@ export class EventServiceCometD implements EventService {
     getSubscriptionRequest?: () => object,
   ): Promise<SubscriptionId> {
     await this.initialize();
+
+    if (this.cometd == null) {
+      throw new Error("CometD not initialized");
+    }
+
     const subscriptionId = (this.nextSubscriptionHandle++).toString(10) as SubscriptionId;
 
     return new Promise<SubscriptionId>(
@@ -172,13 +190,13 @@ export class EventServiceCometD implements EventService {
         const ext = getSubscriptionRequest?.();
 
         const subscriptionHandle = ext != null
-          ? this.cometd.subscribe(
+          ? this.cometd!.subscribe(
             channel,
             messageHandler,
             { ext },
             subscribeCallback,
           )
-          : this.cometd.subscribe(
+          : this.cometd!.subscribe(
             channel,
             messageHandler,
             subscribeCallback,
@@ -208,6 +226,11 @@ export class EventServiceCometD implements EventService {
 
     this.subscriptionById.delete(subscriptionId);
 
+    if (this.cometd == null) {
+      this.logger.warn("CometD not initialized, cannot unsubscribe", { subscriptionId });
+      return;
+    }
+
     this.cometd.unsubscribe(
       handle,
       message => {
@@ -227,8 +250,13 @@ export class EventServiceCometD implements EventService {
     content: T,
   ): Promise<void> {
     await this.initialize();
+
+    if (this.cometd == null) {
+      throw new Error("CometD not initialized");
+    }
+
     return new Promise<void>((resolve, reject) => {
-      this.cometd.publish(channel, content, message => {
+      this.cometd!.publish(channel, content, message => {
         if (message.successful) {
           this.logger.debug("Successfully published message", channel, { content });
           resolve();
@@ -249,6 +277,10 @@ export class EventServiceCometD implements EventService {
   }
 
   private configureCometd(logLevel?: EventServiceLogLevel) {
+    if (this.cometd == null) {
+      return;
+    }
+
     const url = getCometDWebsocketUrl(this.app.config);
     this.logger.info("Configuring cometD ", { url });
     this.cometd.configure({

package/src/cometd/lazyLoadCometD.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type * as cometd from "cometd";
+
+export async function lazyLoadCometD(): Promise<typeof cometd> {
+  const cometdModule = await import("cometd");
+  // cometd module does declare the extensions, however they are added to the module as side-effects
+  // by importing the submodule extension files. So for any we use we'll need to import them explicitly.
+  // Note that this file should be included in package.json "sideEffects" to avoid tree-shaking.
+
+  // TODO: switch back to dynamic import with side-effect loading when supported by new cometD version. Requires
+  // backend version upgrade first.
+  // AckExtension.js modifies the cometd module as a side-effect to add AckExtension.
+  // We need to capture the returned constructor because with ESM bundlers, the module reference
+  // may not reflect the mutation.
+  // @ts-expect-error TS2307: No type declarations for cometd/AckExtension.js, but its default export is the AckExtension constructor
+  const { default: AckExtension } = await import("cometd/AckExtension.js");
+
+  return { ...cometdModule, AckExtension };
+}

package/src/index.ts

@@ -14,22 +14,9 @@
  * limitations under the License.
  */
 
-export { EventServiceCometD } from "./cometd/EventServiceCometD.js";
-export { createFoundryEventService, FoundryEventService } from "./FoundryEventService.js";
+export { createFoundryEventService } from "./FoundryEventService.js";
 export type {
-  CustomPresenceEvent,
-  DocumentPresenceChangeEvent,
-  PresenceCollaborativeUpdate,
-  PresencePublishMessage,
-  PresencePublishMessageCustom,
+  FoundryEventService,
   PresenceSubscriptionOptions,
   SyncSession,
 } from "./FoundryEventService.js";
-export type {
-  ChannelId,
-  EventService,
-  EventServiceLogLevel,
-  SubscriptionId,
-  TypedPublishChannelId,
-  TypedReceiveChannelId,
-} from "./types/EventService.js";