imbi-plugin-pagerduty 2.11.0__tar.gz

imbi_plugin_pagerduty-2.11.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

imbi_plugin_pagerduty-2.11.0/.github/workflows/test.yml

@@ -0,0 +1,54 @@
+name: Testing
+on:
+  pull_request:
+  push:
+    branches: [ "main" ]
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
+    tags-ignore: [ "*" ]
+
+jobs:
+  lint:
+    name: "Static Analysis"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Install just
+        uses: extractions/setup-just@v2
+        with:
+          just-version: '1.47.1'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Run linters
+        run: just lint
+
+  test:
+    name: "Automated Tests"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: [ "3.14" ]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Install just
+        uses: extractions/setup-just@v2
+        with:
+          just-version: '1.47.1'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "${{ matrix.python }}"
+          enable-cache: true
+      - name: Test with python ${{ matrix.python }}
+        run: just test
+      - name: Upload Coverage
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./build/coverage.xml
+          flags: unittests

imbi_plugin_pagerduty-2.11.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.ruff_cache/

imbi_plugin_pagerduty-2.11.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v0.7.25
+    hooks:
+      - id: tombi-format
+        # uv owns uv.lock's formatting; tombi reflows it (2- vs 4-space),
+        # producing whole-file churn on every dependency change.
+        exclude: ^uv\.lock$
+
+  - repo: local
+    hooks:
+      - id: basedpyright
+        name: basedpyright
+        language: system
+        types: [python]
+        pass_filenames: false
+        entry: uv
+        args:
+          - run
+          - basedpyright
+          - src

imbi_plugin_pagerduty-2.11.0/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working
+with code in this repository.
+
+## What This Is
+
+PagerDuty plugins for the Imbi platform, distributed as a single Python
+package (`imbi_plugin_pagerduty`). It ships **three plugin types** —
+lifecycle, webhook, incidents — discovered by the Imbi host through the
+`imbi.plugins` entry points in `pyproject.toml`. That entry-point table
+is the registration surface: adding a plugin class means adding an entry
+point there.
+
+All plugin base classes (`LifecyclePlugin`, `WebhookActionPlugin`,
+`IncidentsPlugin`, `PluginContext`, `PluginManifest`, the result /
+writeback types) come from `imbi_common.plugins.base`. Read that module
+(in the sibling `imbi-common` repo) before changing a plugin's method
+signatures.
+
+Unlike the GitHub plugins, **PagerDuty is cloud-only**: a single
+`api.pagerduty.com` host and one REST API key credential, so there is no
+host-flavor base/subclass pattern — one concrete class per plugin type.
+
+## Commands
+
+```bash
+just setup              # uv sync --all-groups --all-extras + pre-commit hooks
+just test               # coverage run -m pytest (fails under 85%)
+just test tests/test_lifecycle.py                  # one file (no coverage)
+just lint               # pre-commit (ruff, ruff-format, tombi, basedpyright)
+just format [FILES]     # ruff-format + tombi-format
+```
+
+Python is pinned to **3.14**; ruff uses single quotes and a 79-char line
+length; type checking is `basedpyright` in **strict** mode over `src`.
+
+## Architecture
+
+- `_client.py` — the shared PagerDuty REST client factory
+  (`api.pagerduty.com`, `Authorization: Token token=<key>`). An httpx
+  response hook maps `401` → `PluginAuthenticationFailed` and `429` →
+  `PluginRateLimited` (absolute resume epoch from `ratelimit-reset`).
+- `_services.py` — resolves a project's PagerDuty service: the
+  `pagerduty-service` link first, then an exact-name lookup on the
+  project slug (and the pre-rename slug).
+- `lifecycle.py` — `PagerDutyLifecyclePlugin`. Manages the service +
+  escalation-policy routing (`team_escalation_policy_mapping`) + a
+  per-service V3 webhook subscription. Writes results through
+  `ctx.service_writeback`: the host persists the `EXISTS_IN` edge
+  (service id + the **encrypted** webhook signing secret the gateway
+  verifies against) and the `pagerduty-service` dashboard link. The
+  subscription's signing secret is returned by PagerDuty **only once**,
+  at creation, and is encrypted (via `imbi_common` `TokenEncryption`)
+  before it leaves the plugin. `on_project_deleted` finds the
+  subscription by listing `/webhook_subscriptions` and matching
+  `filter.id` (no subscription id is persisted).
+- `webhook.py` — `PagerDutyWebhookPlugin`, a v1 stub (`actions() -> []`);
+  incident events are captured by the gateway's built-in recording.
+- `incidents.py` — `PagerDutyIncidentsPlugin.list_incidents`, a paginated
+  live query of `/incidents` for the project's service.
+- `models.py` — maps PagerDuty incident payloads to `IncidentView`.
+
+### PagerDuty-API assumptions to confirm against a live tenant
+
+- The create-subscription response exposes the signing secret at
+  `webhook_subscription.delivery_method.secret`.
+- A service's webhook subscriptions are found by listing
+  `/webhook_subscriptions` and matching `filter.id` (there is no
+  documented server-side service filter).
+- `/incidents` paginates via `offset`/`more`; the opaque tab cursor is
+  the next `offset`.
+
+## Testing
+
+Tests mock PagerDuty's HTTP with **respx** (`asyncio_mode = auto`, so
+async tests need no decorator). Build a `PluginContext` with the
+relevant project links / options and pass `{'api_key': ...}`
+credentials, mirroring how the host calls in. Coverage must stay ≥ 85%.
+
+## Dependency Management
+
+**NEVER edit `pyproject.toml` dependencies by hand** — use `uv add` /
+`uv remove`. The package pins to PyPI with a 7-day `exclude-newer`
+holdback; `imbi-common` is tracked from git `main` until 2.11 ships (see
+the `[tool.uv.sources]` comment), then the pin moves to `==2.11.x`. After
+changing dependencies, run `uv sync` and verify `uv.lock`.

imbi_plugin_pagerduty-2.11.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Imbi
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

imbi_plugin_pagerduty-2.11.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: imbi-plugin-pagerduty
+Version: 2.11.0
+Summary: PagerDuty lifecycle, webhook, and incidents plugins for Imbi
+Author-email: "Gavin M. Roy" <gavinr@aweber.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: imbi-common[databases]==2.11.0
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# imbi-plugin-pagerduty
+
+PagerDuty plugins for the [Imbi](https://github.com/AWeber-Imbi) platform,
+distributed as a single Python package (`imbi_plugin_pagerduty`) shipping
+three plugin types:
+
+- **`pagerduty-lifecycle`** — provisions and maintains a PagerDuty
+  *service* for each project, routed to the owning team's escalation
+  policy (via the `team_escalation_policy_mapping` option), and a
+  per-service V3 webhook subscription back to Imbi.
+- **`pagerduty-webhook`** — receives PagerDuty incident webhooks. v1
+  records events through the gateway and advertises no custom actions.
+- **`pagerduty-incidents`** — live-queries PagerDuty for the incidents on
+  a project's service for the project-detail Incidents tab.
+
+The Imbi host discovers these through the `imbi.plugins` entry points in
+`pyproject.toml`. All plugin base classes come from
+`imbi_common.plugins.base`.
+
+## Development
+
+```bash
+just setup   # uv sync + pre-commit hooks
+just test    # coverage (fails under 85%)
+just lint    # ruff, ruff-format, basedpyright
+```
+
+Authentication is a PagerDuty REST API key (`auth_type='api_token'`),
+configured as an encrypted plugin credential. PagerDuty is cloud-only, so
+there is no host-flavor routing.

imbi_plugin_pagerduty-2.11.0/README.md

@@ -0,0 +1,30 @@
+# imbi-plugin-pagerduty
+
+PagerDuty plugins for the [Imbi](https://github.com/AWeber-Imbi) platform,
+distributed as a single Python package (`imbi_plugin_pagerduty`) shipping
+three plugin types:
+
+- **`pagerduty-lifecycle`** — provisions and maintains a PagerDuty
+  *service* for each project, routed to the owning team's escalation
+  policy (via the `team_escalation_policy_mapping` option), and a
+  per-service V3 webhook subscription back to Imbi.
+- **`pagerduty-webhook`** — receives PagerDuty incident webhooks. v1
+  records events through the gateway and advertises no custom actions.
+- **`pagerduty-incidents`** — live-queries PagerDuty for the incidents on
+  a project's service for the project-detail Incidents tab.
+
+The Imbi host discovers these through the `imbi.plugins` entry points in
+`pyproject.toml`. All plugin base classes come from
+`imbi_common.plugins.base`.
+
+## Development
+
+```bash
+just setup   # uv sync + pre-commit hooks
+just test    # coverage (fails under 85%)
+just lint    # ruff, ruff-format, basedpyright
+```
+
+Authentication is a PagerDuty REST API key (`auth_type='api_token'`),
+configured as an encrypted plugin credential. PagerDuty is cloud-only, so
+there is no host-flavor routing.

imbi_plugin_pagerduty-2.11.0/justfile

@@ -0,0 +1,59 @@
+[default]
+[private]
+@help:
+    just --list
+
+[private]
+ci: lint test
+
+[doc("Set up your development environment")]
+[group("Environment")]
+setup:
+    uv sync --all-groups --all-extras --frozen
+    uv run pre-commit install --install-hooks --overwrite
+
+[doc("Run tests")]
+[group("Testing")]
+test *FILES: setup
+    #!/usr/bin/env sh
+    set -e
+    env_args=""
+    if [ -f .env ]; then
+      env_args="--env-file .env"
+    fi
+    if [ -z "{{ FILES }}" ]; then
+      uv run $env_args coverage run -m pytest tests
+      uv run coverage report
+      uv run coverage xml -o build/coverage.xml
+    else
+      uv run $env_args pytest {{ FILES }}
+    fi
+
+[doc("Run linters")]
+[group("Testing")]
+lint: setup
+    uv run pre-commit run --all-files
+
+[doc("Reformat code (optionally pass specific files)")]
+[group("Development")]
+format *FILES: setup
+    #!/usr/bin/env sh
+    if [ "{{ FILES }}" = '' ]; then
+        args='--all-files'
+    else
+        args='--files {{ FILES }}'
+    fi
+    uv run pre-commit run ruff-format $args
+    uv run pre-commit run tombi-format $args
+
+[doc("Remove runtime development artifacts")]
+[group("Environment")]
+clean:
+    rm -f .coverage .env
+    rm -fR build
+
+[confirm]
+[doc("Remove caches, virtual env, and output files")]
+[group("Environment")]
+real-clean: clean
+    rm -fR .venv .*_cache dist

imbi_plugin_pagerduty-2.11.0/pyproject.toml

@@ -0,0 +1,123 @@
+[project]
+name = "imbi-plugin-pagerduty"
+version = "2.11.0"
+description = "PagerDuty lifecycle, webhook, and incidents plugins for Imbi"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "Gavin M. Roy", email = "gavinr@aweber.com" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "httpx>=0.27",
+  "imbi-common[databases]==2.11.0",
+  "pydantic>=2",
+]
+
+[project.entry-points."imbi.plugins"]
+pagerduty-lifecycle = "imbi_plugin_pagerduty.lifecycle:PagerDutyLifecyclePlugin"
+pagerduty-webhook = "imbi_plugin_pagerduty.webhook:PagerDutyWebhookPlugin"
+pagerduty-incidents = "imbi_plugin_pagerduty.incidents:PagerDutyIncidentsPlugin"
+
+[dependency-groups]
+dev = [
+  "basedpyright",
+  "coverage[toml]",
+  "imbi-common[server,databases]==2.11.0",
+  "pre-commit",
+  "pytest",
+  "pytest-asyncio",
+  "respx",
+  "ruff~=0.14.6",
+]
+dist = ["build", "twine", "wheel"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.coverage.report]
+exclude_also = ["typing.TYPE_CHECKING"]
+fail_under = 85
+show_missing = true
+
+[tool.coverage.run]
+branch = true
+source = ["src/imbi_plugin_pagerduty"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/imbi_plugin_pagerduty"]
+
+[tool.pyright]
+executionEnvironments = [
+  { root = "src" },
+  { root = "tests", reportPrivateUsage = false },
+]
+deprecateTypingAliases = true
+reportMissingSuperCall = "hint"
+reportMissingTypeStubs = false
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 79
+target-version = "py314"
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+select = [
+  "BLE",
+  "C4",
+  "C90",
+  "E",
+  "W",
+  "F",
+  "G",
+  "I",
+  "N",
+  "Q",
+  "S",
+  "ASYNC",
+  "B",
+  "DTZ",
+  "FURB",
+  "RUF",
+  "T20",
+  "UP",
+]
+ignore = [
+  "ASYNC109",
+  "N818",
+  "RSE",
+  "S105",
+  "TRY003",
+  "TRY400",
+  "UP047",
+]
+flake8-quotes = { inline-quotes = "single" }
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S"]
+
+[tool.uv]
+default-groups = ["dev"]
+exclude-newer = "7 days"
+exclude-newer-package = { "clickhouse-connect" = false, "imbi-common" = false, "imbi-plugin-aws" = false, "imbi-plugin-github" = false, "imbi-plugin-logzio" = false, "imbi-plugin-oidc" = false, "imbi-plugin-pagerduty" = false, "imbi-plugin-sentry" = false, "imbi-plugin-sonarqube" = false }
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true

imbi_plugin_pagerduty-2.11.0/src/imbi_plugin_pagerduty/__init__.py

@@ -0,0 +1,11 @@
+"""Imbi PagerDuty plugins (lifecycle, webhook, incidents)."""
+
+from imbi_plugin_pagerduty.incidents import PagerDutyIncidentsPlugin
+from imbi_plugin_pagerduty.lifecycle import PagerDutyLifecyclePlugin
+from imbi_plugin_pagerduty.webhook import PagerDutyWebhookPlugin
+
+__all__ = [
+    'PagerDutyIncidentsPlugin',
+    'PagerDutyLifecyclePlugin',
+    'PagerDutyWebhookPlugin',
+]

imbi_plugin_pagerduty-2.11.0/src/imbi_plugin_pagerduty/_client.py

@@ -0,0 +1,91 @@
+"""Shared PagerDuty REST client for the plugin family.
+
+PagerDuty is cloud-only (a single ``api.pagerduty.com`` host), so unlike
+the GitHub plugins there is no host-flavor routing -- every plugin uses
+the same base URL and a REST API key credential.
+
+The client converts the two responses the host cares about into the
+shared plugin exceptions via an httpx response hook:
+
+* ``401`` -> :class:`PluginAuthenticationFailed` (a bad / revoked REST
+  key; surfaces to the operator rather than 500ing the request).
+* ``429`` -> :class:`PluginRateLimited` carrying the absolute epoch to
+  resume from, derived from ``ratelimit-reset`` (seconds-until-reset) or
+  a ``retry-after`` header, so the host's sync fan-out can back off
+  instead of hammering the 960 req/min per-key limit.
+"""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+from imbi_common.plugins.errors import (
+    PluginAuthenticationFailed,
+    PluginRateLimited,
+)
+
+API_BASE = 'https://api.pagerduty.com'
+_HTTP_TIMEOUT_SECONDS = 10.0
+#: Small cushion added to a rate-limit reset so the resume lands just
+#: after the window rolls over rather than on the boundary.
+_RATE_LIMIT_PADDING_SECONDS = 1.0
+
+
+def _retry_at(response: httpx.Response) -> float:
+    """Absolute epoch to resume from after a 429, from the headers."""
+    for header in ('ratelimit-reset', 'retry-after'):
+        raw = response.headers.get(header)
+        if raw is None:
+            continue
+        try:
+            seconds = max(0.0, float(raw))
+        except ValueError:
+            continue
+        return time.time() + seconds + _RATE_LIMIT_PADDING_SECONDS
+    # No usable header: PagerDuty's window is one minute, so wait that.
+    return time.time() + 60.0
+
+
+async def _raise_on_error(response: httpx.Response) -> None:
+    """Map auth / rate-limit responses to shared plugin exceptions."""
+    if response.status_code == 401:
+        await response.aread()
+        raise PluginAuthenticationFailed(
+            f'PagerDuty 401 from {response.request.url}: {response.text}'
+        )
+    if response.status_code == 429:
+        await response.aread()
+        raise PluginRateLimited(
+            _retry_at(response),
+            f'PagerDuty rate limit hit at {response.request.url}',
+        )
+
+
+def api_key(credentials: dict[str, str]) -> str:
+    """Return the REST API key from ``credentials`` or raise.
+
+    The manifest declares an ``api_key`` credential field; the host
+    decrypts the plugin configuration and passes it through here.
+    """
+    key = credentials.get('api_key')
+    if not key:
+        raise ValueError(
+            'PagerDuty plugin requires a REST API key; expected '
+            '``credentials["api_key"]``'
+        )
+    return key
+
+
+def client(credentials: dict[str, str]) -> httpx.AsyncClient:
+    """Build an :class:`httpx.AsyncClient` for the PagerDuty REST API."""
+    return httpx.AsyncClient(
+        base_url=API_BASE,
+        timeout=_HTTP_TIMEOUT_SECONDS,
+        headers={
+            'Authorization': f'Token token={api_key(credentials)}',
+            'Accept': 'application/vnd.pagerduty+json;version=2',
+            'Content-Type': 'application/json',
+        },
+        event_hooks={'response': [_raise_on_error]},
+    )