> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification Settings

> Admin notification preferences and delivery configuration

## Overview

Notification Settings API allows administrators to configure their notification delivery preferences, including per-category email and web notification toggles. Settings are stored per admin and control which notifications trigger email delivery via Resend. All functions require authentication.

**Location:** `convex/admins/notificationSettings.ts`

***

## Get Notification Settings

Returns the current admin's notification settings, or `null` if no settings have been initialized yet.

*No parameters required.*

<CodeGroup>
  ```typescript TypeScript theme={null}
  const settings = await convex.query(api.admins.notificationSettings.getNotificationSettings, {});
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "_id": "ns123456789",
    "_creationTime": 1700000000000,
    "adminId": "user_abc123",
    "emailEnabled": true,
    "webEnabled": true,
    "emailPreferences": {
      "storeApprovals": true,
      "payoutRequests": true,
      "reviewFlags": true,
      "orderIssues": true
    },
    "webPreferences": {
      "storeApprovals": true,
      "payoutRequests": true,
      "reviewFlags": false,
      "orderIssues": true
    },
    "emailAddress": "admin@twigz.app",
    "updatedAt": 1700000000000
  }
  ```
</ResponseExample>

<Note>
  Returns `null` if settings have not been initialized. Call `initializeDefaultSettings` to create default settings for a new admin.
</Note>

***

## Update Notification Settings

Updates notification settings for the current admin. All fields are optional and only provided fields are updated. If no settings record exists, one is created with sensible defaults for any omitted fields.

<ParamField path="emailEnabled" type="boolean">
  Master toggle for email notifications
</ParamField>

<ParamField path="webEnabled" type="boolean">
  Master toggle for web/in-app notifications
</ParamField>

<ParamField path="emailPreferences" type="object">
  Per-category email notification toggles

  <Expandable title="properties">
    <ParamField path="storeApprovals" type="boolean">
      Receive emails for store approval requests
    </ParamField>

    <ParamField path="payoutRequests" type="boolean">
      Receive emails for payout requests
    </ParamField>

    <ParamField path="reviewFlags" type="boolean">
      Receive emails for flagged reviews
    </ParamField>

    <ParamField path="orderIssues" type="boolean">
      Receive emails for order issues
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="webPreferences" type="object">
  Per-category web notification toggles

  <Expandable title="properties">
    <ParamField path="storeApprovals" type="boolean">
      Show web notifications for store approval requests
    </ParamField>

    <ParamField path="payoutRequests" type="boolean">
      Show web notifications for payout requests
    </ParamField>

    <ParamField path="reviewFlags" type="boolean">
      Show web notifications for flagged reviews
    </ParamField>

    <ParamField path="orderIssues" type="boolean">
      Show web notifications for order issues
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="emailAddress" type="string">
  Email address for notification delivery
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const settingsId = await convex.mutation(api.admins.notificationSettings.updateNotificationSettings, {
    emailEnabled: true,
    emailPreferences: {
      storeApprovals: true,
      payoutRequests: true,
      reviewFlags: false,
      orderIssues: true
    },
    emailAddress: "admin@twigz.app"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  "ns123456789"
  ```
</ResponseExample>

***

## Initialize Default Settings

Creates default notification settings for a new admin. All notification categories are enabled by default for both email and web channels. If settings already exist for the admin, returns the existing settings ID without modification.

<ParamField path="emailAddress" type="string" required>
  Email address to use for notification delivery
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const settingsId = await convex.mutation(api.admins.notificationSettings.initializeDefaultSettings, {
    emailAddress: "admin@twigz.app"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  "ns123456789"
  ```
</ResponseExample>

<Note>
  This is idempotent -- calling it when settings already exist returns the existing record ID. Call this when an admin first logs in to ensure they have notification settings configured.
</Note>

***

## Send Test Notification

Sends a test notification to verify that the email delivery pipeline is working. Creates an in-app notification (visible in the notification bell) and schedules a test email to the admin's configured email address.

*No parameters required.*

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await convex.mutation(api.admins.notificationSettings.sendTestNotification, {});
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Test notification created! Check the notification bell and your email at admin@twigz.app (including spam folder)."
  }
  ```
</ResponseExample>

Possible failure responses:

<ResponseExample>
  ```json No Settings theme={null}
  {
    "success": false,
    "message": "No notification settings found. Please save your settings first."
  }
  ```

  ```json Email Disabled theme={null}
  {
    "success": false,
    "message": "Email notifications are disabled. Please enable them to receive test emails."
  }
  ```

  ```json No Email Address theme={null}
  {
    "success": false,
    "message": "No email address configured. Please add an email address to your settings."
  }
  ```
</ResponseExample>

<Note>
  The test notification is created with type `order_issue` and priority `low`. Email delivery is handled asynchronously via Resend.
</Note>