@actual-app/sync-server 25.4.0-alpha.0

package/src/app-admin.test.js

@@ -0,0 +1,381 @@
+import request from 'supertest';
+import { v4 as uuidv4 } from 'uuid';
+
+import { getAccountDb } from './account-db.js';
+import { handlers as app } from './app-admin.js';
+
+const ADMIN_ROLE = 'ADMIN';
+const BASIC_ROLE = 'BASIC';
+
+// Create user helper function
+const createUser = (userId, userName, role, owner = 0, enabled = 1) => {
+  getAccountDb().mutate(
+    'INSERT INTO users (id, user_name, display_name, enabled, owner, role) VALUES (?, ?, ?, ?, ?, ?)',
+    [userId, userName, `${userName} display`, enabled, owner, role],
+  );
+};
+
+const deleteUser = userId => {
+  getAccountDb().mutate('DELETE FROM user_access WHERE user_id = ?', [userId]);
+  getAccountDb().mutate('DELETE FROM users WHERE id = ?', [userId]);
+};
+
+const createSession = (userId, sessionToken) => {
+  getAccountDb().mutate(
+    'INSERT INTO sessions (token, user_id, expires_at) VALUES (?, ?, ?)',
+    [sessionToken, userId, Date.now() + 1000 * 60 * 60], // Expire in 1 hour
+  );
+};
+
+const generateSessionToken = () => `token-${uuidv4()}`;
+
+describe('/admin', () => {
+  describe('/owner-created', () => {
+    it('should return 200 and true if an owner user is created', async () => {
+      const sessionToken = generateSessionToken();
+      const adminId = uuidv4();
+      createUser(adminId, 'admin', ADMIN_ROLE, 1);
+      createSession(adminId, sessionToken);
+
+      const res = await request(app)
+        .get('/owner-created')
+        .set('x-actual-token', sessionToken);
+
+      expect(res.statusCode).toEqual(200);
+      expect(res.body).toBe(true);
+    });
+  });
+
+  describe('/users', () => {
+    describe('GET /users', () => {
+      let sessionUserId, testUserId, sessionToken;
+
+      beforeEach(() => {
+        sessionUserId = uuidv4();
+        testUserId = uuidv4();
+        sessionToken = generateSessionToken();
+
+        createUser(sessionUserId, 'sessionUser', ADMIN_ROLE);
+        createSession(sessionUserId, sessionToken);
+        createUser(testUserId, 'testUser', ADMIN_ROLE);
+      });
+
+      afterEach(() => {
+        deleteUser(sessionUserId);
+        deleteUser(testUserId);
+      });
+
+      it('should return 200 and a list of users', async () => {
+        const res = await request(app)
+          .get('/users')
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(200);
+        expect(res.body.length).toBeGreaterThan(0);
+      });
+    });
+
+    describe('POST /users', () => {
+      let sessionUserId, sessionToken;
+      let createdUserId;
+      let duplicateUserId;
+
+      beforeEach(() => {
+        sessionUserId = uuidv4();
+        sessionToken = generateSessionToken();
+        createUser(sessionUserId, 'sessionUser', ADMIN_ROLE);
+        createSession(sessionUserId, sessionToken);
+      });
+
+      afterEach(() => {
+        deleteUser(sessionUserId);
+        if (createdUserId) {
+          deleteUser(createdUserId);
+          createdUserId = null;
+        }
+
+        if (duplicateUserId) {
+          deleteUser(duplicateUserId);
+          duplicateUserId = null;
+        }
+      });
+
+      it('should return 200 and create a new user', async () => {
+        const newUser = {
+          userName: 'user1',
+          displayName: 'User One',
+          enabled: 1,
+          owner: 0,
+          role: BASIC_ROLE,
+        };
+
+        const res = await request(app)
+          .post('/users')
+          .send(newUser)
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(200);
+        expect(res.body.status).toBe('ok');
+        expect(res.body.data).toHaveProperty('id');
+
+        createdUserId = res.body.data.id;
+      });
+
+      it('should return 400 if the user already exists', async () => {
+        const newUser = {
+          userName: 'user1',
+          displayName: 'User One',
+          enabled: 1,
+          owner: 0,
+          role: BASIC_ROLE,
+        };
+
+        let res = await request(app)
+          .post('/users')
+          .send(newUser)
+          .set('x-actual-token', sessionToken);
+
+        duplicateUserId = res.body.data.id;
+
+        res = await request(app)
+          .post('/users')
+          .send(newUser)
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(400);
+        expect(res.body.status).toBe('error');
+        expect(res.body.reason).toBe('user-already-exists');
+      });
+    });
+
+    describe('PATCH /users', () => {
+      let sessionUserId, testUserId, sessionToken;
+
+      beforeEach(() => {
+        sessionUserId = uuidv4();
+        testUserId = uuidv4();
+        sessionToken = generateSessionToken();
+
+        createUser(sessionUserId, 'sessionUser', ADMIN_ROLE);
+        createSession(sessionUserId, sessionToken);
+        createUser(testUserId, 'testUser', ADMIN_ROLE);
+      });
+
+      afterEach(() => {
+        deleteUser(sessionUserId);
+        deleteUser(testUserId);
+      });
+
+      it('should return 200 and update an existing user', async () => {
+        const userToUpdate = {
+          id: testUserId,
+          userName: 'updatedUser',
+          displayName: 'Updated User',
+          enabled: true,
+          role: BASIC_ROLE,
+        };
+
+        const res = await request(app)
+          .patch('/users')
+          .send(userToUpdate)
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(200);
+        expect(res.body.status).toBe('ok');
+        expect(res.body.data.id).toBe(testUserId);
+      });
+
+      it('should return 400 if the user does not exist', async () => {
+        const userToUpdate = {
+          id: 'non-existing-id',
+          userName: 'nonexistinguser',
+          displayName: 'Non-existing User',
+          enabled: true,
+          role: BASIC_ROLE,
+        };
+
+        const res = await request(app)
+          .patch('/users')
+          .send(userToUpdate)
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(400);
+        expect(res.body.status).toBe('error');
+        expect(res.body.reason).toBe('cannot-find-user-to-update');
+      });
+    });
+
+    describe('POST /users/delete-all', () => {
+      let sessionUserId, testUserId, sessionToken;
+
+      beforeEach(() => {
+        sessionUserId = uuidv4();
+        testUserId = uuidv4();
+        sessionToken = generateSessionToken();
+
+        createUser(sessionUserId, 'sessionUser', ADMIN_ROLE);
+        createSession(sessionUserId, sessionToken);
+        createUser(testUserId, 'testUser', ADMIN_ROLE);
+      });
+
+      afterEach(() => {
+        deleteUser(sessionUserId);
+        deleteUser(testUserId);
+      });
+
+      it('should return 200 and delete all specified users', async () => {
+        const userToDelete = {
+          ids: [testUserId],
+        };
+
+        const res = await request(app)
+          .delete('/users')
+          .send(userToDelete)
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(200);
+        expect(res.body.status).toBe('ok');
+        expect(res.body.data.someDeletionsFailed).toBe(false);
+      });
+
+      it('should return 400 if not all users are deleted', async () => {
+        const userToDelete = {
+          ids: ['non-existing-id'],
+        };
+
+        const res = await request(app)
+          .delete('/users')
+          .send(userToDelete)
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(400);
+        expect(res.body.status).toBe('error');
+        expect(res.body.reason).toBe('not-all-deleted');
+      });
+    });
+  });
+
+  describe('/access', () => {
+    describe('POST /access', () => {
+      let sessionUserId, testUserId, fileId, sessionToken;
+
+      beforeEach(() => {
+        sessionUserId = uuidv4();
+        testUserId = uuidv4();
+        fileId = uuidv4();
+        sessionToken = generateSessionToken();
+
+        createUser(sessionUserId, 'sessionUser', ADMIN_ROLE);
+        createSession(sessionUserId, sessionToken);
+        createUser(testUserId, 'testUser', ADMIN_ROLE);
+        getAccountDb().mutate('INSERT INTO files (id, owner) VALUES (?, ?)', [
+          fileId,
+          sessionUserId,
+        ]);
+      });
+
+      afterEach(() => {
+        deleteUser(sessionUserId);
+        deleteUser(testUserId);
+        getAccountDb().mutate('DELETE FROM files WHERE id = ?', [fileId]);
+      });
+
+      it('should return 200 and grant access to a user', async () => {
+        const newUserAccess = {
+          fileId,
+          userId: testUserId,
+        };
+
+        const res = await request(app)
+          .post('/access')
+          .send(newUserAccess)
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(200);
+        expect(res.body.status).toBe('ok');
+      });
+
+      it('should return 400 if the user already has access', async () => {
+        const newUserAccess = {
+          fileId,
+          userId: testUserId,
+        };
+
+        await request(app)
+          .post('/access')
+          .send(newUserAccess)
+          .set('x-actual-token', sessionToken);
+
+        const res = await request(app)
+          .post('/access')
+          .send(newUserAccess)
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(400);
+        expect(res.body.status).toBe('error');
+        expect(res.body.reason).toBe('user-already-have-access');
+      });
+    });
+
+    describe('DELETE /access', () => {
+      let sessionUserId, testUserId, fileId, sessionToken;
+
+      beforeEach(() => {
+        sessionUserId = uuidv4();
+        testUserId = uuidv4();
+        fileId = uuidv4();
+        sessionToken = generateSessionToken();
+
+        createUser(sessionUserId, 'sessionUser', ADMIN_ROLE);
+        createSession(sessionUserId, sessionToken);
+        createUser(testUserId, 'testUser', ADMIN_ROLE);
+        getAccountDb().mutate('INSERT INTO files (id, owner) VALUES (?, ?)', [
+          fileId,
+          sessionUserId,
+        ]);
+        getAccountDb().mutate(
+          'INSERT INTO user_access (user_id, file_id) VALUES (?, ?)',
+          [testUserId, fileId],
+        );
+      });
+
+      afterEach(() => {
+        deleteUser(sessionUserId);
+        deleteUser(testUserId);
+        getAccountDb().mutate('DELETE FROM files WHERE id = ?', [fileId]);
+      });
+
+      it('should return 200 and delete access for the specified user', async () => {
+        const deleteAccess = {
+          ids: [testUserId],
+        };
+
+        const res = await request(app)
+          .delete('/access')
+          .send(deleteAccess)
+          .query({ fileId })
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(200);
+        expect(res.body.status).toBe('ok');
+        expect(res.body.data.someDeletionsFailed).toBe(false);
+      });
+
+      it('should return 400 if not all access deletions are successful', async () => {
+        const deleteAccess = {
+          ids: ['non-existing-id'],
+        };
+
+        const res = await request(app)
+          .delete('/access')
+          .send(deleteAccess)
+          .query({ fileId })
+          .set('x-actual-token', sessionToken);
+
+        expect(res.statusCode).toEqual(400);
+        expect(res.body.status).toBe('error');
+        expect(res.body.reason).toBe('not-all-deleted');
+      });
+    });
+  });
+});

package/src/app-gocardless/README.md

@@ -0,0 +1,198 @@
+# Integration new bank
+
+If the default bank integration does not work for you, you can integrate a new bank by following these steps.
+
+1. Find in [this google doc](https://docs.google.com/spreadsheets/d/1ogpzydzotOltbssrc3IQ8rhBLlIZbQgm5QCiiNJrkyA/edit#gid=489769432) what is the identifier of the bank which you want to integrate.
+
+2. Launch frontend and backend server.
+
+3. In the frontend, create a new linked account selecting the institution which you are interested in.
+
+   This will trigger the process of fetching the data from the bank and will log the data in the backend. Use this data to fill the logic of the bank class.
+
+4. Create new a bank class based on an existing example in `app-gocardless/banks`.
+
+   Name of the file and class should follow the existing patterns and be created based on the ID of the integrated institution, found in step 1.
+
+5. Fill the logic of `normalizeAccount`, `normalizeTransaction`, `sortTransactions`, and `calculateStartingBalance` functions.
+   You do not need to fill every function, only those which are necessary for the integration to work.
+
+   You should do it based on the data which you found in the logs.
+
+   Example logs which help you to fill:
+
+   - `normalizeAccount` function:
+
+     ```log
+     Available account properties for new institution integration {
+       account: '{
+         "iban": "PL00000000000000000987654321",
+         "currency": "PLN",
+         "ownerName": "John Example",
+         "displayName": "Product name",
+         "product": "Daily account",
+         "usage": "PRIV",
+         "ownerAddressUnstructured": [
+           "POL",
+           "UL. Example 1",
+           "00-000 Warsaw"
+         ],
+         "id": "XXXXXXXX-XXXX-XXXXX-XXXXXX-XXXXXXXXX",
+         "created": "2023-01-18T12:15:16.502446Z",
+         "last_accessed": null,
+         "institution_id": "MBANK_RETAIL_BREXPLPW",
+         "status": "READY",
+         "owner_name": "",
+         "institution": {
+           "id": "MBANK_RETAIL_BREXPLPW",
+           "name": "mBank Retail",
+           "bic": "BREXPLPW",
+           "transaction_total_days": "90",
+           "countries": [
+             "PL"
+           ],
+           "logo": "https://cdn.nordigen.com/ais/MBANK_RETAIL_BREXCZPP.png",
+           "supported_payments": {},
+           "supported_features": [
+             "access_scopes",
+             "business_accounts",
+             "card_accounts",
+             "corporate_accounts",
+             "pending_transactions",
+             "private_accounts"
+           ]
+         }
+       }'
+     }
+     ```
+
+   - `sortTransactions` function:
+
+     ```log
+     Available (first 10) transactions properties for new integration of institution in sortTransactions function
+     {
+       top10SortedTransactions: '[
+         {
+           "transactionId": "20220101001",
+           "bookingDate": "2022-01-01",
+           "valueDate": "2022-01-01",
+           "transactionAmount": {
+             "amount": "5.01",
+             "currency": "EUR"
+           },
+           "creditorName": "JOHN EXAMPLE",
+           "creditorAccount": {
+             "iban": "PL00000000000000000987654321"
+           },
+           "debtorName": "CHRIS EXAMPLE",
+           "debtorAccount": {
+             "iban": "PL12345000000000000987654321"
+           },
+           "remittanceInformationUnstructured": "TEST BANK TRANSFER",
+           "remittanceInformationUnstructuredArray": [
+             "TEST BANK TRANSFER"
+           ],
+           "balanceAfterTransaction": {
+             "balanceAmount": {
+               "amount": "448.52",
+               "currency": "EUR"
+             },
+             "balanceType": "interimBooked"
+           },
+           "internalTransactionId": "casfib7720c2a02c0331cw2"
+         }
+       ]'
+     }
+     ```
+
+   - `calculateStartingBalance` function:
+
+     ```log
+     Available (first 10) transactions properties for new integration of institution in calculateStartingBalance function {
+       balances: '[
+         {
+           "balanceAmount": {
+             "amount": "448.52",
+             "currency": "EUR"
+           },
+           "balanceType": "forwardAvailable"
+         },
+         {
+           "balanceAmount": {
+             "amount": "448.52",
+             "currency": "EUR"
+           },
+           "balanceType": "interimBooked"
+         }
+       ]',
+         top10SortedTransactions: '[
+         {
+           "transactionId": "20220101001",
+           "bookingDate": "2022-01-01",
+           "valueDate": "2022-01-01",
+           "transactionAmount": {
+             "amount": "5.01",
+             "currency": "EUR"
+           },
+           "creditorName": "JOHN EXAMPLE",
+           "creditorAccount": {
+             "iban": "PL00000000000000000987654321"
+           },
+           "debtorName": "CHRIS EXAMPLE",
+           "debtorAccount": {
+             "iban": "PL12345000000000000987654321"
+           },
+           "remittanceInformationUnstructured": "TEST BANK TRANSFER",
+           "remittanceInformationUnstructuredArray": [
+             "TEST BANK TRANSFER"
+           ],
+           "balanceAfterTransaction": {
+             "balanceAmount": {
+               "amount": "448.52",
+               "currency": "EUR"
+             },
+             "balanceType": "interimBooked"
+           },
+           "internalTransactionId": "casfib7720c2a02c0331cw2"
+         }
+       ]'
+     }
+     ```
+
+6. Add new bank integration to `BankFactory` class in file `actual-server/app-gocardless/bank-factory.js`
+
+7. Remember to add tests for new bank integration in
+
+## normalizeTransaction
+
+This is the most commonly used override as it allows you to change the data that is returned to the client.
+
+Please follow the following patterns when implementing a custom normalizeTransaction method:
+
+1. If you need to edit the values of transaction fields (excluding the transaction amount) do not mutate the original transaction object. Instead, create a shallow copy and make your changes there.
+2. End the function by returning the result of calling the fallback normalizeTransaction method from integration-bank.js
+
+E.g.
+
+```js
+import Fallback from './integration-bank.js';
+
+export default {
+  ...
+
+  normalizeTransaction(transaction, booked) {
+    // create a shallow copy of the transaction object
+    const editedTrans = { ...transaction };
+
+    // make any changes required to the copy
+    editedTrans.remittanceInformationUnstructured = transaction.remittanceInformationStructured;
+
+    // call the fallback method, passing in your edited transaction as the 3rd parameter
+    // this will calculate the date, payee name and notes fields based on your changes
+    // but leave the original fields available for mapping in the UI
+    return Fallback.normalizeTransaction(transaction, booked, editedTrans);
+  }
+
+  ...
+}
+```