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

package/build/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/DocumentRef.ts","../../src/types/MediaRef.ts","../../src/types/Metadata.ts","../../src/types/Model.ts","../../src/types/ObjectRef.ts","../../src/types/RecordCollectionRef.ts","../../src/types/RecordRef.ts","../../src/types/UserRef.ts"],"names":[],"mappings":";AAgBO,IAAM,gBAAA,GAAmB,OAAO,kBAAkB;;;ACAlD,IAAM,aAAA,GAAgB,OAAO,eAAe;;;ACA5C,IAAM,QAAA,GAAW,OAAO,yCAAyC;AACjE,SAAS,YAAY,GAAA,EAAK;AAE/B,EAAA,MAAM,QAAA,GAAW,IAAI,QAAQ,CAAA;AAC7B,EAAA,IAAI,YAAY,IAAA,EAAM;AACpB,IAAA,MAAM,IAAI,MAAM,+BAA+B,CAAA;AAAA,EACjD;AACA,EAAA,OAAO,QAAA;AACT;;;ACDO,IAAM,eAAA,GAAkB;AAAA,EAC7B,OAAA,EAAS,QAAA;AAAA,EACT,SAAA,EAAW,UAAA;AAAA,EACX,UAAA,EAAY,WAAA;AAAA,EACZ,QAAA,EAAU;AACZ;;;ACZO,IAAM,cAAA,GAAiB,OAAO,gBAAgB;;;ACA9C,IAAM,wBAAA,GAA2B,OAAO,0BAA0B;;;ACAlE,IAAM,cAAA,GAAiB,OAAO,gBAAgB;;;ACA9C,IAAM,YAAA,GAAe,OAAO,cAAc","file":"index.js","sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const DocumentRefBrand = Symbol(\"pack:DocumentRef\");","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const MediaRefBrand = Symbol(\"pack:MediaRef\");\n\n/**\n * @experimental\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const Metadata = Symbol(\"@palantir/pack.document-schema/metadata\");\nexport function getMetadata(obj) {\n  // TS always treats symbol keys as optional\n  const metadata = obj[Metadata];\n  if (metadata == null) {\n    throw new Error(\"Object does not have metadata\");\n  }\n  return metadata;\n}","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A Model defines the structure of a document record or union.\n *\n * It includes a zod schema for validation and type information.\n */\n// TODO: I think we can/should hide the zod types\n\nexport const ExternalRefType = {\n  DOC_REF: \"docRef\",\n  MEDIA_REF: \"mediaRef\",\n  OBJECT_REF: \"objectRef\",\n  USER_REF: \"userRef\"\n};","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const ObjectRefBrand = Symbol(\"pack:ObjectRef\");\n\n/**\n * @experimental\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const RecordCollectionRefBrand = Symbol(\"pack:RecordCollectionRef\");","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const RecordRefBrand = Symbol(\"pack:RecordRef\");","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const UserRefBrand = Symbol(\"pack:UserRef\");"]}
+{"version":3,"sources":["../../src/types/ActivityEvent.ts","../../src/types/DocumentRef.ts","../../src/types/MediaRef.ts","../../src/types/Metadata.ts","../../src/types/Model.ts","../../src/types/ObjectRef.ts","../../src/types/PresenceEvent.ts","../../src/types/RecordCollectionRef.ts","../../src/types/RecordRef.ts","../../src/types/UserRef.ts"],"names":[],"mappings":";AAgBO,IAAM,qBAAA,GAAwB;AAAA,EACnC,YAAA,EAAc,aAAA;AAAA,EACd,OAAA,EAAS;AACX;;;ACCO,IAAM,gBAAA,GAAmB,OAAO,kBAAkB;;;ACJlD,IAAM,aAAA,GAAgB,OAAO,eAAe;;;ACA5C,IAAM,QAAA,GAAW,OAAO,yCAAyC;AACjE,SAAS,YAAY,GAAA,EAAK;AAE/B,EAAA,MAAM,cAAA,GAAiB,IAAI,QAAQ,CAAA;AACnC,EAAA,IAAI,kBAAkB,IAAA,EAAM;AAC1B,IAAA,OAAO,cAAA;AAAA,EACT;AAIA,EAAA,MAAM,cAAA,GAAiB,SAAS,QAAA,EAAS;AACzC,EAAA,MAAM,UAAA,GAAa,MAAA,CAAO,qBAAA,CAAsB,GAAG,CAAA;AACnD,EAAA,KAAA,MAAW,aAAa,UAAA,EAAY;AAClC,IAAA,IAAI,SAAA,CAAU,QAAA,EAAS,KAAM,cAAA,EAAgB;AAC3C,MAAA,MAAM,gBAAA,GAAmB,IAAI,SAAS,CAAA;AACtC,MAAA,IAAI,oBAAoB,IAAA,EAAM;AAC5B,QAAA,OAAO,gBAAA;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACA,EAAA,MAAM,IAAI,MAAM,+BAA+B,CAAA;AACjD;;;ACVO,IAAM,eAAA,GAAkB;AAAA,EAC7B,OAAA,EAAS,QAAA;AAAA,EACT,SAAA,EAAW,UAAA;AAAA,EACX,UAAA,EAAY,WAAA;AAAA,EACZ,QAAA,EAAU;AACZ;;;AChBO,IAAM,cAAA,GAAiB,OAAO,gBAAgB;;;ACA9C,IAAM,qBAAA,GAAwB;AAAA,EACnC,OAAA,EAAS,iBAAA;AAAA,EACT,QAAA,EAAU,kBAAA;AAAA,EACV,YAAA,EAAc,aAAA;AAAA,EACd,OAAA,EAAS;AACX;;;ACLO,IAAM,wBAAA,GAA2B,OAAO,0BAA0B;;;ACAlE,IAAM,cAAA,GAAiB,OAAO,gBAAgB;;;ACA9C,IAAM,YAAA,GAAe,OAAO,cAAc","file":"index.js","sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const ActivityEventDataType = {\n  CUSTOM_EVENT: \"customEvent\",\n  UNKNOWN: \"unknown\"\n};\n\n/**\n * Application specific custom activity event data, as described in a transaction edit,\n * using an application sdk's generated model types.\n *\n * @example\n * ```ts\n * const unsubscribe = docRef.onActivity((docRef, event) => {\n *   console.log(\"Activity event:\", event);\n * });\n * // Submit an edit with a description to generate an activity event.\n * docRef.withTransaction(() => {\n *   // make some edits to the document here\n * }, {\n *   model: MyEventModel,\n *   data: {\n *     myDataField: \"some value\",\n *     foo: 42,\n *   },\n * });\n * ```\n */\n\n// TODO: add standard document activity events (need to be added to api types)\n\n/**\n * Fallback for unrecognized activity event types.\n *\n * This allows some flexibility with new event types added to the platform.\n * Likely unknown events represent a new platform event type and will be handled\n * in a future release of pack libraries and can be safely ignored by\n * applications.\n */\n\n/**\n * An event representing an activity that has occurred on a document. This\n * includes standard document events as well as custom application-specific\n * events describing document edits.\n *\n * ActivityEvents are useful for building activity feeds, or notifications.\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Options for subscribing to presence events on a document.\n */\n\nexport const DocumentRefBrand = Symbol(\"pack:DocumentRef\");\n\n/**\n * A reference to a document in the Pack system.\n *\n * A documentRef returned by various interfaces from the pack app instance or\n * utilities such as react hooks from @palantir/pack.state.react provides\n * methods to interact with the document, such as subscribing to & making\n * changes to the document state and also related activity or presence events.\n *\n * A stable documentRef object is guaranteed for the same document id within the\n * same app instance.\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const MediaRefBrand = Symbol(\"pack:MediaRef\");\n\n/**\n * @experimental\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const Metadata = Symbol(\"@palantir/pack.document-schema/metadata\");\nexport function getMetadata(obj) {\n  // First try the direct symbol access\n  const directMetadata = obj[Metadata];\n  if (directMetadata != null) {\n    return directMetadata;\n  }\n\n  // Fallback: search for a symbol with matching string representation\n  // If the different copies of this package are used, the symbol references will not match directly\n  const metadataString = Metadata.toString();\n  const symbolKeys = Object.getOwnPropertySymbols(obj);\n  for (const symbolKey of symbolKeys) {\n    if (symbolKey.toString() === metadataString) {\n      const fallbackMetadata = obj[symbolKey];\n      if (fallbackMetadata != null) {\n        return fallbackMetadata;\n      }\n    }\n  }\n  throw new Error(\"Object does not have metadata\");\n}","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A Model defines the structure of a document record or union.\n *\n * It includes a zod schema for validation and type information.\n */\n// TODO: I think we can/should hide the zod types\n\n/**\n * Describes an edit made to a document.\n */\n\nexport const ExternalRefType = {\n  DOC_REF: \"docRef\",\n  MEDIA_REF: \"mediaRef\",\n  OBJECT_REF: \"objectRef\",\n  USER_REF: \"userRef\"\n};","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const ObjectRefBrand = Symbol(\"pack:ObjectRef\");\n\n/**\n * @experimental\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const PresenceEventDataType = {\n  ARRIVED: \"presenceArrived\",\n  DEPARTED: \"presenceDeparted\",\n  CUSTOM_EVENT: \"customEvent\",\n  UNKNOWN: \"unknown\"\n};\n\n/**\n * Any client that subscribes to presence events via `DocumentRef.onPresence` will\n * be considered 'present' on the document, and trigger an 'arrived' presence event.\n * When they disconnect or unsubscribe from presence events, a 'departed' presence event\n * will be triggered.\n */\n\n/**\n * Any client that subscribes to presence events via `DocumentRef.onPresence` will\n * be considered 'present' on the document, and trigger an 'arrived' presence event.\n * When they disconnect or unsubscribe from presence events, a 'departed' presence event\n * will be triggered.\n */\n\n/**\n * Application specific custom presence event data.\n *\n * Each different model type used for presence is expected to update the latest\n * 'presence state' for that model type.\n *\n * For example, your app may have need to broadcast user cursor positions and\n * selection ranges as presence data. You could define your schema to include a\n * `CursorPosition` and `SelectionRange` record types, and set them\n * independently via `{@link DocumentRef.updateCustomPresence}`. Each model type\n * sent as a custom presence event should be considered a separate 'channel' of\n * presence data on this document.\n */\n\n/**\n * Fallback for unrecognized activity event types.\n *\n * This allows some flexibility with new event types added to the platform.\n * Likely unknown events represent a new platform event type and will be handled\n * in a future release of pack libraries and can be safely ignored by\n * applications.\n */\n\n/**\n * An event representing a transient awareness or presence change for a user on this document.\n * The presence channel is intended for ephemeral data such as user cursors, selections, or\n * other live collaboration indicators.\n *\n * PresenceEvents are not persisted in document history.\n *\n * When a client goes offline, its presence is considered departed and any presence events\n * associated with that user should be considered stale and / or cleared.\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const RecordCollectionRefBrand = Symbol(\"pack:RecordCollectionRef\");\n\n/**\n * A reference providing an API to interact with a collection of records in a document.\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const RecordRefBrand = Symbol(\"pack:RecordRef\");\n\n/**\n * A reference providing an API to interact with a specific record in a\n * document. This is the main interface for accessing and updating individual\n * records.\n *\n * These will be created by docRef or recordCollectionRef APIs for example and\n * should not be created manually. RecordRefs are stable objects that can be\n * used for reference equality checks.\n *\n * @example\n * ```ts\n * import { DocumentRef, DocumentSchema, MyModel } from \"@myapp/schema\";\n * import { app } from \"./appInstance\";\n *\n * const docRef = app.getDocRef<DocumentSchema>(someDocumentId);\n *\n * const recordRef = docRef.getRecords(MyModel).set(\"my-record-id\", { myFieldName: \"some value\", foo: 42 });\n *\n * // Or get a specific record.\n * const recordRef = docRef.getRecords(MyModel).get(\"my-record-id\");\n */","/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport const UserRefBrand = Symbol(\"pack:UserRef\");\n\n/**\n * A reference providing an API to interact with a user.\n *\n * @experimental\n */"]}

package/build/types/__tests__/Metadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/types/__tests__/Metadata.test.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"","names":[],"sources":["../../../src/__tests__/Metadata.test.ts"],"version":3,"file":"Metadata.test.d.ts"}

package/build/types/index.d.ts

@@ -1,15 +1,19 @@
+export { ActivityEventDataType } from "./types/ActivityEvent.js";
+export type { ActivityEvent, ActivityEventData, ActivityEventDataCustom, ActivityEventDataUnknown, ActivityEventId } from "./types/ActivityEvent.js";
 export type { DiscretionaryPrincipal, DiscretionaryPrincipal_All, DiscretionaryPrincipal_GroupId, DiscretionaryPrincipal_UserId, DocumentMetadata } from "./types/DocumentMetadata.js";
 export { DocumentRefBrand } from "./types/DocumentRef.js";
-export type { DocumentId, DocumentRef } from "./types/DocumentRef.js";
+export type { DocumentId, DocumentRef, PresenceSubscriptionOptions } from "./types/DocumentRef.js";
 export type { DocumentSchema, DocumentSchemaMetadata, DocumentState } from "./types/DocumentSchema.js";
 export { MediaRefBrand } from "./types/MediaRef.js";
 export type { MediaId, MediaRef } from "./types/MediaRef.js";
 export { getMetadata, Metadata } from "./types/Metadata.js";
 export type { WithMetadata } from "./types/Metadata.js";
 export { ExternalRefType } from "./types/Model.js";
-export type { Model, ModelData, ModelMetadata } from "./types/Model.js";
+export type { EditDescription, Model, ModelData, ModelMetadata } from "./types/Model.js";
 export { ObjectRefBrand } from "./types/ObjectRef.js";
 export type { ObjectId, ObjectRef } from "./types/ObjectRef.js";
+export { PresenceEventDataType } from "./types/PresenceEvent.js";
+export type { PresenceEvent, PresenceEventData, PresenceEventDataArrived, PresenceEventDataCustom, PresenceEventDataDeparted, PresenceEventUnknown } from "./types/PresenceEvent.js";
 export { RecordCollectionRefBrand } from "./types/RecordCollectionRef.js";
 export type { RecordCollectionRef } from "./types/RecordCollectionRef.js";
 export { RecordRefBrand } from "./types/RecordRef.js";

package/build/types/index.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cACE,wBACA,4BACA,gCACA,+BACA,wBACK;AACP,SAAS,wBAAwB;AACjC,cAAc,YAAY,mBAAmB;AAC7C,cACE,gBACA,wBACA,qBACK;AACP,SAAS,qBAAqB;AAC9B,cAAc,SAAS,gBAAgB;AACvC,SAAS,aAAa,gBAAgB;AACtC,cAAc,oBAAoB;AAClC,SAAS,uBAAuB;AAChC,cAAc,OAAO,WAAW,qBAAqB;AACrD,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,SAAS,gCAAgC;AACzC,cAAc,2BAA2B;AACzC,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,cAAc,mBAAmB;AACjC,SAAS,oBAAoB;AAC7B,cAAc,QAAQ,eAAe","names":[],"sources":["../../src/index.ts"],"version":3,"file":"index.d.ts"}
+{"mappings":"AAgBA,SAAS,6BAA6B;AACtC,cACE,eACA,mBACA,yBACA,0BACA,uBACK;AACP,cACE,wBACA,4BACA,gCACA,+BACA,wBACK;AACP,SAAS,wBAAwB;AACjC,cAAc,YAAY,aAAa,mCAAmC;AAC1E,cACE,gBACA,wBACA,qBACK;AACP,SAAS,qBAAqB;AAC9B,cAAc,SAAS,gBAAgB;AACvC,SAAS,aAAa,gBAAgB;AACtC,cAAc,oBAAoB;AAClC,SAAS,uBAAuB;AAChC,cAAc,iBAAiB,OAAO,WAAW,qBAAqB;AACtE,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,SAAS,6BAA6B;AACtC,cACE,eACA,mBACA,0BACA,yBACA,2BACA,4BACK;AACP,SAAS,gCAAgC;AACzC,cAAc,2BAA2B;AACzC,SAAS,sBAAsB;AAC/B,cAAc,UAAU,iBAAiB;AACzC,cAAc,mBAAmB;AACjC,SAAS,oBAAoB;AAC7B,cAAc,QAAQ,eAAe","names":[],"sources":["../../src/index.ts"],"version":3,"file":"index.d.ts"}

package/build/types/types/ActivityEvent.d.ts

@@ -0,0 +1,64 @@
+import type { Flavored } from "@palantir/pack.core";
+import type { Model, ModelData } from "./Model.js";
+import type { UserId } from "./UserRef.js";
+export type ActivityEventId = Flavored<"pack:EventId">;
+export 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,
+*   },
+* });
+* ```
+*/
+export 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.
+*/
+export interface ActivityEventDataUnknown {
+	readonly type: "unknown";
+	readonly rawType: string;
+	readonly rawData: unknown;
+}
+export 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.
+*/
+export 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;
+}

package/build/types/types/ActivityEvent.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,OAAO,iBAAiB;AACtC,cAAc,cAAc;AAE5B,YAAY,kBAAkB,SAAS;AAEvC,OAAO,cAAM;UACX,cAAc;UACd,SAAS;;;;;;;;;;;;;;;;;;;;;;;AAwBX,iBAAiB,wBAAwB,UAAU,QAAQ,OAAO;UACvD,aAAa,sBAAsB;UACnC,OAAO;UACP,WAAW,UAAU;;;;;;;;;;AAahC,iBAAiB,yBAAyB;UAC/B,MAAM;UACN;UACA;;AAGX,YAAY,oBAAoB,0BAA0B;;;;;;;;AAS1D,iBAAiB,cAAc;;UAEpB;UACA,WAAW;UACX;UACA,WAAW;UACX,SAAS;UACT","names":[],"sources":["../../../src/types/ActivityEvent.ts"],"version":3,"file":"ActivityEvent.d.ts"}

package/build/types/types/DocumentRef.d.ts

@@ -1,17 +1,211 @@
 import type { Flavored } from "@palantir/pack.core";
+import type { ActivityEvent } from "./ActivityEvent.js";
 import type { DocumentMetadata } from "./DocumentMetadata.js";
 import type { DocumentSchema, DocumentState } from "./DocumentSchema.js";
-import type { Model } from "./Model.js";
+import type { EditDescription, Model, ModelData } from "./Model.js";
+import type { PresenceEvent } from "./PresenceEvent.js";
 import type { RecordCollectionRef } from "./RecordCollectionRef.js";
 import type { Unsubscribe } from "./Unsubscribe.js";
 export type DocumentId = Flavored<"DocumentId">;
+/**
+* Options for subscribing to presence events on a document.
+*/
+export interface PresenceSubscriptionOptions {
+	/**
+	* If true, presence events originating from the local user will be ignored.
+	*
+	* @default true
+	*/
+	readonly ignoreSelfUpdates?: boolean;
+}
 export 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.
+*/
 export 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;
 }

package/build/types/types/DocumentRef.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,wBAAwB;AACtC,cAAc,gBAAgB,qBAAqB;AACnD,cAAc,aAAa;AAC3B,cAAc,2BAA2B;AACzC,cAAc,mBAAmB;AAEjC,YAAY,aAAa,SAAS;AAElC,OAAO,cAAMA;AAEb,iBAAiB,YAAY,UAAU,iBAAiB,gBAAgB;UAC7D,IAAI;UACJ,QAAQ;WACP,0BAA0B;UAE3B,sBAAsB,QAAQ,cAAc;UAC5C,aAAa,UAAU,OAAO,OAAO,MAAM,oBAAoB;UAC/D,mBACP,WAAW,OAAO,YAAY,IAAI,UAAU,8BACzC;UACI,gBACP,WAAW,QAAQ,YAAY,gBAC5B","names":["DocumentRefBrand: unique symbol"],"sources":["../../../src/types/DocumentRef.ts"],"version":3,"file":"DocumentRef.d.ts"}
+{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,qBAAqB;AACnC,cAAc,wBAAwB;AACtC,cAAc,gBAAgB,qBAAqB;AACnD,cAAc,iBAAiB,OAAO,iBAAiB;AACvD,cAAc,qBAAqB;AACnC,cAAc,2BAA2B;AACzC,cAAc,mBAAmB;AAEjC,YAAY,aAAa,SAAS;;;;AAKlC,iBAAiB,4BAA4B;;;;;;UAMlC;;AAGX,OAAO,cAAMA;;;;;;;;;;;;AAab,iBAAiB,YAAY,UAAU,iBAAiB,gBAAgB;UAC7D,IAAI;UACJ,QAAQ;WACP,0BAA0B;;;;;;;;CASpC,kBAAkB,QAAQ,cAAc;;;;;;;;;;;;;;;;;;;;;;CAuBxC,WAAW,UAAU,OAAO,OAAO,IAAI,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiC3D,WACE,WAAW,QAAQ,YAAY,IAAI,OAAO,yBACzC;;;;;;;;;;;;;;;CAgBH,iBACE,WAAW,QAAQ,YAAY,IAAI,UAAU,4BAC5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCH,WACE,WAAW,QAAQ,YAAY,IAAI,OAAO,wBAC1C,UAAU,8BACT;;;;;;;;;;;;;;;;;;;CAoBH,cACE,WAAW,QAAQ,YAAY,cAC9B;;;;;;;;;;;;;;;CAgBH,qBAAqB,UAAU,QAAQ,OACrC,OAAO,GACP,WAAW,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCvB,gBAAgB,gBAAgB,cAAc","names":["DocumentRefBrand: unique symbol"],"sources":["../../../src/types/DocumentRef.ts"],"version":3,"file":"DocumentRef.d.ts"}

package/build/types/types/DocumentSchema.d.ts

@@ -1,8 +1,14 @@
 import type { WithMetadata } from "./Metadata.js";
 import type { Model, ModelData } from "./Model.js";
+/**
+* The base type for an application sdk's generated document schema.
+*/
 export interface DocumentSchema extends WithMetadata<DocumentSchemaMetadata> {
 	readonly [modelName: string]: Model;
 }
+/**
+* The plain object representation of the state of a document.
+*/
 export type DocumentState<S extends DocumentSchema> = { readonly [K in Exclude<keyof S, symbol>] : {
 	readonly [key: string]: ModelData<S[K]>;
 } };

package/build/types/types/DocumentSchema.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,oBAAoB;AAClC,cAAc,OAAO,iBAAiB;AAEtC,iBAAiB,uBAAuB,aAAa,wBAAwB;+BAC7C;;AAGhC,YAAY,cAAc,UAAU,8BACxB,KAAK,cAAc,cAAa;yBAA0B,UAAU,EAAE;;AAGlF,iBAAiB,uBAAuB;UAC7B","names":[],"sources":["../../../src/types/DocumentSchema.ts"],"version":3,"file":"DocumentSchema.d.ts"}
+{"mappings":"AAgBA,cAAc,oBAAoB;AAClC,cAAc,OAAO,iBAAiB;;;;AAKtC,iBAAiB,uBAAuB,aAAa,wBAAwB;+BAC7C;;;;;AAMhC,YAAY,cAAc,UAAU,8BACxB,KAAK,cAAc,cAAa;yBAA0B,UAAU,EAAE;;AAGlF,iBAAiB,uBAAuB;UAC7B","names":[],"sources":["../../../src/types/DocumentSchema.ts"],"version":3,"file":"DocumentSchema.d.ts"}

package/build/types/types/Model.d.ts

@@ -13,6 +13,13 @@ export interface Model<
 	readonly zodSchema: Readonly<Z>;
 }
 export type ModelData<M extends Model> = M["__type"];
+/**
+* Describes an edit made to a document.
+*/
+export interface EditDescription<M extends Model = Model> {
+	readonly data: ModelData<M>;
+	readonly model: M;
+}
 export declare const ExternalRefType: {
 	readonly DOC_REF: "docRef";
 	readonly MEDIA_REF: "mediaRef";
@@ -21,6 +28,12 @@ export declare const ExternalRefType: {
 };
 export type ExternalRefType = typeof ExternalRefType[keyof typeof ExternalRefType];
 export 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;
 }

package/build/types/types/Model.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,eAAe;AAC7B,cAAc,oBAAoB;;;;;;AAQlC,iBAAiB;CAAM;CAAa,UAAU,QAAQ,KAAK,QAAQ;UACzD,aAAa,cAAc,IACrC;UACW,QAAQ;UACR,WAAW,SAAS;;AAG/B,YAAY,UAAU,UAAU,SAAS,EAAE;AAE3C,OAAO,cAAM;UACX,SAAS;UACT,WAAW;UACX,YAAY;UACZ,UAAU;;AAGZ,YAAY,yBAAyB,6BAA6B;AAElE,iBAAiB,cAAc,aAAa;UACjC,wBAAwB,SAAS,aAAa,GAAG;UACjD","names":[],"sources":["../../../src/types/Model.ts"],"version":3,"file":"Model.d.ts"}
+{"mappings":"AAgBA,cAAc,eAAe;AAC7B,cAAc,oBAAoB;;;;;;AAQlC,iBAAiB;CAAM;CAAa,UAAU,QAAQ,KAAK,QAAQ;UACzD,aAAa,cAAc,IACrC;UACW,QAAQ;UACR,WAAW,SAAS;;AAG/B,YAAY,UAAU,UAAU,SAAS,EAAE;;;;AAK3C,iBAAiB,gBAAgB,UAAU,QAAQ,OAAO;UAC/C,MAAM,UAAU;UAChB,OAAO;;AAGlB,OAAO,cAAM;UACX,SAAS;UACT,WAAW;UACX,YAAY;UACZ,UAAU;;AAGZ,YAAY,yBAAyB,6BAA6B;AAElE,iBAAiB,cAAc,aAAa;;;;UAIjC,wBAAwB,SAAS,aAAa,GAAG;;;;UAIjD","names":[],"sources":["../../../src/types/Model.ts"],"version":3,"file":"Model.d.ts"}

package/build/types/types/PresenceEvent.d.ts

@@ -0,0 +1,73 @@
+import type { Model, ModelData } from "./Model.js";
+import type { UserId } from "./UserRef.js";
+export declare const PresenceEventDataType: {
+	readonly ARRIVED: "presenceArrived";
+	readonly DEPARTED: "presenceDeparted";
+	readonly CUSTOM_EVENT: "customEvent";
+	readonly UNKNOWN: "unknown";
+};
+export 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.
+*/
+export 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.
+*/
+export 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.
+*/
+export 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.
+*/
+export interface PresenceEventUnknown {
+	readonly type: "unknown";
+	readonly rawType: string;
+	readonly rawData: unknown;
+}
+export 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.
+*/
+export interface PresenceEvent {
+	readonly userId: UserId;
+	readonly eventData: PresenceEventData;
+}

package/build/types/types/PresenceEvent.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cAAc,OAAO,iBAAiB;AACtC,cAAc,cAAc;AAE5B,OAAO,cAAM;UACX,SAAS;UACT,UAAU;UACV,cAAc;UACd,SAAS;;AAGX,YAAY,+BACH,mCAAmC;;;;;;;AAQ5C,iBAAiB,yBAAyB;UAC/B,aAAa,sBAAsB;;;;;;;;AAS9C,iBAAiB,0BAA0B;UAChC,aAAa,sBAAsB;;;;;;;;;;;;;;;AAgB9C,iBAAiB,wBAAwB,UAAU,QAAQ,OAAO;UACvD,aAAa,sBAAsB;UACnC,WAAW,UAAU;UACrB,OAAO;;;;;;;;;;AAWlB,iBAAiB,qBAAqB;UAC3B,MAAM;UACN;UACA;;AAGX,YAAY,oBACR,2BACA,4BACA,0BACA;;;;;;;;;;;AAYJ,iBAAiB,cAAc;UACpB,QAAQ;UACR,WAAW","names":[],"sources":["../../../src/types/PresenceEvent.ts"],"version":3,"file":"PresenceEvent.d.ts"}

package/build/types/types/RecordCollectionRef.d.ts

@@ -2,17 +2,71 @@ import type { DocumentRef } from "./DocumentRef.js";
 import type { Model, ModelData } from "./Model.js";
 import type { RecordId, RecordRef } from "./RecordRef.js";
 export declare const RecordCollectionRefBrand: unique symbol;
+/**
+* A reference providing an API to interact with a collection of records in a document.
+*/
 export 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;
 }

package/build/types/types/RecordCollectionRef.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,mBAAmB;AACjC,cAAc,OAAO,iBAAiB;AACtC,cAAc,UAAU,iBAAiB;AAEzC,OAAO,cAAMA;AAIb,iBAAiB,oBAAoB,UAAU,QAAQ,OAAO;UACnD,QAAQ;UACR,OAAO;WACN,kCAAkC;CAE5C,OAAO,IAAI,WAAW;CACtB,IAAI,IAAI,WAAW,UAAU;CAC7B,IAAI,IAAI;CACR,IAAI,IAAI,UAAU,OAAO,UAAU,KAAK;UAC/B;EAER,OAAO,aAAa,SAAS,UAAU;UAE/B,eACP,WAAW,gBAAgB,UAAU;UAG9B,iBACP,WAAW,gBAAgB,UAAU;UAG9B,iBACP,WAAW,gBAAgB,UAAU","names":["RecordCollectionRefBrand: unique symbol"],"sources":["../../../src/types/RecordCollectionRef.ts"],"version":3,"file":"RecordCollectionRef.d.ts"}
+{"mappings":"AAgBA,cAAc,mBAAmB;AACjC,cAAc,OAAO,iBAAiB;AACtC,cAAc,UAAU,iBAAiB;AAEzC,OAAO,cAAMA;;;;AAOb,iBAAiB,oBAAoB,UAAU,QAAQ,OAAO;UACnD,QAAQ;UACR,OAAO;WACN,kCAAkC;;;;;;;CAQ5C,OAAO,IAAI,WAAW;;;;;;;;;CAStB,IAAI,IAAI,WAAW,UAAU;;;;;;;CAO7B,IAAI,IAAI;;;;;;;;;;;;;;CAcR,IAAI,IAAI,UAAU,OAAO,UAAU,KAAK;UAC/B;EAER,OAAO,aAAa,SAAS,UAAU;;;;;;;UAQ/B,eACP,WAAW,gBAAgB,UAAU;;;;;;;UAS9B,iBACP,WAAW,gBAAgB,UAAU;;;;;;;UAS9B,iBACP,WAAW,gBAAgB,UAAU","names":["RecordCollectionRefBrand: unique symbol"],"sources":["../../../src/types/RecordCollectionRef.ts"],"version":3,"file":"RecordCollectionRef.d.ts"}