forjio-depllo 0.2.0__tar.gz

forjio_depllo-0.2.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.next/
+.env
+.env.local
+.env.*.local
+*.log
+.DS_Store
+*.swp
+coverage/
+playwright-report/
+test-results/
+tsconfig.tsbuildinfo
+
+# apigen scratch copy (scripts/apigen.sh)
+backend/.apigen/
+
+# Python SDK (sdks/python) caches
+__pycache__/
+.pytest_cache/
+*.egg-info/

forjio_depllo-0.2.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.2.0
+- A route read by id next to its list is named `get` + the list's name: `client.api.projects_get_pipelines` (was `client.api.projects_pipelines_2`). Each old name stays as a deprecated alias.
+

forjio_depllo-0.2.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: forjio-depllo
+Version: 0.2.0
+Summary: Depllo SDK — Python client for the Depllo CI/CD REST API. Sister to @forjio/depllo (JS).
+Project-URL: Homepage, https://depllo.forjio.com/docs/sdk
+Project-URL: Repository, https://github.com/hachimi-cat/saas-depllo
+Author-email: Forjio <support@forjio.com>
+License: Proprietary
+Keywords: cd,ci,depllo,forjio,pipelines,sdk
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# forjio-depllo
+
+Python SDK for [Depllo](https://depllo.forjio.com) — GitLab-CI-style CI/CD
+for your GitHub repos. The sister of the [`@forjio/depllo`](https://www.npmjs.com/package/@forjio/depllo)
+JS SDK, with the same surface and behaviour.
+
+```bash
+pip install forjio-depllo
+```
+
+```python
+import os
+from forjio_depllo import DeplloClient, DeplloError
+
+# Bearer token from token= or the DEPLLO_TOKEN env var — use an sk_live_…
+# API key from Dashboard → API Keys (a Huudis access token works too).
+depllo = DeplloClient(token=os.environ["DEPLLO_TOKEN"])
+
+projects = depllo.api.projects_list()["data"]
+
+# Run a pipeline
+run = depllo.api.projects_create_pipelines(
+    projects[0]["id"], ref="main", variables={"DEPLOY_ENV": "staging"}
+)
+
+# Tail a job's log, check usage
+log = depllo.api.jobs_log("job_01hx…", from_=0)["data"]
+usage = depllo.api.usage_list()["data"]
+
+try:
+    depllo.api.pipelines_cancel("pipe_missing")
+except DeplloError as e:
+    print(e.status, e.code, e.message, e.request_id)
+```
+
+## What you get back
+
+Like the JS SDK, every method returns the Forjio envelope as a dict —
+`{"data": …, "error": None, "meta": {"requestId": …}}` — so read `["data"]`.
+A route that answers with bytes (a job artifact, a badge SVG) returns them as
+the data: `{"data": {"data": bytes, "contentType": …, "filename": …}, "error": None}`.
+A failed HTTP response raises `DeplloError` carrying the API's `code`
+(`NOT_FOUND`, `VALIDATION_ERROR`, `INVALID_TOKEN`, …), the HTTP `status`, the
+`message` and the `request_id`. Transport failures raise `DeplloError` with
+code `NETWORK_ERROR` / `TIMEOUT` and status `0`. Mutating calls send an
+`Idempotency-Key` automatically.
+
+## `client.api` — every feature route
+
+`client.api` has one method per Depllo feature route, named
+`<area>_<action>` — the same names as the CLI's `depllo api <area> <action>`
+commands. It is generated from the API spec (made from Depllo's own code), so
+it always covers the whole API: projects, pipelines, jobs, runners, schedules,
+variables, CI config, audit log, usage, billing and API keys. Path parameters
+are positional; query and body fields are keyword arguments (`json_body=`
+passes a whole body, fields given as arguments override it).
+
+See the [API reference](https://depllo.forjio.com/docs/api/reference) for every
+route and its fields, and [API authentication](https://depllo.forjio.com/docs/api-auth)
+for keys.
+
+## Options
+
+```python
+DeplloClient(
+    token=None,                                  # default: $DEPLLO_TOKEN
+    base_url="https://depllo.forjio.com/api/v1", # e.g. http://localhost:4200/api/v1
+    timeout=30.0,
+    http_client=None,                            # your own httpx.Client
+)
+```
+
+`client.request(method, path, query=None, body=None)` sends any other call
+(paths relative to the base URL, e.g. `"/projects"`).

forjio_depllo-0.2.0/README.md

@@ -0,0 +1,74 @@
+# forjio-depllo
+
+Python SDK for [Depllo](https://depllo.forjio.com) — GitLab-CI-style CI/CD
+for your GitHub repos. The sister of the [`@forjio/depllo`](https://www.npmjs.com/package/@forjio/depllo)
+JS SDK, with the same surface and behaviour.
+
+```bash
+pip install forjio-depllo
+```
+
+```python
+import os
+from forjio_depllo import DeplloClient, DeplloError
+
+# Bearer token from token= or the DEPLLO_TOKEN env var — use an sk_live_…
+# API key from Dashboard → API Keys (a Huudis access token works too).
+depllo = DeplloClient(token=os.environ["DEPLLO_TOKEN"])
+
+projects = depllo.api.projects_list()["data"]
+
+# Run a pipeline
+run = depllo.api.projects_create_pipelines(
+    projects[0]["id"], ref="main", variables={"DEPLOY_ENV": "staging"}
+)
+
+# Tail a job's log, check usage
+log = depllo.api.jobs_log("job_01hx…", from_=0)["data"]
+usage = depllo.api.usage_list()["data"]
+
+try:
+    depllo.api.pipelines_cancel("pipe_missing")
+except DeplloError as e:
+    print(e.status, e.code, e.message, e.request_id)
+```
+
+## What you get back
+
+Like the JS SDK, every method returns the Forjio envelope as a dict —
+`{"data": …, "error": None, "meta": {"requestId": …}}` — so read `["data"]`.
+A route that answers with bytes (a job artifact, a badge SVG) returns them as
+the data: `{"data": {"data": bytes, "contentType": …, "filename": …}, "error": None}`.
+A failed HTTP response raises `DeplloError` carrying the API's `code`
+(`NOT_FOUND`, `VALIDATION_ERROR`, `INVALID_TOKEN`, …), the HTTP `status`, the
+`message` and the `request_id`. Transport failures raise `DeplloError` with
+code `NETWORK_ERROR` / `TIMEOUT` and status `0`. Mutating calls send an
+`Idempotency-Key` automatically.
+
+## `client.api` — every feature route
+
+`client.api` has one method per Depllo feature route, named
+`<area>_<action>` — the same names as the CLI's `depllo api <area> <action>`
+commands. It is generated from the API spec (made from Depllo's own code), so
+it always covers the whole API: projects, pipelines, jobs, runners, schedules,
+variables, CI config, audit log, usage, billing and API keys. Path parameters
+are positional; query and body fields are keyword arguments (`json_body=`
+passes a whole body, fields given as arguments override it).
+
+See the [API reference](https://depllo.forjio.com/docs/api/reference) for every
+route and its fields, and [API authentication](https://depllo.forjio.com/docs/api-auth)
+for keys.
+
+## Options
+
+```python
+DeplloClient(
+    token=None,                                  # default: $DEPLLO_TOKEN
+    base_url="https://depllo.forjio.com/api/v1", # e.g. http://localhost:4200/api/v1
+    timeout=30.0,
+    http_client=None,                            # your own httpx.Client
+)
+```
+
+`client.request(method, path, query=None, body=None)` sends any other call
+(paths relative to the base URL, e.g. `"/projects"`).

forjio_depllo-0.2.0/forjio_depllo/__init__.py

@@ -0,0 +1,6 @@
+"""Depllo Python SDK — client for the Depllo CI/CD REST API."""
+from .client import DeplloClient
+from .errors import DeplloError
+
+__all__ = ["DeplloClient", "DeplloError"]
+__version__ = "0.2.0"

forjio_depllo-0.2.0/forjio_depllo/api_generated.py

@@ -0,0 +1,337 @@
+"""Every Depllo feature route, one method each — generated by apigen from
+backend/openapi.json. Do not edit by hand; regenerate after the API changes.
+
+Reach them as ``client.api.<area>_<action>(...)``. Each call goes through the
+client's own ``_apigen_request`` (its sign-in and response envelope).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class GeneratedApi:
+    """All 45 feature routes of the Depllo API."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def _call(self, method: str, path: str, query: Dict[str, Any], body: Optional[Dict[str, Any]]) -> Any:
+        query = {k: v for k, v in query.items() if v is not None}
+        return self._client._apigen_request(method, path, query=query or None, body=body)
+
+    def api_keys_create(self, *, name: Optional[str] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Create an API key. (POST /api/v1/api-keys).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it)."""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if name is not None:
+            payload["name"] = name
+        if "name" not in payload:
+            raise ValueError("api_keys_create needs name")
+        return self._call("POST", f"/api/v1/api-keys", {}, payload)
+
+    def api_keys_delete(self, id_: str) -> Any:
+        """Revoke an API key: requests with it get 401 from now on. (DELETE /api/v1/api-keys/{id})."""
+        return self._call("DELETE", f"/api/v1/api-keys/{_q(id_)}", {}, None)
+
+    def api_keys_list(self) -> Any:
+        """List the workspace's active API keys (newest first). (GET /api/v1/api-keys)."""
+        return self._call("GET", f"/api/v1/api-keys", {}, None)
+
+    def audit_list(self, *, action: Optional[Any] = None, actor: Optional[Any] = None, q: Optional[Any] = None) -> Any:
+        """List audit (GET /api/v1/audit)."""
+        return self._call("GET", f"/api/v1/audit", {"action": action, "actor": actor, "q": q}, None)
+
+    def billing_checkout(self, *, tier: Optional[str] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """POST /checkout {tier} — create a Plugipay hosted checkout session for a paid tier; the browser redirects to data.hostedUrl. (POST /api/v1/billing/checkout).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it).
+        tier: one of free, starter, growth, business"""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if tier is not None:
+            payload["tier"] = tier
+        if "tier" not in payload:
+            raise ValueError("billing_checkout needs tier")
+        return self._call("POST", f"/api/v1/billing/checkout", {}, payload)
+
+    def billing_list(self) -> Any:
+        """Current subscription (free default) + the tier table. (GET /api/v1/billing)."""
+        return self._call("GET", f"/api/v1/billing", {}, None)
+
+    def ci_lint(self, *, config_text: Optional[str] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Create a lint (POST /api/v1/ci/lint).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it)."""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if config_text is not None:
+            payload["configText"] = config_text
+        if "configText" not in payload:
+            raise ValueError("ci_lint needs config_text")
+        return self._call("POST", f"/api/v1/ci/lint", {}, payload)
+
+    def jobs_artifacts_download(self, id_: str, art_id: str) -> Any:
+        """List download (GET /api/v1/jobs/{id}/artifacts/{artId}/download)."""
+        return self._call("GET", f"/api/v1/jobs/{_q(id_)}/artifacts/{_q(art_id)}/download", {}, None)
+
+    def jobs_cancel(self, id_: str) -> Any:
+        """Cancel a job (POST /api/v1/jobs/{id}/cancel)."""
+        return self._call("POST", f"/api/v1/jobs/{_q(id_)}/cancel", {}, None)
+
+    def jobs_get(self, id_: str) -> Any:
+        """Get a job (GET /api/v1/jobs/{id})."""
+        return self._call("GET", f"/api/v1/jobs/{_q(id_)}", {}, None)
+
+    def jobs_log(self, id_: str, *, from_: Optional[Any] = None) -> Any:
+        """List log (GET /api/v1/jobs/{id}/log)."""
+        return self._call("GET", f"/api/v1/jobs/{_q(id_)}/log", {"from": from_}, None)
+
+    def jobs_log_stream(self, id_: str, *, from_: Optional[Any] = None) -> Any:
+        """SSE tail: replays chunks from ?from= then polls the DB every ~1s. (GET /api/v1/jobs/{id}/log/stream)."""
+        return self._call("GET", f"/api/v1/jobs/{_q(id_)}/log/stream", {"from": from_}, None)
+
+    def jobs_play(self, id_: str) -> Any:
+        """Play a job (POST /api/v1/jobs/{id}/play)."""
+        return self._call("POST", f"/api/v1/jobs/{_q(id_)}/play", {}, None)
+
+    def jobs_retry(self, id_: str) -> Any:
+        """Retry a job (POST /api/v1/jobs/{id}/retry)."""
+        return self._call("POST", f"/api/v1/jobs/{_q(id_)}/retry", {}, None)
+
+    def pipelines_cancel(self, id_: str) -> Any:
+        """Cancel a pipeline (POST /api/v1/pipelines/{id}/cancel)."""
+        return self._call("POST", f"/api/v1/pipelines/{_q(id_)}/cancel", {}, None)
+
+    def pipelines_get(self, id_: str) -> Any:
+        """Get a pipeline (GET /api/v1/pipelines/{id})."""
+        return self._call("GET", f"/api/v1/pipelines/{_q(id_)}", {}, None)
+
+    def pipelines_retry(self, id_: str) -> Any:
+        """Retry a pipeline (POST /api/v1/pipelines/{id}/retry)."""
+        return self._call("POST", f"/api/v1/pipelines/{_q(id_)}/retry", {}, None)
+
+    def projects_config(self, id_: str) -> Any:
+        """List config (GET /api/v1/projects/{id}/config)."""
+        return self._call("GET", f"/api/v1/projects/{_q(id_)}/config", {}, None)
+
+    def projects_create(self, *, name: Optional[str] = None, repo_full_name: Optional[str] = None, default_branch: Optional[str] = None, config_path: Optional[str] = None, clone_token: Optional[str] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Create a project (POST /api/v1/projects).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it)."""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if name is not None:
+            payload["name"] = name
+        if repo_full_name is not None:
+            payload["repoFullName"] = repo_full_name
+        if default_branch is not None:
+            payload["defaultBranch"] = default_branch
+        if config_path is not None:
+            payload["configPath"] = config_path
+        if clone_token is not None:
+            payload["cloneToken"] = clone_token
+        if "repoFullName" not in payload:
+            raise ValueError("projects_create needs repo_full_name")
+        return self._call("POST", f"/api/v1/projects", {}, payload)
+
+    def projects_create_pipelines(self, id_: str, *, ref: Optional[str] = None, variables: Optional[Dict[str, Any]] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Pipelines a project (POST /api/v1/projects/{id}/pipelines).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it)."""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if ref is not None:
+            payload["ref"] = ref
+        if variables is not None:
+            payload["variables"] = variables
+        if "ref" not in payload:
+            raise ValueError("projects_create_pipelines needs ref")
+        return self._call("POST", f"/api/v1/projects/{_q(id_)}/pipelines", {}, payload)
+
+    def projects_create_schedules(self, id_: str, *, cron: Optional[str] = None, ref: Optional[str] = None, active: Optional[bool] = None, variables: Optional[Dict[str, Any]] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Schedules a project (POST /api/v1/projects/{id}/schedules).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it)."""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if cron is not None:
+            payload["cron"] = cron
+        if ref is not None:
+            payload["ref"] = ref
+        if active is not None:
+            payload["active"] = active
+        if variables is not None:
+            payload["variables"] = variables
+        if "cron" not in payload:
+            raise ValueError("projects_create_schedules needs cron")
+        if "ref" not in payload:
+            raise ValueError("projects_create_schedules needs ref")
+        return self._call("POST", f"/api/v1/projects/{_q(id_)}/schedules", {}, payload)
+
+    def projects_create_variables(self, id_: str, *, key: Optional[str] = None, value: Optional[str] = None, backend: Optional[str] = None, masked: Optional[bool] = None, protected: Optional[bool] = None, file_type: Optional[bool] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Variables a project (POST /api/v1/projects/{id}/variables).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it).
+        backend: one of local, secronna"""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if key is not None:
+            payload["key"] = key
+        if value is not None:
+            payload["value"] = value
+        if backend is not None:
+            payload["backend"] = backend
+        if masked is not None:
+            payload["masked"] = masked
+        if protected is not None:
+            payload["protected"] = protected
+        if file_type is not None:
+            payload["fileType"] = file_type
+        if "key" not in payload:
+            raise ValueError("projects_create_variables needs key")
+        if "value" not in payload:
+            raise ValueError("projects_create_variables needs value")
+        return self._call("POST", f"/api/v1/projects/{_q(id_)}/variables", {}, payload)
+
+    def projects_delete(self, id_: str) -> Any:
+        """Delete a project (DELETE /api/v1/projects/{id})."""
+        return self._call("DELETE", f"/api/v1/projects/{_q(id_)}", {}, None)
+
+    def projects_delete_schedules(self, id_: str, sched_id: str) -> Any:
+        """Delete a schedule (DELETE /api/v1/projects/{id}/schedules/{schedId})."""
+        return self._call("DELETE", f"/api/v1/projects/{_q(id_)}/schedules/{_q(sched_id)}", {}, None)
+
+    def projects_delete_variables(self, id_: str, var_id: str) -> Any:
+        """Delete a variable (DELETE /api/v1/projects/{id}/variables/{varId})."""
+        return self._call("DELETE", f"/api/v1/projects/{_q(id_)}/variables/{_q(var_id)}", {}, None)
+
+    def projects_get(self, id_: str) -> Any:
+        """Get a project (GET /api/v1/projects/{id})."""
+        return self._call("GET", f"/api/v1/projects/{_q(id_)}", {}, None)
+
+    def projects_get_pipelines(self, id_: str, iid: str) -> Any:
+        """Get a pipeline (GET /api/v1/projects/{id}/pipelines/{iid})."""
+        return self._call("GET", f"/api/v1/projects/{_q(id_)}/pipelines/{_q(iid)}", {}, None)
+
+    def projects_list(self) -> Any:
+        """List projects (GET /api/v1/projects)."""
+        return self._call("GET", f"/api/v1/projects", {}, None)
+
+    def projects_pipelines(self, id_: str, *, q: Optional[Any] = None, ref: Optional[Any] = None, source: Optional[Any] = None, status: Optional[Any] = None) -> Any:
+        """List pipelines (GET /api/v1/projects/{id}/pipelines)."""
+        return self._call("GET", f"/api/v1/projects/{_q(id_)}/pipelines", {"q": q, "ref": ref, "source": source, "status": status}, None)
+
+    def projects_pipelines_cancel(self, id_: str, iid: str) -> Any:
+        """Cancel a pipeline (POST /api/v1/projects/{id}/pipelines/{iid}/cancel)."""
+        return self._call("POST", f"/api/v1/projects/{_q(id_)}/pipelines/{_q(iid)}/cancel", {}, None)
+
+    def projects_pipelines_retry(self, id_: str, iid: str) -> Any:
+        """Retry a pipeline (POST /api/v1/projects/{id}/pipelines/{iid}/retry)."""
+        return self._call("POST", f"/api/v1/projects/{_q(id_)}/pipelines/{_q(iid)}/retry", {}, None)
+
+    def projects_schedules(self, id_: str) -> Any:
+        """List schedules (GET /api/v1/projects/{id}/schedules)."""
+        return self._call("GET", f"/api/v1/projects/{_q(id_)}/schedules", {}, None)
+
+    def projects_set_config(self, id_: str, *, config_text: Optional[str] = None, commit_message: Optional[str] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Config a project (PUT /api/v1/projects/{id}/config).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it)."""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if config_text is not None:
+            payload["configText"] = config_text
+        if commit_message is not None:
+            payload["commitMessage"] = commit_message
+        if "configText" not in payload:
+            raise ValueError("projects_set_config needs config_text")
+        return self._call("PUT", f"/api/v1/projects/{_q(id_)}/config", {}, payload)
+
+    def projects_update_schedules(self, id_: str, sched_id: str, *, cron: Optional[str] = None, ref: Optional[str] = None, active: Optional[bool] = None, variables: Optional[Dict[str, Any]] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Update a schedule (PATCH /api/v1/projects/{id}/schedules/{schedId}).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it)."""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if cron is not None:
+            payload["cron"] = cron
+        if ref is not None:
+            payload["ref"] = ref
+        if active is not None:
+            payload["active"] = active
+        if variables is not None:
+            payload["variables"] = variables
+        return self._call("PATCH", f"/api/v1/projects/{_q(id_)}/schedules/{_q(sched_id)}", {}, payload)
+
+    def projects_update_variables(self, id_: str, var_id: str, *, value: Optional[str] = None, backend: Optional[str] = None, masked: Optional[bool] = None, protected: Optional[bool] = None, file_type: Optional[bool] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Update a variable (PATCH /api/v1/projects/{id}/variables/{varId}).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it).
+        backend: one of local, secronna"""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if value is not None:
+            payload["value"] = value
+        if backend is not None:
+            payload["backend"] = backend
+        if masked is not None:
+            payload["masked"] = masked
+        if protected is not None:
+            payload["protected"] = protected
+        if file_type is not None:
+            payload["fileType"] = file_type
+        return self._call("PATCH", f"/api/v1/projects/{_q(id_)}/variables/{_q(var_id)}", {}, payload)
+
+    def projects_variables(self, id_: str) -> Any:
+        """List variables (GET /api/v1/projects/{id}/variables)."""
+        return self._call("GET", f"/api/v1/projects/{_q(id_)}/variables", {}, None)
+
+    def projects_webhook(self, id_: str) -> Any:
+        """Idempotent webhook (re)create — the settings page "re-create" button. (POST /api/v1/projects/{id}/webhook)."""
+        return self._call("POST", f"/api/v1/projects/{_q(id_)}/webhook", {}, None)
+
+    def public_badges_pipeline_svg(self, badge_token: str) -> Any:
+        """List pipeline.svg (GET /api/v1/public/badges/{badgeToken}/pipeline.svg)."""
+        return self._call("GET", f"/api/v1/public/badges/{_q(badge_token)}/pipeline.svg", {}, None)
+
+    def runners_list(self) -> Any:
+        """List runners (GET /api/v1/runners)."""
+        return self._call("GET", f"/api/v1/runners", {}, None)
+
+    def runners_pause(self, id_: str) -> Any:
+        """Pause a runner (POST /api/v1/runners/{id}/pause)."""
+        return self._call("POST", f"/api/v1/runners/{_q(id_)}/pause", {}, None)
+
+    def runners_resume(self, id_: str) -> Any:
+        """Resume a runner (POST /api/v1/runners/{id}/resume)."""
+        return self._call("POST", f"/api/v1/runners/{_q(id_)}/resume", {}, None)
+
+    def schedules_delete(self, id_: str) -> Any:
+        """Delete a schedule (DELETE /api/v1/schedules/{id})."""
+        return self._call("DELETE", f"/api/v1/schedules/{_q(id_)}", {}, None)
+
+    def schedules_list(self) -> Any:
+        """List schedules (GET /api/v1/schedules)."""
+        return self._call("GET", f"/api/v1/schedules", {}, None)
+
+    def schedules_update(self, id_: str, *, cron: Optional[str] = None, ref: Optional[str] = None, active: Optional[bool] = None, variables: Optional[Dict[str, Any]] = None, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        """Update a schedule (PATCH /api/v1/schedules/{id}).
+        
+        Body fields are keyword arguments; `json_body=` passes the whole body (fields override it)."""
+        payload: Dict[str, Any] = dict(json_body or {})
+        if cron is not None:
+            payload["cron"] = cron
+        if ref is not None:
+            payload["ref"] = ref
+        if active is not None:
+            payload["active"] = active
+        if variables is not None:
+            payload["variables"] = variables
+        return self._call("PATCH", f"/api/v1/schedules/{_q(id_)}", {}, payload)
+
+    def usage_list(self) -> Any:
+        """List usage (GET /api/v1/usage)."""
+        return self._call("GET", f"/api/v1/usage", {}, None)
+
+    def projects_pipelines_2(self, *args: Any, **kwargs: Any) -> Any:
+        """Deprecated: the old name of ``projects_get_pipelines`` (GET /api/v1/projects/{id}/pipelines/{iid})."""
+        return self.projects_get_pipelines(*args, **kwargs)
+
+
+def _q(value: Any) -> str:
+    from urllib.parse import quote
+
+    return quote(str(value), safe="")

forjio_depllo-0.2.0/forjio_depllo/client.py

@@ -0,0 +1,166 @@
+"""Depllo client — the Python sister of ``@forjio/depllo`` (JS).
+
+Auth = Bearer token: a workspace API key (``sk_live_…``, Dashboard → API
+Keys) or a Huudis access token. Pass ``token=`` or set ``DEPLLO_TOKEN``.
+
+Like the JS SDK, every call returns the Forjio envelope
+``{"data", "error", "meta"}`` as a dict (read ``["data"]``); a route that
+answers with bytes (a job artifact, a badge SVG) returns
+``{"data": {"data": bytes, "contentType", "filename"}, "error": None}``. A
+failed HTTP response raises :class:`DeplloError` with the envelope's
+``error.code``.
+Mutating calls carry an ``Idempotency-Key``.
+
+Every feature route is a method on ``client.api`` (generated from the API
+spec — ``api_generated.py``)::
+
+    client = DeplloClient(token=os.environ["DEPLLO_TOKEN"])
+    projects = client.api.projects_list()["data"]
+    client.api.projects_create_pipelines(projects[0]["id"], ref="main")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import re
+import string
+import time
+from urllib.parse import unquote
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .api_generated import GeneratedApi
+from .errors import DeplloError
+
+DEFAULT_BASE_URL = "https://depllo.forjio.com/api/v1"
+_PREFIX = "/api/v1"
+
+
+def _idempotency_key() -> str:
+    tail = "".join(random.choices(string.ascii_lowercase + string.digits, k=10))
+    return f"sdk_{int(time.time() * 1000)}_{tail}"
+
+
+class DeplloClient:
+    """Depllo API client.
+
+    Parameters
+    ----------
+    token:
+        Bearer token — an ``sk_live_…`` API key or a Huudis access token.
+        Defaults to the ``DEPLLO_TOKEN`` environment variable.
+    base_url:
+        API base, default ``https://depllo.forjio.com/api/v1``.
+    timeout:
+        Per-request timeout in seconds (default 30).
+    http_client:
+        An ``httpx.Client`` to send requests with (tests, proxies, custom
+        transports). The client's own ``base_url`` is not used.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._token = token if token is not None else os.environ.get("DEPLLO_TOKEN")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._http = http_client
+        # Every feature route, one method each (generated from the API spec).
+        self.api = GeneratedApi(self)
+
+    def _apigen_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """The call behind ``client.api.*``: the same bearer token, idempotency key
+        and envelope as every other call. The spec's paths carry the /api/v1 prefix
+        the base URL already ends in."""
+        rel = path[len(_PREFIX):] if path.startswith(_PREFIX + "/") else path
+        return self.request(method, rel, query=query or None, body=body)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+    ) -> Dict[str, Any]:
+        """Send one request; return the envelope dict or raise :class:`DeplloError`."""
+        url = self._base_url + (path if path.startswith("/") else f"/{path}")
+        params = {k: v if isinstance(v, str) else json.dumps(v) for k, v in (query or {}).items() if v is not None}
+        headers = {"Accept": "application/json"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if method.upper() not in ("GET", "HEAD"):
+            headers["Idempotency-Key"] = _idempotency_key()
+        content = json.dumps(body).encode() if body is not None else None
+
+        try:
+            if self._http is not None:
+                resp = self._http.request(
+                    method, url, params=params, headers=headers, content=content, timeout=self._timeout
+                )
+            else:
+                resp = httpx.request(
+                    method, url, params=params, headers=headers, content=content, timeout=self._timeout
+                )
+        except httpx.TimeoutException as e:
+            raise DeplloError(f"request timed out: {e}", "TIMEOUT", 0) from e
+        except httpx.HTTPError as e:
+            raise DeplloError(f"request failed: {e}", "NETWORK_ERROR", 0) from e
+
+        content_type = resp.headers.get("content-type", "")
+        if resp.status_code < 400 and content_type and not re.search(r"json|text/(html|plain)", content_type, re.I):
+            # a file (an artifact, a badge SVG): an HTML or plain-text page at an API path
+            # is a wrong base URL or a proxy, and stays an error below
+            disposition = resp.headers.get("content-disposition", "")
+            star = re.search(r"filename\*=UTF-8''([^;]+)", disposition, re.I)
+            plain = re.search(r'filename="?([^";]+)"?', disposition, re.I)
+            return {
+                "data": {
+                    "data": resp.content,
+                    "contentType": content_type,
+                    "filename": unquote(star.group(1)) if star else (plain.group(1) if plain else None),
+                },
+                "error": None,
+            }
+
+        parsed: Any = None
+        if resp.content:
+            try:
+                parsed = resp.json()
+            except ValueError:
+                parsed = None
+        envelope = parsed if isinstance(parsed, dict) else None
+        error = envelope.get("error") if envelope else None
+        meta = envelope.get("meta") if envelope else None
+        request_id = meta.get("requestId") if isinstance(meta, dict) else None
+
+        if resp.status_code >= 400:
+            raise DeplloError(
+                (error or {}).get("message") or f"HTTP {resp.status_code} {resp.reason_phrase}".strip(),
+                (error or {}).get("code"),
+                resp.status_code,
+                request_id,
+            )
+        if envelope is None:
+            raise DeplloError("Empty or non-JSON response from server.", "INVALID_RESPONSE", resp.status_code)
+        return envelope
+
+
+__all__ = ["DeplloClient", "DeplloError", "DEFAULT_BASE_URL"]

forjio_depllo-0.2.0/forjio_depllo/errors.py

@@ -0,0 +1,43 @@
+"""Error class for the Depllo SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class DeplloError(Exception):
+    """Raised when a Depllo API call fails.
+
+    Attributes
+    ----------
+    message:
+        Human-readable description (the envelope's ``error.message``).
+    code:
+        Machine-readable code from the API envelope (``NOT_FOUND``,
+        ``VALIDATION_ERROR``, ``AUTH_REQUIRED``, ``INVALID_TOKEN``, ...), or
+        ``NETWORK_ERROR`` / ``TIMEOUT`` / ``INVALID_RESPONSE`` for SDK-side
+        failures. ``None`` when the server sent no envelope.
+    status:
+        HTTP status code (0 for transport-level failures).
+    request_id:
+        The ``meta.requestId`` echoed by the API, when present.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return (
+            f"DeplloError(code={self.code!r}, status={self.status!r}, "
+            f"message={self.message!r}, request_id={self.request_id!r})"
+        )

forjio_depllo-0.2.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "forjio-depllo"
+version = "0.2.0"
+description = "Depllo SDK — Python client for the Depllo CI/CD REST API. Sister to @forjio/depllo (JS)."
+authors = [{ name = "Forjio", email = "support@forjio.com" }]
+license = { text = "Proprietary" }
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27.0",
+]
+keywords = ["depllo", "forjio", "ci", "cd", "pipelines", "sdk"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0"]
+
+[project.urls]
+Homepage = "https://depllo.forjio.com/docs/sdk"
+Repository = "https://github.com/hachimi-cat/saas-depllo"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["forjio_depllo"]

forjio_depllo-0.2.0/tests/test_api_generated.py

@@ -0,0 +1,99 @@
+"""client.api: every feature route, one method each, generated from the API spec
+(scripts/apigen.sh). Calls carry the bearer token and idempotency key like every
+other request, and return the envelope like the JS SDK."""
+
+from __future__ import annotations
+
+import json
+from typing import List, Tuple
+from urllib.parse import parse_qs, urlsplit
+
+import httpx
+import pytest
+
+from forjio_depllo import DeplloClient
+from forjio_depllo.api_generated import GeneratedApi
+
+ENVELOPE = {"data": {"ok": True}, "error": None, "meta": {"requestId": "r"}}
+
+
+def _client(token: str = "sk_live_test", base_url: str = "https://depllo.test/api/v1") -> Tuple[DeplloClient, List[httpx.Request]]:
+    seen: List[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return httpx.Response(200, json=ENVELOPE)
+
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    return DeplloClient(token=token, base_url=base_url, http_client=http), seen
+
+
+def test_is_mounted_on_the_client() -> None:
+    client, _ = _client()
+    assert isinstance(client.api, GeneratedApi)
+
+
+def test_create_sends_the_fields_depllo_validates_with_the_bearer_key() -> None:
+    client, seen = _client()
+    out = client.api.projects_create_variables("proj_1", key="API_URL", value="x", masked=True)
+    assert out == ENVELOPE
+    request = seen[0]
+    assert (request.method, request.url.path) == ("POST", "/api/v1/projects/proj_1/variables")
+    assert json.loads(request.content) == {"key": "API_URL", "value": "x", "masked": True}
+    assert request.headers["authorization"] == "Bearer sk_live_test"
+    assert request.headers["content-type"] == "application/json"
+    assert request.headers["idempotency-key"].startswith("sdk_")
+
+
+def test_path_parameters_are_escaped_and_query_fields_go_in_the_query() -> None:
+    client, seen = _client(base_url="http://localhost:4200/api/v1/")
+    client.api.projects_delete_schedules("proj 1", "sch/2")
+    client.api.jobs_log("job_1", from_=5)
+    assert seen[0].method == "DELETE"
+    assert seen[0].url.raw_path.decode() == "/api/v1/projects/proj%201/schedules/sch%2F2"
+    assert seen[1].url.path == "/api/v1/jobs/job_1/log"
+    assert parse_qs(urlsplit(str(seen[1].url)).query) == {"from": ["5"]}
+    assert seen[1].method == "GET"
+    assert "idempotency-key" not in seen[1].headers
+    assert seen[1].content == b""
+
+
+def test_json_body_passes_the_whole_body_and_fields_override_it() -> None:
+    client, seen = _client()
+    client.api.api_keys_create(json_body={"name": "from-body"}, name="catent")
+    assert json.loads(seen[0].content) == {"name": "catent"}
+
+
+def test_a_required_field_is_asked_for() -> None:
+    client, _ = _client()
+    with pytest.raises(ValueError, match="needs"):
+        client.api.api_keys_create()
+
+
+def test_every_feature_route_has_a_method() -> None:
+    client, _ = _client()
+    methods = [n for n in dir(client.api) if not n.startswith("_")]
+    assert len(methods) >= 45
+    for name in ("projects_list", "projects_create_pipelines", "pipelines_cancel", "jobs_log", "runners_list", "api_keys_list"):
+        assert name in methods
+
+
+def _replying(response: httpx.Response) -> DeplloClient:
+    http = httpx.Client(transport=httpx.MockTransport(lambda request: response))
+    return DeplloClient(token="sk_live_test", base_url="https://depllo.test/api/v1", http_client=http)
+
+
+def test_a_file_route_returns_the_bytes_in_the_envelope() -> None:
+    client = _replying(
+        httpx.Response(200, content=b"PK\x03\x04", headers={"content-type": "application/zip", "content-disposition": 'attachment; filename="dist.zip"'})
+    )
+    out = client.api.jobs_artifacts_download("job_1", "art_1")
+    assert out == {"data": {"data": b"PK\x03\x04", "contentType": "application/zip", "filename": "dist.zip"}, "error": None}
+
+
+def test_an_html_page_at_an_api_path_is_still_an_error() -> None:
+    from forjio_depllo import DeplloError
+
+    client = _replying(httpx.Response(200, content=b"<html></html>", headers={"content-type": "text/html"}))
+    with pytest.raises(DeplloError, match="non-JSON"):
+        client.api.projects_list()

forjio_depllo-0.2.0/tests/test_client.py

@@ -0,0 +1,89 @@
+"""DeplloClient: token, base URL, envelope and errors."""
+
+from __future__ import annotations
+
+from typing import List
+
+import httpx
+import pytest
+
+from forjio_depllo import DeplloClient, DeplloError
+
+
+def _http(status: int, body: object = None, *, text: str | None = None, seen: List[httpx.Request] | None = None) -> httpx.Client:
+    def handler(request: httpx.Request) -> httpx.Response:
+        if seen is not None:
+            seen.append(request)
+        if text is not None:
+            return httpx.Response(status, text=text)
+        return httpx.Response(status, json=body)
+
+    return httpx.Client(transport=httpx.MockTransport(handler))
+
+
+def test_token_defaults_to_the_depllo_token_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("DEPLLO_TOKEN", "sk_live_env")
+    seen: List[httpx.Request] = []
+    client = DeplloClient(http_client=_http(200, {"data": [], "error": None}, seen=seen))
+    client.request("GET", "/projects")
+    assert seen[0].headers["authorization"] == "Bearer sk_live_env"
+    assert str(seen[0].url) == "https://depllo.forjio.com/api/v1/projects"
+
+
+def test_no_token_sends_no_authorization_header(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("DEPLLO_TOKEN", raising=False)
+    seen: List[httpx.Request] = []
+    DeplloClient(http_client=_http(200, {"data": None, "error": None}, seen=seen)).request("GET", "/usage")
+    assert "authorization" not in seen[0].headers
+
+
+def test_returns_the_envelope_like_the_js_sdk() -> None:
+    env = {"data": {"id": "proj_1"}, "error": None, "meta": {"requestId": "req_1"}}
+    client = DeplloClient(token="t", http_client=_http(200, env))
+    assert client.api.projects_get("proj_1") == env
+
+
+def test_error_envelope_raises_depllo_error() -> None:
+    body = {"data": None, "error": {"code": "INVALID_TOKEN", "message": "Invalid API key"}, "meta": {"requestId": "req_9"}}
+    client = DeplloClient(token="sk_live_revoked", http_client=_http(401, body))
+    with pytest.raises(DeplloError) as exc:
+        client.api.projects_list()
+    assert (exc.value.code, exc.value.status, exc.value.message, exc.value.request_id) == (
+        "INVALID_TOKEN",
+        401,
+        "Invalid API key",
+        "req_9",
+    )
+
+
+def test_non_json_error_reports_the_status() -> None:
+    client = DeplloClient(token="t", http_client=_http(502, text="<html>bad gateway</html>"))
+    with pytest.raises(DeplloError) as exc:
+        client.api.usage_list()
+    assert exc.value.status == 502
+    assert exc.value.code is None
+    assert "HTTP 502" in exc.value.message
+
+
+def test_non_json_success_is_an_invalid_response() -> None:
+    client = DeplloClient(token="t", http_client=_http(200, text="ok"))
+    with pytest.raises(DeplloError) as exc:
+        client.request("GET", "/usage")
+    assert exc.value.code == "INVALID_RESPONSE"
+
+
+def test_transport_failure_is_a_network_error() -> None:
+    def boom(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("refused", request=request)
+
+    client = DeplloClient(token="t", http_client=httpx.Client(transport=httpx.MockTransport(boom)))
+    with pytest.raises(DeplloError) as exc:
+        client.api.runners_list()
+    assert (exc.value.code, exc.value.status) == ("NETWORK_ERROR", 0)
+
+
+def test_query_values_are_sent_as_the_js_sdk_sends_them() -> None:
+    seen: List[httpx.Request] = []
+    client = DeplloClient(token="t", http_client=_http(200, {"data": [], "error": None}, seen=seen))
+    client.request("GET", "/audit", query={"limit": 5, "flag": True, "action": "x", "skip": None})
+    assert dict(seen[0].url.params) == {"limit": "5", "flag": "true", "action": "x"}