Metadata-Version: 2.5
Name: pybabytracker
Version: 0.5.0
Summary: Async Python client for the Nighp Baby Tracker sync service
Project-URL: Source, https://github.com/wtadler/pybabytracker
Project-URL: Issues, https://github.com/wtadler/pybabytracker/issues
Author: Will Adler
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://github.com/wtadler/pybabytracker/raw/main/docs/icon.png" alt="Baby Tracker icon" width="128">
</p>

# pybabytracker

Async Python client for the sync service of
[Baby Tracker](https://apps.apple.com/us/app/baby-tracker-newborn-log/id779656557), the app by
[Nighp](https://nighp.com), built for the
[Baby Tracker (Nighp) for Home Assistant](https://github.com/wtadler/ha-baby-tracker)
integration. It is unofficial and identifies itself as `pybabytracker/<version>`.

## Use

```python
import aiohttp
from pybabytracker import DIAPER_WET, BabyTrackerClient, SyncEngine

async with aiohttp.ClientSession() as session:
    client = BabyTrackerClient(
        "parent@example.com", "password", "STABLE-DEVICE-UUID", "Home Assistant", session=session
    )
    engine = SyncEngine(device_uuid="STABLE-DEVICE-UUID")  # or SyncEngine.from_dict(saved_state)
    result = await engine.sync(client)  # the first also reads the seed; then only what's new
    diaper = await engine.add_diaper(client, baby_id, DIAPER_WET)  # posts as this device
    await engine.delete_record(client, diaper.object_id)  # only records this device created
    saved_state = engine.to_dict()  # JSON-safe: save it after writes, and after a sync with
    # result.transactions_applied or result.seed_read
```

- Pass your own `aiohttp.ClientSession` (the client never closes it), and make it dedicated to
  this client: the service authenticates by cookie, so two accounts must not share a session (in
  Home Assistant, use `async_create_clientsession`). Without one, the client makes its own and
  closes it in `close()`.
- `AuthenticationError` means the credentials were rejected. `BabyTrackerConnectionError` means
  the service was unreachable or answered with a server error. A 401 mid-session triggers one
  sign-in and a retry before it becomes an `AuthenticationError`.
- `AccountChangedError` means a sign-in opened a different sync group (`AccountID`) from the one
  the engine's state came from: the group was reset in the app. The engine saves the first
  `AccountID` it sees and refuses to sync or write after it changes, as the app does; the client
  also refuses a sign-in to a different group from its own earlier one. Join the new group with a
  new `BabyTrackerClient` and a new engine (the aiohttp session can be reused). State saved before
  this version adopts the first `AccountID` it sees, so a reset that happened before upgrading
  isn't detected.
- Records are typed (`Diaper`, `Sleep`, `Nursing`, and so on). A record type the library
  doesn't know stays raw as an `UnknownRecord` (a debug line is logged once per type).
  `Medication` is a medicine dose with the medicine embedded, and `NursingSession`, the Android
  app's timed nursing, is a `Nursing`. The Android app sends codes such as a diaper's `status` as
  strings of digits and `englishMeasure` as a JSON boolean; `numeric_code()` reads either form,
  and volumes read both. Decoding then encoding any
  payload returns the same JSON, including keys the library doesn't model.

## Writes

The engine posts as its own device (`device_uuid`, which must match the client's):

- A write needs a completed sync first (`NotSyncedError` otherwise), because the payload embeds
  the baby record as known from sync (`UnknownBabyError` for a baby it hasn't seen).
- Numbers are at-most-once. The next number is one more than the highest of this device's
  `LastSyncID` on the server, its own log already applied, and its last confirmed post. Before
  choosing, the engine applies any of its own log it hasn't seen (another process using the same
  device ID).
- When a post fails, the engine reads its own log at that number. If the same transaction is
  there, the write succeeded. Otherwise the error is raised and the post stays pending; the next
  write settles it first. After a definite HTTP error, a number nothing holds is reused. After
  no answer at all (`NoResponseError`: a timeout or dropped connection), the post may still
  land, so the number is reused only once `unknown_outcome_grace` seconds (default 90) have
  passed with nothing under it; until then a write raises `WriteOutcomeUnknownError` without
  posting. A 401 signs in again and resends the same number. Nothing is resent blindly.
- To retry an add safely, pass the same `object_id` again: if the earlier attempt landed after
  all, its record is returned instead of a second copy being posted.
- If this device's own log is shorter than its `LastSyncID`, a write is refused
  (`ProtocolError`) rather than skipping the missing entries.
- A confirmed write is applied locally at once, so the next sync doesn't fetch it back.
- Writes and syncs share a lock, so concurrent writes get consecutive numbers.
- `delete_record` only deletes records this device added (`NotOwnRecordError`), and raises
  `RecordNotFoundError` if one is already deleted. Like the app, the delete sends the record as
  last saved with only `newFlage` set to `"false"`; its timestamp is not bumped.
- Save `to_dict()` after every write, including one that raised: a pending post lives only in
  that state. Use one device ID per running process; two processes writing as one device can
  collide on a number while `LastSyncID` lags.

### Record types you can add

Every add shares the rules above (numbering, pending posts, `object_id` retries, local apply),
and bad input raises `ValueError` before any request. Payloads match the iPad capture key for
key.

| Method | Writes | Notes |
|---|---|---|
| `add_diaper(client, baby_id, status, ...)` | `Diaper` | `DIAPER_WET`, `DIAPER_DIRTY`, `DIAPER_MIXED` |
| `add_formula(client, baby_id, volume=, ...)` | `Formula` | volume more than zero |
| `add_pumped(client, baby_id, volume=, ...)` | `Pumped` | a bottle of pumped milk |
| `add_nursing(client, baby_id, left_minutes=, right_minutes=, ...)` | `Nursing` | a finished session |
| `add_sleep(client, baby_id, start=, end=, ...)` | `Sleep` | a finished sleep |
| `add_pump(client, amount=, ...)` or `add_pump(client, left_volume=, right_volume=, ...)` | `Pump` | a pumping session; belongs to the account, so no `baby_id` |
| `add_milestone(client, baby_id, milestone, ...)` | `Milestone` | `milestone` is a name or ID from `milestone_choices(baby_id)` |
| `add_vaccine(client, baby_id, vaccine, ...)` | `Vaccine` | `vaccine` is a name or ID from `vaccine_choices()` |
| `add_medication(client, baby_id, medicine, amount=None, ...)` | `Medication` | a dose; `medicine` is a name or ID from `medicine_choices()`, `amount` defaults to its usual dose |
| `add_activity(client, baby_id, activity, duration=0, ...)` | `OtherActivity` | tummy time, a bath, and so on; `activity` is a name or ID from `activity_choices()` |

- A milestone names one from the app's pick list: one of the 20 it ships with
  (`BUILT_IN_MILESTONES`, under the app's own `EasyLogSeed` IDs, which never sync) or one added
  in the app and known from sync. `milestone_choices(baby_id)` lists them and `find_milestone`
  resolves a name (ignoring case) or ID. An unknown one raises `UnknownMilestoneError`, an empty
  or non-text one `InvalidSelectionNameError` (a `ValueError`), and a name that matches two
  entries `AmbiguousSelectionError` naming their IDs, so pass the ID; all before any request. The three unknown-entry errors share the base
  `UnknownSelectionError` (with `.what`), and a dose with no `amount` for a medicine that has no
  usual dose raises `NoUsualDoseError`.
  A milestone added for one baby is left out for the others. Adding a new milestone to the pick
  list isn't supported yet. Vaccines work the same way: the app's 10 built-ins
  (`BUILT_IN_VACCINES`) plus synced ones, `vaccine_choices()`, `find_vaccine`, and
  `UnknownVaccineError`. A medicine has no built-ins: `medicine_choices()` lists the ones doses
  already carry, and a `Medication` is logged against one by name or ID. Activity types work
  like vaccines: the app's 5 built-ins (`BUILT_IN_ACTIVITIES`: Crawling, Cruising, Tummy Time, TV
  Time, Story Time) plus ones added in the app, `activity_choices()`, `find_activity`, and
  `UnknownActivityError`. The app has no bath screen: a bath is an activity of a type added in
  the app, such as "Bath". An activity's `duration` is whole minutes, 0 when not timed.
- Where several records carry a copy of one entry, a synced copy wins, then the copy in the
  newest record (by its `timestamp`, then its `time`), so a dose's default amount is the usual
  dose of the newest dose. A medicine without a usual dose that is a number above zero needs an
  `amount`. Doses are rounded to 2 decimals, like volumes, in the medicine's own unit.
- How well this is checked: a built-in milestone ("Back home") and vaccine ("HepB") and a
  medicine dose were posted on iOS and read back unchanged, and the app showed each as the entry
  it is. The other built-in IDs, Android, and a custom milestone or vaccine are unverified. A
  pick-list entry syncing as its own transaction (`MilestoneSelection`,
  `VaccineSelection`, `MedicationSelection`) is an expected shape, not yet seen in synced data.
  A medicine's `interval` is in minutes.
- Volumes are `Volume(value, "oz")` or `Volume(value, "ml")`, written as a `VolumeMeasure` with
  `englishMeasure` `"true"` (ounces) or `"false"` (milliliters), rounded to 2 decimals (an integer
  when whole). The number is written as given, with no conversion, as the app does.
- `time` is when the activity started (or, for a bottle or diaper, when it happened), written in
  UTC. `timezone_offset` (seconds east of UTC) defaults to the offset of the time given. The app itself writes the zone's *standard* offset
  all year, ignoring daylight saving, so to match it pass
  `timezone_offset=standard_offset_seconds(tz, time)`: New York is -18000 in July and January.
- Nursing: `time` is the session's start, as in the capture. Give `start_time`, or `end_time`
  (start is end minus the total minutes), or neither (the session just ended). `finish_side` is
  `SIDE_LEFT` (1), `SIDE_RIGHT` (2), or `SIDE_NONE` (0), the app's numbering. The app shows the
  field as the side a session started on. It defaults to the only side used, or `SIDE_NONE` when
  both were, since the totals can't tell which came first (the app also saves most two-sided
  pumps with `SIDE_NONE`), so pass `finish_side` yourself when you know it. A `NursingTimer`
  knows: its `start_side` is the side it started on.
- Sleep: `time` is `start`. `duration` is whole minutes: the length rounded half up (the capture
  stored about 30 seconds as 1), and at least 1, because a duration of 0 means a sleep in
  progress. `end` must be after `start`, and a sleep can't be longer than 24 hours.
- Nursing and pump minutes are whole numbers, at most 240 per side (a guard against seconds
  passed as minutes).
- Pump: a pump belongs to the account, not a baby, so it takes no `baby_id` and its payload has
  no `baby` key, like the app's. Give the total as `amount`, or the side volumes (not both):
  with only `amount` the payload has no per-side amounts, and with sides `amount` is their sum,
  a side left out is written as 0 in the other's unit, and both sides must use one unit.
  With no volume at all, minutes are required and the payload carries the durations and an
  `amount` of 0 in `default_unit` (default `oz`), as the app writes a timed pump with no volume.
  `sides` is written as 0, as captured. Babies are never derived from pumps, and a pump that
  carries a `baby` still decodes (kept raw, not read). `engine.latest_pump()` is the newest pump
  on the account; `latest_records(baby_id)` never includes pumps.

### Sleep timers

The app syncs a running sleep: an add with `duration` 0 at the start, then an update (opcode 1)
to the same record at the stop. Nursing timers stay on the phone until they stop, so a timed
nursing session is written once, finished, with `add_nursing`.

| Method | Writes | Notes |
|---|---|---|
| `start_sleep(client, baby_id, start=None, ...)` | `Sleep` (add) | `duration` 0; `start` defaults to now, no more than a minute ahead or 24 hours back |
| `end_sleep(client, object_id, end=None)` | `Sleep` (update) | ends a running sleep, whichever device started it |

- `end_sleep` sends the record as last saved, changing only `duration` (rounded like
  `add_sleep`), `newFlage` (`"false"`), and `timestamp` (the write time, or one second past the
  stored one when that's ahead of this clock, so the end wins the merge). Key order and unknown
  keys are kept.
- A sleep longer than 24 hours at the stop is **clamped to 1,440 minutes** with a warning, not
  refused, so a forgotten timer can always be stopped. An `end` more than a minute in the future
  is clamped to now, and an end at or up to a minute before the start (a clock running a little
  fast) is written as 1 minute.
- Refused before any request: a record never seen or deleted (`RecordNotFoundError`), one that
  isn't a sleep (`WrongRecordTypeError`), or a sleep another device finished
  (`TimerNotRunningError`). A sleep this device already ended (its end is in this device's log,
  even if a phone edited it since) is returned as is, with nothing posted, so retries are safe.
- The end carries the whole record as this device last saw it, so a phone edit that hasn't synced
  yet (a note, say) is overwritten by it, as the app's own edits overwrite each other.
- A phone delete racing an end: the app's delete keeps the record's old timestamp, so an end
  posted after it (with a newer timestamp) outlives it, and the sleep stays here as ended. How the
  app shows that case is still to be checked on a test device.
- An end is an update, not an add: it doesn't make another device's sleep this device's own, so
  `delete_record` still refuses it. Undo of a sleep this device started works running or ended.

The service lists a device only after its first post; on the test account, the dev device
appeared with `LastSyncID` 1 right after its first add, with no confirmation step.

### Nursing and pump timers

Because a nursing timer isn't synced while it runs, a client that offers one keeps its own.
`NursingTimer` is that state as an immutable value: `NursingTimer.start(object_id, "left", now)`,
`timer.switched("right", now)`, and `timer.minutes(now)` for the whole minutes per side to pass to
`add_nursing`. Each side rounds half up; a session under 30 seconds is 1 minute on the side it
ended on; a side past 240 minutes is written as 240 and logged. `to_dict()` and
`NursingTimer.from_dict()` give a form to save between runs, and `PumpTimer` does the same for a
pump (one length for both sides, never under 1 minute).

### Day totals and write validation

`day_totals(records, baby_id, start, end)` counts a baby's diapers (by kind), feeds, and bottle
volume in milliliters from `start` up to `end`. The caller passes the bounds, so a local calendar
day, including a 23- or 25-hour day at a clock change, is local midnight to the next local
midnight. `pybabytracker.validation` has the checks behind a bad request (`check_amount`,
`check_pump_amounts`, `check_minutes`, `check_sleep_range`, `check_end_after_start`,
`check_sleep_start`). Each raises a `ValidationError` subclass (`InvalidAmountError`,
`AmountTooSmallError`, `MinutesTooLongError`, `EndBeforeStartError`, `SleepTooLongError`,
`SleepStartOutOfRangeError`) that carries what was wrong, so a caller can pick its own message.

## Merge rules

Records are keyed by `objectID`. Each stored record carries a version made of the record's
`timestamp`, the device, and the sync number. Within one device's log, later numbers always win.
Across devices the result doesn't depend on which device is fetched first:

- An add or update replaces a stored record if its (timestamp, device, number) is newer.
- A delete removes the record unless the record's timestamp is newer than the delete's, and it
  leaves a tombstone, so a delete that arrives before the add it targets still wins.
- An add or update from another device brings a deleted record back only with a strictly newer
  timestamp than the tombstone. Within one device, a later add always wins.

Tombstones are saved by `to_dict()`. State saved by an older version (1) loads with none.
A payload that can't be decoded at all is skipped with a warning, and the sync moves past it. A
fresh `SyncEngine` replays every log, so it recovers skipped payloads once a fix ships, and it
reads the seed again.

### The seed

The logs don't hold the whole history. The account also has a seed, a full copy of its database
as of some point (`client.get_seed()`, a zip that `read_seed` decodes), and records from devices
that have since left the account are only there. The first sync reads it before the logs, and
state saved before this version reads it on its next sync. Seed records are merged as adds from
no device: a log copy of a record wins unless its timestamp is older, and a delete in a log
removes it. Every log is still read from the start, as the app does after loading a seed.

`SyncResult.seed_read` is true for the sync that read the seed (or learned there is none), so save
the state after it even when no log entry was applied. `SyncEngine.seeded` turns true as soon as
the seed is read, even in a sync that then fails, so a caller can save when it changes. A download
that fails is warned about once and tried again on the next sync, while the logs keep syncing. A
seed that can't be read, or that the client refuses (`DownloadRefusedError`: a redirect, or over
the size cap), is warned about and skipped. Saved state records the seed format it was read at
(`seeded: 1`; `true` from earlier versions counts as 1), and a library with a newer
`SEED_FORMAT` reads the seed again. Text that isn't valid UTF-8 is read with replacement
characters. Pick-list entries in the seed aren't records of their own; the records that use them
carry them, as synced records do.

## Command line

```sh
export BT_EMAIL=... BT_PASSWORD=...   # or put them in .env
python -m pybabytracker                # latest record of each type, per baby
python -m pybabytracker --probe-history

# Writes go to a throwaway test account only (BT_TEST_EMAIL, BT_TEST_PASSWORD):
python -m pybabytracker --write-test-diaper [--status wet|dirty|mixed]
python -m pybabytracker --delete-test-diaper OBJECT_ID
```

The tool signs in as a separate device named "Home Assistant (dev)". Its ID is made once and
kept in `.pybabytracker-device.json` (gitignored). `--probe-history` reads every device's log
from 0 and reports how many transactions come back versus its `LastSyncID`, the lowest and
highest numbers returned, and a verdict (full, paged, paged newest first, starts at K with older
numbers trimmed, duplicates, or gaps), then whether the probe device now appears in the device
list. It only reads. History older than the logs is in the account's seed (see
[The seed](#the-seed)), which the probe doesn't read; the default run reads it, so its latest
records include it.

`--write-test-diaper` adds one diaper for the test account's first baby and reports whether the
dev device is in the device list before and after, with its `LastSyncID`, and whether the next
sync fetched its own log back. `--delete-test-diaper` deletes one the dev device wrote. Both
read only the `BT_TEST_*` credentials, and keep their device ID and engine state in
`.pybabytracker-test-device.json` and `.pybabytracker-test-state.json` (both gitignored).

## Develop

```sh
uv venv --python 3.12 && uv pip install -e ".[dev]"
pytest && mypy && ruff check .
```

## Release

Releases publish to PyPI from a `v<version>` tag such as `v0.2.0` through trusted publishing: there is no API token
anywhere. `.github/workflows/release.yml` runs on that tag and needs the tests to pass, then
builds the sdist and wheel, checks them with `twine check --strict`, installs the wheel in a clean
venv, and publishes from the GitHub environment named `pypi`.

To cut a release:

1. Set `__version__` in `src/pybabytracker/_version.py` (for example `0.2.0`, or `0.2.0rc1` for a
   pre-release) and merge it to `main`.
2. Tag that commit with the same version and push the tag: `git tag v0.2.0 && git push origin v0.2.0`.
   The workflow fails before building if the tag and `_version.py` disagree
   (`python scripts/check_version.py v0.2.0` runs the same check locally).

One-time setup, done on PyPI and in GitHub before the first tag:

1. On PyPI, add a pending publisher at <https://pypi.org/manage/account/publishing/> for
   the project name `pybabytracker`, with owner `wtadler`, repository `pybabytracker`, workflow
   `release.yml`, and environment `pypi`.
2. In the repository settings, create an environment named `pypi`, and under deployment branches
   and tags choose Selected branches and tags with the tag rule `v*`, so only a version tag can
   reach the publish step (a branch could otherwise run the workflow with the publish
   permission). Adding required reviewers there makes each publish wait for an approval.

The first successful publish turns the pending publisher into a normal one.
