Skip to content

A local-first personal finance app

[AI] Add getNote and updateNote to public API (#7769)

Will Lapinel3799b587ec01
diff --git a/packages/api/methods.test.ts b/packages/api/methods.test.ts
index e8b0f5a76f..3625a8efc7 100644
--- a/packages/api/methods.test.ts
+++ b/packages/api/methods.test.ts
@@ -516,6 +516,29 @@ describe('API CRUD operations', () => {
);
});
+ // apis: getNote, updateNote
+ test('Notes: successfully get and update note', async () => {
+ const categories = await api.getCategories();
+ const categoryId = categories[0].id;
+
+ // No note exists initially
+ const initial = await api.getNote(categoryId);
+ expect(initial).toBeNull();
+
+ // Set a note
+ await api.updateNote(categoryId, 'Test note content');
+ const afterSet = await api.getNote(categoryId);
+ expect(afterSet).toEqual({ id: categoryId, note: 'Test note content' });
+
+ // Update the note
+ await api.updateNote(categoryId, 'Updated note content');
+ const afterUpdate = await api.getNote(categoryId);
+ expect(afterUpdate).toEqual({
+ id: categoryId,
+ note: 'Updated note content',
+ });
+ });
+
// apis: getRules, getPayeeRules, createRule, updateRule, deleteRule
test('Rules: successfully update rules', async () => {
await api.createPayee({ name: 'test-payee' });
diff --git a/packages/api/methods.ts b/packages/api/methods.ts
index 14137aad41..62405e673c 100644
--- a/packages/api/methods.ts
+++ b/packages/api/methods.ts
@@ -13,6 +13,7 @@ import type { ImportTransactionsOpts } from '@actual-app/core/types/api-handlers
import type { Handlers } from '@actual-app/core/types/handlers';
import type {
ImportTransactionEntity,
+ NoteEntity,
RuleEntity,
TransactionEntity,
} from '@actual-app/core/types/models';
@@ -247,6 +248,14 @@ export function deleteCategory(
return send('api/category-delete', { id, transferCategoryId });
}
+export function getNote(id: NoteEntity['id']) {
+ return send('api/note-get', { id });
+}
+
+export function updateNote(id: NoteEntity['id'], note: NoteEntity['note']) {
+ return send('api/note-update', { id, note });
+}
+
export function getCommonPayees() {
return send('api/common-payees-get');
}
diff --git a/packages/docs/docs/api/reference.md b/packages/docs/docs/api/reference.md
index 37e4ac2ffb..c07a8262ba 100644
--- a/packages/docs/docs/api/reference.md
+++ b/packages/docs/docs/api/reference.md
@@ -87,6 +87,11 @@ import APIList from './APIList';
"deleteSchedule"
]} />
+<APIList title="Notes" sections={[
+"getNote",
+"updateNote"
+]} />
+
<APIList title="Misc" sections={[
"BudgetFile",
"initConfig",
@@ -730,6 +735,22 @@ Update fields of a rule. `fields` can specify any field described in [`Schedule`
<Method name="deleteSchedule" args={[{ name: 'id', type: 'id' }]} returns="Promise<null>" />
+## Notes
+
+Notes can be attached to any entity (categories, budget months, etc.) by ID. They are also used to define budget templates and savings goals (e.g. `#template 250`, `#goal 1000`).
+
+#### `getNote`
+
+<Method name="getNote" args={[{ name: 'id', type: 'id' }]} returns="Promise<Note | null>" />
+
+Returns the note for the given entity ID, or `null` if no note has been set.
+
+#### `updateNote`
+
+<Method name="updateNote" args={[{ name: 'id', type: 'id' }, { name: 'note', type: 'string' }]} returns="Promise<void>" />
+
+Sets the note on the entity with the given ID. Pass an empty string to clear the note.
+
## Misc
#### BudgetFile
diff --git a/packages/loot-core/src/server/api.ts b/packages/loot-core/src/server/api.ts
index 7d5a5e3ed0..bd27a3378d 100644
--- a/packages/loot-core/src/server/api.ts
+++ b/packages/loot-core/src/server/api.ts
@@ -707,6 +707,16 @@ handlers['api/category-delete'] = withMutation(async function ({
});
});
+handlers['api/note-get'] = async function ({ id }) {
+ checkFileOpen();
+ return handlers['notes-get']({ id });
+};
+
+handlers['api/note-update'] = withMutation(async function ({ id, note }) {
+ checkFileOpen();
+ return handlers['notes-save']({ id, note });
+});
+
handlers['api/common-payees-get'] = async function () {
checkFileOpen();
const payees = await handlers['common-payees-get']();
diff --git a/packages/loot-core/src/server/notes/app.ts b/packages/loot-core/src/server/notes/app.ts
index 961087eeed..fd6e667048 100644
--- a/packages/loot-core/src/server/notes/app.ts
+++ b/packages/loot-core/src/server/notes/app.ts
@@ -7,12 +7,20 @@ import type { NoteEntity } from '#types/models';
export type NotesHandlers = {
'notes-save': typeof updateNotes;
'notes-save-undoable': typeof updateNotes;
+ 'notes-get': (arg: Pick<NoteEntity, 'id'>) => Promise<NoteEntity | null>;
};
export const app = createApp<NotesHandlers>();
app.method('notes-save', updateNotes);
app.method('notes-save-undoable', mutator(undoable(updateNotes)));
+app.method('notes-get', getNote);
async function updateNotes({ id, note }: NoteEntity) {
await db.update('notes', { id, note });
}
+
+async function getNote({
+ id,
+}: Pick<NoteEntity, 'id'>): Promise<NoteEntity | null> {
+ return db.first<NoteEntity>('SELECT id, note FROM notes WHERE id = ?', [id]);
+}
diff --git a/packages/loot-core/src/types/api-handlers.ts b/packages/loot-core/src/types/api-handlers.ts
index fa1b422490..8b74b194a1 100644
--- a/packages/loot-core/src/types/api-handlers.ts
+++ b/packages/loot-core/src/types/api-handlers.ts
@@ -19,6 +19,7 @@ import type {
ImportTransactionEntity,
NearbyPayeeEntity,
NewRuleEntity,
+ NoteEntity,
PayeeEntity,
PayeeLocationEntity,
RuleEntity,
@@ -195,6 +196,10 @@ export type ApiHandlers = {
transferCategoryId?: APICategoryEntity['id'];
}) => Promise<void>;
+ 'api/note-get': (arg: Pick<NoteEntity, 'id'>) => Promise<NoteEntity | null>;
+
+ 'api/note-update': (arg: NoteEntity) => Promise<void>;
+
'api/payees-get': () => Promise<APIPayeeEntity[]>;
'api/common-payees-get': () => Promise<APIPayeeEntity[]>;
diff --git a/upcoming-release-notes/7769.md b/upcoming-release-notes/7769.md
new file mode 100644
index 0000000000..41e305a1c2
--- /dev/null
+++ b/upcoming-release-notes/7769.md
@@ -0,0 +1,6 @@
+---
+category: Enhancements
+authors: [whlapinel]
+---
+
+Add `getNote` and `updateNote` to the public `@actual-app/api`, enabling programmatic read/write of category notes (templates, goals, etc.) without internal API access.