Publicar artefactos

import { Aside } from ‘@astrojs/starlight/components’;

Un artefacto es un bundle versionado de archivos servido en una URL en vivo. Publicar el mismo slug de nuevo crea una nueva versión — las anteriores siguen accesibles.

Publicar

POST /v1/publish con tus archivos:

{
  "name": "My App",
  "slug": "my-app",
  "entrypoint": "index.html",
  "visibility": "public",
  "files": [
    { "path": "index.html", "content": "<!DOCTYPE html>…", "mime": "text/html", "encoding": "utf8" }
  ]
}

Omití el slug y ShareOut genera uno. Mirá el schema completo en la referencia de la API.

URLs para compartir

La respuesta de publish incluye un objeto deployment con las URLs en vivo:

Campo	Uso
deployment.subdomain_url	Link para compartir en artefactos de workspace — https://{workspace}.shareout.site/{slug}/
deployment.url	Link para artefactos personales (https://shareout.site/a/{slug}/); también la clave de routing interna para artefactos de workspace
deployment.slug	Slug de routing globalmente único (puede diferir del slug humano que enviaste)
deployment.mobile_url	Entrypoint mobile cuando hay mobile_html

Para artefactos de workspace, mostrá deployment.subdomain_url a los usuarios — no la URL apex /a/{routing-slug}/. El slug apex es una clave de routing interna que puede llevar sufijo hash si hay colisión entre workspaces; el subdominio y las URLs con namespace mantienen el slug humano limpio. Usá deployment.url solo para links de máquina (embeds, manifests, KV).

Editor readiness

Las publicaciones HTML devuelven un perfil advisory editor_readiness — cuánto puede hacer el editor visual con el artefacto. La publicación nunca se bloquea por gaps; el artefacto queda en vivo igual.

{
  "editor_readiness": {
    "manifest": "valid",
    "outline": true,
    "counts": { "pages": 3, "bindings": 12, "templates": 1 },
    "summary": { "errors": 0, "warnings": 1, "infos": 0 },
    "findings": [
      {
        "rule": "binding-undeclared",
        "level": "warning",
        "message": "Binding \"json:revenue\" references undeclared json \"revenue\"",
        "suggestion": "Declare \"revenue\" in the manifest sources",
        "disables": "inline editing and formatting of this value"
      }
    ]
  }
}

El campo disables de cada finding nombra qué función del estudio cuesta ese gap. Ausente en artefactos no-HTML. Los findings pueden incluir una category — p. ej. provenance advierte cuando una fuente en vivo no tiene query/description o cuando los gráficos carecen de data-shareout-source / vínculos en feeds. Ver Procedencia de datos.

Mirá el resumen de la spec y el editor visual para el checklist completo.

Visibilidad

Valor	Quién puede ver
private	Solo colaboradores con viewer+
workspace	Cualquier miembro del workspace del artefacto
public	Cualquiera en internet con el enlace; descubrible

(unlisted es un alias legacy retirado, aún aceptado en la API y tratado como public.)

Artefactos públicos

La visibilidad public activa reglas adicionales:

Revisión de seguridad. Al publicar o cambiar a visibilidad abierta, ShareOut ejecuta un control automático del HTML. Si no puede aprobar al instante, el artefacto queda privado con moderation_status: "pending" y un objeto moderation al publicar (o code: "MODERATION_HELD" + reason en PATCH) — pero ShareOut revisa los holds pendientes automáticamente (cada hora) y restaura la visibilidad pública solicitada cuando se libera; la mayoría de los casos se resuelven en una hora sin acción.

Los owners ven badges Under review / Blocked en las tarjetas de Home y un banner en el inspector mientras dura el hold. Los visitantes que abren una URL pública en hold ven una página dedicada de revisión (no el contenido del artefacto). Al liberarse el hold, el owner recibe notificación en la campana y por email.

Scripts y CDNs externos. En artefactos public la Content-Security-Policy del sandbox permite scripts, estilos y fuentes desde una amplia lista de CDNs reputados — jsDelivr, unpkg, cdnjs, esm.sh, Skypack, librerías de Google, la Tailwind Play CDN (cdn.tailwindcss.com), jQuery, D3, Plotly, Highcharts, DataTables, Bootstrap y más — que cubre la mayoría de las librerías. Un CDN fuera de la lista queda bloqueado y su <script> no cargará. Si tu artefacto carga un CDN no permitido, al intentar hacerlo público se rechaza: queda privado y recibís un mensaje con el host problemático.

Los artefactos privados no tienen esa restricción. Un artefacto private puede cargar scripts, estilos y fuentes desde cualquier origen HTTPS. Para un CDN de nicho o propio, dejá el artefacto privado y agregá colaboradores uno a uno (Configuración → Compartir): tienen acceso completo y vos conservás el uso libre de CDNs. Alternativa: alojá la librería como archivo dentro del artefacto, o cambiá a un CDN permitido.

Visitantes anónimos son de solo lectura por defecto. En artefactos públicos, los visitantes anónimos no pueden escribir en json/tablas/blobs/datasets, enviar email, usar el chat IA ni colaborar en tiempo real salvo que el dueño habilite cada capacidad con allow_anon_write, allow_anon_email, allow_anon_agent o allow_anon_collab (todos false por defecto).

Badge. Apagado por defecto. Poné ARTIFACT_BADGE=1 en el Worker para agregar un badge “Made with ShareOut” con enlace Report a los artefactos públicos.

Cuota de almacenamiento. Publicar verifica el total de bytes del dueño contra STORAGE_QUOTA_BYTES; superarlo devuelve 413 STORAGE_LIMIT_EXCEEDED. Sin setear o en 0 es ilimitado, el default.

La visibilidad abierta (pública) está activa salvo que la instancia setee `OPEN_VISIBILITY_DISABLED`. Donde está apagada, `POST /v1/publish` y `PATCH /v1/artifacts/{id}` devuelven un `notice` (publicar) o `VISIBILITY_HELD` (actualizar) en lugar de hacer downgrade silencioso. Ver [Política de artefactos públicos](/es/public-artifacts/overview/#quien-puede-publicar-publicamente).

Gobernanza de publicación del workspace

Los owners/admins pueden controlar la visibilidad abierta con una política por workspace (allow / prohibit / require_approval). Por defecto es allow. Mirá Política de artefactos públicos para el contexto completo.

Configurar (admin/owner):

GET  /v1/workspaces/{id}/publish-policy
PATCH /v1/workspaces/{id}/publish-policy

{ "policy": "require_approval", "approvals_required": 2 }

approvals_required va de 1 a 10 cuando la política es require_approval.

Cuando un miembro publica o cambia visibilidad a abierto, corre el gate antes de la moderación de plataforma:

Política	Comportamiento
prohibit	Visibilidad forzada a workspace; la respuesta incluye notice.
require_approval	Visibilidad forzada a workspace; la respuesta incluye notice y approval_required.

{
  "deployment": { "url": "…" },
  "notice": "Tu workspace requiere aprobación para publicar en público. Quedó visible para tu workspace — pedí aprobación a 2 compañero(s).",
  "approval_required": { "required": 2, "artifact_id": "art_abc123" }
}

Pedir aprobación (el solicitante nombra exactamente N miembros del workspace, no a sí mismo):

POST /v1/artifacts/{id}/publish-approval
{ "visibility": "public", "approver_ids": ["usr_a", "usr_b"] }

Aprobar o rechazar (cada aprobador nominado):

POST /v1/artifacts/{id}/publish-approval/{requestId}/decision
{ "decision": "approve" }

Listar solicitudes pendientes (cualquier miembro del workspace):

GET /v1/workspaces/{id}/publish-approvals?status=pending

Cuando todos los aprobadores nominados aprueban, la visibilidad cambia al nivel pedido y corre la revisión de seguridad automática. Cualquier rechazo cancela la solicitud. La aprobación es por hash de contenido — republicar sin cambios no requiere una nueva ronda.

Colaboradores

Agregá gente por email con un rol:

curl -X POST https://shareout.site/v1/artifacts/art_abc123/collaborators \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "emails": ["teammate@example.com"], "role": "editor" }'

Acción	Owner	Editor	Viewer
Ver	✓	✓	✓
Editar y publicar	✓	✓	✗
Gestionar colaboradores	✓	✓	✗
Eliminar	✓	✗	✗
Transferir propiedad	✓	✗	✗

Previews de links

Configurá og:title, og:description y og:image en el <head> de tu entrypoint y ShareOut los sirve para los unfurls de Slack, WhatsApp e iMessage. Sobrescribilos por artefacto con PATCH /v1/artifacts/{id} (social_title, social_description, social_image_url).

Regenerá la miniatura del preview cuando quieras con `POST /v1/artifacts/{id}/screenshot` — un screenshot headless usado como `og:image` por defecto.

Servido

URL	Sirve
/a/{slug}/	Entrypoint (detección automática de mobile)
/a/{slug}/{path}	Un asset específico
/a/{slug}/{path}?_raw	Contenido raw para embeber en iframe

Auto-resumen y tags

Tras cada publish HTML exitoso, ShareOut corre un paso de IA en background sobre el entrypoint de producción. Escribe una descripción de 1–2 oraciones (solo si dejaste el campo vacío) y 3–6 tags en la tabla artifact_tags existente. El publish nunca espera este job — si la IA no está disponible, el artefacto igual queda en vivo.

Los auto-resúmenes alimentan subtítulos en tarjetas de Home, hits de búsqueda ⌘K, el digest semanal del workspace y la entrada del learner de Knowledge. Los artefactos viejos se rellenan con un drip horario.

Podés setear tu propia descripción o tags con PATCH /v1/artifacts/{id} — tus valores se conservan; el auto-resumen solo llena huecos.

Versiones y notas de cambios

Cada publicación sobre un artefacto existente agrega una versión; nunca se pisa nada. Mandá un message opcional con la publicación para contar qué cambió:

{ "slug": "my-app", "message": "Agrego la columna de Q3", "files": [ … ] }

Si no mandás message, ShareOut escribe una nota de IA de una línea a partir de las diferencias con la versión anterior (flag ai.version_summaries, activado por defecto). Cada versión registra quién la publicó y cómo (api, agent, editor o restore).

Para recuperar una versión anterior, restaurala: eso publica una versión nueva con los archivos de la vieja y conserva todo el historial. POST /v1/artifacts/{id}/rollback sigue funcionando pero está deprecado en favor de restaurar. La interfaz, las diferencias y las vistas previas están en Historial de versiones y restauración; los endpoints, en la referencia de la API.

Para publicar varios archivos HTML como un solo artefacto, mirá Artefactos de varias secciones.

Eliminar y restaurar

Eliminar un artefacto es un borrado suave con una ventana de recuperación de 30 días — no un borrado inmediato:

curl -X DELETE https://shareout.site/v1/artifacts/art_abc123 \
  -H "Authorization: Bearer $TOKEN"
# → { "recoverable_until": "...", "retention_days": 30, "restore_url": "..." }

El artefacto deja de servirse y desaparece de tus listados, y su slug se libera para poder volver a publicar el mismo slug — pero sus archivos, versiones y datos se conservan intactos. Dentro de los 30 días podés recuperarlo:

curl https://shareout.site/v1/artifacts/deleted -H "Authorization: Bearer $TOKEN"   # papelera
curl -X POST https://shareout.site/v1/artifacts/art_abc123/restore \
  -H "Authorization: Bearer $TOKEN"                                                  # restaurar

En la UI del home está en el menú de la cuenta → Eliminados recientemente. Al restaurar se asigna un slug nuevo si el original fue reclamado mientras tanto.

Janitor de artefactos sin uso

Una vez al mes (por workspace o cuenta personal), ShareOut marca artefactos publicados con cero vistas en 90+ días cuando hay al menos tres. Los artefactos con estrella siempre se conservan. La campana muestra una tarjeta Unused pages con títulos de muestra y Archive all — soft-delete de un clic a la misma papelera de 30 días (lotes de 100 por clic). Admins de workspace usan POST /v1/workspaces/{id}/unused/archive; cuentas personales usan POST /v1/artifacts/unused/archive.

Pasados 30 días, un barrido diario **elimina el artefacto de forma permanente** — archivos, datos y todo. A partir de ahí no se puede restaurar.