invenio-pidslink 0.1.0__tar.gz

invenio_pidslink-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

invenio_pidslink-0.1.0/CHANGES.rst

@@ -0,0 +1,8 @@
+Changes
+=======
+
+Version 0.1.0 (unreleased)
+
+- Initial release: PIDsLink public API client (mint, update, query, bulk-mint,
+  list, stats) and an InvenioRDM ARK PID provider authenticated with an
+  organisation API key.

invenio_pidslink-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WACREN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

invenio_pidslink-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: invenio-pidslink
+Version: 0.1.0
+Summary: InvenioRDM persistent identifier provider for ARKs minted through WACREN PIDsLink.
+Project-URL: Repository, https://gitlab.wacren.net/libsense/invenio-pidslink
+Author-email: Donald Doe Seanedzu <donald.seanedzu@wacren.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ARK,Invenio,InvenioRDM,PID,PIDsLink,WACREN
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Flask
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: invenio-base<3.0.0,>=2.4.0
+Requires-Dist: invenio-i18n<4.0.0,>=3.0.0
+Requires-Dist: invenio-pidstore<4.0.0,>=3.0.0
+Requires-Dist: invenio-rdm-records<33.0.0,>=32.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: tests
+Requires-Dist: pytest-invenio<5.0.0,>=4.0.0; extra == 'tests'
+Requires-Dist: pytest>=7.0.0; extra == 'tests'
+Description-Content-Type: text/x-rst
+
+================
+Invenio-PIDsLink
+================
+
+InvenioRDM persistent identifier provider that mints **ARKs** through the
+WACREN `PIDsLink <https://pidslink.ren.africa>`_ public API, authenticated with
+an organisation API key.
+
+Install
+-------
+
+.. code-block:: console
+
+   pip install invenio-pidslink
+
+Configure (``invenio.cfg``)
+---------------------------
+
+.. code-block:: python
+
+   import os
+   from invenio_i18n import lazy_gettext as _
+   from invenio_rdm_records.services.pids import providers
+   from invenio_pidslink.providers import PIDsLinkClient, PIDsLinkPIDProvider
+
+   PIDSLINK_ENABLED = True
+   PIDSLINK_API_KEY = os.environ["PIDSLINK_API_KEY"]   # server-side secret
+   PIDSLINK_NAAN = "12345"
+   PIDSLINK_SHOULDER = "abc"
+
+   RDM_PERSISTENT_IDENTIFIER_PROVIDERS = [
+       PIDsLinkPIDProvider("ark", client=PIDsLinkClient("pidslink"),
+                           label=_("ARK")),
+       providers.OAIPIDProvider("oai", label=_("OAI ID")),
+   ]
+
+   RDM_PERSISTENT_IDENTIFIERS = {
+       "ark": {
+           "providers": ["ark"],
+           "required": True,
+           "label": _("ARK"),
+           "is_enabled": PIDsLinkPIDProvider.is_enabled,
+           "system_managed": True,
+       },
+       "oai": {
+           "providers": ["oai"],
+           "required": True,
+           "is_enabled": providers.OAIPIDProvider.is_enabled,
+       },
+   }
+
+To keep DOI off, remove ``doi`` from ``RDM_PERSISTENT_IDENTIFIERS`` or
+disable ``DATACITE_ENABLED`` / ``CROSSREF_ENABLED``.
+
+Public API coverage
+-------------------
+
+``invenio_pidslink.client.PIDsLinkClient`` wraps ``/api/public/pids/``:
+``mint``, ``update``, ``query``, ``bulk_mint``, ``list``, ``stats``. It has no
+Invenio dependency and can be used from plain scripts.
+
+Development
+-----------
+
+.. code-block:: console
+
+   pip install -e ".[tests]"
+   ./run-tests.sh
+
+Releases are published to PyPI by the GitLab CI ``publish`` job when a ``v*`` tag is pushed.
+
+License: MIT.

invenio_pidslink-0.1.0/README.rst

@@ -0,0 +1,72 @@
+================
+Invenio-PIDsLink
+================
+
+InvenioRDM persistent identifier provider that mints **ARKs** through the
+WACREN `PIDsLink <https://pidslink.ren.africa>`_ public API, authenticated with
+an organisation API key.
+
+Install
+-------
+
+.. code-block:: console
+
+   pip install invenio-pidslink
+
+Configure (``invenio.cfg``)
+---------------------------
+
+.. code-block:: python
+
+   import os
+   from invenio_i18n import lazy_gettext as _
+   from invenio_rdm_records.services.pids import providers
+   from invenio_pidslink.providers import PIDsLinkClient, PIDsLinkPIDProvider
+
+   PIDSLINK_ENABLED = True
+   PIDSLINK_API_KEY = os.environ["PIDSLINK_API_KEY"]   # server-side secret
+   PIDSLINK_NAAN = "12345"
+   PIDSLINK_SHOULDER = "abc"
+
+   RDM_PERSISTENT_IDENTIFIER_PROVIDERS = [
+       PIDsLinkPIDProvider("ark", client=PIDsLinkClient("pidslink"),
+                           label=_("ARK")),
+       providers.OAIPIDProvider("oai", label=_("OAI ID")),
+   ]
+
+   RDM_PERSISTENT_IDENTIFIERS = {
+       "ark": {
+           "providers": ["ark"],
+           "required": True,
+           "label": _("ARK"),
+           "is_enabled": PIDsLinkPIDProvider.is_enabled,
+           "system_managed": True,
+       },
+       "oai": {
+           "providers": ["oai"],
+           "required": True,
+           "is_enabled": providers.OAIPIDProvider.is_enabled,
+       },
+   }
+
+To keep DOI off, remove ``doi`` from ``RDM_PERSISTENT_IDENTIFIERS`` or
+disable ``DATACITE_ENABLED`` / ``CROSSREF_ENABLED``.
+
+Public API coverage
+-------------------
+
+``invenio_pidslink.client.PIDsLinkClient`` wraps ``/api/public/pids/``:
+``mint``, ``update``, ``query``, ``bulk_mint``, ``list``, ``stats``. It has no
+Invenio dependency and can be used from plain scripts.
+
+Development
+-----------
+
+.. code-block:: console
+
+   pip install -e ".[tests]"
+   ./run-tests.sh
+
+Releases are published to PyPI by the GitLab CI ``publish`` job when a ``v*`` tag is pushed.
+
+License: MIT.

invenio_pidslink-0.1.0/docs/index.rst

@@ -0,0 +1,4 @@
+Invenio-PIDsLink
+================
+
+.. include:: ../README.rst

invenio_pidslink-0.1.0/invenio_pidslink/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+"""InvenioRDM ARK provider backed by the WACREN PIDsLink public API."""
+
+from .ext import InvenioPIDsLink
+
+__version__ = "0.1.0"
+
+__all__ = ("__version__", "InvenioPIDsLink")

invenio_pidslink-0.1.0/invenio_pidslink/client.py

@@ -0,0 +1,114 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+"""Thin client for the PIDsLink *Public API* (``/api/public/pids/*``).
+
+Pure ``requests``; it has no Invenio dependency so it can be reused in scripts.
+"""
+
+import time
+from urllib.parse import quote
+
+import requests
+
+from .errors import PIDsLinkConnectionError, PIDsLinkError
+
+_RETRY_STATUS = {429, 500, 502, 503, 504}
+
+
+def strip_ark_scheme(value):
+    """``ark:/50962/abc`` -> ``50962/abc`` (the form used in URL paths)."""
+    value = (value or "").strip()
+    return value[5:] if value.startswith("ark:/") else value.lstrip("/")
+
+
+def resolver_url(ark, resolver="https://pidslink.ren.africa"):
+    """Return the public resolver link for an ARK."""
+    return f"{resolver.rstrip('/')}/ark:/{strip_ark_scheme(ark)}"
+
+
+class PIDsLinkClient:
+    """API-key authenticated client. One instance per organisation key."""
+
+    def __init__(self, api_key, base_url="https://pidslinkapi.ren.africa",
+                 timeout=30, retries=3, session=None):
+        if not api_key:
+            raise ValueError("A PIDsLink API key is required.")
+        base = base_url.rstrip("/")
+        self.api_root = base if base.endswith("/api") else f"{base}/api"
+        self.timeout = timeout
+        self.retries = max(1, int(retries))
+        self.session = session or requests.Session()
+        self.session.headers.update(
+            {"X-API-Key": api_key, "Accept": "application/json"}
+        )
+
+    def __repr__(self):  # never print the key
+        return f"<PIDsLinkClient {self.api_root}>"
+
+    def _request(self, method, path, json=None, params=None):
+        url = f"{self.api_root}/public/pids/{path}"
+        last = None
+        for attempt in range(self.retries):
+            try:
+                resp = self.session.request(
+                    method, url, json=json, params=params, timeout=self.timeout
+                )
+            except requests.RequestException as exc:
+                last = PIDsLinkConnectionError(str(exc))
+            else:
+                if resp.status_code < 400:
+                    try:
+                        return resp.json()
+                    except ValueError as exc:
+                        raise PIDsLinkError(
+                            "Invalid JSON from PIDsLink", resp.status_code, resp.text
+                        ) from exc
+                last = PIDsLinkError.factory(
+                    resp.status_code,
+                    f"{method} {path} failed with HTTP {resp.status_code}",
+                    resp.text[:1000],
+                )
+                if resp.status_code not in _RETRY_STATUS:
+                    raise last
+            if attempt + 1 < self.retries:
+                time.sleep(min(2 ** attempt, 8))
+        raise last
+
+    # -- single PID ---------------------------------------------------------
+    def mint(self, naan, shoulder, url, **fields):
+        """``POST /public/pids/mint``. Returns the response ``data`` dict.
+
+        ``fields``: metadata, type, commitment, identifier, format, relation,
+        source, title.
+        """
+        payload = {"naan": naan, "shoulder": shoulder, "url": url, **fields}
+        payload.setdefault("source", url)
+        payload = {k: v for k, v in payload.items() if v is not None}
+        return self._request("POST", "mint", json=payload)["data"]
+
+    def update(self, pid, **fields):
+        """``PATCH /public/pids/update/{pidsId}``."""
+        payload = {k: v for k, v in fields.items() if v is not None}
+        return self._request(
+            "PATCH", f"update/{quote(strip_ark_scheme(pid), safe='/')}", json=payload
+        )
+
+    def query(self, pid):
+        """``GET /public/pids/query/{pidsId}``. Returns the ``data`` dict."""
+        return self._request(
+            "GET", f"query/{quote(strip_ark_scheme(pid), safe='/')}"
+        )["data"]
+
+    # -- bulk / organisation ------------------------------------------------
+    def bulk_mint(self, naan, items):
+        """``POST /public/pids/bulk-mint`` with ``{"naan", "data": [...]}``."""
+        return self._request("POST", "bulk-mint", json={"naan": naan, "data": list(items)})
+
+    def list(self, page=1):
+        """``GET /public/pids/list/{pageNumber}``."""
+        return self._request("GET", f"list/{int(page)}")
+
+    def stats(self):
+        """``GET /public/pids/stats``."""
+        return self._request("GET", "stats")

invenio_pidslink-0.1.0/invenio_pidslink/config.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+"""Default configuration. Every key can be overridden in ``invenio.cfg``."""
+
+PIDSLINK_ENABLED = False
+"""Enable the ARK provider. Off by default so installing the package is inert."""
+
+PIDSLINK_API_URL = "https://pidslinkapi.ren.africa"
+"""PIDsLink API host (the ``/api`` path is added by the client)."""
+
+PIDSLINK_RESOLVER_URL = "https://pidslink.ren.africa"
+"""Resolver host used to build ``https://.../ark:/NAAN/...`` links."""
+
+PIDSLINK_API_KEY = ""
+"""Organisation API key (``pidslink_...``). Keep it server-side, e.g. in an
+environment variable; never expose it to browser JavaScript."""
+
+PIDSLINK_NAAN = ""
+"""Name Assigning Authority Number issued to your organisation."""
+
+PIDSLINK_SHOULDER = ""
+"""ARK shoulder for your repository."""
+
+PIDSLINK_TIMEOUT = 30
+"""Request timeout in seconds."""
+
+PIDSLINK_RETRY_ATTEMPTS = 3
+"""Attempts for transient failures (connection errors, HTTP 429/5xx)."""
+
+PIDSLINK_RECORD_URL_FORMAT = "{site_ui_url}/records/{id}"
+"""Landing page URL registered as the ARK target. Variables: ``site_ui_url``
+(from ``SITE_UI_URL``) and ``id`` (record id). A callable ``f(record)`` is
+also accepted."""
+
+PIDSLINK_RESOURCE_TYPE = "text"
+PIDSLINK_COMMITMENT = "permanent"
+PIDSLINK_TARGET_FORMAT = "html"
+PIDSLINK_RELATION = "isPartOf"
+"""Defaults sent in the mint payload."""

invenio_pidslink-0.1.0/invenio_pidslink/errors.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+"""Exceptions raised by the PIDsLink client."""
+
+
+class PIDsLinkError(Exception):
+    """Base error. ``status_code`` and ``body`` are set for HTTP errors."""
+
+    def __init__(self, message, status_code=None, body=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+    @staticmethod
+    def factory(status_code, message, body=None):
+        """Map an HTTP status code to the matching exception class."""
+        cls = {
+            400: PIDsLinkBadRequestError,
+            401: PIDsLinkAuthError,
+            403: PIDsLinkAuthError,
+            404: PIDsLinkNotFoundError,
+            409: PIDsLinkConflictError,
+            429: PIDsLinkRateLimitError,
+        }.get(status_code)
+        if cls is None:
+            cls = PIDsLinkServerError if status_code >= 500 else PIDsLinkError
+        return cls(message, status_code=status_code, body=body)
+
+
+class PIDsLinkConnectionError(PIDsLinkError):
+    """The service could not be reached."""
+
+
+class PIDsLinkBadRequestError(PIDsLinkError):
+    """400: the payload was rejected."""
+
+
+class PIDsLinkAuthError(PIDsLinkError):
+    """401/403: key missing, inactive, expired, or IP not allow-listed."""
+
+
+class PIDsLinkNotFoundError(PIDsLinkError):
+    """404: identifier unknown to this organisation."""
+
+
+class PIDsLinkConflictError(PIDsLinkError):
+    """409: e.g. the URL is already bound to another PID."""
+
+
+class PIDsLinkRateLimitError(PIDsLinkError):
+    """429: API key rate limit exceeded."""
+
+
+class PIDsLinkServerError(PIDsLinkError):
+    """5xx: PIDsLink failed; retry later."""

invenio_pidslink-0.1.0/invenio_pidslink/ext.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+"""Flask extension: loads default config."""
+
+from . import config
+
+
+class InvenioPIDsLink:
+    """Invenio-PIDsLink extension."""
+
+    def __init__(self, app=None):
+        if app:
+            self.init_app(app)
+
+    def init_app(self, app):
+        """Flask application initialization."""
+        for key in dir(config):
+            if key.startswith("PIDSLINK_"):
+                app.config.setdefault(key, getattr(config, key))
+        app.extensions["invenio-pidslink"] = self

invenio_pidslink-0.1.0/invenio_pidslink/providers.py

@@ -0,0 +1,183 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+"""InvenioRDM PID provider for ARKs minted via the PIDsLink public API."""
+
+from collections import ChainMap
+
+from flask import current_app
+from invenio_pidstore.models import PIDStatus
+from invenio_rdm_records.services.pids.providers import PIDProvider
+
+from .client import PIDsLinkClient as _ApiClient
+from .client import resolver_url
+from .errors import PIDsLinkError
+
+
+class PIDsLinkClient:
+    """Config-driven holder, mirroring ``DataCiteClient``.
+
+    Settings are read lazily from ``<config_prefix>_*`` keys of the app config.
+    """
+
+    def __init__(self, name, config_prefix="PIDSLINK", config_overrides=None):
+        self.name = name
+        self._config_prefix = config_prefix
+        self._config_overrides = config_overrides or {}
+        self._api = None
+
+    def cfgkey(self, key):
+        return f"{self._config_prefix}_{key.upper()}"
+
+    def cfg(self, key, default=None):
+        config = ChainMap(self._config_overrides, current_app.config)
+        return config.get(self.cfgkey(key), default)
+
+    @property
+    def api(self):
+        """Public API client (created on first use)."""
+        if self._api is None:
+            self._api = _ApiClient(
+                self.cfg("api_key"),
+                base_url=self.cfg("api_url"),
+                timeout=self.cfg("timeout", 30),
+                retries=self.cfg("retry_attempts", 3),
+            )
+        return self._api
+
+    def record_url(self, record):
+        """Landing page URL registered as the ARK target."""
+        fmt = self.cfg("record_url_format")
+        if callable(fmt):
+            return fmt(record)
+        site = (current_app.config.get("SITE_UI_URL") or "").rstrip("/")
+        return fmt.format(site_ui_url=site, id=record["id"])
+
+    def mint_payload(self, record):
+        """Fields sent to ``/public/pids/mint``."""
+        metadata = record.get("metadata") or {}
+        title = metadata.get("title") or f"Record {record['id']}"
+        url = self.record_url(record)
+        return {
+            "naan": self.cfg("naan"),
+            "shoulder": self.cfg("shoulder"),
+            "url": url,
+            "metadata": title,
+            "title": title,
+            "type": self.cfg("resource_type", "text"),
+            "commitment": self.cfg("commitment", "permanent"),
+            "identifier": record["id"],
+            "format": self.cfg("target_format", "html"),
+            "relation": self.cfg("relation", "isPartOf"),
+            "source": url,
+        }
+
+    def generate_ark(self, record):
+        """Mint an ARK and return it (``ark:/NAAN/...``)."""
+        if not (self.cfg("naan") and self.cfg("shoulder") and self.cfg("api_key")):
+            raise RuntimeError(
+                f"{self.cfgkey('naan')}, {self.cfgkey('shoulder')} and "
+                f"{self.cfgkey('api_key')} must be configured."
+            )
+        payload = self.mint_payload(record)
+        data = self.api.mint(**payload)
+        ark = data.get("ark")
+        if not ark:
+            raise RuntimeError("PIDsLink mint response did not contain an ARK.")
+        return ark
+
+
+class PIDsLinkPIDProvider(PIDProvider):
+    """ARK provider.
+
+    The ARK is minted when InvenioRDM first asks for an identifier (draft
+    creation) because PIDsLink assigns the value. ``register`` (publish) and
+    ``update`` re-point the ARK at the record landing page.
+    """
+
+    def __init__(self, id_="ark", client=None, pid_type="ark",
+                 default_status=PIDStatus.NEW, **kwargs):
+        super().__init__(
+            id_,
+            client=client or PIDsLinkClient("pidslink", config_prefix="PIDSLINK"),
+            pid_type=pid_type,
+            default_status=default_status,
+            managed=True,
+            **kwargs,
+        )
+
+    @classmethod
+    def is_enabled(cls, app=None):
+        """InvenioRDM calls this with or without the app depending on version."""
+        app = app or current_app
+        return bool(app.config.get("PIDSLINK_ENABLED", False))
+
+    def generate_id(self, record, **kwargs):
+        return self.client.generate_ark(record)
+
+    def can_modify(self, pid, **kwargs):
+        return not pid.is_registered()
+
+    def _push(self, pid, record):
+        payload = self.client.mint_payload(record)
+        self.client.api.update(
+            pid.pid_value,
+            url=payload["url"],
+            metadata=payload["metadata"],
+            title=payload["title"],
+            source=payload["source"],
+        )
+
+    def register(self, pid, record=None, **kwargs):
+        """Mark registered locally, then make sure the target URL is current."""
+        if record is not None:
+            try:
+                self._push(pid, record)
+            except PIDsLinkError:
+                current_app.logger.exception(
+                    "PIDsLink update failed while registering %s", pid.pid_value
+                )
+                return False
+        return super().register(pid)
+
+    def update(self, pid, record=None, **kwargs):
+        if record is None:
+            return False
+        try:
+            self._push(pid, record)
+        except PIDsLinkError:
+            current_app.logger.exception("PIDsLink update failed for %s", pid.pid_value)
+            return False
+        if pid.is_deleted():
+            return pid.sync_status(PIDStatus.REGISTERED)
+        return True
+
+    def validate(self, record, identifier=None, provider=None, **kwargs):
+        success, errors = super().validate(record, identifier, provider, **kwargs)
+        if identifier and not self._is_valid_ark(identifier):
+            self._insert_pid_type_error_msg(
+                errors, "Invalid ARK. Expected ark:/NAAN/name."
+            )
+        return (not errors), errors
+
+    @staticmethod
+    def _is_valid_ark(identifier):
+        rest = identifier[5:] if identifier.startswith("ark:/") else identifier
+        parts = rest.split("/", 1)
+        return len(parts) == 2 and parts[0].isdigit() and bool(parts[1])
+
+    def create_and_reserve(self, record, **kwargs):
+        """Create the PID (minting an ARK) and store it on ``record.pids``."""
+        pid = self.create(record)
+        self.reserve(pid, record=record)
+        record.pids[self.pid_type] = {
+            "identifier": pid.pid_value,
+            "provider": self.name,
+            "client": self.client.name,
+        }
+        return pid
+
+    @staticmethod
+    def resolver_url(ark):
+        """Public resolver link for an ARK."""
+        return resolver_url(ark, current_app.config["PIDSLINK_RESOLVER_URL"])

invenio_pidslink-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+[project]
+name = "invenio-pidslink"
+description = "InvenioRDM persistent identifier provider for ARKs minted through WACREN PIDsLink."
+readme = "README.rst"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Donald Doe Seanedzu", email = "donald.seanedzu@wacren.net" }]
+keywords = ["Invenio", "InvenioRDM", "ARK", "PID", "PIDsLink", "WACREN"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Flask",
+  "Programming Language :: Python :: 3",
+]
+dependencies = [
+  "invenio-base>=2.4.0,<3.0.0",
+  "invenio-i18n>=3.0.0,<4.0.0",
+  "invenio-pidstore>=3.0.0,<4.0.0",
+  "invenio-rdm-records>=32.0.0,<33.0.0",
+  "requests>=2.31.0",
+]
+dynamic = ["version"]
+
+[project.urls]
+Repository = "https://gitlab.wacren.net/libsense/invenio-pidslink"
+
+[project.entry-points."invenio_base.apps"]
+invenio_pidslink = "invenio_pidslink:InvenioPIDsLink"
+
+[project.entry-points."invenio_base.api_apps"]
+invenio_pidslink = "invenio_pidslink:InvenioPIDsLink"
+
+[project.optional-dependencies]
+tests = [
+  "pytest>=7.0.0",
+  "pytest-invenio>=4.0.0,<5.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "invenio_pidslink/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["/invenio_pidslink", "/tests", "/docs", "CHANGES.rst", "README.rst", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

invenio_pidslink-0.1.0/tests/test_client.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+"""Client tests; need only ``requests`` and ``pytest``."""
+
+from unittest.mock import MagicMock
+
+import pytest
+import requests
+
+from invenio_pidslink.client import PIDsLinkClient, resolver_url, strip_ark_scheme
+from invenio_pidslink.errors import (
+    PIDsLinkAuthError,
+    PIDsLinkConflictError,
+    PIDsLinkConnectionError,
+    PIDsLinkServerError,
+)
+
+
+def resp(status=200, body=None):
+    r = MagicMock()
+    r.status_code = status
+    r.json.return_value = body if body is not None else {}
+    r.text = str(body)
+    return r
+
+
+def client(*responses, retries=3):
+    session = MagicMock()
+    session.headers = {}
+    session.request.side_effect = list(responses)
+    c = PIDsLinkClient("pidslink_k", session=session, retries=retries)
+    return c, session
+
+
+@pytest.fixture(autouse=True)
+def no_sleep(monkeypatch):
+    monkeypatch.setattr("invenio_pidslink.client.time.sleep", lambda s: None)
+
+
+def test_requires_key():
+    with pytest.raises(ValueError):
+        PIDsLinkClient("")
+
+
+def test_key_header_and_repr_hides_key():
+    c, s = client()
+    assert s.headers["X-API-Key"] == "pidslink_k"
+    assert "pidslink_k" not in repr(c)
+
+
+def test_mint_posts_to_public_endpoint():
+    c, s = client(resp(201, {"data": {"ark": "ark:/1/a"}}))
+    data = c.mint("1", "s", "https://x/r/1", title="T", type=None)
+    assert data["ark"] == "ark:/1/a"
+    method, url = s.request.call_args.args
+    assert (method, url) == ("POST", "https://pidslinkapi.ren.africa/api/public/pids/mint")
+    body = s.request.call_args.kwargs["json"]
+    assert body["source"] == "https://x/r/1" and "type" not in body
+
+
+def test_update_and_query_strip_scheme():
+    c, s = client(resp(200, {}), resp(200, {"data": {"x": 1}}))
+    c.update("ark:/50962/bb1", url="https://x")
+    assert s.request.call_args.args[1].endswith("/public/pids/update/50962/bb1")
+    assert c.query("ark:/50962/bb1") == {"x": 1}
+
+
+def test_bulk_list_stats():
+    c, s = client(resp(201, {}), resp(200, {}), resp(200, {}))
+    c.bulk_mint("1", [{"url": "u"}])
+    assert s.request.call_args.kwargs["json"] == {"naan": "1", "data": [{"url": "u"}]}
+    c.list(2)
+    assert s.request.call_args.args[1].endswith("/list/2")
+    c.stats()
+    assert s.request.call_args.args[1].endswith("/stats")
+
+
+def test_no_retry_on_auth_or_conflict():
+    c, s = client(resp(401, "no"))
+    with pytest.raises(PIDsLinkAuthError):
+        c.stats()
+    assert s.request.call_count == 1
+    c, s = client(resp(409, "dup"))
+    with pytest.raises(PIDsLinkConflictError):
+        c.mint("1", "s", "u")
+
+
+def test_retries_then_succeeds():
+    c, s = client(resp(503, "x"), resp(200, {"data": {}}))
+    assert c.query("1/a") == {}
+    assert s.request.call_count == 2
+
+
+def test_retries_exhausted():
+    c, s = client(resp(500, "x"), resp(500, "x"), retries=2)
+    with pytest.raises(PIDsLinkServerError):
+        c.stats()
+
+
+def test_connection_error():
+    c, s = client(requests.ConnectionError("down"), retries=1)
+    with pytest.raises(PIDsLinkConnectionError):
+        c.stats()
+
+
+def test_helpers():
+    assert strip_ark_scheme("ark:/1/a") == "1/a"
+    assert resolver_url("1/a") == "https://pidslink.ren.africa/ark:/1/a"

invenio_pidslink-0.1.0/tests/test_provider.py

@@ -0,0 +1,81 @@
+# SPDX-FileCopyrightText: 2026 WACREN.
+# SPDX-License-Identifier: MIT
+
+"""Provider tests using a bare Flask app (no database)."""
+
+from unittest.mock import MagicMock
+
+import pytest
+from flask import Flask
+
+from invenio_pidslink import InvenioPIDsLink
+from invenio_pidslink.providers import PIDsLinkClient, PIDsLinkPIDProvider
+
+
+@pytest.fixture()
+def app():
+    app = Flask("t")
+    app.config.update(
+        SITE_UI_URL="https://repo.example.org/",
+        PIDSLINK_ENABLED=True,
+        PIDSLINK_API_KEY="pidslink_k",
+        PIDSLINK_NAAN="12345",
+        PIDSLINK_SHOULDER="abc",
+    )
+    InvenioPIDsLink(app)
+    with app.app_context():
+        yield app
+
+
+RECORD = {"id": "r1", "metadata": {"title": "My record"}}
+
+
+def test_defaults_do_not_override(app):
+    assert app.config["PIDSLINK_NAAN"] == "12345"
+    assert app.config["PIDSLINK_TIMEOUT"] == 30
+
+
+def test_is_enabled(app):
+    assert PIDsLinkPIDProvider.is_enabled() is True
+    assert PIDsLinkPIDProvider.is_enabled(app) is True
+    app.config["PIDSLINK_ENABLED"] = False
+    assert PIDsLinkPIDProvider.is_enabled() is False
+
+
+def test_mint_payload(app):
+    p = PIDsLinkClient("pidslink").mint_payload(RECORD)
+    assert p["url"] == "https://repo.example.org/records/r1"
+    assert p["naan"] == "12345" and p["identifier"] == "r1"
+    assert p["commitment"] == "permanent"
+
+
+def test_generate_id_mints_via_public_api(app):
+    client = PIDsLinkClient("pidslink")
+    client._api = MagicMock()
+    client._api.mint.return_value = {"ark": "ark:/12345/abc9"}
+    assert PIDsLinkPIDProvider("ark", client=client).generate_id(RECORD) == "ark:/12345/abc9"
+    assert client._api.mint.call_args.kwargs["shoulder"] == "abc"
+
+
+def test_requires_config(app):
+    app.config["PIDSLINK_API_KEY"] = ""
+    with pytest.raises(RuntimeError):
+        PIDsLinkClient("pidslink").generate_ark(RECORD)
+
+
+@pytest.mark.parametrize(
+    "value,ok",
+    [("ark:/12345/abc9", True), ("12345/abc9", True), ("ark:/x/abc", False), ("ark:/12345", False)],
+)
+def test_ark_validation(value, ok):
+    assert PIDsLinkPIDProvider._is_valid_ark(value) is ok
+
+
+def test_update_pushes_url(app):
+    client = PIDsLinkClient("pidslink")
+    client._api = MagicMock()
+    pid = MagicMock(pid_value="ark:/12345/abc9")
+    pid.is_deleted.return_value = False
+    assert PIDsLinkPIDProvider("ark", client=client).update(pid, record=RECORD) is True
+    client._api.update.assert_called_once()
+    assert client._api.update.call_args.kwargs["url"].endswith("/records/r1")