Reminder Schedules API

Manage scheduled reminders used by the platform (e.g., to notify clients before/after important dates). All endpoints are admin-only.

Base URL

/api/reminderSchedules

Authentication & Authorization

• Auth: Cookie-based JWT (set via the authentication flow).
• Role required: admin (middleware: authorize(["admin"])).
• Requests from non-admin users receive 401/403 depending on your global auth middleware behavior.

Resource Model

A Reminder Schedule defines a relative offset around a business event (like an installment due date) and how the system should schedule the reminder.

Field	Type	Description
id	number	Auto-increment identifier.
status	string | boolean	Schedule enablement state. Implementation accepts arbitrary input; recommended values: "active"/"inactive" or boolean true/false.
offsetAmount	number	Magnitude of the offset (e.g., 3).
offsetDirection	string	Direction of the offset relative to the event. Recommended values: "before" or "after".
reminderType	string	Semantic label for the event type (e.g., "installment_due", "fee_due").
createdAt	string (ISO datetime)	When the schedule was created. (Set by DB.)
updatedAt	string (ISO datetime)	When the schedule was last updated. (Set on update.)

Note: The server code does not currently enforce enums or shape validation for status, offsetDirection, or reminderType. Use consistent values in your client.

---

Endpoints

List Schedules

GET / → 200 OK

Returns all reminder schedules.

Response (200)

[
  {
    "id": 12,
    "status": "active",
    "offsetAmount": 3,
    "offsetDirection": "before",
    "reminderType": "installment_due",
    "createdAt": "2025-01-10T12:00:00.000Z",
    "updatedAt": "2025-01-10T12:00:00.000Z"
  }
]

Errors

• 500 – Failed to fetch reminder schedules

cURL

curl -X GET \
  -b "token=<JWT_COOKIE>" \
  http://<host>/api/reminderSchedules

---

Get Schedule by ID

GET /:id → 200 OK

Fetch a single schedule.

Path params

• id (number) – Schedule ID

Response (200)

{
  "id": 12,
  "status": "active",
  "offsetAmount": 3,
  "offsetDirection": "before",
  "reminderType": "installment_due",
  "createdAt": "2025-01-10T12:00:00.000Z",
  "updatedAt": "2025-01-10T12:00:00.000Z"
}

Errors

• 404 – Reminder schedule not found
• 500 – Failed to fetch reminder schedule

cURL

curl -X GET \
  -b "token=<JWT_COOKIE>" \
  http://<host>/api/reminderSchedules/12

---

Create Schedule

POST / → 201 Created

Body

{
  "status": "active",            // or true/false
  "offsetAmount": 3,               // integer or number
  "offsetDirection": "before",    // "before" | "after" (recommended)
  "reminderType": "installment_due"
}

Response (201)

{
  "id": 42
}

The raw response mirrors the DB/driver return. Some setups return an insert result object; others may return the full row. Treat this as returning the created record/identifier.

Errors

• 500 – Failed to create reminder schedule

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -b "token=<JWT_COOKIE>" \
  -d '{
    "status": "active",
    "offsetAmount": 3,
    "offsetDirection": "before",
    "reminderType": "installment_due"
  }' \
  http://<host>/api/reminderSchedules

---

Update Schedule

PUT /:id → 200 OK

Path params

• id (number) – Schedule ID

Body (any subset is allowed)

{
  "status": "inactive",
  "offsetAmount": 7,
  "offsetDirection": "after",
  "reminderType": "fee_due"
}

Response (200)

{ "message": "Reminder schedule updated successfully" }

Errors

• 404 – Reminder schedule not found
• 500 – Failed to update reminder schedule

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -b "token=<JWT_COOKIE>" \
  -d '{
    "status": "inactive",
    "offsetAmount": 7,
    "offsetDirection": "after",
    "reminderType": "fee_due"
  }' \
  http://<host>/api/reminderSchedules/42

---

Delete Schedule

DELETE /:id → 200 OK

Path params

• id (number) – Schedule ID

Response (200)

{ "message": "Reminder schedule deleted successfully" }

Errors

• 404 – Reminder schedule not found
• 500 – Failed to delete reminder schedule

cURL

curl -X DELETE \
  -b "token=<JWT_COOKIE>" \
  http://<host>/api/reminderSchedules/42

---

Notes & Best Practices

• Validation: The current handlers accept raw values; consider adding request validation (e.g., zod/Joi) to enforce enums and types for status, offsetDirection, and reminderType.
• Idempotency: Creating the same schedule twice is allowed by default; add unique constraints if needed (e.g., (reminderType, offsetAmount, offsetDirection)).
• Scheduling engine: This API only stores schedule definitions. The actual dispatch of reminders should be implemented by a worker/cron using these definitions.
• Time units: offsetAmount is treated as a numeric quantity; standardize on days unless your business logic requires otherwise.

---

OpenAPI (excerpt)

openapi: 3.0.3
info:
  title: Reminder Schedules API
  version: 1.0.0
servers:
  - url: /api/reminderSchedules
paths:
  /:
    get:
      summary: List reminder schedules
      responses:
        '200': { description: OK }
    post:
      summary: Create a reminder schedule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { oneOf: [ { type: string }, { type: boolean } ] }
                offsetAmount: { type: number }
                offsetDirection: { type: string }
                reminderType: { type: string }
      responses:
        '201': { description: Created }
  /{id}:
    get:
      summary: Get schedule by id
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        '200': { description: OK }
        '404': { description: Not Found }
    put:
      summary: Update schedule
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { oneOf: [ { type: string }, { type: boolean } ] }
                offsetAmount: { type: number }
                offsetDirection: { type: string }
                reminderType: { type: string }
      responses:
        '200': { description: Updated }
        '404': { description: Not Found }
    delete:
      summary: Delete schedule
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        '200': { description: Deleted }
        '404': { description: Not Found }