uptimer-python-sdk 1.7.0__tar.gz → 1.8.0__tar.gz

uptimer_python_sdk-1.8.0/.cursor/rules/sdk-docs-implemented-only.mdc

@@ -0,0 +1,47 @@
+---
+description: SDK docs describe only what this package implements — no gaps, no roadmap, no release process
+alwaysApply: true
+---
+
+# SDK docs describe only what this package implements
+
+Applies to everything a user of the published package reads: `README.md` (which
+is also the PyPI long description), docstrings under `src/`, and `examples/`.
+
+## The rule
+
+**Document only capabilities present in this package version.** That is all.
+
+A README is a contract for the package somebody just installed, not a status
+board for the work around it.
+
+## Do not write
+
+- "this SDK does not wrap those routes **yet**", "not implemented", "missing",
+  "unsupported" — anything that describes an absence;
+- "not in the published package", "until X is on PyPI", "use a checkout of this
+  repository" — release sequencing and workarounds;
+- ticket or issue numbers, internal milestones, or which release something is
+  planned for;
+- TODOs or roadmap notes in public docstrings.
+
+## Do instead
+
+- **Omit it.** A capability this package does not have simply does not appear.
+  The reader loses nothing: they cannot call it either way.
+- Where the HTTP API has something the package does not, the
+  [REST documentation](https://uptimer.myuptime.info/latest/reference/rest-api/)
+  covers it. Link that for the full reference when it helps — without saying
+  what is missing here.
+- State the **server** a capability needs when it is not the package minimum
+  ("needs an Uptimer 1.7.0+ server"). That is a fact about an implemented
+  feature, not a gap.
+- When something ships, add it to the docs in the same change that adds the
+  code.
+
+## Why
+
+Users read this to decide what to call. "We have not wrapped that yet" answers a
+question nobody asked and dates the moment it is written; a checkout instruction
+sends somebody around a problem that a later release quietly removed. Both have
+happened here.

uptimer_python_sdk-1.8.0/AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md — uptimer-python-sdk
+
+The public Python client for Uptimer. Fleet-wide rules apply (see the workspace
+`AGENTS.md`): trunk-based on `main`, no agent attribution, Commitizen subjects.
+
+## Documentation policy
+
+**SDK docs describe only what this package implements.** That is all.
+
+`README.md` (the PyPI long description), the docstrings under `src/`, and
+`examples/` document capabilities present in **this package version**. No "not
+wrapped yet", no checkout workarounds, no ticket numbers, no release
+sequencing. A capability this package does not have is **omitted** — the
+[REST documentation](https://uptimer.myuptime.info/latest/reference/rest-api/)
+covers the HTTP API in full, and may be linked for that.
+
+The same rule, in the form Cursor reads:
+[`.cursor/rules/sdk-docs-implemented-only.mdc`](.cursor/rules/sdk-docs-implemented-only.mdc).
+
+## Working here
+
+```sh
+task cq        # lint + type-check + tests (ruff, mypy, pytest)
+task test      # pytest alone
+task build     # sdist + wheel into dist/
+```
+
+- The package version tracks the Uptimer release it targets: 1.8.x speaks to
+  Uptimer 1.8.0 and later. `uptimer.__version__` is where the compatibility
+  minimum comes from, and `cz` bumps it with `pyproject.toml`.
+- **Never publish a prerelease** (rc/a/b/dev) to TestPyPI or PyPI. This package
+  ships final `X.Y.Z` only; publishing is an operator action.

{uptimer_python_sdk-1.7.0 → uptimer_python_sdk-1.8.0}/CHANGELOG.md

@@ -1,3 +1,53 @@
+## 1.8.0 (2026-09-19)
+
+Targets Uptimer **1.8.0** and later.
+
+### Feat
+
+- **notifications**: `client.v2.notifications.destinations` — list, create, get,
+  update, delete, plus `set_enabled`, `make_default` and `send_test`. A
+  destination is one place a workspace's alerts can go: a Slack incoming
+  webhook, or any HTTP endpoint.
+- **notifications**: `client.v2.notifications.transformations` — list, create,
+  get, update, delete, plus `samples` (the field vocabulary a template may
+  read) and `preview` (the same judgement a save makes, storing nothing). A
+  template is stored only once it renders all three messages.
+- **notifications**: `client.v2.notifications.deliveries.all(...)` — the
+  delivery log, filtered by destination and by undelivered. Records are kept 30
+  days.
+- **delivery**: `client.v2.subjects(slug).delivery` and
+  `client.v2.monitoring.websites(id).delivery` — `get`, `replace` and `clear`
+  for which destinations one subject tells, and about what. The table is the
+  resource: a save replaces it rather than merging.
+- **signals**: `client.v2.subjects(slug).signals` — list, create, get, update
+  and delete. Reporting observations to an existing signal is unchanged.
+- **rules**: `client.v2.subjects(slug).rules` — list, create, get, update and
+  delete, with typed policy models (`RuleDocument`, `RuleInput`,
+  `RuleDecision`, `RuleWait`). A rule input citing another rule is `from_rule`
+  in Python, because `from` is a keyword.
+
+### Fix
+
+- **subjects**: a `workspace_id` given to `client.v2.subjects(slug, ws)` now
+  reaches the signal, rule and observation routes under it. Without it, a
+  caller holding the same subject slug in two workspaces was answered
+  `Ambiguous subject` by the server — by the one call that could have
+  disambiguated.
+- **compat**: `uptimer.__version__` is bumped with the package, so the minimum
+  server version it derives is the version this package targets. It had
+  drifted: 1.7.0 moved `pyproject.toml` alone, and the published client went on
+  accepting a 1.6.0 server.
+
+### Docs
+
+- The README documents only what this package implements, with runnable
+  examples for destinations, transformations, subject delivery, the delivery
+  log, signals and rules. The complete HTTP API — including anything not
+  wrapped here — is at
+  <https://uptimer.myuptime.info/latest/reference/rest-api/>.
+- That policy is now written down for contributors and agents in `AGENTS.md`
+  and `.cursor/rules/sdk-docs-implemented-only.mdc`.
+
 ## 1.7.0 (2026-09-14)
 
 ### Feat

{uptimer_python_sdk-1.7.0 → uptimer_python_sdk-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uptimer-python-sdk
-Version: 1.7.0
+Version: 1.8.0
 Summary: A Python SDK for hosted and self-hosted Uptimer
 Project-URL: Homepage, https://myuptime.info
 Project-URL: Documentation, https://uptimer.myuptime.info/latest/reference/python-sdk/
@@ -41,6 +41,17 @@ or
 uv add uptimer-python-sdk
 ```
 
+**This package targets Uptimer 1.8.0 and later.** The SDK's major.minor tracks
+the server release it speaks to, so install the one that matches yours; patch
+numbers move independently. `client.ensure_compatible()` checks it for you and
+fails with a message that names the fix.
+
+Still on API v1? Pin `uptimer-python-sdk<1`. The server's v1 is unchanged and
+supported, so 0.4.x keeps working — it just cannot use anything newer.
+
+The complete REST API reference is at
+[uptimer.myuptime.info](https://uptimer.myuptime.info/latest/reference/rest-api/).
+
 ## Usage
 
 ### Create client
@@ -208,9 +219,97 @@ locations, so it has its own call — `client.v2.monitoring.websites.create` —
 and asking for `subject_kind="website"` on this route is refused with a message
 saying so.
 
-**Signals and rules are added in the Uptimer UI.** Uptimer 1.6.0 also serves
-them over the API, under `/v2/subjects/{subject}/signals` and
-`/v2/subjects/{subject}/rules`; this SDK does not wrap those routes yet.
+### Signals: what reports to a subject
+
+A **signal** is one thing that reports. A **heartbeat** is expected to keep
+reporting, so its silence is itself a symptom; an **event** reports only when
+there is something to say, so its silence means nothing. The kind is fixed when
+the signal is created — senders are already posting to it, and changing what
+their silence means underneath them is not a rename.
+
+```python
+from uptimer.models.v2 import (
+    SIGNAL_KIND_HEARTBEAT,
+    CreateSignalRequest,
+    UpdateSignalRequest,
+)
+
+signals = client.v2.subjects("nightly-export", "your-workspace-id").signals
+
+signal = signals.create(
+    CreateSignalRequest(
+        name="Worker pulse",
+        kind=SIGNAL_KIND_HEARTBEAT,
+        meta={"team": "payments"},          # stored and returned untouched
+    ),
+)
+
+# `id` is the slug a sender posts to. A rename never moves it.
+signals.update(signal.id, UpdateSignalRequest(name="Worker heartbeat", meta={}))
+
+for existing in signals.all():
+    print(existing.id, existing.signal_kind)
+
+# Deleting a signal deletes its observations. One a rule reads is refused:
+# retarget or remove those rules first.
+signals.delete(signal.id)
+```
+
+### Rules: what counts as a problem
+
+A **rule** reads a subject's signals — or another of its rules — and decides
+whether there is a problem. The policy is a document: what it reads, what those
+inputs have to agree on, and how long a state must hold.
+
+```python
+from uptimer.models.v2 import (
+    INPUT_MODE_LATEST_VALUE,
+    INPUT_MODE_STATUS,
+    NEED_ANY,
+    CreateRuleRequest,
+    RuleDecision,
+    RuleDocument,
+    RuleInput,
+    RuleWait,
+    UpdateRuleRequest,
+)
+
+rules = client.v2.subjects("nightly-export", "your-workspace-id").rules
+
+rule = rules.create(
+    CreateRuleRequest(
+        name="Export health",
+        document=RuleDocument(
+            inputs=[
+                # The heartbeat stopped, or its last observation said "problem".
+                RuleInput(signal="worker-pulse", mode=INPUT_MODE_STATUS,
+                          no_data_after="5m"),
+                # A number out of range.
+                RuleInput(signal="queue-depth", mode=INPUT_MODE_LATEST_VALUE,
+                          compare=">", threshold=1000),
+                # Another rule's verdict. `from` is a Python keyword, so it is
+                # `from_rule` here and `from` on the wire.
+                RuleInput(from_rule="queue-health"),
+            ],
+            decision=RuleDecision(need=NEED_ANY),
+            wait=RuleWait(confirm_after="2m", close_after="2m"),
+        ),
+    ),
+)
+
+# The policy is a REPLACEMENT, not a patch: read it, change it, send the whole
+# thing back. A CHANGED policy increments policy_version; sending the same
+# document back leaves it where it was. Either way the rule keeps its slug, so
+# the incidents already pointing at it stay attached.
+rule.document.wait.confirm_after = "5m"
+rules.update(rule.id, UpdateRuleRequest(name=rule.name, document=rule.document))
+
+rules.delete(rule.id)
+```
+
+Durations are strings — `"5m"`, `"2m0s"` — so a stored policy reads the way you
+would write it. Every input must cite a signal or a rule **of this subject**: a
+subject is the boundary, so add the signals first.
 
 ### Reporting your own observations
 
@@ -281,12 +380,8 @@ under its subject on v2. Neither method falls back to the other, and there is no
 kind-agnostic one: acknowledging is a claim about a specific incident, and an
 SDK that guessed which family it belonged to could claim the wrong one.
 
-**Availability.** These methods are part of the SDK's **1.7.0** release: they are
-not in the published 1.6.0 package, so until 1.7.0 is on PyPI use them from a
-checkout of this repository. They need a matching **Uptimer 1.7.0+** server —
-the routes do not exist before that — and on
-[myuptime.info](https://myuptime.info) they arrive when the hosted service picks
-up the 1.7.0 API.
+**Availability.** These methods need an **Uptimer 1.7.0+** server — the routes
+do not exist before that.
 
 **Custom monitoring** — list the subject's open incidents, pick one, acknowledge
 it by id:
@@ -403,6 +498,201 @@ out — and `muted` says what waits, in the server's own words.
 A past end time, a window already running, a website subject, or a caller who is
 not an editor raise `DefaultUptimerApiError`. Reading takes the viewer role.
 
+### Alert destinations
+
+A **destination** is one place a workspace's alerts can go: a Slack incoming
+webhook, or any HTTP endpoint that accepts a POST. A workspace has as many as it
+needs, and each subject chooses which of them it tells.
+
+Reading a destination takes the **editor** role, not just membership: a
+destination holds a webhook URL, and a URL is enough for anyone holding it to
+post into your channel.
+
+```python
+from uptimer.models.v2 import (
+    DESTINATION_TYPE_SLACK,
+    DESTINATION_TYPE_WEBHOOK,
+    CreateDestinationRequest,
+    UpdateDestinationRequest,
+)
+
+destinations = client.v2.notifications.destinations
+
+# The FIRST destination in a workspace becomes its default, asked for or not:
+# a workspace whose only destination is not the default notifies nobody.
+slack = destinations.create(
+    CreateDestinationRequest(
+        name="Acme · #incidents",
+        url="https://hooks.slack.com/services/T00/B00/xxxx",
+        destination_type=DESTINATION_TYPE_SLACK,
+        channel="#incidents",          # stored without the '#'
+    ),
+    workspace_id="your-workspace-id",
+)
+
+relay = destinations.create(
+    CreateDestinationRequest(
+        name="Pager relay",
+        url="https://hooks.example.com/uptimer",
+        destination_type=DESTINATION_TYPE_WEBHOOK,
+    ),
+    workspace_id="your-workspace-id",
+)
+
+# Move the address, or attach a payload template (see below). The TYPE is fixed
+# at creation: delete and recreate to change it.
+destinations.update(
+    relay.id,
+    UpdateDestinationRequest(name=relay.name, url="https://hooks.example.com/v2"),
+    workspace_id="your-workspace-id",
+)
+
+destinations.set_enabled(relay.id, enabled=False, workspace_id="your-workspace-id")
+destinations.make_default(slack.id, workspace_id="your-workspace-id")
+
+# A REAL send: same render, same transport, same delivery record as an alert.
+# A destination that refuses it raises, with the far end's own words.
+destinations.send_test(slack.id, workspace_id="your-workspace-id")
+
+# Deleting the default promotes nobody — check what you did.
+answer = destinations.delete(relay.id, workspace_id="your-workspace-id")
+assert answer.was_default is False
+```
+
+`workspace_id` is optional everywhere here. It settles an ambiguity rather than
+being required: these resources have no slug of their own, so the server
+searches your memberships when it is absent and says so if the answer is more
+than one.
+
+### Transformations: the shape a destination receives
+
+A **transformation** is a named template for the body a destination gets — a
+PagerDuty event, your own JSON, a line of text. A destination with none gets
+Uptimer's built-in Slack-shaped message, which is what `transformation_id=None`
+means.
+
+```python
+from uptimer.models.v2 import (
+    CreateTransformationRequest,
+    UpdateDestinationRequest,
+)
+
+transformations = client.v2.notifications.transformations
+
+# The vocabulary: three sample messages, each with every field a template may
+# read. No workspace — these are the product's own fixtures.
+for sample in transformations.samples():
+    print(sample.label, sorted(sample.fields))
+
+# Ask before you write. `passed` is exactly the condition a save enforces.
+preview = transformations.preview(
+    '{"event": "{{ kind }}", "summary": "{{ summary }}"}',
+    workspace_id="your-workspace-id",
+)
+assert preview.passed
+for result in preview.results:
+    print(result.label, result.ok, result.output or result.error)
+
+template = transformations.create(
+    CreateTransformationRequest(
+        name="PagerDuty compact",
+        template='{"event": "{{ kind }}", "summary": "{{ summary }}"}',
+    ),
+    workspace_id="your-workspace-id",
+)
+assert template.content_type == "application/json"
+
+# Attach it. Passing transformation_id=None puts the destination back on
+# Uptimer's own message.
+client.v2.notifications.destinations.update(
+    slack.id,
+    UpdateDestinationRequest(
+        name=slack.name,
+        url=slack.url,
+        channel=slack.channel,
+        transformation_id=template.id,
+    ),
+    workspace_id="your-workspace-id",
+)
+```
+
+**A template is stored only once it renders all three messages.** There is no
+force flag: a template that breaks on one of them raises, naming the sample that
+broke, and a refused edit leaves the stored template exactly as it was. A
+template starting with `{` or `[` is treated as JSON — values are escaped as
+they are substituted and the result has to parse, so a quoted error cannot break
+the document.
+
+### Alert delivery: which destinations a subject tells
+
+The choice lives on the **subject**, not on the workspace: the marketing site
+telling nobody must not stop the payments API paging the on-call.
+
+```python
+from uptimer.models.v2 import (
+    ALERT_KIND_NO_DATA,
+    ALERT_KIND_PROBLEM,
+    ALERT_KIND_RECOVERY,
+    DeliverySelection,
+)
+
+delivery = client.v2.subjects("nightly-export", "your-workspace-id").delivery
+
+table = delivery.get()
+if table.uses_workspace_default:
+    print("this subject falls back to", table.default_destination_id)
+elif table.is_silent:
+    print("nothing is sent for this subject")
+
+# The body is the WHOLE table: what you send is what the subject will have.
+delivery.replace(
+    [
+        DeliverySelection(
+            destination_id=slack.id,
+            alert_kinds=[ALERT_KIND_PROBLEM, ALERT_KIND_NO_DATA, ALERT_KIND_RECOVERY],
+        ),
+        DeliverySelection(destination_id=relay.id, alert_kinds=[ALERT_KIND_PROBLEM]),
+    ],
+)
+
+# Back to the workspace default — or to silence, if there is no default.
+delivery.clear()
+```
+
+A reminder about an unanswered problem rides with `problem`: a destination that
+hears about problems hears the four-hourly reminders too, which is why there is
+no fourth alert kind.
+
+A **website monitor** carries the same table on its own collection, because
+`/v2/subjects` serves Custom subjects only:
+
+```python
+client.v2.monitoring.websites("monitor-id").delivery.get()
+```
+
+Saving a table changes delivery **only**. Signals, rules, incidents,
+acknowledgement and maintenance are untouched, and nothing is sent by saving.
+
+### Delivery log: what was actually sent
+
+```python
+records = client.v2.notifications.deliveries.all(
+    workspace_id="your-workspace-id",
+    destination_id=slack.id,        # optional: one destination
+    undelivered=True,               # optional: only what did not arrive
+)
+
+for record in records:
+    print(record.at, record.destination_name, record.status)
+    if not record.delivered:
+        print("  refused:", record.error)
+```
+
+It is a read — nothing here sends or resends, and there is no retry. Each record
+keeps the destination's **name and type as they were at the attempt**, so a
+rename or a delete later leaves the row still saying where the message went; the
+webhook URL is never recorded. Records are kept **30 days**.
+
 ### Incident status
 
 `client.v2.incidents.all()` returns only **open** incidents. `status` carries the