Bookmarks API

A bookmark and a tracked application are the same record: one row in the trackedApplications table, created the moment a user saves a job and carrying that job through saved → applied → interviewing → offer → accepted. All of it lives in convex/bookmarks.ts; the status rules it enforces live in convex/applicationIntegrity.ts. Ownership is checked on every write by comparing userId against the Clerk identity, so a bookmark id from another user is rejected rather than ignored.

toggleBookmark

Saves a job, or un-saves it — but only while there is nothing to lose.

Returns: { bookmarked: boolean, tracked: boolean }

A row counts as having progress when its status is anything other than saved, or when its notes contain non-whitespace text. In that case the toggle is a no-op and returns tracked: true so the caller can explain why the job stayed saved — deleting an application history from a one-click toggle on a list page is never correct. Removing a tracked application is a separate, explicit action: the "Remove from tracker" button on the dashboard card, which calls removeTrackedApplication.

New rows are created with a jobSnapshot (a copy of the job's title, company, location, url, creation time, tags and role level) and a statusHistory seeded with a single saved entry.

Throws: Not authenticated, Job not found.

const toggleBookmark = useMutation(api.bookmarks.toggleBookmark);

const result = await toggleBookmark({ jobId: job._id });
if (result.bookmarked && result.tracked) {
  // Kept: this job is being tracked on the dashboard.
}

updateBookmarkStatus

The mutation that powers application tracking. It writes the status, optionally the notes, and appends to statusHistory whenever the status actually changes.

Returns: { success: true }

Throws:

Passing the current status is always allowed — that is how a notes-only edit is saved, and it does not append a history entry.

const updateBookmarkStatus = useMutation(api.bookmarks.updateBookmarkStatus);

await updateBookmarkStatus({ bookmarkId, status: "applied" });
await updateBookmarkStatus({ bookmarkId, status: "applied", notes: "Phone screen booked" });

Allowed status transitions

From allowedStatusTransitions in convex/applicationIntegrity.ts. Forward progress, plus a way back out of the two end states so a mis-click on Rejected or Accepted is recoverable without deleting the record.

stateDiagram-v2
[*] --> saved : toggleBookmark
saved --> applied
saved --> interviewing
saved --> rejected
applied --> interviewing
applied --> offer
applied --> rejected
interviewing --> offer
interviewing --> rejected
offer --> accepted
offer --> rejected
accepted --> offer
accepted --> rejected
rejected --> saved
rejected --> applied
rejected --> interviewing
rejected --> offer

Note what is not there: saved cannot jump straight to offer or accepted, interviewing cannot fall back to applied, and nothing can move to saved except from rejected.

The dashboard's status dropdown is built from the same table — DashboardJobCard imports getAllowedStatusTransitions directly from convex/applicationIntegrity.ts, so the menu only ever offers transitions the server will accept.

removeTrackedApplication

Deletes a tracked application outright, including its status history and notes. This is the "Remove from tracker" button on the dashboard card, and it is the only way to delete a row that has progress on it.

Returns: { success: true }

Throws: Not authenticated, Bookmark not found, Unauthorized.

getBookmarkStatus

Returns: { bookmarked: boolean }. Signed-out callers always get { bookmarked: false } rather than an error.

The job list does not need this query: jobs.listApprovedJobs already returns an isBookmarked flag per job for authenticated callers.

getUserBookmarks

Returns: an array, newest first, of:

job is resolved in one of three ways:

A row whose job was deleted and which has no jobSnapshot is dropped from the result. dashboard.getDashboardData returns bookmarks in exactly this shape.

backfillTrackedApplicationSnapshots

Fills in jobSnapshot for older rows created before snapshots existed, skipping rows that already have one and rows whose job is already gone. Returns { updatedCount }. Run it from the Convex dashboard or CLI, not from the app.