@spec archive(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Archive a notification

Moves a notification to "archived" status regardless of whether it is currently "unread" or "read". Archived notifications are excluded from the default inbox view but remain retrievable by passing status: "archived" to the list endpoint.

The authenticated user must own the notification. Passing a notification ID that belongs to a different user returns a 404. If the notification is already archived this call succeeds without error (idempotent).

Requires an app-scoped token. Returns 204 No Content on success.

No content

@spec list(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1Notifications.Params.t()
) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1Notifications.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List a user's notifications

Returns a cursor-paginated list of inbox notifications for the authenticated user, ordered by creation time descending (newest first). All status groups are included by default; pass status to narrow results to a specific group.

Each notification's rendered field contains type-specific display data resolved at request time. Notifications whose type is no longer registered in the platform are rendered with kind: "unknown" rather than being omitted.

Pagination is forward-only: supply after_cursor from a previous response to fetch the next (older) page. The before_cursor field is always null for this endpoint. Requires an app-scoped token.

Successful response

@spec read(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Mark a notification as read

Transitions a notification from "unread" to "read" status. If the notification is already "read" or "archived", the call succeeds without changing its status (idempotent).

The authenticated user must own the notification. Passing a notification ID that belongs to a different user returns a 404. Requires an app-scoped token. Returns 204 No Content on success.

No content

@spec read_all(ArchAstro.Client.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Mark all notifications as read

Marks every "unread" notification belonging to the authenticated user as "read" in a single operation. Notifications that are already "read" or "archived" are not affected.

This call is safe to retry — if there are no unread notifications, it succeeds without error. Requires an app-scoped token. Returns 204 No Content on success.

No content

@spec send(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1NotificationsSend.Input.t()
) ::
  {:ok, ArchAstro.Types.Notification.t()} | {:error, ArchAstro.Error.reason()}

Send a custom notification to a user

Delivers a custom-typed notification to one of the calling app's users. Apps define notification types by declaring NotificationType config objects in their bundle (one per lookup_key). Supply the type as "custom:<lookup_key>" and provide a data map that is merged with platform-provided context to render the notification's display fields.

Only app-scoped tokens may call this endpoint — user tokens are rejected with

403. The app scope is stamped onto the notification automatically; an app cannot target recipients outside its tenant. Built-in platform types such as "app_info" and "billing_alert" are not accepted here.

Pass idempotency_key to deduplicate sends. If you call this endpoint twice with the same idempotency_key for the same recipient, the second call returns the original notification without creating a duplicate. The key is scoped to the calling app, so the same raw key used by different apps cannot collide.

The created notification, or the existing notification when deduplicated by idempotency_key.

@spec unarchive(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Unarchive a notification

Restores an "archived" notification to its previous active status: "read" if the notification had been read before archiving, or "unread" otherwise. The notification will appear again in the default inbox view.

The authenticated user must own the notification. Passing a notification ID that belongs to a different user returns a 404. If the notification is not currently archived this call succeeds without changing its status (idempotent). Requires an app-scoped token. Returns 204 No Content on success.

No content

@spec unread_count(ArchAstro.Client.t()) ::
  {:ok,
   ArchAstro.Types.Operations.GetApiV1NotificationsUnreadCount.Response.t()}
  | {:error, ArchAstro.Error.reason()}

Get the unread notification count

Returns the total number of "unread" notifications for the authenticated user. Useful for displaying a badge or indicator in your UI without fetching the full notification list.

Notifications with "read" or "archived" status are not included in the count. Requires an app-scoped token.

Successful response