Skip to content

A local-first personal finance app

[AI] Warn API users about deferred sync messages and fix stale docs row (#8925)

Matiss Janis Aboltinsf8ad7c0ebd76
diff --git a/packages/docs/docs/api/index.md b/packages/docs/docs/api/index.md
index 8dea344732..e7800a1dd0 100644
--- a/packages/docs/docs/api/index.md
+++ b/packages/docs/docs/api/index.md
@@ -157,7 +157,7 @@ These are the codes for the common failures:
| `missing-key` | The budget file is end-to-end encrypted, and no encryption password was given. |
| `decrypt-failure` | The budget file could not be decrypted — the encryption password is wrong. |
| `old-key-style` | The budget file uses an old, unsupported encryption key style. |
-| `out-of-sync-migrations` | The budget file needs a newer version of Actual — update the API package. |
+| `out-of-sync-migrations` | The budget file is damaged or from a version too old to open. Files from a newer Actual open fine. |
:::note
`code` is present for the common connection and download failures listed above. Other errors may only carry a `message`, so always keep a fallback.
diff --git a/packages/loot-core/src/platform/server/connection/index.api.test.ts b/packages/loot-core/src/platform/server/connection/index.api.test.ts
new file mode 100644
index 0000000000..575fba28cf
--- /dev/null
+++ b/packages/loot-core/src/platform/server/connection/index.api.test.ts
@@ -0,0 +1,19 @@
+import { afterEach, expect, test, vi } from 'vitest';
+
+// oxlint-disable-next-line no-restricted-imports
+import { send } from './index.api';
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+test('warns the script author about deferred and dropped sync messages only', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+ send('sync-event', { type: 'success', tables: [] });
+ expect(warn).not.toHaveBeenCalled();
+
+ send('sync-event', { type: 'deferred-messages' });
+ send('sync-event', { type: 'dropped-messages' });
+ expect(warn).toHaveBeenCalledTimes(2);
+});
diff --git a/packages/loot-core/src/platform/server/connection/index.api.ts b/packages/loot-core/src/platform/server/connection/index.api.ts
index b204f37d08..214e86e916 100644
--- a/packages/loot-core/src/platform/server/connection/index.api.ts
+++ b/packages/loot-core/src/platform/server/connection/index.api.ts
@@ -1,11 +1,28 @@
+import { logger } from '#platform/server/log';
+import type { ServerEvents } from '#types/server-events';
+
import type * as T from './index-types';
export const init: T.Init = function () {
// Nothing
};
-export const send: T.Send = function () {
- // Nothing
+// The API has no UI for server events; the two below mean synced data is
+// parked on (or lost from) this device, so surface them to the script author
+export const send: T.Send = function (type, args) {
+ if (type !== 'sync-event' || !args) {
+ return;
+ }
+ const event = args as ServerEvents['sync-event'];
+ if (event.type === 'deferred-messages') {
+ logger.warn(
+ 'Some synced changes were made with a newer version of Actual and will apply once @actual-app/api is updated',
+ );
+ } else if (event.type === 'dropped-messages') {
+ logger.warn(
+ 'Some changes made on another device could not be applied on this device, so your data may differ',
+ );
+ }
};
export const getNumClients: T.GetNumClients = function () {
diff --git a/upcoming-release-notes/api-warn-deferred-sync-changes.md b/upcoming-release-notes/api-warn-deferred-sync-changes.md
new file mode 100644
index 0000000000..2c2cb1c902
--- /dev/null
+++ b/upcoming-release-notes/api-warn-deferred-sync-changes.md
@@ -0,0 +1,6 @@
+---
+category: Enhancements
+authors: [MatissJanis]
+---
+
+Warn API and CLI users when synced changes from a newer version of Actual are waiting for an update