diff --git a/pkg/models/subscription.go b/pkg/models/subscription.go
index ad664c23f..4afb59ea3 100644
--- a/pkg/models/subscription.go
+++ b/pkg/models/subscription.go
@@ -96,18 +96,18 @@ const (
// Subscription represents a subscription for an entity
type Subscription struct {
// The numeric ID of the subscription
- ID int64 `xorm:"autoincr not null unique pk" json:"id"`
+ ID int64 `xorm:"autoincr not null unique pk" json:"id" readOnly:"true" doc:"The numeric id of the subscription."`
- EntityType SubscriptionEntityType `xorm:"index not null" json:"entity"`
+ EntityType SubscriptionEntityType `xorm:"index not null" json:"entity" readOnly:"true" doc:"The kind of entity this subscription is for. Either project or task; derived server-side from the request path."`
Entity string `xorm:"-" json:"-" param:"entity"`
// The id of the entity to subscribe to.
- EntityID int64 `xorm:"bigint index not null" json:"entity_id" param:"entityID"`
+ EntityID int64 `xorm:"bigint index not null" json:"entity_id" param:"entityID" readOnly:"true" doc:"The numeric id of the subscribed entity; taken from the request path."`
// The user who made this subscription
UserID int64 `xorm:"bigint index not null" json:"-"`
// A timestamp when this subscription was created. You cannot change this value.
- Created time.Time `xorm:"created not null" json:"created"`
+ Created time.Time `xorm:"created not null" json:"created" readOnly:"true" doc:"A timestamp when this subscription was created. You cannot change this value."`
web.CRUDable `xorm:"-" json:"-"`
web.Permissions `xorm:"-" json:"-"`
diff --git a/pkg/routes/api/v2/subscriptions.go b/pkg/routes/api/v2/subscriptions.go
new file mode 100644
index 000000000..19e9e22ee
--- /dev/null
+++ b/pkg/routes/api/v2/subscriptions.go
@@ -0,0 +1,90 @@
+// Vikunja is a to-do list application to facilitate your life.
+// Copyright 2018-present Vikunja and contributors. All rights reserved.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see .
+
+package apiv2
+
+import (
+ "context"
+ "net/http"
+
+ "code.vikunja.io/api/pkg/models"
+ "code.vikunja.io/api/pkg/web/handler"
+
+ "github.com/danielgtaylor/huma/v2"
+)
+
+// subscriptionPathParams binds the {entity}/{entityID} discriminator onto the
+// Subscription model. {entity} stays a string — Subscription.CanCreate /
+// CanDelete derive the numeric EntityType from it and reject unknown kinds with
+// ErrUnknownSubscriptionEntityType (412). The enum tag documents the valid
+// values and lets Huma reject anything else with a 422 before the handler runs.
+type subscriptionPathParams struct {
+ Entity string `path:"entity" enum:"project,task" doc:"The kind of entity to (un)subscribe from. Either project or task."`
+ EntityID int64 `path:"entityID" doc:"The numeric id of the entity to (un)subscribe from."`
+}
+
+// RegisterSubscriptionRoutes wires subscribe/unsubscribe onto the Huma API.
+//
+// Subscription is a CRUDable whose Create/Delete only ever touch the current
+// user's own subscription, so the routes reuse handler.DoCreate/DoDelete; the
+// only custom part is binding the entity discriminator from the path.
+func RegisterSubscriptionRoutes(api huma.API) {
+ tags := []string{"subscriptions"}
+
+ Register(api, huma.Operation{
+ OperationID: "subscriptions-create",
+ Summary: "Subscribe to an entity",
+ Description: "Subscribes the authenticated user to a project or task so they receive its notifications. The user needs read access to the entity. Fails if a subscription already exists.",
+ Method: http.MethodPost,
+ Path: "/subscriptions/{entity}/{entityID}",
+ Tags: tags,
+ }, subscriptionsCreate)
+
+ Register(api, huma.Operation{
+ OperationID: "subscriptions-delete",
+ Summary: "Unsubscribe from an entity",
+ Description: "Removes the authenticated user's own subscription to a project or task. Only affects the caller's subscription, not other users'.",
+ Method: http.MethodDelete,
+ Path: "/subscriptions/{entity}/{entityID}",
+ Tags: tags,
+ }, subscriptionsDelete)
+}
+
+func init() { AddRouteRegistrar(RegisterSubscriptionRoutes) }
+
+func subscriptionsCreate(ctx context.Context, in *subscriptionPathParams) (*singleBody[models.Subscription], error) {
+ a, err := authFromCtx(ctx)
+ if err != nil {
+ return nil, err
+ }
+ sb := &models.Subscription{Entity: in.Entity, EntityID: in.EntityID}
+ if err := handler.DoCreate(ctx, sb, a); err != nil {
+ return nil, translateDomainError(err)
+ }
+ return &singleBody[models.Subscription]{Body: sb}, nil
+}
+
+func subscriptionsDelete(ctx context.Context, in *subscriptionPathParams) (*emptyBody, error) {
+ a, err := authFromCtx(ctx)
+ if err != nil {
+ return nil, err
+ }
+ sb := &models.Subscription{Entity: in.Entity, EntityID: in.EntityID}
+ if err := handler.DoDelete(ctx, sb, a); err != nil {
+ return nil, translateDomainError(err)
+ }
+ return &emptyBody{}, nil
+}
diff --git a/pkg/webtests/huma_subscription_test.go b/pkg/webtests/huma_subscription_test.go
new file mode 100644
index 000000000..d72ba7d9a
--- /dev/null
+++ b/pkg/webtests/huma_subscription_test.go
@@ -0,0 +1,122 @@
+// Vikunja is a to-do list application to facilitate your life.
+// Copyright 2018-present Vikunja and contributors. All rights reserved.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see .
+
+package webtests
+
+import (
+ "net/http"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// TestHumaSubscription ports the model-level matrix in
+// pkg/models/subscription_test.go to the v2 HTTP surface: subscribing requires
+// access to the target entity, an invalid entity kind is rejected, and
+// inaccessible entities are forbidden. Subscriptions has no v1 webtest, so this
+// proves the contract independently.
+//
+// Fixture facts the matrix relies on (see pkg/db/fixtures):
+// - user1 has read access to task 1 and project 1.
+// - user1 is already subscribed to task 2 (subscriptions.yml id 1).
+// - user1 cannot see task 14 or project 20.
+func TestHumaSubscription(t *testing.T) {
+ token := func(t *testing.T) string { return humaTokenFor(t, &testuser1) }
+
+ t.Run("Create", func(t *testing.T) {
+ t.Run("task - normal", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ rec := humaRequest(t, e, http.MethodPost, "/api/v2/subscriptions/task/1", "", token(t), "")
+ assert.Equal(t, http.StatusCreated, rec.Code, "body: %s", rec.Body.String())
+ assert.Contains(t, rec.Body.String(), `"entity":"task"`)
+ assert.Contains(t, rec.Body.String(), `"entity_id":1`)
+ })
+ t.Run("project - normal", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ rec := humaRequest(t, e, http.MethodPost, "/api/v2/subscriptions/project/1", "", token(t), "")
+ assert.Equal(t, http.StatusCreated, rec.Code, "body: %s", rec.Body.String())
+ assert.Contains(t, rec.Body.String(), `"entity":"project"`)
+ })
+ t.Run("already exists", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ // user1 is already subscribed to task 2.
+ rec := humaRequest(t, e, http.MethodPost, "/api/v2/subscriptions/task/2", "", token(t), "")
+ assert.Equal(t, http.StatusPreconditionFailed, rec.Code, "body: %s", rec.Body.String())
+ })
+ t.Run("invalid entity kind", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ // The enum on the path param makes Huma reject unknown kinds before the handler.
+ rec := humaRequest(t, e, http.MethodPost, "/api/v2/subscriptions/bogus/1", "", token(t), "")
+ assert.Equal(t, http.StatusUnprocessableEntity, rec.Code, "body: %s", rec.Body.String())
+ })
+ t.Run("nonexisting task", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ rec := humaRequest(t, e, http.MethodPost, "/api/v2/subscriptions/task/9999999", "", token(t), "")
+ assert.Equal(t, http.StatusNotFound, rec.Code, "body: %s", rec.Body.String())
+ })
+ t.Run("nonexisting project", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ rec := humaRequest(t, e, http.MethodPost, "/api/v2/subscriptions/project/9999999", "", token(t), "")
+ assert.Equal(t, http.StatusNotFound, rec.Code, "body: %s", rec.Body.String())
+ })
+ t.Run("forbidden - no access to task", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ // task 14 is not accessible to user1.
+ rec := humaRequest(t, e, http.MethodPost, "/api/v2/subscriptions/task/14", "", token(t), "")
+ assert.Equal(t, http.StatusForbidden, rec.Code, "body: %s", rec.Body.String())
+ })
+ t.Run("forbidden - no access to project", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ // project 20 is not accessible to user1.
+ rec := humaRequest(t, e, http.MethodPost, "/api/v2/subscriptions/project/20", "", token(t), "")
+ assert.Equal(t, http.StatusForbidden, rec.Code, "body: %s", rec.Body.String())
+ })
+ })
+
+ t.Run("Delete", func(t *testing.T) {
+ t.Run("normal", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ // user1 is subscribed to task 2.
+ rec := humaRequest(t, e, http.MethodDelete, "/api/v2/subscriptions/task/2", "", token(t), "")
+ assert.Equal(t, http.StatusNoContent, rec.Code, "body: %s", rec.Body.String())
+ assert.Empty(t, rec.Body.String())
+ })
+ t.Run("not subscribed - forbidden", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ // CanDelete returns false when no subscription exists, so the generic
+ // handler refuses with 403 (mirrors v1's DeleteWeb).
+ rec := humaRequest(t, e, http.MethodDelete, "/api/v2/subscriptions/task/1", "", token(t), "")
+ assert.Equal(t, http.StatusForbidden, rec.Code, "body: %s", rec.Body.String())
+ })
+ t.Run("invalid entity kind", func(t *testing.T) {
+ e, err := setupTestEnv()
+ require.NoError(t, err)
+ rec := humaRequest(t, e, http.MethodDelete, "/api/v2/subscriptions/bogus/2", "", token(t), "")
+ assert.Equal(t, http.StatusUnprocessableEntity, rec.Code, "body: %s", rec.Body.String())
+ })
+ })
+}