CreditsPackageResource
======================

Introduction
------------
Credits Package Resource.

Hosts the API to manage WASDI credit packages:

- Retrieve the available credit package types.
- Query the total credits remaining for the authenticated user.
- List credit packages purchased by the authenticated user.
- Create a new credit package.
- Obtain a Stripe payment URL to purchase a credit package.
- Handle the Stripe payment confirmation callback to activate a credit package.

All endpoints are under the base path ``/credits``.

Most endpoints require a valid session via the ``x-session-token`` header. The Stripe confirmation endpoint is called by Stripe and does not require a session token.

Common Models
-------------
- CreditsPackageViewModel: creditPackageId, name, description, type, buyDate, userId, buySuccess, creditsRemaining, lastUpdate
- SubscriptionTypeViewModel: typeId, name, description
- SuccessResponse: message
- ErrorResponse: message

APIs
----

GET /credits/types
^^^^^^^^^^^^^^^^^^
- Description: Returns the list of available credit package types that a user can purchase. Does not require authentication.
- HTTP Verb: GET
- Headers: x-session-token (optional — not validated by this endpoint)
- Query params: none
- Body: none
- Success:
  - 200 OK, body: list of SubscriptionTypeViewModel (typeId, name, description)
- Return codes:
  - 200 OK
  - 500 Internal Server Error

GET /credits/totalbyuser
^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Returns the total amount of credits remaining across all credit packages owned by the authenticated user.
- HTTP Verb: GET
- Headers: x-session-token
- Query params: none
- Body: none
- Success:
  - 200 OK, body: Double (total credits remaining)
- Return codes:
  - 200 OK
  - 401 Unauthorized (invalid session)
  - 500 Internal Server Error

GET /credits/listbyuser
^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Returns all credit packages that have been purchased by the authenticated user, optionally sorted by purchase date in ascending order.
- HTTP Verb: GET
- Headers: x-session-token
- Query params:
  - ascendingOrder (boolean, optional) — if true, results are sorted by buy date ascending; default is descending
- Body: none
- Success:
  - 200 OK, body: list of CreditsPackageViewModel
- Return codes:
  - 200 OK
  - 401 Unauthorized (invalid session)
  - 500 Internal Server Error

POST /credits/add
^^^^^^^^^^^^^^^^^^
- Description: Creates a new credit package for the authenticated user. The amount of credits is determined by the package type. Only admin users can create a package with ``buySuccess`` set to true; for non-admin users the flag is forced to false and the package must be activated via the Stripe payment flow.
- HTTP Verb: POST
- Headers: x-session-token
- Query params: none
- Body: CreditsPackageViewModel (required): name, description, type, buySuccess
- Success:
  - 200 OK, body: SuccessResponse (message = new creditPackageId)
- Notes:
  - If a credit package with the same name already exists for the user, the name is automatically suffixed to make it unique.
- Return codes:
  - 200 OK
  - 400 Bad Request (invalid package type)
  - 401 Unauthorized (invalid session)
  - 500 Internal Server Error

GET /credits/stripe/paymentUrl
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Generates a Stripe Checkout payment URL for the specified credit package. The URL includes the ``creditPackageId`` as a client reference so Stripe can link the payment back to the package on confirmation.
- HTTP Verb: GET
- Headers: x-session-token
- Query params:
  - creditPackageId (string, required) — ID of the credit package to pay for
- Body: none
- Success:
  - 200 OK, body: SuccessResponse (message = Stripe Checkout URL)
- Return codes:
  - 200 OK
  - 400 Bad Request (missing/invalid creditPackageId or unsupported package type)
  - 401 Unauthorized (invalid session)
  - 403 Forbidden (package belongs to a different user)
  - 500 Internal Server Error

GET /credits/stripe/confirmation/{CHECKOUT_SESSION_ID}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Stripe payment confirmation callback. Called by Stripe after a successful payment. Verifies the payment details with Stripe, then marks the corresponding credit package as successfully purchased (sets buySuccess=true, records the buy date and Stripe payment intent ID). This endpoint is not protected by a session token — it is intended to be called by Stripe's redirect mechanism.
- HTTP Verb: GET
- Headers: none
- Path params:
  - CHECKOUT_SESSION_ID (string, required) — the Stripe checkout session identifier embedded in the redirect URL
- Query params: none
- Body: none
- Success:
  - 200 OK
- Return codes:
  - 200 OK
  - 401 Unauthorized (missing or empty CHECKOUT_SESSION_ID)
  - 500 Internal Server Error (Stripe verification failed or DB update error)