socialcli 0.3.0__tar.gz

socialcli-0.3.0/.gitignore

@@ -0,0 +1,38 @@
+# Never publish credentials, machine state or creator workspaces.
+.env
+.env.*
+**/.secrets/
+**/.secrets*
+**/.socialctl/
+**/accounts.yml
+!socialctl/plantillas/accounts.yml
+**/resultado.json*
+**/historial.md
+**/metricas/
+!socialctl/metricas/
+!socialctl/metricas/**
+**/media/
+**/posts/
+.cache/
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.DS_Store
+*.pem
+*.key
+*.sqlite3*
+*.mp4
+*.mov
+*.wav
+*.mp3
+
+.worktrees/
+.superpowers/
+
+**/service.env
+**/auth.env
+**/database.env

socialcli-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Engels Florentino
+
+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.

socialcli-0.3.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: socialcli
+Version: 0.3.0
+Summary: SocialCli: publish and manage creator-owned social content from the terminal.
+Project-URL: Homepage, https://socialcli.app
+Project-URL: Repository, https://github.com/engels-florentino/SocialCli
+Project-URL: Issues, https://github.com/engels-florentino/SocialCli/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: keyring>=25.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: typer>=0.27.2
+Provides-Extra: connection-server
+Requires-Dist: cryptography>=43; extra == 'connection-server'
+Requires-Dist: fastapi>=0.115; extra == 'connection-server'
+Requires-Dist: uvicorn>=0.30; extra == 'connection-server'
+Provides-Extra: headless-credentials
+Requires-Dist: cryptography>=43; extra == 'headless-credentials'
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="docs/assets/socialcli-logo.png" width="128" height="128" alt="SocialCli logo: S and terminal prompt &gt;_"></p>
+
+# SocialCli
+
+**Current source version: 0.3.0.** SocialCli SaaS is the current SocialCli
+product. The repository root on `main` is its single development workspace;
+the CLI, hosted connection service and account/billing components live together
+here. Earlier versions remain in Git history for reference and migration.
+
+**A social media CLI for AI agents and the people who supervise them.** Use a terminal-enabled assistant to inspect your accounts, draft posts and prepare user-approved actions on YouTube, Facebook, Instagram and TikTok. SocialCli provides concrete commands, validation, previews and local records for creators and teams.
+
+[Website and documentation](https://socialcli.app/) · [AI agent guide](docs/ai-agents.md) · [Setup](SETUP.md) · [Security](SECURITY.md) · [TikTok limitations](docs/tiktok-review.md)
+
+## Work with your AI agent
+
+Install SocialCli where your agent can run shell commands, point it at your creator workspace and name the brand explicitly. Try:
+
+> Check MyBrand's TikTok connection and available capabilities. Summarize missing permissions without publishing.
+
+> Use MyBrand/media/my-video.mp4, draft a caption in our brand voice and show the complete TikTok dry-run preview. Wait for my approval before sending it.
+
+> Inspect my YouTube video and propose a description change. Show the proposal and fingerprint before applying anything.
+
+[The AI agent guide](docs/ai-agents.md) includes the commands behind these prompts, workspace instructions and the approval workflow. JSON is available on supported diagnostics and inventory commands. SocialCli runs through the agent's shell; it does not include an AI model or an MCP server. Your agent must keep credentials private and preserve the distinction between confirmed, pending and uncertain results.
+
+## Public SaaS pilot
+
+Copy this line into your terminal-enabled AI assistant:
+
+> Install SocialCli: https://socialcli.app/agents
+
+The installation guide verifies the selected release download and uses
+https://pilot.socialcli.app for email sign-in, assistant approval and account
+connections. The pilot supports eligible YouTube, Facebook, Instagram and TikTok
+test accounts. Provider verification is separate from the OAuth publishing
+toggle; Meta development access and TikTok sandbox restrictions still apply.
+Stripe uses test mode. Planned access costs
+USD 10/month after 14 free days from the first successful connection. No real
+subscriptions are collected in this pilot.
+
+The current client release target is **0.3.0** (published first to TestPyPI and
+then to PyPI through the reviewed release workflow). The compatible hosted
+runtime is `socialcli-saas-candidate:45fda63`. The client's wheel and
+source archive are verified against the
+reviewed build hashes before publication. Provider commercial approvals and live
+billing cutover remain separate from package publication. See the
+[release record](deploy/saas/release.md).
+The [stable release scope](docs/stable-scope.md) excludes unsupported automatic
+operations; disabled research catalogue entries are not offered features.
+
+## Install and connect
+
+Use the short installation prompt above. Your assistant needs a persistent shell,
+Python 3.11+, macOS or Linux and protected credential storage. The bootstrap
+verifies the exact wheel before installation and resolves dependencies from normal
+PyPI. Video validation also requires ffprobe from FFmpeg.
+
+The setup order is **brand → credentials → account login → connect**. Ask for the
+brand name explicitly, preserve its workspace outside the application repository,
+and read socialcli agent-guide setup. The account step uses
+https://pilot.socialcli.app. Give each printed link directly to the user without
+opening it; the user signs in and approves the assistant and provider account in
+their browser. Never request OTPs or provider tokens in chat.
+
+```bash
+socialcli account login --brand MyBrand --service https://pilot.socialcli.app --no-browser
+socialcli connect youtube --brand MyBrand --management --analytics --no-browser
+socialcli connections --brand MyBrand --json
+```
+
+Run these after creating the brand and configuring protected credentials as shown
+in the [connection guide](docs/connections.md). OS keyring and explicit encrypted
+file storage are supported; there is no silent fallback. Use the same workspace,
+store and key in later conversations. Connecting never authorizes publication.
+
+For source development use uv sync --group dev, uv run pytest and
+uv run socialcli --help in the repository. [SETUP.md](SETUP.md) covers independent
+operator apps; customers of the hosted SaaS do not need developer credentials.
+
+## Review and publish
+
+Create `MyBrand/posts/my-video/post.yml` and place your produced file in `MyBrand/media/`. [Example](examples/post.yml):
+
+```yaml
+slug: my-video
+campaign: clip-vertical
+platforms:
+  tiktok:
+    body: "A story worth telling."
+    hashtags: []
+    media: ["my-video.mp4"]
+```
+
+```bash
+socialcli publish my-video --brand MyBrand --only tiktok --dry-run
+socialcli publish my-video --brand MyBrand --only tiktok
+```
+
+The first command displays a preview without publishing. The second displays it again and requests confirmation. TikTok defaults to **inbox**: the video reaches your inbox and you complete publication in TikTok. A pending confirmation status does not mean the video is published.
+
+## Features
+
+- Separate brands, local credentials and token renewal where supported by the provider.
+- File validation, previews and confirmation before publication.
+- Publishing, inventory, metrics and content management, subject to each platform's permissions and capabilities.
+- Scheduling with approval checks and handling of ambiguous results to reduce duplicates.
+- Adapter tests with simulated responses that do not publish to real accounts.
+
+Each command group documents its options with `socialcli <group> --help`. The internal Python package remains `socialctl`; the public command is `socialcli`. `socialctl` remains a compatibility alias.
+
+## Status and limitations
+
+Public source code does not grant production API access. Each platform imposes requirements, permissions, quotas and reviews. SocialCli **has no accredited TikTok production approval**. Direct Post is disabled and excluded from the current offer; creator-reviewed inbox upload is supported. Direct Post still lacks the complete user experience controls described in [the technical review](docs/tiktok-review.md). Publishing this repository does not satisfy those requirements.
+
+Metrics and management permissions are separate from publishing permissions. A valid connection does not demonstrate authorization for every feature. Check capabilities and verify remote results before retrying an uncertain operation.
+
+## Contributing and support
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md). For questions or bugs, open an [issue](https://github.com/engels-florentino/SocialCli/issues) without tokens, keys, `.env` files or private logs. Report vulnerabilities through the private channel described in [SECURITY.md](SECURITY.md).
+
+[MIT license](LICENSE). SocialCli is not affiliated with the platforms it integrates.
+
+## Account, media and scheduling
+
+[Account](https://socialcli.app/account/) lets you manage your brand, connected
+platforms, approved assistants and billing. The plan covers one brand and one
+account per supported platform. Subscribe during the 14-day trial without losing
+its remaining days; the first USD 10 payment is due at the original trial end.
+The current pilot uses Stripe test mode and collects no live payments.
+
+Instagram can use automatic 15-minute temporary staging on florentino.pro for
+supplied originals, up to 512 MiB and subject to quotas. Files are excluded from
+backups and removed after the operation or by expiry cleanup. Local schedules
+keep the original on the customer runner and stage it only at dispatch. Verified
+native scheduling uses provider storage where supported. See
+[media handling](MEDIA-INGESTION.md) and [scheduling](NATIVE-SCHEDULING.md).
+
+Read the packaged socialcli agent-guide topic for the operation, the
+[capability matrix](docs/capabilities.md), [security](SECURITY.md),
+[privacy policy](https://socialcli.app/privacy.html) and
+[terms](https://socialcli.app/terms.html). Historical 0.2.6 releases and deploy
+records are migration evidence, not a second current product.
+
+SocialCli is operated by **Florentino.pro**. For private account, billing or privacy
+questions, contact [admin@socialcli.app](mailto:admin@socialcli.app).

socialcli-0.3.0/README.md

@@ -0,0 +1,145 @@
+<p align="center"><img src="docs/assets/socialcli-logo.png" width="128" height="128" alt="SocialCli logo: S and terminal prompt &gt;_"></p>
+
+# SocialCli
+
+**Current source version: 0.3.0.** SocialCli SaaS is the current SocialCli
+product. The repository root on `main` is its single development workspace;
+the CLI, hosted connection service and account/billing components live together
+here. Earlier versions remain in Git history for reference and migration.
+
+**A social media CLI for AI agents and the people who supervise them.** Use a terminal-enabled assistant to inspect your accounts, draft posts and prepare user-approved actions on YouTube, Facebook, Instagram and TikTok. SocialCli provides concrete commands, validation, previews and local records for creators and teams.
+
+[Website and documentation](https://socialcli.app/) · [AI agent guide](docs/ai-agents.md) · [Setup](SETUP.md) · [Security](SECURITY.md) · [TikTok limitations](docs/tiktok-review.md)
+
+## Work with your AI agent
+
+Install SocialCli where your agent can run shell commands, point it at your creator workspace and name the brand explicitly. Try:
+
+> Check MyBrand's TikTok connection and available capabilities. Summarize missing permissions without publishing.
+
+> Use MyBrand/media/my-video.mp4, draft a caption in our brand voice and show the complete TikTok dry-run preview. Wait for my approval before sending it.
+
+> Inspect my YouTube video and propose a description change. Show the proposal and fingerprint before applying anything.
+
+[The AI agent guide](docs/ai-agents.md) includes the commands behind these prompts, workspace instructions and the approval workflow. JSON is available on supported diagnostics and inventory commands. SocialCli runs through the agent's shell; it does not include an AI model or an MCP server. Your agent must keep credentials private and preserve the distinction between confirmed, pending and uncertain results.
+
+## Public SaaS pilot
+
+Copy this line into your terminal-enabled AI assistant:
+
+> Install SocialCli: https://socialcli.app/agents
+
+The installation guide verifies the selected release download and uses
+https://pilot.socialcli.app for email sign-in, assistant approval and account
+connections. The pilot supports eligible YouTube, Facebook, Instagram and TikTok
+test accounts. Provider verification is separate from the OAuth publishing
+toggle; Meta development access and TikTok sandbox restrictions still apply.
+Stripe uses test mode. Planned access costs
+USD 10/month after 14 free days from the first successful connection. No real
+subscriptions are collected in this pilot.
+
+The current client release target is **0.3.0** (published first to TestPyPI and
+then to PyPI through the reviewed release workflow). The compatible hosted
+runtime is `socialcli-saas-candidate:45fda63`. The client's wheel and
+source archive are verified against the
+reviewed build hashes before publication. Provider commercial approvals and live
+billing cutover remain separate from package publication. See the
+[release record](deploy/saas/release.md).
+The [stable release scope](docs/stable-scope.md) excludes unsupported automatic
+operations; disabled research catalogue entries are not offered features.
+
+## Install and connect
+
+Use the short installation prompt above. Your assistant needs a persistent shell,
+Python 3.11+, macOS or Linux and protected credential storage. The bootstrap
+verifies the exact wheel before installation and resolves dependencies from normal
+PyPI. Video validation also requires ffprobe from FFmpeg.
+
+The setup order is **brand → credentials → account login → connect**. Ask for the
+brand name explicitly, preserve its workspace outside the application repository,
+and read socialcli agent-guide setup. The account step uses
+https://pilot.socialcli.app. Give each printed link directly to the user without
+opening it; the user signs in and approves the assistant and provider account in
+their browser. Never request OTPs or provider tokens in chat.
+
+```bash
+socialcli account login --brand MyBrand --service https://pilot.socialcli.app --no-browser
+socialcli connect youtube --brand MyBrand --management --analytics --no-browser
+socialcli connections --brand MyBrand --json
+```
+
+Run these after creating the brand and configuring protected credentials as shown
+in the [connection guide](docs/connections.md). OS keyring and explicit encrypted
+file storage are supported; there is no silent fallback. Use the same workspace,
+store and key in later conversations. Connecting never authorizes publication.
+
+For source development use uv sync --group dev, uv run pytest and
+uv run socialcli --help in the repository. [SETUP.md](SETUP.md) covers independent
+operator apps; customers of the hosted SaaS do not need developer credentials.
+
+## Review and publish
+
+Create `MyBrand/posts/my-video/post.yml` and place your produced file in `MyBrand/media/`. [Example](examples/post.yml):
+
+```yaml
+slug: my-video
+campaign: clip-vertical
+platforms:
+  tiktok:
+    body: "A story worth telling."
+    hashtags: []
+    media: ["my-video.mp4"]
+```
+
+```bash
+socialcli publish my-video --brand MyBrand --only tiktok --dry-run
+socialcli publish my-video --brand MyBrand --only tiktok
+```
+
+The first command displays a preview without publishing. The second displays it again and requests confirmation. TikTok defaults to **inbox**: the video reaches your inbox and you complete publication in TikTok. A pending confirmation status does not mean the video is published.
+
+## Features
+
+- Separate brands, local credentials and token renewal where supported by the provider.
+- File validation, previews and confirmation before publication.
+- Publishing, inventory, metrics and content management, subject to each platform's permissions and capabilities.
+- Scheduling with approval checks and handling of ambiguous results to reduce duplicates.
+- Adapter tests with simulated responses that do not publish to real accounts.
+
+Each command group documents its options with `socialcli <group> --help`. The internal Python package remains `socialctl`; the public command is `socialcli`. `socialctl` remains a compatibility alias.
+
+## Status and limitations
+
+Public source code does not grant production API access. Each platform imposes requirements, permissions, quotas and reviews. SocialCli **has no accredited TikTok production approval**. Direct Post is disabled and excluded from the current offer; creator-reviewed inbox upload is supported. Direct Post still lacks the complete user experience controls described in [the technical review](docs/tiktok-review.md). Publishing this repository does not satisfy those requirements.
+
+Metrics and management permissions are separate from publishing permissions. A valid connection does not demonstrate authorization for every feature. Check capabilities and verify remote results before retrying an uncertain operation.
+
+## Contributing and support
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md). For questions or bugs, open an [issue](https://github.com/engels-florentino/SocialCli/issues) without tokens, keys, `.env` files or private logs. Report vulnerabilities through the private channel described in [SECURITY.md](SECURITY.md).
+
+[MIT license](LICENSE). SocialCli is not affiliated with the platforms it integrates.
+
+## Account, media and scheduling
+
+[Account](https://socialcli.app/account/) lets you manage your brand, connected
+platforms, approved assistants and billing. The plan covers one brand and one
+account per supported platform. Subscribe during the 14-day trial without losing
+its remaining days; the first USD 10 payment is due at the original trial end.
+The current pilot uses Stripe test mode and collects no live payments.
+
+Instagram can use automatic 15-minute temporary staging on florentino.pro for
+supplied originals, up to 512 MiB and subject to quotas. Files are excluded from
+backups and removed after the operation or by expiry cleanup. Local schedules
+keep the original on the customer runner and stage it only at dispatch. Verified
+native scheduling uses provider storage where supported. See
+[media handling](MEDIA-INGESTION.md) and [scheduling](NATIVE-SCHEDULING.md).
+
+Read the packaged socialcli agent-guide topic for the operation, the
+[capability matrix](docs/capabilities.md), [security](SECURITY.md),
+[privacy policy](https://socialcli.app/privacy.html) and
+[terms](https://socialcli.app/terms.html). Historical 0.2.6 releases and deploy
+records are migration evidence, not a second current product.
+
+SocialCli is operated by **Florentino.pro**. For private account, billing or privacy
+questions, contact [admin@socialcli.app](mailto:admin@socialcli.app).

socialcli-0.3.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "socialcli"
+version = "0.3.0"
+description = "SocialCli: publish and manage creator-owned social content from the terminal."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.1",
+    "keyring>=25.0",
+    "pydantic>=2.13.5",
+    "pyyaml>=6.0.3",
+    "typer>=0.27.2",
+]
+
+[project.scripts]
+socialcli = "socialctl.cli:app"
+socialctl = "socialctl.cli:app"
+
+[project.urls]
+Homepage = "https://socialcli.app"
+Repository = "https://github.com/engels-florentino/SocialCli"
+Issues = "https://github.com/engels-florentino/SocialCli/issues"
+
+[project.optional-dependencies]
+headless-credentials = ["cryptography>=43"]
+connection-server = [
+    "cryptography>=43",
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+]
+
+[dependency-groups]
+dev = [
+    "cryptography>=43",
+    "fastapi>=0.115",
+    "pytest>=9.1.1",
+    "respx>=0.23.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["socialctl"]
+
+# Do not rely on VCS ignore discovery inside a linked worktree for sdist safety.
+[tool.hatch.build.targets.sdist]
+only-include = ["socialctl", "pyproject.toml", "README.md", "LICENSE"]
+exclude = ["**/.env", "**/.env.*", "**/*.env", "**/.secrets/**", "**/__pycache__/**", "**/*.pyc", "**/*.key", "**/*.pem", "**/*.sqlite3*"]

socialcli-0.3.0/socialctl/__main__.py

@@ -0,0 +1,6 @@
+"""Run the installed socialcli interface through its Python package."""
+
+from socialctl.cli import app
+
+if __name__ == "__main__":
+    app()

socialcli-0.3.0/socialctl/adapters/__init__.py

@@ -0,0 +1,6 @@
+'Importing this package registers all four adapters in ADAPTADORES.'
+
+from __future__ import annotations
+
+from socialctl.adapters import facebook, instagram, tiktok, youtube  # noqa: F401
+from socialctl.adapters.base import ADAPTADORES, Adapter  # noqa: F401

socialcli-0.3.0/socialctl/adapters/base.py

@@ -0,0 +1,68 @@
+'Common interface for platform adapters.'
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import httpx
+
+from socialctl.brands import Brand
+from socialctl.formatter import validar_privacidad, validar_texto
+from socialctl.media import validar_media
+from socialctl.models import Platform, PlatformPost, PostResult, ValidationError
+
+_SIN_VALOR = object()
+
+
+def _sigue_siendo_abstracta(cls: type) -> bool:
+    'Return whether cls still has an unimplemented abstract method.'
+    for nombre in dir(cls):
+        try:
+            miembro = getattr(cls, nombre)
+        except AttributeError:
+            continue
+        if getattr(miembro, "__isabstractmethod__", False):
+            return True
+    return False
+
+
+class Adapter(ABC):
+    'Common validation and publication interface for every supported platform.'
+
+    platform: Platform
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        'Require every concrete adapter to declare a valid Platform value.'
+        super().__init_subclass__(**kwargs)
+
+        if _sigue_siendo_abstracta(cls):
+            return
+
+        valor = getattr(cls, "platform", _SIN_VALOR)
+
+        if valor is _SIN_VALOR:
+            raise TypeError(
+                f"{cls.__name__} does not declare 'platform': every concrete "
+                'Adapter must assign a Platform value. The type annotation '
+                'inherited from Adapter is insufficient; assign a value '
+                "(for example, 'platform = Platform.TIKTOK')."
+            )
+
+        if not isinstance(valor, Platform):
+            raise TypeError(
+                f"{cls.__name__} declares 'platform = {valor!r}', which is not a "
+                'Platform member. Use a Platform value '
+                '(for example, Platform.TIKTOK).'
+            )
+
+    def validate(self, post: PlatformPost, brand: Brand) -> list[ValidationError]:
+        'Validate platform content limits without network access.'
+        return validar_texto(post) + validar_media(post) + validar_privacidad(post)
+
+    @abstractmethod
+    def publish(self, post: PlatformPost, brand: Brand, client: httpx.Client) -> PostResult:
+        'Publish the post only after validate() returns no errors.'
+
+
+ADAPTADORES: dict[Platform, type[Adapter]] = {}
+'Registry of adapter classes keyed by Platform. Consumers instantiate ADAPTADORES[platform]() without arguments; concrete adapters must not require constructor parameters.'

socialcli-0.3.0/socialctl/adapters/errores.py

@@ -0,0 +1,56 @@
+'Extract actionable provider error text while redacting known credentials.\n\nPrefer the provider error.message field when it is a nonempty string. Otherwise\nretain a bounded response-body excerpt. Redact literal and URL-encoded known\nsecrets of at least eight characters, including proxy responses that reflect\nrequest URLs or bodies. This keeps diagnostics useful without disclosing tokens.'
+
+from __future__ import annotations
+
+import urllib.parse
+
+import httpx
+
+# Recorte razonable para no volcar cuerpos de respuesta gigantes (p. ej. una
+# página de error HTML de un proxy intermedio) en un mensaje de error.
+_LONGITUD_MAXIMA_CUERPO_ERROR = 500
+
+_MARCA_REDACCION = '[TOKEN REDACTED]'
+
+# Ver docstring del módulo: evita que un "secreto" de relleno (típicamente
+# muy corto en los tests que no versan sobre seguridad, p. ej. la cadena
+# "t") acabe redactando subcadenas normales de un mensaje legítimo. Ningún
+# token real de las cuatro redes que publica este proyecto es tan corto.
+_LONGITUD_MINIMA_SECRETO_REDACTABLE = 8
+
+
+def _redactar_secretos(texto: str, secretos: tuple[str, ...]) -> str:
+    'Redact literal and URL-encoded occurrences of each sufficiently long secret.'
+    for secreto in secretos:
+        if not secreto or len(secreto) < _LONGITUD_MINIMA_SECRETO_REDACTABLE:
+            continue
+        texto = texto.replace(secreto, _MARCA_REDACCION)
+        codificado = urllib.parse.quote(secreto, safe="")
+        if codificado != secreto:
+            texto = texto.replace(codificado, _MARCA_REDACCION)
+    return texto
+
+
+def mensaje_de_error(respuesta: httpx.Response, *secretos: str) -> str:
+    'Return bounded provider error text with known credentials redacted.'
+    try:
+        mensaje = respuesta.json()["error"]["message"]
+        if isinstance(mensaje, str) and mensaje:
+            return _redactar_secretos(mensaje, secretos)
+    except Exception:
+        pass
+
+    try:
+        cuerpo = respuesta.text.strip()
+    except Exception:
+        cuerpo = ""
+
+    cuerpo = _redactar_secretos(cuerpo, secretos)
+
+    if not cuerpo:
+        return f"HTTP {respuesta.status_code}"
+
+    if len(cuerpo) > _LONGITUD_MAXIMA_CUERPO_ERROR:
+        cuerpo = cuerpo[:_LONGITUD_MAXIMA_CUERPO_ERROR] + "…"
+
+    return f"HTTP {respuesta.status_code}: {cuerpo}"