# Change Discovery

The [Change Discovery API](https://iiif.io/api/discovery/) lets a repository
publish a stream of what changed — created, updated, and deleted resources — as a
W3C Activity Streams `OrderedCollection`. iiisight consumes that stream so a
harvester can find changed resources and re-fetch them.

Activities are ordered oldest → newest across the (usually paged) collection.
iiisight walks the pages for you.

## Iterating activities

`iter_activities` yields {class}`~iiisight.Activity` objects across all pages. By
default it walks **newest-first** (from `last` backwards) — the common "what
changed recently" case:

::::{tab-set}
:::{tab-item} Async
```python
async with iiisight.AsyncClient() as client:
    async for activity in client.iter_activities("https://example.org/activity/all-changes"):
        print(activity.end_time, activity.type, activity.object.id)
        if activity.type != "Delete":
            doc = await client.resolve(activity.reference)   # re-fetch the changed resource
```
:::
:::{tab-item} Sync
```python
with iiisight.Client() as client:
    for activity in client.iter_activities("https://example.org/activity/all-changes"):
        print(activity.end_time, activity.type, activity.object.id)
        if activity.type != "Delete":
            doc = client.resolve(activity.reference)
```
:::
::::

Each {class}`~iiisight.Activity` has a `type` (`Create` / `Update` / `Delete` /
`Move` / `Add` / `Remove` / `Refresh`), an `object` (a {class}`~iiisight.Reference`
to the changed resource), an `end_time`, and an optional `actor`. Its
`.reference` plugs straight into `client.resolve(...)`.

## Incremental harvesting with `since`

Pass `since` (an `endTime` string) to process only newer activities — and, walking
newest-first, iteration **stops** as soon as it reaches activities at or before
`since`, so you never page further back than you need:

```python
async for activity in client.iter_activities(url, since="2024-01-01T00:00:00Z"):
    ...
```

For a full oldest-first sync, pass `newest_first=False` (walks from `first`
forwards via `next`).

```{note}
`since` is compared against `endTime` as a string, so timestamps should be
ISO 8601 in a consistent form (UTC `Z`), which is what Change Discovery uses.
```

## Fetching the collection directly

```python
collection = await client.fetch_changes(url)   # a ChangeCollection
collection.total_items
collection.first, collection.last               # page URLs
```

## From the command line

```console
$ iiisight changes https://example.org/activity/all-changes --limit 20
2024-03-01T09:00:00Z      Update    https://example.org/iiif/book1/manifest
2024-02-28T12:30:00Z      Create    https://example.org/iiif/book2/manifest
...
```

`--since <endTime>` limits to newer activities; `--limit N` stops after N.