Chore/drop axios dependency

.npmignore

@@ -6,6 +6,7 @@ node_modules/
 .prettierignore
 .prettierrc.cjs
 src/
+docs/
 *.js.map
 .prettierignore
 .prettierrc.cjs

.prettierrc.cjs

@@ -5,6 +5,7 @@ module.exports = {
   printWidth: 80,
   tabWidth: 2,
   useTabs: false,
+  plugins: ['@trivago/prettier-plugin-sort-imports'],
   importOrder: ['<THIRD_PARTY_MODULES>', '^@/(.*)$', '^[./]'],
   importOrderSeparation: true,
   importOrderSortSpecifiers: true,

README.md

@@ -1,7 +1,12 @@
-# Splid.Js
+<img src="docs/banner.svg" width="100%" />
 
-a reverse-engineered typescript client for the Splid (https://splid.app) API.
-at the moment, only read operations are supported.
+# splid.js
+
+a feature-complete typescript client for the Splid (https://splid.app) API.
+Splid is a free mobile app for keeping track of expenses among friend groups.
+this package is not officially associated with Splid.
+
+last updated Nov 7 2024
 
 ## Install
 
@@ -18,56 +23,65 @@ npm install splid-js
 import { SplidClient } from 'splid-js';
 
 async function main() {
-  const client = new SplidClient();
+  const splid = new SplidClient();
 
   const inviteCode = 'PWJ E2B P7A';
 
-  const groupRes = await client.group.getByInviteCode(inviteCode);
+  const groupRes = await splid.group.getByInviteCode(inviteCode);
 
-  const groupInfoRes = await client.groupInfo.getByGroup(
-    groupRes.result.objectId
-  );
+  const groupId = groupRes.result.objectId;
 
-  const entriesRes = await client.entry.getByGroup(groupRes.result.objectId);
+  const groupInfo = await splid.groupInfo.getOneByGroup(groupId);
+  const members = await splid.person.getAllByGroup(groupId);
+  const expensesAndPayments = await splid.entry.getAllByGroup(groupId);
 
-  const membersRes = await client.person.getByGroup(groupRes.result.objectId);
-
-  const expensesAndPayments = await client.entry.getByGroup(
-    groupRes.result.objectId
+  const balance = SplidClient.getBalance(
+    members,
+    expensesAndPayments,
+    groupInfo
   );
+  const suggestedPayments = SplidClient.getSuggestedPayments(balance);
+
+  console.log(balance, suggestedPayments);
 }
 main();
 ```
 
 ```typescript
-// using the returned data
+// parsing the returned data
 import { SplidClient } from 'splid-js';
 
-const formatCurrency = (amount: number, currencyCode: string) => {
-  return (
-    amount.toLocaleString(undefined, {
-      minimumFractionDigits: 2,
-      maximumFractionDigits: 2,
-    }) + currencyCode
-  );
+const formatCurrency = (amount: number, currency: string) => {
+  return amount.toLocaleString(undefined, {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  });
 };
 
 const getEntryDescription = (
   entry: SplidJs.Entry,
   members: SplidJs.Person[]
 ) => {
-  const primaryPayer = members.find((j) => j.GlobalId === entry.primaryPayer);
+  const primaryPayer = members.find((i) => i.GlobalId === entry.primaryPayer)!;
 
   for (const item of entry.items) {
     const totalAmount = item.AM;
-
-    const profiteers = Object.entries(item.P.P).map(([userId, share]) => {
-      const user = members.find((j) => j.GlobalId === userId);
-
-      const shareText = formatCurrency(totalAmount * share, entry.currencyCode);
-
-      return user.name + ' (' + shareText + ')';
-    });
+    // a map of a userId to their share (how much they profit from the expense). the shares are floats between 0 and 1 and their sum is exactly 1.
+    const userIdToShareMap = item.P.P;
+
+    const profiteers = Object.entries(userIdToShareMap).map(
+      ([userId, share]) => {
+        const user = members.find((i) => i.GlobalId === userId)!;
+
+        const shareText = formatCurrency(
+          totalAmount * share,
+          entry.currencyCode
+        );
+        return user.name + ' (' + shareText + ')';
+      }
+    );
     const profiteersText = profiteers.join(', ');
 
     const totalText = formatCurrency(totalAmount, entry.currencyCode);
@@ -87,32 +101,213 @@ const getEntryDescription = (
 };
 
 async function main() {
-  const client = new SplidClient();
+  const splid = new SplidClient();
 
   const inviteCode = 'PWJ E2B P7A';
 
-  const groupRes = await client.group.getByInviteCode(inviteCode);
+  const groupRes = await splid.group.getByInviteCode(inviteCode);
 
-  const groupInfoRes = await client.groupInfo.getByGroup(
-    groupRes.result.objectId
-  );
-
-  const entriesRes = await client.entry.getByGroup(groupRes.result.objectId);
+  const groupId = groupRes.result.objectId;
 
-  const membersRes = await client.person.getByGroup(groupRes.result.objectId);
+  const members = await splid.person.getAllByGroup(groupId);
+  const expensesAndPayments = await splid.entry.getAllByGroup(groupId);
 
-  for (const entry of entriesRes.result.results) {
-    console.log(getEntryDescription(entry, membersRes.result.results));
+  for (const entry of expensesAndPayments) {
+    console.log(getEntryDescription(entry, members));
   }
 }
 main();
 ```
 
 ```typescript
-// calculating members balances and suggested payments
-const people = await client.person.getAllByGroup(groupId);
-const entries = await client.entry.getAllByGroup(groupId);
+// updating group properties
+const groupInfo = await splid.groupInfo.getOneByGroup(groupId);
+
+groupInfo.name = 'Modified Group 🔥';
+
+groupInfo.customCategories.push('Pharmaceuticals 💊');
+
+// setting the currency exchange rates to the most recent values
+groupInfo.currencyRates = await splid.getCurrencyRates();
+
+groupInfo.defaultCurrencyCode = 'EUR';
+
+await splid.groupInfo.set(groupInfo);
+```
+
+```typescript
+// updating group wallpaper (NodeJs)
+import fs from 'fs';
+
+const file = await fs.promises.readFile('image.png');
+
+const uploadRes = await splid.file.upload(file);
+
+groupInfo.wallpaperID = uploadRes.dataID;
+```
+
+```typescript
+// updating person properties
+const members = await splid.person.getAllByGroup(groupId);
+
+const linus = members.find((i) => i.name === 'Linus');
+
+linus.name = 'Alex';
+linus.initials = 'A';
+
+await splid.person.set(linus);
+```
+
+```typescript
+// updating entry properties
+const entries = await splid.entry.getAllByGroup(groupId);
+
+const pizzaEntries = entries.filter((i) =>
+  i.title.toLowerCase().includes('pizza')
+);
+
+for (const entry of pizzaEntries) {
+  // setting the category of an entry
+  entry.category = {
+    type: 'custom',
+    originalName: 'Italian Food 🍕',
+  };
+  // setting the date of an entry
+  if (!entry.date) {
+    entry.date = {
+      __type: 'Date',
+      iso: new Date().toISOString(),
+    };
+  } else {
+    entry.date.iso = new Date().toISOString();
+  }
+}
+await splid.entry.set(pizzaEntries);
+```
+
+```typescript
+// converting all foreign currency entries to the default currency of the group
 
-const balance = SplidClient.getBalance(people, entries);
-const suggestedPayments = SplidClient.getSuggestedPayments(balance);
+const foreignCurrencyEntries = expensesAndPayments.filter(
+  (i) => !i.isPayment && i.currencyCode !== groupInfo.defaultCurrencyCode
+);
+
+for (const entry of foreignCurrencyEntries) {
+  const factor =
+    groupInfo.currencyRates[entry.currencyCode] /
+    groupInfo.currencyRates[groupInfo.defaultCurrencyCode];
+
+  entry.currencyCode = groupInfo.defaultCurrencyCode;
+
+  for (const item of entry.items) {
+    item.AM = item.AM * factor;
+  }
+  for (const [payerId, amount] of Object.entries(entry.secondaryPayers ?? {})) {
+    entry.secondaryPayers[payerId] = amount * factor;
+  }
+}
+await splid.entry.set(foreignCurrencyEntries);
+```
+
+```typescript
+// deleting entries
+const entries = await splid.entry.getAllByGroup(groupId);
+
+const entry = entries[0];
+
+entry.isDeleted = true;
+
+await splid.entry.set(entry);
+```
+
+```typescript
+// creating a group
+await splid.group.create('🎉 Ramber Zamber', ['Linus', 'Laurin', 'Oskar']);
+```
+
+```typescript
+// creating a basic expense
+await splid.entry.expense.create(
+  {
+    groupId,
+    payers: [linus.GlobalId],
+    title: 'döner',
+  },
+  {
+    amount: 10,
+    // equivalent to equivalent to { [laurin.GlobalId]: 0.5, [oskar.GlobalId]: 0.5 }
+    profiteers: [laurin.GlobalId, oskar.GlobalId],
+  }
+);
+```
+
+```typescript
+// creating an expense with multiple items
+await splid.entry.expense.create(
+  {
+    groupId,
+    payers: [linus.GlobalId],
+    title: 'shopping spree 😌',
+  },
+  [
+    {
+      title: 'gucci belt',
+      amount: 10,
+      profiteers: [laurin.GlobalId],
+    },
+    {
+      title: 'drippy hat',
+      amount: 15,
+      profiteers: [oskar.GlobalId],
+    },
+  ]
+);
+```
+
+```typescript
+// creating an expense with multiple payers (both pay half)
+await splid.entry.expense.create(
+  {
+    groupId,
+    // equivalent to { [linus.GlobalId]: 5, [oskar.GlobalId]: 5 }
+    payers: [linus.GlobalId, oskar.GlobalId],
+    title: 'döner',
+  },
+  {
+    amount: 10,
+    profiteers: [linus.GlobalId, oskar.GlobalId],
+  }
+);
+```
+
+```typescript
+// creating an expense with unevenly split payers (oskar pays 3€)
+await splid.entry.expense.create(
+  {
+    groupId,
+    // equivalent to { [linus.GlobalId]: 7, [oskar.GlobalId]: 3 }
+    payers: [linus.GlobalId, { id: oskar.GlobalId, amount: 3 }],
+    title: 'shopping',
+  },
+  {
+    amount: 10,
+    profiteers: [laurin.GlobalId],
+  }
+);
+```
+
+```typescript
+// creating an expense with unevenly split profiteers (oskar owes 2.25€)
+await splid.entry.expense.create(
+  {
+    groupId,
+    payers: [linus.GlobalId],
+    title: 'shopping',
+  },
+  {
+    amount: 10,
+    // equivalent to { [linus.GlobalId]: 3 / 4, [oskar.GlobalId]: 1 / 4 }
+    profiteers: [linus.GlobalId, { id: oskar.GlobalId, share: 1 / 4 }],
+  }
+);
 ```