SubscriptionResource
====================

Introduction
------------
Subscription Resource.

Hosts APIs to create, manage, share, and purchase subscriptions.

Main capabilities:

- Read active/user/admin subscription lists and counts
- Create, update, and delete subscriptions
- Share subscriptions with users and manage sharing entries
- Retrieve available subscription types
- Generate Stripe checkout URL and confirm Stripe checkout callback

All endpoints are under base path /subscriptions.

Authentication:

- Most endpoints require x-session-token.
- Stripe confirmation callback endpoint is called by Stripe and uses path parameter only.

Common Models
-------------
- SubscriptionViewModel:
	- subscriptionId, name, description, typeId, typeName, buyDate, startDate, endDate, durationDays, userId, organizationId, organizationName, buySuccess, readOnly
- SubscriptionListViewModel:
	- subscriptionId, ownerUserId, name, typeId, typeName, startDate, endDate, organizationName, organizationId, reason, buySuccess, runningTime, readOnly
- SubscriptionSharingViewModel:
	- subscriptionId, userId, ownerId, permissions
- SubscriptionTypeViewModel:
	- typeId, name, description
- StripePaymentDetail:
	- clientReferenceId, customerName, customerEmail, paymentIntentId, paymentStatus, paymentCurrency, paymentAmountInCents, invoiceId, productDescription, paymentDateInSeconds, date, invoicePdfUrl
- PrimitiveResult:
	- IntValue, StringValue, DoubleValue, BoolValue
- SuccessResponse:
	- message
- ErrorResponse:
	- message

APIs
----

GET /subscriptions/active
^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Returns active subscription for current user from valid subscriptions.
- Success: 200 OK, body: SubscriptionListViewModel
- Return codes: 200, 401, 404, 500

GET /subscriptions/byuser
^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Returns subscriptions associated with current user (owned/shared/organization-based via permission utility).
- Query params: valid (optional boolean, default false)
- Success: 200 OK, body: array of SubscriptionListViewModel
- Return codes: 200, 401, 500

GET /subscriptions/count
^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Returns total subscriptions count.
- Success: 200 OK, body: PrimitiveResult (IntValue)
- Return codes: 200, 401, 403, 500
- Notes: admin-only endpoint.

GET /subscriptions/byId
^^^^^^^^^^^^^^^^^^^^^^^
- Description: Returns full subscription details by id.
- Query params: subscription (required)
- Success: 200 OK, body: SubscriptionViewModel
- Return codes: 200, 401, 400, 403, 500

POST /subscriptions/add
^^^^^^^^^^^^^^^^^^^^^^^
- Description: Creates a subscription and automatically creates a default project with same name.
- Body: SubscriptionViewModel
- Success: 200 OK, body: SuccessResponse (message contains subscription id)
- Return codes: 200, 401, 500
- Notes:
	- For non-admin callers, target user is forced to current user.
	- Non-admin callers cannot force buySuccess=true.
	- Name collisions are resolved by cloning/renaming.

PUT /subscriptions/update
^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Updates an existing subscription.
- Body: SubscriptionViewModel
- Success: 200 OK, body: SuccessResponse
- Return codes: 200, 401, 400, 403, 500
- Notes: non-admin callers cannot change buySuccess state.

DELETE /subscriptions/delete
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Deletes a subscription or removes caller sharing if caller is not owner/admin.
- Query params: subscription (required)
- Success: 200 OK, body: SuccessResponse
- Return codes: 200, 401, 400, 403, 500
- Notes:
	- Owner/admin path removes sharings, deletes related projects, then deletes subscription.
	- Non-owner shared user path removes own sharing only.

GET /subscriptions/types
^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Returns available subscription types.
- Success: 200 OK, body: array of SubscriptionTypeViewModel
- Return codes: 200, 500

POST /subscriptions/share/add
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Shares a subscription with another user.
- Query params: subscription (required), userId (required), rights (optional; defaults to READ if invalid)
- Success: 200 OK, body: SuccessResponse
- Return codes: 200, 401, 400, 403, 500
- Notes:
	- Prevents sharing with self and owner.
	- Returns success with message Already Shared when permission already exists.

GET /subscriptions/share/bysubscription
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Returns users currently sharing a subscription.
- Query params: subscription (required)
- Success: 200 OK, body: array of SubscriptionSharingViewModel
- Return codes: 200, 401, 403, 500

DELETE /subscriptions/share/delete
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Removes one user sharing entry from a subscription.
- Query params: subscription (required), userId (required)
- Success: 200 OK, body: SuccessResponse
- Return codes: 200, 401, 400, 403, 500
- Notes:
	- Cannot remove owner from its own subscription.
	- Allowed for owner/writer/admin, and in beneficiary-removal flow as implemented.

GET /subscriptions/stripe/paymentUrl
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Generates Stripe checkout URL for a subscription type configured in server settings.
- Query params: subscription (required), workspace (optional)
- Success: 200 OK, body: SuccessResponse (message contains URL)
- Return codes: 200, 401, 400, 403, 500

GET /subscriptions/stripe/confirmation/{CHECKOUT_SESSION_ID}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Description: Stripe callback endpoint to confirm payment and activate subscription.
- Path params: CHECKOUT_SESSION_ID (required)
- Success: 200 OK
- Return codes: 200, 401, 500
- Notes:
	- Retrieves payment details from Stripe using checkout session id.
	- Sets buySuccess=true and buyDate when confirmation succeeds.
	- Optionally emits RabbitMQ message if workspace id is present in client reference id.

GET /subscriptions/list
^^^^^^^^^^^^^^^^^^^^^^^
- Description: Admin dashboard listing endpoint with filters, sorting, and paging.
- Query params: userfilter, idfilter, namefilter, statusfilter, offset, limit, sortby, order
- Success: 200 OK, body: array of SubscriptionListViewModel
- Return codes: 200, 401, 403, 500
- Notes:
	- Admin-only endpoint.
	- Defaults: offset=0, limit=10, sortby=name, order=asc.