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.mdindex 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.tsnew file mode 100644index 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.tsindex 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.mdnew file mode 100644index 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