@palantir/pack.document-schema.model-types 0.1.0-beta.3 → 0.1.1

package/build/cjs/index.d.cts

@@ -1,6 +1,122 @@
 import { Flavored } from '@palantir/pack.core';
 import { ZodType } from 'zod';
 
+declare const Metadata: symbol;
+interface WithMetadata<T> {
+    readonly [Metadata]: T;
+}
+declare function getMetadata<T>(obj: WithMetadata<T>): T;
+
+/**
+ * A Model defines the structure of a document record or union.
+ *
+ * It includes a zod schema for validation and type information.
+ */
+interface Model<T = unknown, Z extends ZodType<T> = ZodType<T>> extends WithMetadata<ModelMetadata<T>> {
+    readonly __type: T;
+    readonly zodSchema: Readonly<Z>;
+}
+type ModelData<M extends Model> = M["__type"];
+/**
+ * Describes an edit made to a document.
+ */
+interface EditDescription<M extends Model = Model> {
+    readonly data: ModelData<M>;
+    readonly model: M;
+}
+declare const ExternalRefType: {
+    readonly DOC_REF: "docRef";
+    readonly MEDIA_REF: "mediaRef";
+    readonly OBJECT_REF: "objectRef";
+    readonly USER_REF: "userRef";
+};
+type ExternalRefType = typeof ExternalRefType[keyof typeof ExternalRefType];
+interface ModelMetadata<T = unknown> {
+    /**
+     * Which fields in the model are external references (e.g. UserRef, DocumentRef, etc).
+     */
+    readonly externalRefFieldTypes?: Readonly<Record<keyof T, ExternalRefType>>;
+    /**
+     * The name of the model (should match the typescript symbol).
+     */
+    readonly name: string;
+}
+
+type UserId = Flavored<"pack:UserId">;
+declare const UserRefBrand: unique symbol;
+/**
+ * A reference providing an API to interact with a user.
+ *
+ * @experimental
+ */
+interface UserRef {
+    readonly userId: UserId;
+    readonly [UserRefBrand]: typeof UserRefBrand;
+    readonly get: (force?: boolean) => Promise<unknown>;
+}
+
+type ActivityEventId = Flavored<"pack:EventId">;
+declare const ActivityEventDataType: {
+    readonly CUSTOM_EVENT: "customEvent";
+    readonly UNKNOWN: "unknown";
+};
+/**
+ * Application specific custom activity event data, as described in a transaction edit,
+ * using an application sdk's generated model types.
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = docRef.onActivity((docRef, event) => {
+ *   console.log("Activity event:", event);
+ * });
+ * // Submit an edit with a description to generate an activity event.
+ * docRef.withTransaction(() => {
+ *   // make some edits to the document here
+ * }, {
+ *   model: MyEventModel,
+ *   data: {
+ *     myDataField: "some value",
+ *     foo: 42,
+ *   },
+ * });
+ * ```
+ */
+interface ActivityEventDataCustom<M extends Model = Model> {
+    readonly type: typeof ActivityEventDataType.CUSTOM_EVENT;
+    readonly model: M;
+    readonly eventData: ModelData<M>;
+}
+/**
+ * Fallback for unrecognized activity event types.
+ *
+ * This allows some flexibility with new event types added to the platform.
+ * Likely unknown events represent a new platform event type and will be handled
+ * in a future release of pack libraries and can be safely ignored by
+ * applications.
+ */
+interface ActivityEventDataUnknown {
+    readonly type: "unknown";
+    readonly rawType: string;
+    readonly rawData: unknown;
+}
+type ActivityEventData = ActivityEventDataCustom | ActivityEventDataUnknown;
+/**
+ * An event representing an activity that has occurred on a document. This
+ * includes standard document events as well as custom application-specific
+ * events describing document edits.
+ *
+ * ActivityEvents are useful for building activity feeds, or notifications.
+ */
+interface ActivityEvent {
+    /** Multiple events with the same aggregationKey may be collapsed. */
+    readonly aggregationKey: string;
+    readonly createdBy: UserId;
+    readonly createdInstant: number;
+    readonly eventData: ActivityEventData;
+    readonly eventId: ActivityEventId;
+    readonly isRead: boolean;
+}
+
 interface DiscretionaryPrincipal_All {
     "all": Record<string, never>;
     "type": "all";
@@ -31,37 +147,15 @@ interface DocumentMetadata {
     };
 }
 
-declare const Metadata: symbol;
-interface WithMetadata<T> {
-    readonly [Metadata]: T;
-}
-declare function getMetadata<T>(obj: WithMetadata<T>): T;
-
 /**
- * A Model defines the structure of a document record or union.
- *
- * It includes a zod schema for validation and type information.
+ * The base type for an application sdk's generated document schema.
  */
-interface Model<T = unknown, Z extends ZodType<T> = ZodType<T>> extends WithMetadata<ModelMetadata<T>> {
-    readonly __type: T;
-    readonly zodSchema: Readonly<Z>;
-}
-type ModelData<M extends Model> = M["__type"];
-declare const ExternalRefType: {
-    readonly DOC_REF: "docRef";
-    readonly MEDIA_REF: "mediaRef";
-    readonly OBJECT_REF: "objectRef";
-    readonly USER_REF: "userRef";
-};
-type ExternalRefType = typeof ExternalRefType[keyof typeof ExternalRefType];
-interface ModelMetadata<T = unknown> {
-    readonly externalRefFieldTypes?: Readonly<Record<keyof T, ExternalRefType>>;
-    readonly name: string;
-}
-
 interface DocumentSchema extends WithMetadata<DocumentSchemaMetadata> {
     readonly [modelName: string]: Model;
 }
+/**
+ * The plain object representation of the state of a document.
+ */
 type DocumentState<S extends DocumentSchema> = {
     readonly [K in Exclude<keyof S, symbol>]: {
         readonly [key: string]: ModelData<S[K]>;
@@ -71,47 +165,439 @@ interface DocumentSchemaMetadata {
     readonly version: number;
 }
 
+declare const PresenceEventDataType: {
+    readonly ARRIVED: "presenceArrived";
+    readonly DEPARTED: "presenceDeparted";
+    readonly CUSTOM_EVENT: "customEvent";
+    readonly UNKNOWN: "unknown";
+};
+type PresenceEventDataType = typeof PresenceEventDataType[keyof typeof PresenceEventDataType];
+/**
+ * Any client that subscribes to presence events via `DocumentRef.onPresence` will
+ * be considered 'present' on the document, and trigger an 'arrived' presence event.
+ * When they disconnect or unsubscribe from presence events, a 'departed' presence event
+ * will be triggered.
+ */
+interface PresenceEventDataArrived {
+    readonly type: typeof PresenceEventDataType.ARRIVED;
+}
+/**
+ * Any client that subscribes to presence events via `DocumentRef.onPresence` will
+ * be considered 'present' on the document, and trigger an 'arrived' presence event.
+ * When they disconnect or unsubscribe from presence events, a 'departed' presence event
+ * will be triggered.
+ */
+interface PresenceEventDataDeparted {
+    readonly type: typeof PresenceEventDataType.DEPARTED;
+}
+/**
+ * Application specific custom presence event data.
+ *
+ * Each different model type used for presence is expected to update the latest
+ * 'presence state' for that model type.
+ *
+ * For example, your app may have need to broadcast user cursor positions and
+ * selection ranges as presence data. You could define your schema to include a
+ * `CursorPosition` and `SelectionRange` record types, and set them
+ * independently via `{@link DocumentRef.updateCustomPresence}`. Each model type
+ * sent as a custom presence event should be considered a separate 'channel' of
+ * presence data on this document.
+ */
+interface PresenceEventDataCustom<M extends Model = Model> {
+    readonly type: typeof PresenceEventDataType.CUSTOM_EVENT;
+    readonly eventData: ModelData<M>;
+    readonly model: M;
+}
+/**
+ * Fallback for unrecognized activity event types.
+ *
+ * This allows some flexibility with new event types added to the platform.
+ * Likely unknown events represent a new platform event type and will be handled
+ * in a future release of pack libraries and can be safely ignored by
+ * applications.
+ */
+interface PresenceEventUnknown {
+    readonly type: "unknown";
+    readonly rawType: string;
+    readonly rawData: unknown;
+}
+type PresenceEventData = PresenceEventDataArrived | PresenceEventDataDeparted | PresenceEventDataCustom | PresenceEventUnknown;
+/**
+ * An event representing a transient awareness or presence change for a user on this document.
+ * The presence channel is intended for ephemeral data such as user cursors, selections, or
+ * other live collaboration indicators.
+ *
+ * PresenceEvents are not persisted in document history.
+ *
+ * When a client goes offline, its presence is considered departed and any presence events
+ * associated with that user should be considered stale and / or cleared.
+ */
+interface PresenceEvent {
+    readonly userId: UserId;
+    readonly eventData: PresenceEventData;
+}
+
+/**
+ * A function that can be called to unsubscribe from a previously subscribed event interface.
+ */
 type Unsubscribe = () => void;
 
 type RecordId = Flavored<"RecordId">;
 declare const RecordRefBrand: unique symbol;
+/**
+ * A reference providing an API to interact with a specific record in a
+ * document. This is the main interface for accessing and updating individual
+ * records.
+ *
+ * These will be created by docRef or recordCollectionRef APIs for example and
+ * should not be created manually. RecordRefs are stable objects that can be
+ * used for reference equality checks.
+ *
+ * @example
+ * ```ts
+ * import { DocumentRef, DocumentSchema, MyModel } from "@myapp/schema";
+ * import { app } from "./appInstance";
+ *
+ * const docRef = app.getDocRef<DocumentSchema>(someDocumentId);
+ *
+ * const recordRef = docRef.getRecords(MyModel).set("my-record-id", { myFieldName: "some value", foo: 42 });
+ *
+ * // Or get a specific record.
+ * const recordRef = docRef.getRecords(MyModel).get("my-record-id");
+ */
 interface RecordRef<M extends Model = Model> {
     readonly docRef: DocumentRef;
     readonly id: RecordId;
     readonly model: M;
     readonly [RecordRefBrand]: typeof RecordRefBrand;
+    /**
+     * Get the current state of the record in a plain object.
+     * If there is an active subscription to the document this is the current state of the record in memory.
+     * Otherwise, this will fetch the latest state from the server.
+     */
     getSnapshot(): Promise<ModelData<M>>;
+    /**
+     * Subscribe to changes in the record.
+     * @param callback The callback to invoke when the record changes.
+     * @returns An unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * // Subscribe to changes
+     * recordRef.onChange((newSnapshot, recordRef) => {
+     *   console.log("Record changed:", newSnapshot);
+     * });
+     *
+     * // Submit a change
+     * recordRef.set({ myFieldName: "new value" });
+     * ```
+     */
     onChange(callback: (snapshot: ModelData<M>, recordRef: RecordRef<M>) => void): Unsubscribe;
+    /**
+     * Subscribe to deletion of the record.
+     * @param callback The callback to invoke when the record is deleted.
+     * @returns An unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * // Subscribe to deletion
+     * recordRef.onDeleted((recordRef) => {
+     *   console.log("Record deleted:", recordRef.id);
+     * });
+     *
+     * // Trigger the deletion
+     * docRef.getRecords(MyModel).delete(recordRef.id);
+     * ```
+     */
     onDeleted(callback: (recordRef: RecordRef<M>) => void): Unsubscribe;
+    /**
+     * Set the data for the record (creating it if it doesn't exist).
+     *
+     * @see {onChange} to subscribe to changes to the record.
+     *
+     * @param record - The plain object data to set for the record, corresponding to the model's schema.
+     * @returns An ignorable promise that resolves when the record is published.
+     *
+     * @example
+     * ```ts
+     * await recordRef.set({ field: "value" });
+     * ```
+     */
     set(record: ModelData<M>): Promise<void>;
 }
 
 declare const RecordCollectionRefBrand: unique symbol;
+/**
+ * A reference providing an API to interact with a collection of records in a document.
+ */
 interface RecordCollectionRef<M extends Model = Model> {
     readonly docRef: DocumentRef;
     readonly model: M;
     readonly [RecordCollectionRefBrand]: typeof RecordCollectionRefBrand;
+    /**
+     * Delete a record from the collection (and the document).
+     *
+     * @param id - The ID of the record to delete.
+     * @returns A promise that resolves when the record is deleted.
+     */
     delete(id: RecordId): Promise<void>;
+    /**
+     * Get a {@link RecordRef} from the collection. This provides the main API for
+     * accessing and updating individual records in a document.
+     *
+     * @param id - The ID of the record to get.
+     * @returns The record reference, or undefined if it doesn't exist. The
+     * recordRef is a stable object and can be used for reference equality checks.
+     */
     get(id: RecordId): RecordRef<M> | undefined;
+    /**
+     * Check if a record exists in the collection.
+     *
+     * @param id - The ID of the record to check.
+     * @returns True if the record exists, false otherwise.
+     */
     has(id: RecordId): boolean;
+    /**
+     * Set the data for a record in the collection (creating it if it doesn't exist).
+     *
+     * @param id - The ID of the record to set.
+     * @param state - The data to set for the record.
+     * @returns A promise that resolves when the record is set.
+     *
+     * @example
+     * ```ts
+     * const recordCollection = docRef.getRecords(MyModel);
+     * await recordCollection.set("record-id", { field: "value" });
+     * ```
+     */
     set(id: RecordId, state: ModelData<M>): Promise<void>;
     readonly size: number;
     [Symbol.iterator](): Iterator<RecordRef<M>>;
+    /**
+     * Subscribe to added items in the collection.
+     *
+     * @param callback - The callback to invoke when items are added.
+     * @returns An unsubscribe function.
+     */
     readonly onItemsAdded: (callback: (items: readonly RecordRef<M>[]) => void) => () => void;
+    /**
+     * Subscribe to changed items in the collection.
+     *
+     * @param callback - The callback to invoke when items are changed.
+     * @returns An unsubscribe function.
+     */
     readonly onItemsChanged: (callback: (items: readonly RecordRef<M>[]) => void) => () => void;
+    /**
+     * Subscribe to deleted items in the collection.
+     *
+     * @param callback - The callback to invoke when items are deleted.
+     * @returns An unsubscribe function.
+     */
     readonly onItemsDeleted: (callback: (items: readonly RecordRef<M>[]) => void) => () => void;
 }
 
 type DocumentId = Flavored<"DocumentId">;
+/**
+ * Options for subscribing to presence events on a document.
+ */
+interface PresenceSubscriptionOptions {
+    /**
+     * If true, presence events originating from the local user will be ignored.
+     *
+     * @default true
+     */
+    readonly ignoreSelfUpdates?: boolean;
+}
 declare const DocumentRefBrand: unique symbol;
+/**
+ * A reference to a document in the Pack system.
+ *
+ * A documentRef returned by various interfaces from the pack app instance or
+ * utilities such as react hooks from @palantir/pack.state.react provides
+ * methods to interact with the document, such as subscribing to & making
+ * changes to the document state and also related activity or presence events.
+ *
+ * A stable documentRef object is guaranteed for the same document id within the
+ * same app instance.
+ */
 interface DocumentRef<D extends DocumentSchema = DocumentSchema> {
     readonly id: DocumentId;
     readonly schema: D;
     readonly [DocumentRefBrand]: typeof DocumentRefBrand;
-    readonly getDocSnapshot: () => Promise<DocumentState<D>>;
-    readonly getRecords: <R extends Model>(model: R) => RecordCollectionRef<R>;
-    readonly onMetadataChange: (callback: (docId: DocumentRef<D>, metadata: DocumentMetadata) => void) => Unsubscribe;
-    readonly onStateChange: (callback: (docRef: DocumentRef<D>) => void) => Unsubscribe;
+    /**
+     * Get a snapshot of the current document state.
+     *
+     * This is largely for debugging and dumps a json view of the whole document state.
+     *
+     * @experimental
+     */
+    getDocSnapshot(): Promise<DocumentState<D>>;
+    /**
+     * Get or create a ref to the collection of all records for the specified
+     * model in this document.
+     *
+     * @param model The model type from the application's generated schema.
+     * @returns A stable {@link RecordCollectionRef} object providing an interface
+     * to interact with the records of the specified model type in this document.
+     *
+     * @example
+     * ```ts
+     * import { DocumentModel, MyModel } from "@myapp/schema";
+     * import { app } from "./appInstance";
+     *
+     * const docRef = app.state.createDocRef(DocumentModel, someDocumentId);
+     * const myRecordCollection = docRef.getRecords(MyModel);
+     *
+     * myRecordCollection.onItemsAdded((items) => {
+     *   console.log("New records added:", items);
+     * })
+     * ```
+     */
+    getRecords<R extends Model>(model: R): RecordCollectionRef<R>;
+    /**
+     * Subscribe to activity events for the document.
+     *
+     * Activity is used by applications to describe changes to the document, for
+     * populating activity feeds, change histories, notifications and similar
+     * features.
+     *
+     * @see {withTransaction} for making edits that generate activity events.
+     *
+     * @returns An unsubscribe function.
+     * @example
+     * ```ts
+     * const unsubscribe = docRef.onActivity((docRef, event) => {
+     *   console.log("Activity event:", event);
+     * });
+     *
+     * // Submit an edit with a description to generate an activity event.
+     * docRef.withTransaction(() => {
+     *   // make some edits to the document here
+     * }, {
+     *   model: MyEventModel,
+     *   data: {
+     *     myDataField: "some value",
+     *     foo: 42,
+     *   },
+     * });
+     *
+     * // Later, to unsubscribe:
+     * unsubscribe();
+     * ```
+     */
+    onActivity(callback: (docRef: DocumentRef<D>, event: ActivityEvent) => void): Unsubscribe;
+    /**
+     * Subscribe to metadata changes for the document.
+     *
+     * @returns An unsubscribe function.
+     * @example
+     * ```ts
+     * const unsubscribe = docRef.onMetadataChange((docRef, metadata) => {
+     *   console.log("Metadata changed:", metadata);
+     * });
+     *
+     * // Later, to unsubscribe:
+     * unsubscribe();
+     * ```
+     */
+    onMetadataChange(callback: (docRef: DocumentRef<D>, metadata: DocumentMetadata) => void): Unsubscribe;
+    /**
+     * Subscribe to presence events for the document.
+     *
+     * Presence events are a way to broadcast and receive non-persisted awareness
+     * and presence events. For example, a user moving their cursor in a
+     * collaborative editor could be broadcast via custom presence events.
+     *
+     * @see {@link updateCustomPresence} to publish custom presence updates.
+     *
+     * @param callback The callback to invoke on presence events.
+     * @param options Options for the presence subscription.
+     * @returns An unsubscribe function.
+     * @example
+     * ```ts
+     * const unsubscribe = docRef.onPresence((docRef, event) => {
+     *   console.log("Presence event:", event);
+     *   if (event.model === MyPresenceModel) {
+     *     updateCursor((event.eventData as ModelData<MyPresenceModel>).cursorPosition);
+     *   }
+     * }, { ignoreSelfUpdates: true });
+     *
+     * // Broadcast a presence update
+     * docRef.updateCustomPresence(MyPresenceModel, {
+     *  cursorPosition: [42, 7],
+     * });
+     *
+     * // Later, to unsubscribe:
+     * unsubscribe();
+     * ```
+     */
+    onPresence(callback: (docRef: DocumentRef<D>, event: PresenceEvent) => void, options?: PresenceSubscriptionOptions): Unsubscribe;
+    /**
+     * Subscribe to be notified any time the document state changes.
+     * This is largely for testing purposes.
+     *
+     * @experimental
+     *
+     * @param callback The callback to invoke on state changes.
+     * @returns An unsubscribe function.
+     * @example
+     * ```ts
+     * const unsubscribe = docRef.onStateChange((docRef) => {
+     *   console.log("Document state changed:", docRef);
+     * });
+     *
+     * // Later, to unsubscribe:
+     * unsubscribe();
+     * ```
+     */
+    onStateChange(callback: (docRef: DocumentRef<D>) => void): Unsubscribe;
+    /**
+     * Broadcasts an update for the specified model as presence data to other
+     * subscribers.
+     *
+     * Presence data is ephemeral and not stored as part of the document state. It
+     * is intended for broadcasting transient user presence and awareness
+     * information. Each different model type used for presence is expected to
+     * update the latest 'presence state' for that model type.
+     *
+     * @see {@link onPresence} to subscribe to presence updates.
+     *
+     * @param model The model type to update presence for.
+     * @param eventData The new presence data for the model.
+     */
+    updateCustomPresence<M extends Model = Model>(model: M, eventData: ModelData<M>): void;
+    /**
+     * Execute one or more document edits within a transaction, optionally providing
+     * a description of the edit for activity tracking.
+     *
+     * All edits made within the provided function will be treated as a single
+     * atomic edit operation. If a description is provided, an activity event will
+     * be generated for the edit.
+     *
+     * If this is called within an existing transaction, the inner edits will be
+     * included in the outer transaction only, and the inner descriptions will be
+     * discarded.
+     *
+     * @see {@link onActivity} to subscribe to activity events on this document.
+     *
+     * @param fn A lambda including some document edits.
+     * @param description Optional description of the edit for activity tracking.
+     *
+     * @example
+     * ```ts
+     * docRef.withTransaction(() => {
+     *   const myRecords = docRef.getRecords(MyModel);
+     *   myRecords.set("record-1", { field: "new value" });
+     *   myRecords.delete("record-2");
+     * }, {
+     *   model: MyEditEventModel,
+     *   data: {
+     *     summary: "Updated record-1 and deleted record-2",
+     *   },
+     * });
+     * ```
+     */
+    withTransaction(fn: () => void, description?: EditDescription): void;
 }
 
 type MediaId = Flavored<"MediaId">;
@@ -136,12 +622,4 @@ interface ObjectRef {
     readonly subscribe?: (callback: unknown) => unknown;
 }
 
-type UserId = Flavored<"pack:UserId">;
-declare const UserRefBrand: unique symbol;
-interface UserRef {
-    readonly userId: UserId;
-    readonly [UserRefBrand]: typeof UserRefBrand;
-    readonly get: (force?: boolean) => Promise<unknown>;
-}
-
-export { type DiscretionaryPrincipal, type DiscretionaryPrincipal_All, type DiscretionaryPrincipal_GroupId, type DiscretionaryPrincipal_UserId, type DocumentId, type DocumentMetadata, type DocumentRef, DocumentRefBrand, type DocumentSchema, type DocumentSchemaMetadata, type DocumentState, ExternalRefType, type MediaId, type MediaRef, MediaRefBrand, Metadata, type Model, type ModelData, type ModelMetadata, type ObjectId, type ObjectRef, ObjectRefBrand, type RecordCollectionRef, RecordCollectionRefBrand, type RecordId, type RecordRef, RecordRefBrand, type Unsubscribe, type UserId, type UserRef, UserRefBrand, type WithMetadata, getMetadata };
+export { type ActivityEvent, type ActivityEventData, type ActivityEventDataCustom, ActivityEventDataType, type ActivityEventDataUnknown, type ActivityEventId, type DiscretionaryPrincipal, type DiscretionaryPrincipal_All, type DiscretionaryPrincipal_GroupId, type DiscretionaryPrincipal_UserId, type DocumentId, type DocumentMetadata, type DocumentRef, DocumentRefBrand, type DocumentSchema, type DocumentSchemaMetadata, type DocumentState, type EditDescription, ExternalRefType, type MediaId, type MediaRef, MediaRefBrand, Metadata, type Model, type ModelData, type ModelMetadata, type ObjectId, type ObjectRef, ObjectRefBrand, type PresenceEvent, type PresenceEventData, type PresenceEventDataArrived, type PresenceEventDataCustom, type PresenceEventDataDeparted, PresenceEventDataType, type PresenceEventUnknown, type PresenceSubscriptionOptions, type RecordCollectionRef, RecordCollectionRefBrand, type RecordId, type RecordRef, RecordRefBrand, type Unsubscribe, type UserId, type UserRef, UserRefBrand, type WithMetadata, getMetadata };

package/build/esm/index.js

@@ -1,3 +1,9 @@
+// src/types/ActivityEvent.ts
+var ActivityEventDataType = {
+  CUSTOM_EVENT: "customEvent",
+  UNKNOWN: "unknown"
+};
+
 // src/types/DocumentRef.ts
 var DocumentRefBrand = Symbol("pack:DocumentRef");
 
@@ -7,11 +13,21 @@ var MediaRefBrand = Symbol("pack:MediaRef");
 // src/types/Metadata.ts
 var Metadata = Symbol("@palantir/pack.document-schema/metadata");
 function getMetadata(obj) {
-  const metadata = obj[Metadata];
-  if (metadata == null) {
-    throw new Error("Object does not have metadata");
+  const directMetadata = obj[Metadata];
+  if (directMetadata != null) {
+    return directMetadata;
+  }
+  const metadataString = Metadata.toString();
+  const symbolKeys = Object.getOwnPropertySymbols(obj);
+  for (const symbolKey of symbolKeys) {
+    if (symbolKey.toString() === metadataString) {
+      const fallbackMetadata = obj[symbolKey];
+      if (fallbackMetadata != null) {
+        return fallbackMetadata;
+      }
+    }
   }
-  return metadata;
+  throw new Error("Object does not have metadata");
 }
 
 // src/types/Model.ts
@@ -25,6 +41,14 @@ var ExternalRefType = {
 // src/types/ObjectRef.ts
 var ObjectRefBrand = Symbol("pack:ObjectRef");
 
+// src/types/PresenceEvent.ts
+var PresenceEventDataType = {
+  ARRIVED: "presenceArrived",
+  DEPARTED: "presenceDeparted",
+  CUSTOM_EVENT: "customEvent",
+  UNKNOWN: "unknown"
+};
+
 // src/types/RecordCollectionRef.ts
 var RecordCollectionRefBrand = Symbol("pack:RecordCollectionRef");
 
@@ -34,6 +58,6 @@ var RecordRefBrand = Symbol("pack:RecordRef");
 // src/types/UserRef.ts
 var UserRefBrand = Symbol("pack:UserRef");
 
-export { DocumentRefBrand, ExternalRefType, MediaRefBrand, Metadata, ObjectRefBrand, RecordCollectionRefBrand, RecordRefBrand, UserRefBrand, getMetadata };
+export { ActivityEventDataType, DocumentRefBrand, ExternalRefType, MediaRefBrand, Metadata, ObjectRefBrand, PresenceEventDataType, RecordCollectionRefBrand, RecordRefBrand, UserRefBrand, getMetadata };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map