api: Add support for links origins

Author: marienfressinaud

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog of Flus
 
+## unreleased
+
+### Migration notes
+
+The `source` field has been deprecated in the API.
+You must use the new `origin` field instead.
+
 ## 2026-04-22 - v2.4.0
 
 ### Features

docs/api/journal.md

@@ -30,6 +30,11 @@ $ curl -H "Content-Type: application/json" \
         "reading_time": 3,
         "tags": [],
         "source": "collection#<id>",
+        "origin": {
+            "value": "https://app.flus.fr/collections/<id>",
+            "label": "<collection's name>",
+            "url": "https://app.flus.fr/collections/<id>"
+        },
         "is_read": false,
         "is_read_later": false,
         "collections": [],
@@ -50,6 +55,7 @@ $ curl -H "Content-Type: application/json" \
 ### Changelog
 
 - 2.0.0: added
+- 2.5.0: `source` is deprecated, use `origin` instead
 
 ## Refresh the journal
 
@@ -97,7 +103,8 @@ POST /api/v1/journal/read
 ### JSON Parameters
 
 - `date` (string, optional, format: `YYYY-MM-DD`): a date to filter the links to mark as read
-- `source` (string, optional): a source to filter the links to mark as read
+- `origin` (string, optional): an origin to filter the links to mark as read
+- `source` (**deprecated,** string, optional): a source to filter the links to mark as read
 
 ### Example
 
@@ -128,6 +135,7 @@ $ curl -H "Content-Type: application/json" \
 ### Changelog
 
 - 2.0.0: added
+- 2.5.0: `source` is deprecated, use `origin` instead
 
 ## Mark the links of the journal to read later
 
@@ -138,7 +146,8 @@ POST /api/v1/journal/later
 ### JSON Parameters
 
 - `date` (string, optional, format: `YYYY-MM-DD`): a date to filter the links to mark to read later
-- `source` (string, optional): a source to filter the links to mark to read later
+- `origin` (string, optional): an origin to filter the links to mark to read later
+- `source` (**deprecated,** string, optional): a source to filter the links to mark to read later
 
 ### Example
 
@@ -169,6 +178,7 @@ $ curl -H "Content-Type: application/json" \
 ### Changelog
 
 - 2.0.0: added
+- 2.5.0: `source` is deprecated, use `origin` instead
 
 ## Remove the links from the journal
 
@@ -179,7 +189,8 @@ DELETE /api/v1/journal/links
 ### JSON Parameters
 
 - `date` (string, optional, format: `YYYY-MM-DD`): a date to filter the links to remove
-- `source` (string, optional): a source to filter the links to remove
+- `origin` (string, optional): an origin to filter the links to remove
+- `source` (**deprecated,** string, optional): a source to filter the links to remove
 
 ### Example
 
@@ -210,6 +221,7 @@ $ curl -H "Content-Type: application/json" \
 ### Changelog
 
 - 2.0.0: added
+- 2.5.0: `source` is deprecated, use `origin` instead
 
 ## Remove a single link from the journal
 

docs/api/links.md

@@ -36,6 +36,7 @@ $ curl -H "Content-Type: application/json" \
         "reading_time": 3,
         "tags": [],
         "source": null,
+        "origin": null,
         "is_read": false,
         "is_read_later": false,
         "collections": [],
@@ -80,6 +81,7 @@ $ curl -H "Content-Type: application/json" \
 ### Changelog
 
 - 2.0.0: added
+- 2.5.0: `source` is deprecated, use `origin` instead
 
 ## Get a link
 
@@ -110,6 +112,7 @@ $ curl -H "Content-Type: application/json" \
     "reading_time": 3,
     "tags": [],
     "source": null,
+    "origin": null,
     "is_read": false,
     "is_read_later": false,
     "collections": [],
@@ -145,6 +148,7 @@ $ curl -H "Content-Type: application/json" \
 ### Changelog
 
 - 2.0.0: added
+- 2.5.0: `source` is deprecated, use `origin` instead
 
 ## Update a link
 
@@ -163,7 +167,7 @@ PATCH /api/v1/links/:id
 $ curl -H "Content-Type: application/json" \
        -H "Authorization: Bearer <token>" \
        -X PATCH \
-       -d '{"title": "Flus homepage", "reading_time": 10}' \
+       -d '{"title": "Flus homepage", "reading_time": 10, "origin": "https://example.org", "origin_is_public": true}' \
        "https://app.flus.fr/api/v1/links/<id>"
 ```
 
@@ -181,6 +185,11 @@ $ curl -H "Content-Type: application/json" \
     "reading_time": 10,
     "tags": [],
     "source": null,
+    "origin": {
+        "value": "https://example.org",
+        "label": "example.org",
+        "url": "https://example.org"
+    },
     "is_read": false,
     "is_read_later": false,
     "collections": [],
@@ -240,6 +249,8 @@ $ curl -H "Content-Type: application/json" \
 ### Changelog
 
 - 2.0.0: added
+- 2.5.0: `origin` and `origin_is_public` can be updated
+- 2.5.0: `source` is deprecated, use `origin` instead
 
 ## Delete a link
 

docs/api/search.md

@@ -36,6 +36,7 @@ $ curl -H "Content-Type: application/json" \
             "reading_time": 3,
             "tags": [],
             "source": null,
+            "origin": null,
             "is_read": false,
             "is_read_later": false,
             "collections": [],
@@ -89,3 +90,4 @@ Thus, you can follow feeds using the same endpoint as for the collections.
 - 2.0.0: added
 - 2.0.5: add missing `created_at`, `is_hidden`, `source`, `published_at`, `number_notes`
 - 2.0.5: `feeds` entry added
+- 2.5.0: `source` is deprecated, use `origin` instead

src/forms/api/EmptyJournal.php

@@ -14,6 +14,9 @@ class EmptyJournal extends Form
     #[Form\Field(format: 'Y-m-d')]
     public ?\DateTimeImmutable $date = null;
 
+    #[Form\Field]
+    public ?string $origin = null;
+
     #[Form\Field]
     public ?string $source = null;
 
@@ -42,6 +45,10 @@ public function links(): array
             $options['origin'] = $source_origin;
         }
 
+        if ($this->origin) {
+            $options['origin'] = $this->origin;
+        }
+
         $news = $this->user->news();
         return $news->links(options: $options);
     }

src/forms/api/Link.php

@@ -18,4 +18,10 @@ class Link extends Form
 
     #[Form\Field]
     public int $reading_time;
+
+    #[Form\Field(bind: 'setOrigin')]
+    public string $origin;
+
+    #[Form\Field]
+    public bool $origin_is_public;
 }

src/models/Link.php

@@ -2,6 +2,7 @@
 
 namespace App\models;
 
+use App\auth;
 use App\utils;
 use Minz\Database;
 use Minz\Translatable;
@@ -549,9 +550,16 @@ public static function hashUrl(string $url): string
     public function toJson(User $context_user): array
     {
         $origin_model = $this->origin();
+        $origin = null;
         $source = null;
 
-        if ($context_user->id === $this->user_id && $origin_model) {
+        if ($origin_model && auth\Access::can($context_user, 'viewOrigin', $this)) {
+            $origin = [
+                'value' => $origin_model->value,
+                'label' => $origin_model->label,
+                'url' => $origin_model->url,
+            ];
+
             $source = $this->source();
         }
 
@@ -564,6 +572,7 @@ public function toJson(User $context_user): array
             'reading_time' => $this->reading_time,
             'tags' => $this->tags,
             'source' => $source, // @deprecated Can be removed in version 3.0.0.
+            'origin' => $origin,
             'is_read' => $this->isReadBy($context_user),
             'is_read_later' => $this->isInBookmarksOf($context_user),
             'collections' => array_column($this->collections(), 'id'),

tests/controllers/api/v1/LinksTest.php

@@ -321,21 +321,31 @@ public function testUpdateUpdatesTheLink(): void
         $old_reading_time = 21;
         $new_title = 'The link';
         $new_reading_time = 42;
+        $old_origin = 'Internet';
+        $new_origin = 'The Web';
+        $old_origin_is_public = false;
+        $new_origin_is_public = true;
         $link = LinkFactory::create([
             'user_id' => $user->id,
             'title' => $old_title,
             'reading_time' => $old_reading_time,
+            'origin' => $old_origin,
+            'origin_is_public' => $old_origin_is_public,
         ]);
 
         $response = $this->apiRun('PATCH', "/api/v1/links/{$link->id}", [
             'title' => $new_title,
             'reading_time' => $new_reading_time,
+            'origin' => $new_origin,
+            'origin_is_public' => $new_origin_is_public,
         ]);
 
         $this->assertResponseCode($response, 200);
         $link = $link->reload();
         $this->assertSame($new_title, $link->title);
         $this->assertSame($new_reading_time, $link->reading_time);
+        $this->assertSame($new_origin, $link->origin);
+        $this->assertSame($new_origin_is_public, $link->origin_is_public);
         $this->assertApiResponse($response, $link->toJson($user));
     }
 

tests/controllers/api/v1/journal/LaterTest.php

@@ -59,7 +59,7 @@ public function testCreateCanMakAsReadLaterByDate(): void
         $this->assertFalse($link2->isInBookmarksOf($user));
     }
 
-    public function testCreateCanMakAsReadLaterBySource(): void
+    public function testCreateCanMakAsReadLaterByOrigin(): void
     {
         $user = $this->login();
         $news = $user->news();
@@ -79,7 +79,7 @@ public function testCreateCanMakAsReadLaterBySource(): void
         $this->assertFalse($link2->isInBookmarksOf($user));
 
         $response = $this->apiRun('POST', '/api/v1/journal/later', [
-            'source' => "collection#{$collection->id}",
+            'origin' => $origin,
         ]);
 
         $this->assertResponseCode($response, 200);

tests/controllers/api/v1/journal/LinksTest.php

@@ -59,7 +59,7 @@ public function testDeleteAllCanRemoveLinksByDate(): void
         $this->assertFalse($link2->isInNeverList($user));
     }
 
-    public function testDeleteAllCanRemoveLinksBySource(): void
+    public function testDeleteAllCanRemoveLinksByOrigin(): void
     {
         $user = $this->login();
         $news = $user->news();
@@ -79,7 +79,7 @@ public function testDeleteAllCanRemoveLinksBySource(): void
         $this->assertFalse($link2->isInNeverList($user));
 
         $response = $this->apiRun('DELETE', '/api/v1/journal/links', [
-            'source' => "collection#{$collection->id}",
+            'origin' => $origin,
         ]);
 
         $this->assertResponseCode($response, 200);