Lightsplit

Read a group's budgets: the shared group budget everyone sees, plus the caller's own personal budget. Each budget is {amount, period_type}, in the group's primary currency. period_type is 'monthly' or 'all_time'; a null period_type means no budget is set (amount is then 0). personal_budget is null when the caller is not a member of the group. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

Get the exchange rate between two currencies. `rate` converts quote into base: quote=JPY, base=TWD, rate=0.21 means 1 JPY is worth 0.21 TWD. You do not need this to record a foreign-currency expense — pass `currency` to create_expense and Lightsplit converts it itself. PASS `group` whenever the question is about a group's money ('what rate are we using for yen?'). A group can be running on a rate its members fixed rather than the market's, and its transactions convert at that one; with `group` you get the number those transactions use, and without it you get the market's, which may not be what the group is spending at.

Read a group: its settings, its full member roster and its share links. Call this FIRST for any group you are about to touch. Every other tool identifies people by member_id, and this is the only place those ids come from. Each member carries: - member_id — what you pass to the other tools - display_name — the name to use when talking to the user - is_caller — true for the member row belonging to the person whose token this is; this is how you resolve 'I', 'me' and 'my share' - is_seated — true when a real Lightsplit account occupies the seat, false for a placeholder - permission — 'edit', 'view', or 'deactivated' for a seat that has been turned off. A deactivated member takes no new money: they are not among the 'all active members' an omitted `splits` divides between, and naming one in a split they were not already part of is refused - balance — their net position in the group's primary currency: positive means the group owes them, negative means they owe the group

Get the shortest set of payments that clears every balance in the group — the answer to 'who owes whom, and how do we settle up?'. Each suggested payment names both members, so you can read it out directly. When the user then actually pays one of them, record it with create_transfer. An empty list means everybody is already square. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

Break a group's spending down by category: per-category sums of money spent (expense) and money received (income), in the group's primary currency. Returns two lists, expense and income. Each row is {category, amount_for_primary}, where amount_for_primary carries the ledger's sign — expense rows are NEGATIVE (money out), income rows positive (money in) — so a row's magnitude is what the group spent or received on that category. A row with an empty category is spending Lightsplit has not categorised. Optionally narrow it: `member_id` reports just that one member's share of each transaction, and `from`/`to` restrict it to a date window. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

List a group's shared reminders — its running to-buy / to-do list, the same list everyone in the group sees. Each reminder carries: id (what you pass to complete_reminder, update_reminder and delete_reminder), what (the reminder text), completed (whether it has been ticked off), and an optional currency+amount when the reminder has a price attached. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

List a group's transactions, newest first. Each transaction carries its from/to legs already resolved to display names, so one call is enough to tell the user '1200 for dinner, paid by Ming'. This is where transaction ids come from: call it before update_transaction or delete_transaction. Paging: pass the previous page's `next_cursor` back verbatim as `cursor`, and stop when next_cursor comes back null. The cursor is opaque — never construct or edit one. Narrow with `from`/`to` when the user names a day or a period. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

Remove an unseated placeholder member (is_seated=false) from a group. Three refusals worth knowing before you call: - Only the group's OWNER may remove anyone. Anybody else is refused before either of the checks below is reached, so a non-owner gets this answer whatever the member looks like. - A SEATED member — a real Lightsplit account holder, including the caller themselves — cannot be removed here. They have to leave the group themselves in the Lightsplit app; say so rather than trying again. - A member with a non-zero balance cannot be removed. Settle them up first (see get_settle_transfers and create_transfer), then remove them. Member ids come from get_group; call it first if you do not already have this group's roster. In that roster is_caller marks the member row belonging to the person whose token this is, which is who 'I', 'me' and 'my share' refer to.

Turn a Lightsplit share link into a group id, and return the same group's links for the other channels. You rarely need this: every other tool's `group` argument already accepts a share link. Reach for it when the user has a link and wants the same group on other channels ('send me the LINE version') — and hand back every link that comes with it, not just the one they named, so they can still choose. It only succeeds for a group the caller may already see, so it cannot be used to probe whether a link is real.

Set (or clear) the group's shared spending budget — the cap everyone in the group sees. Only the group's OWNER may set it; anyone else is refused. To set one, pass `amount` (>= 0, in the group's primary currency) and `period_type` ('monthly' or 'all_time'). To CLEAR it, omit both `amount` and `period_type`. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

Set (or clear) the caller's OWN personal spending budget in a group — private to them, not the shared group budget. The caller must be a member of the group. To set one, pass `amount` (>= 0, in the group's primary currency) and `period_type` ('monthly' or 'all_time'). To CLEAR it, omit both. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

Reopen a reminder that was ticked off, putting it back on the group's active list. Get the reminder_id from list_reminders.

Rename a group, change its note, or change who may open its share links. Only the fields you pass are changed; everything else is left alone. This is where you open a group up for sharing: other people can only get in through a share link, and only `public_permission` 'login' lets them claim a seat. Only the group's owner may do this. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

Rename a member of a group, or change their permission between 'edit' and 'view'. Renaming only has a visible effect on an UNSEATED placeholder member (is_seated=false). Once a real Lightsplit account claims the seat, that account's own display name is shown everywhere and `name` is ignored. Only the group's owner may do this. Member ids come from get_group; call it first if you do not already have this group's roster. In that roster is_caller marks the member row belonging to the person whose token this is, which is who 'I', 'me' and 'my share' refer to.

Edit a reminder. Editing REPLACES the reminder wholesale, so pass `what` as the full text you want it to read, not just the change. Get the reminder_id from list_reminders. `currency` and `amount` go together, exactly as in create_reminder: pass both to set (or change) the reminder's price, omit BOTH to leave it a plain reminder with no price.

Edit an existing transaction. Only the fields you pass change; everything else is left alone. Get the transaction_id from list_transactions. ONE RULE: if you change `amount` or `currency`, you must ALSO say how the transaction now divides — pass `splits`, or `equal_split: true`. `payers` on its own does not satisfy it. And if the transaction has MORE THAN ONE payer and the amount changes, restate `payers` as well: one payer scales to the new total unambiguously, several do not. Rescaling the old division to a new total would have to guess, and the guess is somebody's money. On a TRANSFER, `receiver_member_id` retargets who received the money, and `splits` and `equal_split` are rejected, because a transfer is not divided at all; on an expense or an income it is `receiver_member_id` that is rejected. Passing an argument that means nothing for the transaction's type is rejected rather than ignored, so a refusal here means the edit did not half-happen. A member whose seat has since been deactivated can still be named on a transaction they were already part of — correcting last year's dinner does not require re-activating everybody who was at it. Adding a deactivated member who was NOT already on the transaction is refused. A transaction's KIND cannot be changed — an expense cannot become an income or a transfer — and a transaction cannot be moved to another group. For either, delete it and create it again with the right tool instead. HOW THE MONEY IS DIVIDED `splits` says who the money was FOR: - omit `splits` entirely -> split equally among ALL active members of the group - [{member_id}, {member_id}] -> split equally among just those people - [{member_id, share: 2}, {member_id, share: 1}] -> weighted, so the first person carries a double portion - [{member_id, amount: 300}, {member_id, amount: 900}] -> exact figures; then EVERY entry needs an amount and they must add up to `amount` Mixing `share` and `amount` in one call is rejected rather than guessed at. `payers` says who PUT THE MONEY IN: - omit `payers` -> the caller (the member with is_caller=true) paid all of it - [{member_id}] -> that one member paid all of it - [{member_id, amount}, ...] -> several payers; every one needs an amount and they must add up to `amount` Every figure is POSITIVE. The direction of the money comes from which tool you call, never from a minus sign. WHEN YOU REPORT THE RESULT, give the user the reply's `links` — every non-null one, labelled by channel — so they can open the transaction and check it.