feat(client): return created events from insert_event(s)

[TimeToBuildBob]

Summary

• insert_event() now returns Optional[Event] (was None)
• insert_events() now returns Optional[List[Event]] (was None)
• The server already returns created events with assigned IDs in the response body, but the client was discarding them

This is backward-compatible — callers that ignore the return value still work fine. The main use case is getting server-assigned event IDs for later update/delete operations.

Fixes #77.

Test plan

• Verify existing tests pass
• Test that returned events have server-assigned IDs

---

Important

insert_event and insert_events in aw_client/client.py now return created events, allowing retrieval of server-assigned IDs.

• Behavior:
  • insert_event() now returns Optional[Event] instead of None.
  • insert_events() now returns Optional[List[Event]] instead of None.
  • Allows retrieval of server-assigned event IDs for further operations.
• Compatibility:
  • Backward-compatible with existing code that ignores return values.

^{This description was created by for 0513857. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 0513857 in 6 seconds. Click for details.

• Reviewed 30 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 0 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

Workflow ID: wflow_naKw15lRQ5iOgqaO

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[greptile-apps]

Greptile Summary

Modified insert_event() and insert_events() to return the created events with server-assigned IDs instead of discarding them.

Key changes:

• insert_event() now returns Optional[Event] containing the created event with its server-assigned ID
• insert_events() now returns Optional[List[Event]] containing all created events with their IDs
• Both methods capture and parse the server response which already included this data
• Fully backward-compatible — existing code that ignores return values continues to work
• Enables callers to retrieve event IDs for subsequent update/delete operations

The implementation follows existing code patterns in the codebase and maintains consistency with error handling approaches used in other methods.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are minimal, well-scoped, and fully backward-compatible. The implementation follows existing patterns in the codebase, adds useful functionality by exposing data the server already provides, and doesn't introduce any breaking changes or side effects
• No files require special attention

Important Files Changed

Filename	Overview
aw_client/client.py	Added return values to insert_event() and insert_events() to expose server-assigned event IDs; changes are backward-compatible and follow existing code patterns

_{Last reviewed commit: 0513857}

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[ErikBjare]

Hmm, please inspect the log/blame here. I think we removed the "return event" since in the aw-server-rust implementation events are received and their IDs are difficult to predict in time. Something like it gets sent to a queue or something, lacking an efficient way to return the event with set ID. (iirc)

[TimeToBuildBob]

Investigated the git log/blame as requested. Here's what I found:

Timeline:

1. June 2017 (commit 4e5d69f): Erik originally made insert_event return an Event — single event dict POST, parsed response back to Event
2. Feb 2021 (commit 6521df6): Johan fixed aw-server-rust compatibility by wrapping event in a list (data = [event.to_json_dict()]) and parsing response.json()[0]
3. March 2021 (commit e427a4d → 669c574, PR api: Make insert_event not return anything anymore #55): Johan removed the return value entirely, with rationale: "This feature has not been used since our very old replace_last code before heartbeats were a thing."

Key finding: The removal was not due to aw-server-rust's queue architecture making IDs unpredictable. The aw-server-rust worker queue is synchronous (mpsc_requests with receiver.collect() blocking until response) and has always returned events with SQLite-assigned IDs. The actual issue was a broken list-wrapping fix that Johan chose to remove rather than fix.

Server-side behavior today:

• aw-server-rust: Returns [{"id": 1, ...}] (list of events with IDs) — works correctly with this PR
• aw-server (Python): After PR chore: Export intended public imports #76, returns either a single event dict (not a list) for single inserts or null for bulk — response.json()[0] would fail against it (indexing into a dict, not a list)

Options:

1. Target aw-server-rust only (recommended default) — PR works as-is
2. Handle both formats — detect if response is list vs dict and adapt
3. Close — if the return value truly isn't needed by any consumers

Given that aw-server-rust is the recommended server and the Python server's response format is inconsistent anyway, option 1 seems most pragmatic. But if you'd prefer I close this, happy to do so.

[ErikBjare]

Then I think we should fix the Python server's inconsistent response format in a separate PR so that we actually target both once everything lands.

The actual issue was a broken list-wrapping fix that Johan chose to remove rather than fix.

I guess fix it now?

[TimeToBuildBob]

Submitted ActivityWatch/aw-server#158 to fix the Python server's response format — POST /events now always returns a list of events (matching aw-server-rust). Once that lands, this PR should work against both server implementations.

[ErikBjare]

See the discussion about insert_event vs insert_events (one returns ID, the other does not): ActivityWatch/aw-server#158