Convenience functions for the GitHub Notifications REST API.
Each function is a thin wrapper over GhEx.REST that fills in the endpoint
path. They return the same {:ok, body, meta} / {:error, reason} shape as
GhEx.REST and pass opts through to Req, so :params, headers, and a
Req.Test plug all work. For an endpoint without a wrapper, call GhEx.REST
directly.
This module covers consuming the inbox. It has no poll loop, dedup, or state
of its own: a consumer supplies those (an Oban worker, a GenServer, ...). For
polite polling, gh_ex already gives you the pieces:
- conditional requests: send
If-Modified-Since(orIf-None-Match) viaheaders:; an unchanged inbox returns{:ok, :not_modified, meta}and does not count against the rate limit. poll_interval/2reads GitHub'sX-Poll-Intervalheader, the seconds it asks you to wait before polling again.GhEx.RateLimit.delay_until_reset/2is the rate-limit backstop.
See guides/notifications.md for the full pattern.
A notification thread is a pointer ("thread X had activity, reason Y, subject
URL"), not a payload. Fetch the subject (thread["subject"]["url"]) to learn
what changed; that is the consumer's job.
Summary
Functions
Deletes a thread's subscription
(DELETE /notifications/threads/{id}/subscription), unsubscribing without
muting.
Gets a single notification thread (GET /notifications/threads/{id}).
Gets a thread's subscription (GET /notifications/threads/{id}/subscription).
Lists notifications for the authenticated user (GET /notifications).
Lists notifications in a single repository
(GET /repos/{owner}/{repo}/notifications). Accepts the same params: as
list/2.
Marks all notifications as read (PUT /notifications).
Marks a repository's notifications as read
(PUT /repos/{owner}/{repo}/notifications). Accepts last_read_at: like
mark_read/2.
Marks a thread as done (DELETE /notifications/threads/{id}), removing it from
the inbox.
Marks a thread as read (PATCH /notifications/threads/{id}).
Reads the X-Poll-Interval response header off a GhEx.REST.Meta, the number
of seconds GitHub asks you to wait before polling /notifications again.
Sets a thread's subscription (PUT /notifications/threads/{id}/subscription).
Types
Functions
@spec delete_thread_subscription(GhEx.Client.t(), thread_ref(), keyword()) :: GhEx.REST.result()
Deletes a thread's subscription
(DELETE /notifications/threads/{id}/subscription), unsubscribing without
muting.
@spec get_thread(GhEx.Client.t(), thread_ref(), keyword()) :: GhEx.REST.result()
Gets a single notification thread (GET /notifications/threads/{id}).
@spec get_thread_subscription(GhEx.Client.t(), thread_ref(), keyword()) :: GhEx.REST.result()
Gets a thread's subscription (GET /notifications/threads/{id}/subscription).
@spec list( GhEx.Client.t(), keyword() ) :: GhEx.REST.result()
Lists notifications for the authenticated user (GET /notifications).
Use params: for all, participating, since, before, per_page, and
page. Pass headers: [{"if-modified-since", last_modified}] (or
if-none-match) to poll conditionally; an unchanged inbox comes back as
{:ok, :not_modified, meta}.
@spec list_repo(GhEx.Client.t(), String.t(), String.t(), keyword()) :: GhEx.REST.result()
Lists notifications in a single repository
(GET /repos/{owner}/{repo}/notifications). Accepts the same params: as
list/2.
@spec mark_read( GhEx.Client.t(), keyword() ) :: GhEx.REST.result()
Marks all notifications as read (PUT /notifications).
Pass last_read_at: (an ISO 8601 timestamp) to only mark notifications updated
at or before that time; it defaults to now on GitHub's side.
@spec mark_repo_read(GhEx.Client.t(), String.t(), String.t(), keyword()) :: GhEx.REST.result()
Marks a repository's notifications as read
(PUT /repos/{owner}/{repo}/notifications). Accepts last_read_at: like
mark_read/2.
@spec mark_thread_done(GhEx.Client.t(), thread_ref(), keyword()) :: GhEx.REST.result()
Marks a thread as done (DELETE /notifications/threads/{id}), removing it from
the inbox.
@spec mark_thread_read(GhEx.Client.t(), thread_ref(), keyword()) :: GhEx.REST.result()
Marks a thread as read (PATCH /notifications/threads/{id}).
@spec poll_interval(GhEx.REST.Meta.t(), non_neg_integer()) :: non_neg_integer()
Reads the X-Poll-Interval response header off a GhEx.REST.Meta, the number
of seconds GitHub asks you to wait before polling /notifications again.
Returns default (60) when the header is absent or unparseable. gh_ex parses
the header; the caller decides what to do with it (for example
Process.sleep/1, or an Oban {:snooze, seconds}).
@spec set_thread_subscription(GhEx.Client.t(), thread_ref(), map(), keyword()) :: GhEx.REST.result()
Sets a thread's subscription (PUT /notifications/threads/{id}/subscription).
attrs is the JSON body: %{ignored: true} mutes the thread, %{ignored: false}
subscribes to it.