@openneuro/server 4.33.4 → 4.34.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openneuro/server",
-  "version": "4.33.4",
+  "version": "4.34.0-alpha.0",
   "description": "Core service for the OpenNeuro platform.",
   "license": "MIT",
   "main": "src/server.js",
@@ -21,7 +21,7 @@
     "@elastic/elasticsearch": "8.13.1",
     "@graphql-tools/schema": "^10.0.0",
     "@keyv/redis": "^2.7.0",
-    "@openneuro/search": "^4.33.4",
+    "@openneuro/search": "^4.34.0-alpha.0",
     "@sentry/node": "^8.25.0",
     "@sentry/profiling-node": "^8.25.0",
     "base64url": "^3.0.0",
@@ -85,5 +85,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6ea88e06a699358523ad7b47f8c8e9ac3ef8a2c2"
+  "gitHead": "7711b48292c2e7f40bb45759617def2bbd07c88b"
 }

package/src/datalad/__tests__/description.spec.ts

@@ -87,6 +87,25 @@ describe("datalad dataset descriptions", () => {
       expect(Array.isArray(repaired.ReferencesAndLinks)).toBe(true)
       expect(Array.isArray(repaired.Funding)).toBe(true)
     })
+    it("converts array of objects to empty array for Funding", () => {
+      const description = {
+        Funding: [{ grant: "123" }, { grant: "456" }],
+      }
+      const repaired = repairDescriptionTypes(description)
+      expect(repaired.Funding).toEqual([])
+    })
+    it("sets DatasetType to 'raw' if not a string", () => {
+      const description = {
+        DatasetType: 123,
+      }
+      const repaired = repairDescriptionTypes(description)
+      expect(repaired.DatasetType).toEqual("raw")
+    })
+    it("sets BIDSVersion to '1.8.0' if missing", () => {
+      const description = {}
+      const repaired = repairDescriptionTypes(description)
+      expect(repaired.BIDSVersion).toEqual("1.8.0")
+    })
   })
   describe("getDescriptionObject()", () => {
     beforeAll(() => {

package/src/datalad/__tests__/snapshots.spec.ts

@@ -23,6 +23,7 @@ vi.mock("../draft.ts", () => ({
 }))
 vi.mock("../../config.ts")
 vi.mock("../../libs/notifications.ts")
+vi.mock("../../libs/events.ts")
 
 describe("snapshot model operations", () => {
   describe("createSnapshot()", () => {

package/src/datalad/dataset.ts

@@ -25,6 +25,7 @@ import BadAnnexObject from "../models/badAnnexObject"
 import { datasetsConnection } from "./pagination"
 import { getDatasetWorker } from "../libs/datalad-service"
 import notifications from "../libs/notifications"
+import { createEvent, updateEvent } from "../libs/events"
 
 export const giveUploaderPermission = (datasetId, userId) => {
   const permission = new Permission({ datasetId, userId, level: "admin" })
@@ -42,12 +43,18 @@ export const giveUploaderPermission = (datasetId, userId) => {
  * @returns {Promise} Resolves to {id: accessionNumber} for the new dataset
  */
 export const createDataset = async (
-  uploader,
+  uploader: string,
   userInfo,
   { affirmedDefaced, affirmedConsent },
 ) => {
   // Obtain an accession number
   const datasetId = await getAccessionNumber()
+  // Generate the created event
+  const event = await createEvent(
+    datasetId,
+    uploader,
+    { type: "created" },
+  )
   try {
     const ds = new Dataset({ id: datasetId, uploader })
     await request
@@ -59,6 +66,8 @@ export const createDataset = async (
     const md = new Metadata({ datasetId, affirmedDefaced, affirmedConsent })
     await md.save()
     await giveUploaderPermission(datasetId, uploader)
+    // Creation is complete here, mark successful
+    await updateEvent(event)
     await subscriptions.subscribe(datasetId, uploader)
     await notifications.snapshotReminder(datasetId)
     return ds
@@ -105,11 +114,18 @@ export const getDataset = async (id) => {
 /**
  * Delete dataset and associated documents
  */
-export const deleteDataset = (id) =>
-  request
-    .del(`${getDatasetWorker(id)}/datasets/${id}`)
-    .then(() => Dataset.deleteOne({ id }).exec())
-    .then(() => true)
+export const deleteDataset = async (datasetId, user) => {
+  const event = await createEvent(
+    datasetId,
+    user.id,
+    { type: "deleted" },
+  )
+  await request
+    .del(`${getDatasetWorker(datasetId)}/datasets/${datasetId}`)
+  await Dataset.deleteOne({ datasetId }).exec()
+  await updateEvent(event)
+  return true
+}
 
 /**
  * For public datasets, cache combinations of sorts/limits/cursors to speed responses
@@ -498,12 +514,19 @@ export const flagAnnexObject = (
 /**
  * Update public state
  */
-export const updatePublic = (datasetId, publicFlag) =>
-  Dataset.updateOne(
+export async function updatePublic(datasetId, publicFlag, user) {
+  const event = await createEvent(
+    datasetId,
+    user.id,
+    { type: "published", public: publicFlag },
+  )
+  await Dataset.updateOne(
     { id: datasetId },
     { public: publicFlag, publishDate: new Date() },
     { upsert: true },
   ).exec()
+  await updateEvent(event)
+}
 
 export const getDatasetAnalytics = (datasetId, _tag) => {
   return Dataset.findOne({ id: datasetId }).then((ds) => ({

package/src/datalad/description.ts

@@ -11,6 +11,15 @@ import { getDatasetWorker } from "../libs/datalad-service"
 import CacheItem, { CacheType } from "../cache/item"
 import { datasetOrSnapshot } from "../utils/datasetOrSnapshot"
 
+/**
+ * Checks if all elements in an array are strings.
+ * @param arr The array to check.
+ * @returns True if all elements are strings, false otherwise.
+ */
+const isArrayOfStrings = (arr: unknown): arr is string[] => {
+  return Array.isArray(arr) && arr.every((item) => typeof item === "string")
+}
+
 /**
  * Find dataset_description.json id and fetch description object
  * @param {string} datasetId
@@ -36,64 +45,65 @@ export const descriptionCacheKey = (datasetId, revision) => {
 
 export const repairDescriptionTypes = (description) => {
   const newDescription = { ...description }
-  // Array types
-  if (
-    Object.hasOwn(description, "Authors") &&
-    !Array.isArray(description.Authors)
-  ) {
-    newDescription.Authors = [description.Authors]
-  }
-  if (
-    Object.hasOwn(description, "ReferencesAndLinks") &&
-    !Array.isArray(description.ReferencesAndLinks)
-  ) {
-    newDescription.ReferencesAndLinks = [description.ReferencesAndLinks]
-  }
-  if (
-    Object.hasOwn(description, "Funding") &&
-    !Array.isArray(description.Funding)
-  ) {
-    newDescription.Funding = [description.Funding]
-  }
-  if (
-    Object.hasOwn(description, "EthicsApprovals") &&
-    !Array.isArray(description.EthicsApprovals)
-  ) {
-    newDescription.EthicsApprovals = [description.EthicsApprovals]
-  }
-  // String types
-  if (
-    Object.hasOwn(description, "Name") &&
-    typeof description.Name !== "string"
-  ) {
-    newDescription.Name = JSON.stringify(description.Name) || ""
-  }
-  if (
-    Object.hasOwn(description, "DatasetDOI") &&
-    typeof description.DatasetDOI !== "string"
-  ) {
-    newDescription.DatasetDOI = JSON.stringify(description.DatasetDOI) || ""
-  }
-  if (
-    Object.hasOwn(description, "Acknowledgements") &&
-    typeof description.Acknowledgements !== "string"
-  ) {
-    newDescription.Acknowledgements =
-      JSON.stringify(description.Acknowledgements) || ""
+
+  // Define fields that should be arrays of strings
+  const arrayStringFields = [
+    "Authors",
+    "ReferencesAndLinks",
+    "Funding",
+    "EthicsApprovals",
+  ]
+
+  // Repair array types - ensure they are arrays of strings
+  for (const field of arrayStringFields) {
+    if (Object.hasOwn(description, field)) {
+      if (!isArrayOfStrings(description[field])) {
+        // If it's not an array of strings (or not an array at all), replace with an empty array
+        newDescription[field] = []
+      }
+      // If it is already a valid array of strings, no change is needed.
+    }
+    // If the field doesn't exist, we don't add it.
   }
-  if (
-    Object.hasOwn(description, "HowToAcknowledge") &&
-    typeof description.HowToAcknowledge !== "string"
-  ) {
-    newDescription.HowToAcknowledge =
-      JSON.stringify(description.HowToAcknowledge) || ""
+
+  // Define fields that should be strings
+  const stringFields = [
+    "Name",
+    "DatasetDOI",
+    "Acknowledgements",
+    "HowToAcknowledge",
+    "DatasetType",
+  ]
+
+  // Repair string types - ensure they are strings
+  for (const field of stringFields) {
+    if (Object.hasOwn(description, field)) {
+      if (typeof description[field] !== "string") {
+        // Attempt to stringify non-string types, default to empty string or specific default
+        if (field === "DatasetType") {
+          newDescription[field] = "raw" // Specific default for DatasetType
+        } else {
+          try {
+            // Use JSON.stringify for complex types, otherwise just convert
+            const stringified = typeof description[field] === "object"
+              ? JSON.stringify(description[field])
+              : String(description[field])
+            newDescription[field] = stringified || ""
+          } catch (_err) {
+            newDescription[field] = "" // Fallback to empty string on error
+          }
+        }
+      }
+      // If it's already a string, no change needed.
+    }
+    // If the field doesn't exist, we don't add it.
   }
-  if (
-    Object.hasOwn(description, "DatasetType") &&
-    typeof description.DatasetType !== "string"
-  ) {
-    newDescription.DatasetType = "raw"
+
+  // Ensure BIDSVersion is present if missing (common default)
+  if (!Object.hasOwn(newDescription, "BIDSVersion")) {
+    newDescription.BIDSVersion = "1.8.0" // Or your desired default BIDS version
   }
+
   return newDescription
 }
 

package/src/datalad/readme.ts

@@ -34,8 +34,8 @@ export const readme = (obj) => {
   })
 }
 
-export const setReadme = (datasetId, readme, user) => {
-  return addFileString(datasetId, "README", "text/plain", readme).then(() =>
+export const setReadme = (datasetId, readme, filename, user) => {
+  return addFileString(datasetId, filename, "text/plain", readme).then(() =>
     commitFiles(datasetId, user)
   )
 }

package/src/datalad/snapshots.ts

@@ -22,6 +22,7 @@ import type { SnapshotDocument } from "../models/snapshot"
 import { updateDatasetRevision } from "./draft"
 import { getDatasetWorker } from "../libs/datalad-service"
 import { join } from "path"
+import { createEvent, updateEvent } from "../libs/events"
 
 const lockSnapshot = (datasetId, tag) => {
   return redlock.lock(
@@ -140,6 +141,11 @@ export const createSnapshot = async (
   const snapshotLock = await lockSnapshot(datasetId, tag)
 
   try {
+    // Create a version attempt event
+    const event = await createEvent(datasetId, user.id, {
+      type: "versioned",
+      version: tag,
+    })
     await createIfNotExistsDoi(datasetId, tag, descriptionFieldUpdates)
 
     const createSnapshotUrl = `${
@@ -167,6 +173,10 @@ export const createSnapshot = async (
       updateDatasetName(datasetId),
     ])
 
+    // Version is created here and event is updated
+    await updateEvent(event)
+
+    // Immediate indexing for new snapshots
     await reindexDataset(datasetId)
 
     announceNewSnapshot(snapshot, datasetId, user)

package/src/graphql/resolvers/dataset.ts

@@ -22,6 +22,7 @@ import { onBrainlife } from "./brainlife"
 import { brainInitiative } from "./brainInitiative"
 import { derivatives } from "./derivatives"
 import { promiseTimeout } from "../../utils/promiseTimeout"
+import { datasetEvents } from "./datasetEvents"
 import semver from "semver"
 
 export const dataset = async (obj, { id }, { user, userInfo }) => {
@@ -120,7 +121,7 @@ export const deleteDataset = async (
   { user, userInfo },
 ) => {
   await checkDatasetWrite(id, user, userInfo)
-  const deleted = await datalad.deleteDataset(id)
+  const deleted = await datalad.deleteDataset(id, userInfo)
   // Remove from the current version of the Elastic index
   try {
     await removeDatasetSearchDocument(id)
@@ -205,7 +206,7 @@ export const updatePublic = (
   { user, userInfo },
 ) => {
   return checkDatasetWrite(datasetId, user, userInfo).then(() => {
-    return datalad.updatePublic(datasetId, publicFlag)
+    return datalad.updatePublic(datasetId, publicFlag, user)
   })
 }
 
@@ -303,6 +304,7 @@ const Dataset = {
   worker,
   reviewers,
   brainInitiative,
+  events: datasetEvents,
 }
 
 export default Dataset

package/src/graphql/resolvers/datasetEvents.ts

@@ -0,0 +1,59 @@
+import DatasetEvent from "../../models/datasetEvents"
+
+/**
+ * Get all events for a dataset
+ */
+export function datasetEvents(obj, _, { userInfo }) {
+  if (userInfo.admin) {
+    // Site admins can see all events
+    return DatasetEvent.find({ datasetId: obj.id })
+      .sort({ timestamp: -1 })
+      .populate("user")
+      .exec()
+  } else {
+    // Non-admin users can only see notes without the admin flag
+    return DatasetEvent.find({
+      datasetId: obj.id,
+      event: { admin: { $ne: true } },
+    })
+      .sort({ timestamp: -1 })
+      .populate("user")
+      .exec()
+  }
+}
+
+/**
+ * Create or update an admin note event
+ */
+export async function saveAdminNote(
+  obj,
+  { id, datasetId, note },
+  { user, userInfo },
+) {
+  // Only site admin users can create an admin note
+  if (!userInfo?.admin) {
+    throw new Error("Not authorized")
+  }
+  if (id) {
+    const event = await DatasetEvent.findOne({ id, datasetId })
+    event.note = note
+    await event.save()
+    await event.populate("user")
+    return event
+  } else {
+    const event = new DatasetEvent({
+      id,
+      datasetId,
+      userId: user,
+      event: {
+        type: "note",
+        admin: true,
+      },
+      success: true,
+      note,
+    })
+    await event.save()
+    await event.populate("user")
+    return event
+  }
+}

package/src/graphql/resolvers/draft.ts

@@ -10,7 +10,7 @@ import { filterRemovedAnnexObjects } from "../utils/file.js"
 import { validation } from "./validation"
 
 // A draft must have a dataset parent
-const draftFiles = async (dataset, args, { userInfo }) => {
+export const draftFiles = async (dataset, args, { userInfo }) => {
   const hexsha = await getDraftRevision(dataset.id)
   const files = await getFiles(dataset.id, args.tree || hexsha)
   return filterRemovedAnnexObjects(dataset.id, userInfo)(files)

package/src/graphql/resolvers/gitEvents.ts

@@ -0,0 +1,25 @@
+import { createEvent } from "../../libs/events"
+import { checkDatasetWrite } from "../permissions"
+
+/**
+ * Create a git event
+ */
+export const createGitEvent = async (
+  obj,
+  { datasetId, commit, reference },
+  { user, userInfo },
+) => {
+  await checkDatasetWrite(datasetId, user, userInfo)
+  const event = await createEvent(
+    datasetId,
+    user,
+    {
+      type: "git",
+      commit,
+      reference,
+    },
+    "",
+    true,
+  )
+  return event.toObject()
+}

package/src/graphql/resolvers/mutation.ts

@@ -43,6 +43,8 @@ import {
   finishImportRemoteDataset,
   importRemoteDataset,
 } from "./importRemoteDataset"
+import { saveAdminNote } from "./datasetEvents"
+import { createGitEvent } from "./gitEvents"
 
 const Mutation = {
   createDataset,
@@ -89,6 +91,8 @@ const Mutation = {
   importRemoteDataset,
   finishImportRemoteDataset,
   updateUser,
+  saveAdminNote,
+  createGitEvent,
 }
 
 export default Mutation

package/src/graphql/resolvers/permissions.ts

@@ -4,6 +4,7 @@ import Permission from "../../models/permission"
 import type { PermissionDocument } from "../../models/permission"
 import { checkDatasetAdmin } from "../permissions"
 import { user } from "./user"
+import { createEvent, updateEvent } from "../../libs/events"
 
 interface DatasetPermission {
   id: string
@@ -40,8 +41,16 @@ const publishPermissions = async (datasetId) => {
   return permissionsUpdated
 }
 
+/**
+ * Apply permission updates to a list of users
+ */
 async function updateUsers(datasetId: string, level: string, users) {
   for (const user of users) {
+    const event = await createEvent(datasetId, user, {
+      type: "permissionChange",
+      target: user.id,
+      level: level,
+    })
     await Permission.updateOne(
       {
         datasetId: datasetId,
@@ -54,6 +63,7 @@ async function updateUsers(datasetId: string, level: string, users) {
       },
       { upsert: true },
     ).exec()
+    await updateEvent(event)
   }
   return publishPermissions(datasetId)
 }

package/src/graphql/resolvers/publish.ts

@@ -7,7 +7,7 @@ import { getDatasetWorker } from "../../libs/datalad-service"
 
 export const publishDataset = (obj, { datasetId }, { user, userInfo }) => {
   return checkDatasetWrite(datasetId, user, userInfo).then(async () => {
-    await updatePublic(datasetId, true)
+    await updatePublic(datasetId, true, userInfo)
     const uri = `${getDatasetWorker(datasetId)}/datasets/${datasetId}/publish`
     return await request
       .post(uri)

package/src/graphql/resolvers/readme.ts

@@ -5,10 +5,30 @@
 import { setReadme } from "../../datalad/readme"
 import { checkDatasetWrite } from "../permissions"
 export { readme } from "../../datalad/readme"
+import { draftFiles } from "./draft"
 
-export const updateReadme = (obj, { datasetId, value }, { user, userInfo }) => {
-  return checkDatasetWrite(datasetId, user, userInfo).then(() => {
-    // Save to backend
-    return setReadme(datasetId, value, userInfo).then(() => true)
+export async function updateReadme(
+  obj,
+  { datasetId, value },
+  { user, userInfo },
+) {
+  await checkDatasetWrite(datasetId, user, userInfo)
+  const files = await draftFiles({ id: datasetId }, { tree: "HEAD" }, {
+    userInfo,
   })
+  // Default to README.md if none exists
+  let filename = "README.md"
+  for (const file of files) {
+    if (
+      file.filename === "README.md" || file.filename === "README.rst" ||
+      file.filename === "README.txt" ||
+      file.filename === "README"
+    ) {
+      filename = file.filename
+      break
+    }
+  }
+  // Save to backend
+  await setReadme(datasetId, value, filename, userInfo)
+  return true
 }

package/src/graphql/resolvers/snapshots.ts

@@ -136,20 +136,23 @@ export const undoDeprecateSnapshot = async (
 }
 
 export const participantCount = (obj, { modality }) => {
+  const cacheKey = modality === "NIH" ? "NIH" : modality || "all"
   const cache = new CacheItem(
     redis,
     CacheType.participantCount,
-    [modality || "all"],
+    [cacheKey],
     3600,
   )
+
   return cache.get(async () => {
     const queryHasSubjects = {
-      "summary.subjects": {
-        $exists: true,
-      },
+      "summary.subjects": { $exists: true },
     }
-    const matchQuery = modality
-      ? {
+
+    let matchQuery: Record<string, unknown> = queryHasSubjects
+
+    if (modality && modality !== "NIH") {
+      matchQuery = {
         $and: [
           queryHasSubjects,
           {
@@ -157,7 +160,19 @@ export const participantCount = (obj, { modality }) => {
           },
         ],
       }
-      : queryHasSubjects
+    } else if (modality === "NIH") {
+      // When modality is 'NIH', we don't filter by a specific modality.
+      // Instead, we query for datasets that have any modality within the NIH portal
+      matchQuery = {
+        $and: [
+          queryHasSubjects,
+          {
+            "summary.modalities": { $exists: true },
+          },
+        ],
+      }
+    }
+
     const aggregateResult = await DatasetModel.aggregate([
       {
         $match: {
@@ -198,8 +213,12 @@ export const participantCount = (obj, { modality }) => {
         },
       },
     ]).exec()
-    if (aggregateResult.length) return aggregateResult[0].participantCount
-    else return 0
+
+    if (aggregateResult.length) {
+      return aggregateResult[0].participantCount
+    } else {
+      return 0
+    }
   })
 }
 

package/src/graphql/resolvers/summary.ts

@@ -19,7 +19,12 @@ export async function summary(dataset): Promise<Partial<SummaryDocument>> {
   if (datasetSummary) {
     return {
       ...datasetSummary,
-      primaryModality: datasetSummary?.modalities[0],
+      // Lowercase all modality fields
+      modalities: datasetSummary?.modalities?.map((str) => str.toLowerCase()),
+      secondaryModalities: datasetSummary?.secondaryModalities?.map(
+        (str) => str.toLowerCase(),
+      ),
+      primaryModality: datasetSummary?.modalities[0]?.toLowerCase(),
     }
   } else {
     return null

package/src/graphql/schema.ts

@@ -188,6 +188,10 @@ export const typeDefs = `
     importRemoteDataset(datasetId: ID!, url: String!): ID
     # Finish and notify import is done, returns true if successful
     finishImportRemoteDataset(id: ID!, success: Boolean!, message: String): Boolean
+    # Create or update an admin note on a dataset
+    saveAdminNote(id: ID, datasetId: ID!, note: String!): DatasetEvent
+    # Create a git event log for dataset changes
+    createGitEvent(datasetId: ID!, commit: String!, reference: String!): DatasetEvent
   }
 
   # Anonymous dataset reviewer
@@ -412,6 +416,8 @@ export const typeDefs = `
     reviewers: [DatasetReviewer]
     # Dataset belongs to Brain Initiative
     brainInitiative: Boolean
+    # Log of events associated with this dataset
+    events: [DatasetEvent]
   }
 
   type DatasetDerivatives {
@@ -849,6 +855,32 @@ export const typeDefs = `
     flagger: User
     createdAt: DateTime
   }
+
+  type DatasetEventDescription {
+    type: String
+    version: String
+    public: Boolean
+    target: User
+    level: String
+    ref: String
+    message: String
+  }
+
+  # Dataset events
+  type DatasetEvent {
+    # Unique identifier for the event
+    id: ID
+    # Timestamp of the event
+    timestamp: DateTime
+    # User associated with the event
+    user: User
+    # Event description object
+    event: DatasetEventDescription
+    # True if the event succeeded
+    success: Boolean
+    # Notes associated with the event
+    note: String
+  }
 `
 
 schemaComposer.addTypeDefs(typeDefs)

package/src/libs/events.ts

@@ -0,0 +1,51 @@
+import DatasetEvent from "../models/datasetEvents"
+import type {
+  DatasetEventDocument,
+  DatasetEventType,
+} from "../models/datasetEvents"
+import * as Sentry from "@sentry/node"
+/**
+ * Create a new dataset event
+ */
+export async function createEvent(
+  datasetId: string,
+  user: string,
+  event: DatasetEventType,
+  note: string = "",
+  success: boolean = false,
+): Promise<DatasetEventDocument> {
+  // Save a Sentry breadcrumb to help debug complex server events
+  const breadcrumb: Sentry.Breadcrumb = {
+    category: "dataset-event",
+    message: `${event.type} event created for dataset ${datasetId}`,
+    level: "info",
+    data: {
+      datasetId,
+      user,
+      event,
+      note,
+    },
+  }
+  Sentry.addBreadcrumb(breadcrumb)
+  const created = new DatasetEvent({
+    datasetId,
+    userId: user,
+    event,
+    note,
+    // Initially create the event as failed - update to success on successful state
+    success,
+  })
+  await created.save()
+  return created
+}
+
+/**
+ * Call when event is finished to mark complete or add failure info
+ */
+export async function updateEvent(
+  event: DatasetEventDocument,
+  success: boolean = true,
+) {
+  event.success = success
+  await event.save()
+}

package/src/models/__tests__/datasetEvents.spec.ts

@@ -0,0 +1,106 @@
+import mongoose from "mongoose"
+import { MongoMemoryServer } from "mongodb-memory-server"
+import DatasetEvent from "../datasetEvents"
+import type { DatasetEventDocument, DatasetEventType } from "../datasetEvents"
+import type { OpenNeuroUserId } from "../../types/user"
+
+describe("DatasetEvent Model", () => {
+  let mongoServer: MongoMemoryServer
+
+  beforeAll(async () => {
+    mongoServer = await MongoMemoryServer.create()
+    const mongoUri = mongoServer.getUri()
+    await mongoose.connect(mongoUri)
+  })
+
+  afterAll(async () => {
+    await mongoose.disconnect()
+    await mongoServer.stop()
+  })
+
+  beforeEach(async () => {
+    await DatasetEvent.deleteMany({})
+  })
+
+  it("should create a new DatasetEvent", async () => {
+    const eventData: Partial<DatasetEventDocument> = {
+      datasetId: "ds000001",
+      timestamp: new Date(),
+      userId: "user123" as OpenNeuroUserId,
+      event: {
+        type: "created",
+      },
+      success: true,
+      note: "Dataset created successfully",
+    }
+
+    const datasetEvent = new DatasetEvent(eventData)
+    const savedDatasetEvent = await datasetEvent.save()
+
+    expect(savedDatasetEvent._id).toBeDefined()
+    expect(savedDatasetEvent.datasetId).toBe("ds000001")
+    expect(savedDatasetEvent.userId).toBe("user123")
+    expect(savedDatasetEvent.event.type).toBe("created")
+    expect(savedDatasetEvent.success).toBe(true)
+    expect(savedDatasetEvent.note).toBe("Dataset created successfully")
+    expect(savedDatasetEvent.timestamp).toBeInstanceOf(Date)
+  })
+
+  it("should create a DatasetEvent with default values", async () => {
+    const eventData: Partial<DatasetEventDocument> = {
+      datasetId: "ds000002",
+      timestamp: new Date(),
+      userId: "user456" as OpenNeuroUserId,
+      event: {
+        type: "versioned",
+        version: "1.0.0",
+      },
+    }
+
+    const datasetEvent = new DatasetEvent(eventData)
+    const savedDatasetEvent = await datasetEvent.save()
+
+    expect(savedDatasetEvent._id).toBeDefined()
+    expect(savedDatasetEvent.success).toBe(false)
+    expect(savedDatasetEvent.note).toBe("")
+  })
+
+  it("should require datasetId, timestamp, user, and event", async () => {
+    const eventData = {}
+
+    const datasetEvent = new DatasetEvent(eventData)
+
+    await expect(datasetEvent.save()).rejects.toThrow()
+  })
+
+  it("should handle different event types", async () => {
+    const events: DatasetEventType[] = [
+      { type: "created" },
+      { type: "versioned", version: "1.0.0" },
+      { type: "deleted" },
+      { type: "published", public: true },
+      {
+        type: "permissionChange",
+        target: "user789" as OpenNeuroUserId,
+        level: "admin",
+      },
+      { type: "git", reference: "head/refs/main", commit: "12345667" },
+      { type: "upload" },
+      { type: "note", admin: false },
+    ]
+
+    for (const event of events) {
+      const eventData: Partial<DatasetEventDocument> = {
+        datasetId: "ds000003",
+        timestamp: new Date(),
+        userId: "user101" as OpenNeuroUserId,
+        event: event,
+        success: true,
+        note: "Testing different event types",
+      }
+      const datasetEvent = new DatasetEvent(eventData)
+      const savedDatasetEvent = await datasetEvent.save()
+      expect(savedDatasetEvent.event.type).toBe(event.type)
+    }
+  })
+})

package/src/models/datasetEvents.ts

@@ -0,0 +1,139 @@
+import mongoose from "mongoose"
+import type { Document } from "mongoose"
+import type { OpenNeuroUserId } from "../types/user"
+import { v4 as uuidv4 } from "uuid"
+import type { UserDocument } from "./user"
+const { Schema, model } = mongoose
+
+const _datasetEventTypes = [
+  "created",
+  "versioned",
+  "deleted",
+  "published",
+  "permissionChange",
+  "git",
+  "upload",
+  "note",
+] as const
+
+/**
+ * Various events that occur affecting one dataset
+ *
+ * created - Dataset was created
+ * versioned - Dataset has a snapshot created
+ * deleted - The dataset was deleted
+ * published - Dataset was made public
+ * permissionChange - Dataset permissions were modified
+ * git - A git event modified the dataset's repository (git history provides details)
+ * upload - A non-git upload occurred (typically one file changed)
+ * note - A note unrelated to another event
+ */
+export type DatasetEventName = typeof _datasetEventTypes[number]
+
+export type DatasetEventCommon = {
+  type: DatasetEventName
+}
+
+export type DatasetEventCreated = DatasetEventCommon & {
+  type: "created"
+}
+
+export type DatasetEventVersioned = DatasetEventCommon & {
+  type: "versioned"
+  version: string
+}
+
+export type DatasetEventDeleted = DatasetEventCommon & {
+  type: "deleted"
+}
+
+export type DatasetEventPublished = DatasetEventCommon & {
+  type: "published"
+  // True if made public, false if made private
+  public: boolean
+}
+
+export type DatasetEventPermissionChange = DatasetEventCommon & {
+  type: "permissionChange"
+  // User with the permission being changed
+  target: OpenNeuroUserId
+  level: string
+}
+
+export type DatasetEventGit = DatasetEventCommon & {
+  type: "git"
+  commit: string
+  reference: string
+}
+
+export type DatasetEventUpload = DatasetEventCommon & {
+  type: "upload"
+}
+
+export type DatasetEventNote = DatasetEventCommon & {
+  type: "note"
+  // Is this note visible only to site admins?
+  admin: boolean
+}
+
+/**
+ * Description of a dataset event
+ */
+export type DatasetEventType =
+  | DatasetEventCreated
+  | DatasetEventVersioned
+  | DatasetEventDeleted
+  | DatasetEventPublished
+  | DatasetEventPermissionChange
+  | DatasetEventGit
+  | DatasetEventUpload
+  | DatasetEventNote
+
+/**
+ * Dataset events log changes to a dataset
+ */
+export interface DatasetEventDocument extends Document {
+  // Unique id for the event
+  id: string
+  // Affected dataset
+  datasetId: string
+  // Timestamp of the event
+  timestamp: Date
+  // User id that triggered the event
+  userId: string
+  // User that triggered the event
+  user: UserDocument
+  // A description of the event, optional but recommended to provide context
+  event: DatasetEventType
+  // Did the action logged succeed?
+  success: boolean
+  // Admin notes
+  note: string
+}
+
+const datasetEventSchema = new Schema<DatasetEventDocument>({
+  id: { type: String, required: true, default: uuidv4 },
+  datasetId: { type: String, required: true },
+  timestamp: { type: Date, default: Date.now },
+  userId: { type: String, required: true },
+  event: {
+    type: Object,
+    required: true,
+  },
+  success: { type: Boolean, default: false },
+  note: { type: String, default: "" },
+})
+
+datasetEventSchema.virtual("user", {
+  ref: "User",
+  localField: "userId",
+  foreignField: "id",
+  justOne: true,
+})
+
+const DatasetEvent = model<DatasetEventDocument>(
+  "DatasetEvent",
+  datasetEventSchema,
+)
+
+export default DatasetEvent

package/src/types/user.ts

@@ -0,0 +1,2 @@
+/** OpenNeuro UUID string used to identify a user uniquely */
+export type OpenNeuroUserId = string