Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

20.6 KB
Raw Blame
import type {
  folders,
  notes,
  actions,
  transcriptSegments,
  speakers,
  speakerProfiles,
} from '@/db/schema';
import type { TranscriptionStatus } from '@/lib/diarization/diarizer';

export type Note = typeof notes.$inferSelect;
export type Folder = typeof folders.$inferSelect;
export type Action = typeof actions.$inferSelect;
export type Segment = typeof transcriptSegments.$inferSelect;
export type NewSegment = typeof transcriptSegments.$inferInsert;
export type Speaker = typeof speakers.$inferSelect;
export type NewSpeaker = typeof speakers.$inferInsert;
export type SpeakerProfileRow = typeof speakerProfiles.$inferSelect;
export type SpeakerProfileOwnerFlag = 0 | 1;
export type SpeakerProfile = Omit<SpeakerProfileRow, 'embedding' | 'isOwner'> & {
  embedding: number[];
  isOwner: SpeakerProfileOwnerFlag;
};
export type NewSpeakerProfile = Omit<
  typeof speakerProfiles.$inferInsert,
  'id' | 'embedding' | 'isOwner' | 'createdAt' | 'updatedAt'
> & {
  embedding: number[];
  isOwner?: SpeakerProfileOwnerFlag;
  createdAt?: string | null;
  updatedAt?: string | null;
};

export type NoteUpdate = Partial<
  Pick<
    Note,
    | 'title'
    | 'content'
    | 'folderId'
    | 'enhancedContent'
    | 'enhancementPrompt'
    | 'enhancedAtContentHash'
  >
>;
export type ActionUpdate = Partial<Pick<Action, 'name' | 'description' | 'prompt'>>;

// Meeting/diarization columns NoteUpdate cannot reach. These remain local-only; selected calendar
// context uses MeetingCalendarContextUpdate so public notes can sync it without syncing diarization.
// transcriptionStatus is intentionally NOT here: status changes go ONLY through the guarded transition
// path (store.transitionStatus / the service's advance()), never a bulk meta write that bypasses assertTransition.
export type MeetingNoteUpdate = Partial<
  Pick<
    Note,
    | 'noteType'
    | 'diarizationEnabled'
    | 'expectedSpeakerCount'
    | 'sourceFile'
    | 'audioDurationSeconds'
  >
>;
export type MeetingCalendarContextUpdate = Partial<Pick<Note, 'calendarEventId' | 'participants'>>;

/** Server-shaped folder used by sync apply paths. */
export interface RemoteFolder {
  id: string;
  client_folder_id: string | null;
  name: string;
  is_default: boolean;
  sort_order: number;
  deleted_at: string | null;
  updated_at: string;
  // Scope fields declared for a later task; not yet populated by pull/apply.
  space_id?: string | null;
  workspace_id?: string | null;
  previous_space_id?: string | null;
  /**
   * Redacted stub: the folder left the caller's reach. The server sends only
   * ids, scope and updated_at — `name`, `is_default`, `sort_order` and
   * `deleted_at` are absent despite this type declaring them, so a stub must
   * never reach an apply path (see pullFoldersTeam).
   */
  access_removed?: boolean;
}

/** Server-shaped note used by sync apply paths. */
export interface RemoteNote {
  id: string;
  client_note_id: string | null;
  title: string | null;
  content: string;
  enhanced_content: string | null;
  enhancement_prompt: string | null;
  note_type: string;
  source_file: string | null;
  audio_duration_seconds: number | null;
  folder_id: string | null;
  participants: string | null;
  calendar_event_id: string | null;
  /** Desktop-shape transcript JSON; decomposed into segments/speakers on apply. */
  transcript: string | null;
  deleted_at: string | null;
  /** Optional: not every server payload that reaches an apply path carries it. */
  created_at?: string;
  updated_at: string;
  // Scope fields declared for a later task; not yet populated by pull/apply.
  space_id?: string | null;
  workspace_id?: string | null;
  previous_space_id?: string | null;
  user_id?: string | null;
  updated_by_user_id?: string | null;
  access_removed?: boolean;
}

/**
 * Scope context for a remote apply. Omitted entirely by the personal pull
 * passes, which own `space_id IS NULL` rows and must keep their existing
 * behavior.
 */
export interface ApplyRemoteOptions {
  /**
   * Local `spaces.id` this row belongs to. Always written on INSERT (falling
   * back to the private space when omitted, so no apply path leaves
   * `space_id` NULL); written on UPDATE only when explicitly provided, so a
   * personal-pass apply never relocates an existing row.
   */
  spaceId?: number;
}

export interface ApplyRemoteNoteOptions extends ApplyRemoteOptions {
  /**
   * Persist `user_id` / `updated_by_user_id` from the remote row. Team-pass
   * only: `scope=all` responses carry cloud ownership, the personal list
   * doesn't, so the personal pass must not write (or clear) these columns.
   */
  applyOwnership?: boolean;
}

export interface RemoteNoteCreateResult {
  id: string;
  client_note_id?: string | null;
  updated_at?: string | null;
}

/** A note parked after a push-time 409 note_version_conflict — the future Keep-mine/Use-server banner's data source. */
export interface ConflictedNote {
  id: number;
  title: string | null;
  /** null when the stashed JSON fails to parse (defensive — should not happen in practice); keep-mine still resolves such a row with no dependency on this. */
  conflictServerNote: RemoteNote | null;
}

/** The notes picked to answer a chat question, and how many matched before the cap. */
export interface ChatCandidateNotes {
  notes: Note[];
  total: number;
  /** The returned notes whose transcript matches a term, so their matching lines can be sent. */
  transcriptMatchIds?: number[];
}

/** A period a chat question names: the notes created from `start` up to (not including) `end`. */
export interface ChatNoteWindow {
  start: Date;
  end: Date;
  meetingsOnly: boolean;
}

export interface ChatCandidateOptions {
  includePrivate: boolean;
  limit: number;
  window?: ChatNoteWindow;
}

export interface NotesRepository {
  // Existing methods
  getFolders(): Folder[];
  /**
   * Every folder row, soft-deleted ones included — unlike getFolders(). The
   * team pull pass resolves remote folder ids against this: a locally
   * soft-deleted folder is still a real row with a perfectly usable id, and
   * treating it as missing would park the crawl on every note filed there
   * until the pending delete finally pushes.
   */
  getFoldersIncludingDeleted(): Folder[];
  /**
   * Private-space folders only — what every personal folder surface shows
   * (browsing list, the move-note picker, rename/delete/create). Team-space
   * folders are reachable through the Spaces section instead: offering them as
   * personal targets would file a personal note into a folder the server
   * rejects, and deleting one would tombstone teammates' notes.
   */
  getPrivateFolders(): Folder[];
  /** Folders belonging to one space — the private space's own list is getPrivateFolders(). */
  getFoldersBySpace(spaceId: number): Folder[];
  getFolderCounts(): Record<number, number>;
  /** Defaults to the private space; pass `spaceId` to create the folder inside a team space. */
  createFolder(name: string, spaceId?: number): Folder;
  renameFolder(id: number, name: string): void;
  deleteFolder(id: number): void;
  getNotesByFolder(folderId: number): Note[];
  /** Mirrors getNotesByFolder — notes browsing/filtering by space (see FoldersScreen's Spaces section). */
  getNotesBySpace(spaceId: number): Note[];
  /**
   * Notes sitting directly in a space rather than in one of its folders. Browsing a space lists
   * its folders above its notes, so the note list must exclude what the folder rows already
   * account for — otherwise every foldered note appears twice.
   */
  getSpaceNotesWithoutFolder(spaceId: number): Note[];
  getAllNotes(): Note[];
  getNoteById(id: number): Note | null;
  /**
   * `spaceId` files the note directly into a space with no folder (browsing that space); otherwise
   * the note lands in `folderId` and inherits whichever space that folder belongs to.
   */
  createNote(title: string, content: string, folderId?: number, spaceId?: number): Note;
  updateNote(id: number, updates: NoteUpdate): void;
  deleteNote(id: number): void;
  moveNoteToFolder(noteId: number, folderId: number): void;
  moveNotesToFolder(fromFolderId: number, toFolderId: number): void;
  /**
   * Deletes a folder the way the server does — tombstoning its notes with it — journaling every
   * touched row first so the delete can be undone, and holding those notes out of the push queue
   * and every pull until pushFolders reports the server's verdict.
   */
  deleteFolderCascade(folderId: number): void;
  /** The server accepted the folder delete: purge the folder and its cascaded notes. */
  finalizeFolderDelete(folderId: number): void;
  /** The server refused the folder delete: restore every row the cascade touched. */
  revertFolderDelete(folderId: number): void;
  /** True while an in-flight folder delete owns this note, so no pull may apply over it. */
  isRemoteNoteHeldByFolderDelete(remote: Pick<RemoteNote, 'id' | 'client_note_id'>): boolean;
  /**
   * Re-homes a note into a different space: sets space_id to the target, clears folder_id (a
   * folder from the old space is never valid in the new one), and marks pending so the next push
   * carries the move. Which targets the UI may offer is canMoveBetweenSpaces' call — personal
   * content into any team space, team content only within its own workspace.
   */
  moveNoteToSpace(noteId: number, spaceId: number): void;
  searchNotes(query: string, folderId?: number): Note[];
  /**
   * Notes for answering a chat question: a term matches title, content, AI summary or transcript,
   * and a term held by fewer of the notes searched weighs more. Only notes scoring at least half
   * as well as the best one count, the best first, then the newest. With a window, only notes
   * created in it are searched. With no terms, the most recent notes. Capped at `limit`; `total`
   * counts them all before the cap.
   */
  getChatCandidateNotes(terms: string[], options: ChatCandidateOptions): ChatCandidateNotes;
  getActions(): Action[];
  getActionById(id: number): Action | null;
  createAction(name: string, description: string, prompt: string): Action;
  updateAction(id: number, updates: ActionUpdate): void;
  deleteAction(id: number): void;

  // Sync helpers
  getPendingFolders(): Folder[];
  getPendingNotes(): Note[];
  getPrivateNotesPendingDeletion(): Note[];
  applyRemoteFolder(remote: RemoteFolder, options?: ApplyRemoteOptions): void;
  applyRemoteNote(
    remote: RemoteNote,
    resolveFolder: (serverFolderId: string | null) => number | null,
    options?: ApplyRemoteNoteOptions,
  ): void;
  /**
   * Resolves the local row a remote note maps to, using the same matching rule
   * as applyRemoteNote (client_note_id when present, else remote_id). Lets the
   * team pull pass decide what to do with an access-removed stub, which carries
   * no content and so must never go through an apply path.
   */
  getNoteForRemote(remote: Pick<RemoteNote, 'id' | 'client_note_id'>): Note | null;
  /**
   * Resolves the local row a remote folder id maps to. Lets the team pull pass
   * decide what to do with an access-removed folder stub, which carries no
   * fields and so must never go through an apply path. Matching is by remote id
   * alone: a stub is only ever about a folder this device already synced.
   */
  getFolderByRemoteId(remoteId: string): Folder | null;
  /**
   * Re-homes a note into the private space as a brand-new personal note: fresh
   * client_note_id, no cloud identity (remote_id / cloud_updated_at / owner /
   * editor cleared), no folder, no parked conflict, still pending so the next
   * push re-creates it. Used when access to its space is revoked but the row
   * still holds unpushed local work.
   */
  forkNoteToPrivate(noteId: number): void;
  markFolderPushed(
    localId: number,
    remoteId: string,
    serverUpdatedAt: string,
    pushed?: Folder,
  ): void;
  /**
   * Clears a folder's pendingSync with no other changes — used when the server
   * permanently refused the push (space access lost, or the caller lacks
   * permission on this folder). The local row is deliberately left as-is; its
   * notes recover individually through their own push errors and pull stubs.
   */
  markFolderTerminal(localId: number): void;
  /**
   * Merges a locally-pending default folder into an already-synced duplicate
   * row a later pull inserted for the same server folder (see pushFolders.ts's
   * pre-create adoption check). `survivingLocalId` keeps its own local id —
   * every pre-existing note.folder_id already points at it — and is pointed at
   * `remoteId`/`serverUpdatedAt` with pendingSync cleared, exactly like
   * markFolderPushed. Notes filed under `duplicateLocalId` are re-parented onto
   * `survivingLocalId` with NO pendingSync change: the server's folder_id for
   * those notes is unchanged (both local rows already resolve to the same
   * server folder), so this is a pure local FK fixup, not a push-worthy edit.
   * `duplicateLocalId` is then removed.
   */
  adoptDuplicateFolder(
    survivingLocalId: number,
    duplicateLocalId: number,
    remoteId: string,
    serverUpdatedAt: string,
  ): void;
  /**
   * Acknowledges a push of `pushed`, the row exactly as it was serialized. The
   * row settles (pendingSync cleared) only if it is still unchanged; a note
   * edited or deleted while the request was in flight stays queued and merely
   * records the server revision as its next base.
   *
   * cloudUpdatedAt defaults to serverUpdatedAt when omitted. Pass it explicitly
   * as `null` when serverUpdatedAt is itself a local-clock fallback (the server
   * response omitted its own updated_at) — cloudUpdatedAt must only ever hold a
   * genuine server ack, never a value guaranteed to mismatch on the next push.
   *
   * serverCreatedAt, when the response carries it, repairs a createdAt stamped
   * with the pull time by builds that didn't sync created_at.
   */
  markNotePushed(
    pushed: Note,
    remoteId: string,
    serverUpdatedAt: string,
    cloudUpdatedAt?: string | null,
    serverCreatedAt?: string,
  ): void;
  /** Clears pendingSync with no other changes — used when a push was permanently rejected (e.g. HTTP 400) and retrying would never succeed. */
  markNoteTerminal(localId: number): void;
  /**
   * Abandons the local push attempt for a row the server refused on permission
   * grounds (note_access_denied / note_scope_change_denied): clears pendingSync
   * AND drops cloud_updated_at. The server row is untouched by the rejected
   * write, so the next pull's copy is the truth — and without clearing the base
   * that pull could otherwise be followed by a stale-base 409.
   */
  dropNotePushAttempt(localId: number): void;
  /** True while the note's latest push was refused (terminal or dropped) and no later push, pull or delete has settled it. */
  isNotePushRejected(localId: number): boolean;
  /**
   * Records a push-time 409 note_version_conflict: stores the server's current
   * copy in conflict_server_note and leaves pendingSync untouched (local edits
   * are preserved). The row is excluded from getPendingNotes until resolved.
   */
  parkNoteConflict(localId: number, serverNote: RemoteNote): void;
  /** Rows currently parked in conflict — data source for the future Keep-mine/Use-server banner. */
  listConflictedNotes(): ConflictedNote[];
  /** Keep the local edit: clear the conflict and adopt the stored server updated_at as the new base (so the next push wins); pendingSync stays set. */
  resolveConflictKeepMine(noteId: number): void;
  /** Use the server's copy: apply the stored server note over the local row, then clear the conflict and pendingSync. */
  resolveConflictUseServer(noteId: number): void;
  hardDeleteFolder(localId: number): void;
  hardDeleteNote(localId: number): void;
  getSyncState(key: string): string | null;
  setSyncState(key: string, value: string): void;
  /**
   * Removes the key entirely, so getSyncState reads `null` again — the exact
   * state a device that never synced is in. Used to reset a pull cursor (see
   * resetTeamCursors); writing an empty string instead would not do, because a
   * stored '' reads back as a non-null cursor that then drops out of the
   * request as falsy — putting the list endpoint into its tombstone-free browse
   * mode rather than replaying the delta crawl from epoch.
   */
  clearSyncState(key: string): void;

  // Initial backfill
  getFoldersMissingClientId(): Folder[];
  getNotesMissingClientId(): Note[];
  setFolderClientId(localId: number, clientFolderId: string): Folder;
  setNoteClientId(localId: number, clientNoteId: string): Note;

  // Private mode
  setNotePrivacy(localId: number, isPrivate: boolean): void;
  clearNoteRemoteId(localId: number): void;
  /** Forgets every remote id and re-dirties all rows when an anonymous session links to an account. */
  dropRemoteIdsForAccountLink(): void;
  clearNoteClientId(localId: number): void;

  // Account switch — wipe all syncable data
  wipeAllSyncableData(): void;

  // Transcript segments
  getSegments(noteId: number): Segment[];
  /** Atomically replaces ALL segments for a note (hard-deletes existing, then inserts). Use after a diarize/merge pass. */
  replaceSegments(noteId: number, segments: NewSegment[]): void;

  // Cross-device transcript sync (desktop <-> mobile via notes.transcript)
  /** Rebuilds a note's segments + speakers from desktop-shape transcript JSON and stores the raw string. */
  applyRemoteTranscript(noteId: number, raw: string): void;
  /** True when the note has locally-authored segment or speaker rows awaiting push. */
  hasDirtyTranscript(noteId: number): boolean;
  /** After a successful push: stores the serialized string and clears pendingSync on exactly the pushed rows. */
  markTranscriptPushed(
    noteId: number,
    raw: string,
    segmentIds: number[],
    speakerIds: number[],
  ): void;

  // Speakers
  getSpeakers(noteId: number): Speaker[];
  /**
   * INSERT-ONLY (no conflict resolution despite the name) — inserts new speaker rows for a note.
   * Re-diarize reconciliation (dedupe/merge by label, preserving locks) is M2's job and MUST go
   * through `speakerState.mergeSpeakerState` before persisting. Do not call this to update existing speakers.
   */
  upsertSpeakers(noteId: number, speakers: NewSpeaker[]): void;
  /**
   * Dumb sink: writes `updates` unconditionally and does NOT enforce the speaker lock.
   * Callers (M3 rename / M4 voiceprint) MUST route changes through `speakerState`
   * (`isLocked`/`applySuggested`/`lockSpeaker`/`mergeSpeakerState`) first, or a locked speaker can be clobbered.
   * Note: `Speaker.speakerLocked` is an integer (0/1) from SQLite — map to boolean before passing a row into `speakerState`.
   */
  updateSpeaker(id: number, updates: Partial<Speaker>): void;
  /**
   * User merge operation: relabel source segments to target and soft-delete the source speaker.
   * Dumb persistence sink — callers must build targetUpdates through speakerState policy helpers.
   */
  mergeSpeakers(
    noteId: number,
    sourceSpeakerId: number,
    targetSpeakerId: number,
    targetUpdates: Partial<Speaker>,
  ): void;

  // Speaker profiles — local only, never synced
  getSpeakerProfiles(): SpeakerProfile[];
  getSpeakerProfileById(id: number): SpeakerProfile | null;
  createSpeakerProfile(input: NewSpeakerProfile): SpeakerProfile;
  /**
   * Atomically creates the owner speaker profile and applies `speakerPatch` (plus the new
   * profile's id) to the speaker row in one transaction, so a failure partway through never
   * leaves an owner profile with no speaker linked to it, which would block every later
   * claim until the profile was deleted. Used by the "claim this speaker as me" flow.
   */
  createOwnerProfileForSpeaker(
    speakerId: number,
    profileInput: Omit<NewSpeakerProfile, 'isOwner'>,
    speakerPatch: Partial<Speaker>,
  ): SpeakerProfile;
  updateSpeakerProfile(id: number, updates: Partial<SpeakerProfile>): void;
  deleteSpeakerProfile(id: number): void;
  deleteAllSpeakerProfiles(): void;

  // Transcription status
  /** Read the note's current status (defaults to 'idle'). Used by the guarded transition path. */
  getTranscriptionStatus(noteId: number): TranscriptionStatus;
  /** Low-level status writer. Call ONLY inside a guarded transition (store.transitionStatus / service advance()). */
  setTranscriptionStatus(noteId: number, status: TranscriptionStatus): void;
  /** Update local-only meeting/diarization columns NoteUpdate cannot reach. */
  updateNoteMeta(noteId: number, updates: MeetingNoteUpdate): void;
  /** Points a meeting with no recording path back at its recording, keeping its place in lists. */
  restoreMeetingRecordingPath(noteId: number, sourceFile: string): void;
  /** Update selected calendar context; public notes mark pending sync, private notes stay local-only. */
  updateNoteCalendarContext(noteId: number, updates: MeetingCalendarContextUpdate): void;
}