API and Hooks

Don’t Forget! publishes the ReminderManager class on its module entry and on a global namespace during init.

const api = game.modules.get('dont-forget').api;
// or
const api = globalThis.DONTFORGET.api;

The reminder record

A reminder is a plain object stored as a flag on the user it belongs to.

{
  id: 'AbCdEf0123456789',
  label: 'Ask the innkeeper about the sigil',
  isDone: false,
  userId: 'yZx...',
  createdAt: 1750000000000,
  source: 'my-module',
  ref: 'quest-42',
  dueDate: { year: 1492, month: 6, day: 12 },
  noteId: 'JournalEntryPage id or null',
  isDue: false
}

dueDate uses 1-indexed month and day. noteId is the Calendaria note backing the due date. isDue turns true once that note delivers.

Deleting the backing note in Calendaria clears dueDate, noteId, and isDue. The reminder record itself survives.

Attribution

source is the module id that produced the reminder. A reminder created without a source is attributed to dont-forget.

ref is your own key for whatever the reminder is about. Store the id of the quest, item, or record the reminder tracks, then find the reminder again with findReminders.

updateReminder, completeReminder, deleteReminder, and deleteReminders each take an optional trailing source. When you pass one that does not match the reminder’s own source, the call is refused and an error notification names the owning module. Passing no source skips the check.

Permissions

Every write is checked against the current user. A user may write to their own reminders, and a GM may write to anyone’s. A player writing to another user’s reminders gets an error notification. createReminder, updateReminder, completeReminder, and deleteReminder return null when the write is refused. deleteReminders skips the reminders it may not write and returns its count for the rest.

Methods

getReminders

const reminders = api.getReminders(userId);

Returns a dictionary of reminders keyed by id. For a GM user id this returns every reminder in the world. For a player user id it returns that player’s reminders. An unknown user id returns an empty object.

getUserReminders

const reminders = api.getUserReminders(userId);

Returns the reminders belonging to one user, keyed by id, whether or not that user is a GM.

getAllReminders

const reminders = api.getAllReminders();

Returns every reminder across all users, keyed by id.

findReminders

const open = api.findReminders({ source: 'my-module', ref: 'quest-42', isDone: false });

Returns an array of matching reminders. Every term is optional, and an omitted term matches anything. Passing userId narrows the scan to that user. A reminder with no source matches source: 'dont-forget', and a reminder with no ref matches ref: null.

createReminder

const reminder = await api.createReminder(userId, { label, source, ref, dueDate });

Creates a reminder for a user and returns the created record. Returns null when the user does not exist or the write is refused. The new record always starts with isDone and isDue false.

updateReminder

await api.updateReminder(reminderId, { label: 'New text' }, 'my-module');

Applies a partial update to a reminder. Returns null when the reminder is missing or the call is refused. On success the call resolves to the owning user document, not to the updated reminder. Read the record back with getUserReminders when you need its new state.

completeReminder

await api.completeReminder(reminderId, 'my-module');

Marks a reminder done.

deleteReminder

await api.deleteReminder(reminderId, userId, 'my-module');

Deletes one reminder. The owning userId is required.

deleteReminders

const count = await api.deleteReminders(reminders, 'my-module');

Deletes an array of reminder records with one write per owning user. Returns how many were deleted. Reminders whose source does not match are skipped rather than failing the batch.

Backing calendar notes

The API writes reminder records only. Creating a reminder with a dueDate does not create the backing calendar note. Changing a dueDate through updateReminder leaves the backing note on its old date, and deleting a reminder through deleteReminder or deleteReminders leaves its backing note in the calendar. Notes are created, moved, and removed only by the module’s own reminder UI, alongside the record they belong to.

Hooks

The three reminder hooks fire from the flag change, so they fire on every connected client. The second argument carries remote, which is true on clients other than the one that made the change. Act on remote === false when you want the work done once.

dontForget.reminderCreated

Hooks.on('dontForget.reminderCreated', (reminder, { remote }) => {
  if (!remote) console.log(`${reminder.label} added`);
});

Fires when a reminder appears on a user.

dontForget.reminderCompleted

Hooks.on('dontForget.reminderCompleted', (reminder, { remote }) => {});

Fires when a reminder’s isDone turns true. It does not fire when a completed reminder is reopened.

dontForget.reminderDeleted

Hooks.on('dontForget.reminderDeleted', (reminder, { remote }) => {});

Fires when a reminder is removed. The payload is the record as it stood before deletion.

dontForget.noteSync

Hands a backing-note request to the primary GM. The payload is an internal note request rather than a reminder record. The module listens for it only while Calendaria is active.