Skip to content

sergebulaev/youtube-skills / .codex-marketplace/youtube-skills

youtube-marketing

Verified

Plan, write, and publish for YouTube and YouTube Shorts. Use when the user wants high-CTR video titles, an SEO description with chapters and links, a first-30-seconds retention script (or a 3-second Shorts hook), a designer-ready thumbnail brief, a community-tab post or poll, or a weekly upload plan. The user supplies the video; the skills produce the title, description, hook, and thumbnail brief, then on approval upload and schedule via the Publora API.

lib/publora_client.py

View on GitHub
"""Thin Publora REST client for the YouTube Skills project.

Wraps the Publora API endpoints this bundle uses. As of 2026-06 Publora exposes:
- POST /create-post              (create a draft or scheduled post)
- POST /get-upload-url           (pre-signed S3 URL for media)
- PUT  /update-post/:postGroupId (set scheduledTime, status, platformSettings)
- GET  /platform-connections     (list connected accounts + token health)

YouTube is a video-only platform: every published post REQUIRES a single video.
A text-only YouTube post is accepted by create-post but fails at publish time
(VIDEO_REQUIRED). So the correct flow is:

    1. POST /create-post            -> create a DRAFT (omit scheduledTime)
    2. POST /get-upload-url         -> pre-signed S3 URL for the video
    3. PUT  {uploadUrl}             -> upload the .mp4 to S3
    4. PUT  /update-post/:id        -> set scheduledTime (and any youtube settings)

The custom thumbnail cannot be set on create-post (the thumbnail upload itself
requires a postGroupId). This client provides the thumbnail ATTACH step only:
update-post with platformSettings.youtube.thumbnail = {mediaId, url} (see
`set_thumbnail`). It does NOT upload the thumbnail image. Publora requires the
thumbnail to be a tracked media asset from its dedicated YouTube thumbnail
endpoint, and that upload route is out of band here (do it in the Publora
dashboard, or via the dedicated endpoint once available) — the generic
get-upload-url media flow is not accepted for thumbnails. So in practice this
bundle outputs the thumbnail brief plus attach instructions rather than a
one-call thumbnail upload. YouTube community-tab posts have no Publora endpoint
at all, so those are draft-only (copy-paste) in this bundle.

Base URL: https://api.publora.com/api/v1
Auth header: x-publora-key: sk_...  (NOT Bearer)
Content-Type: application/json. Server-to-server only (custom headers are not in
the CORS allowlist, so browser calls fail preflight).

Design note: this client is deliberately minimal. Skills call exactly one method
per action, after the user has approved a draft rendered via `lib/approval.py`.
Write methods retry on transient 408/429/5xx via the shared retry decorator.
"""
from __future__ import annotations
import os
import time
import random
from datetime import datetime, timezone
from typing import Any, Optional

import requests
from ._env import load_env


class PubloraError(RuntimeError):
    pass


def _utc_now_iso() -> str:
    """Current UTC time as an ISO 8601 string with millisecond precision and a
    trailing Z (e.g. '2026-06-30T16:00:00.000Z'), matching the client's
    scheduledTime style. Used for publish-now: Publora treats a past/current
    scheduledTime as 'send now'."""
    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"


RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}


def _retry(attempts: int = 3, base_delay: float = 0.6):
    """Retry decorator for HTTP methods. Triggers on 408/429/5xx and on
    transient network errors. Exponential backoff with jitter."""

    def decorator(fn):
        def wrapper(*args, **kwargs):
            last_exc: Optional[Exception] = None
            for attempt in range(attempts):
                try:
                    return fn(*args, **kwargs)
                except PubloraError as e:
                    msg = str(e)
                    retryable = any(f"HTTP {s}" in msg for s in RETRYABLE_STATUSES)
                    if not retryable or attempt == attempts - 1:
                        raise
                    last_exc = e
                except (requests.ConnectionError, requests.Timeout) as e:
                    if attempt == attempts - 1:
                        raise
                    last_exc = e
                time.sleep(base_delay * (2**attempt) + random.uniform(0, 0.25))
            assert last_exc is not None
            raise last_exc

        return wrapper

    return decorator


# Platform IDs must match Publora's regex: /^[a-z]+-[a-zA-Z0-9_-]+$/
# For YouTube the prefix is `youtube-` followed by the channel id
# (e.g. "youtube-UCxxxxxxxxxxxxxxxxxxxxxx").
PLATFORM_ID_PREFIX = "youtube-"

# YouTube text limits (the API itself allows YouTube's native 5,000 description
# chars; Publora's dashboard validates at 1,000, but the API does not).
TITLE_MAX = 100
DESCRIPTION_MAX = 5000
DESCRIPTION_VISIBLE = 150  # chars shown before "Show more"


class PubloraClient:
    BASE_URL = "https://api.publora.com/api/v1"

    def __init__(self, api_key: Optional[str] = None, timeout: float = 60.0):
        load_env()
        self.api_key = api_key or os.getenv("PUBLORA_API_KEY")
        if not self.api_key:
            raise PubloraError(
                "PUBLORA_API_KEY not set. Export it or pass api_key= explicitly."
            )
        self.timeout = timeout
        self._session = requests.Session()
        self._session.headers.update(
            {
                "x-publora-key": self.api_key,
                "Content-Type": "application/json",
            }
        )

    # ---- Create / schedule ------------------------------------------------

    def create_post(
        self,
        *,
        content: str,
        platforms: list[str],
        scheduled_time: Optional[str] = None,
        platform_settings: Optional[dict[str, Any]] = None,
    ) -> dict[str, Any]:
        """Create a YouTube post group.

        For a real video upload, call this with NO scheduled_time so it lands as
        a draft, then upload the video and schedule via `update_post`. Use the
        `publish_video` helper to run all four steps in order.

        Args:
            content: The video description. The first ~150 chars are visible
                before "Show more". Max 5,000 chars on YouTube. If you do not
                pass a title in platform_settings, YouTube derives one from the
                first 70 chars of this content, so always set the title.
            platforms: List of platform connection IDs, e.g. ["youtube-UC..."].
                Each must match /^[a-z]+-[a-zA-Z0-9_-]+$/.
            scheduled_time: ISO 8601 UTC datetime. Omit for a draft. A past time
                is silently set to now. For video uploads, leave this OFF here
                and set it in update_post AFTER the video finishes uploading.
            platform_settings: Per-platform object. YouTube keys: title, privacy
                ("public"|"unlisted"|"private"), tags (list or comma string),
                categoryId, madeForKids (bool), playlist ({id, platformId}).
                The thumbnail CANNOT be set here (needs a postGroupId first).

        Returns:
            { "success": true, "postGroupId": "..." } on HTTP 200.
        """
        if not content or not content.strip():
            raise PubloraError("content is required (cannot be empty or whitespace)")
        if len(content) > DESCRIPTION_MAX:
            raise PubloraError(
                f"description is {len(content)} characters; YouTube allows "
                f"{DESCRIPTION_MAX}. Shorten it and re-approve rather than "
                "discovering this after the upload."
            )
        if not platforms:
            raise PubloraError("at least one platform ID is required")
        payload: dict[str, Any] = {"content": content, "platforms": platforms}
        if scheduled_time:
            payload["scheduledTime"] = scheduled_time
        if platform_settings:
            payload["platformSettings"] = platform_settings
        return self._post("/create-post", payload)

    def update_post(
        self,
        post_group_id: str,
        *,
        status: Optional[str] = None,
        scheduled_time: Optional[str] = None,
        platform_settings: Optional[dict[str, Any]] = None,
    ) -> dict[str, Any]:
        """Update a draft: schedule it, or attach YouTube settings / thumbnail.

        Used after the video upload completes. Pass scheduled_time (and
        status="scheduled") to publish at a time, or platform_settings to set
        the youtube.thumbnail / playlist / privacy after the fact.

        Note: you cannot change the playlist or thumbnail while the post is
        already `processing` (Publora returns 409). Set them on a draft.
        """
        payload: dict[str, Any] = {}
        if status:
            payload["status"] = status
        if scheduled_time:
            payload["scheduledTime"] = scheduled_time
        if platform_settings:
            payload["platformSettings"] = platform_settings
        if not payload:
            raise PubloraError("update_post needs at least one field to change")
        return self._put(f"/update-post/{post_group_id}", payload)

    # ---- Media ------------------------------------------------------------

    def get_upload_url(
        self,
        *,
        file_name: str,
        content_type: str,
        post_group_id: str,
        media_type: str = "video",
    ) -> dict[str, Any]:
        """Request a pre-signed S3 URL to upload a video (or image) file.

        Args:
            file_name: e.g. "episode-12.mp4". Sanitized server-side.
            content_type: MIME type, e.g. "video/mp4".
            post_group_id: The draft post group to attach the media to.
            media_type: "video" or "image". Always required; omitting it makes
                the S3 PutObjectCommand fail. Defaults to "video" for YouTube.

        Returns:
            { success, uploadUrl, fileUrl, mediaId }. `uploadUrl` expires in 1h.
        """
        payload = {
            "fileName": file_name,
            "contentType": content_type,
            "postGroupId": post_group_id,
            "type": media_type,
        }
        return self._post("/get-upload-url", payload)

    def upload_to_s3(self, upload_url: str, file_path: str, content_type: str) -> None:
        """PUT a local file to the pre-signed S3 URL from `get_upload_url`."""
        with open(file_path, "rb") as f:
            r = requests.put(
                upload_url,
                data=f,
                headers={"Content-Type": content_type},
                allow_redirects=False, timeout=self.timeout,
            )
        if r.status_code >= 400:
            raise PubloraError(f"S3 upload failed: HTTP {r.status_code}: {r.text[:300]}")

    # ---- High-level YouTube video flow ------------------------------------

    def publish_video(
        self,
        *,
        content: str,
        platforms: list[str],
        video_path: str,
        title: str,
        content_type: str = "video/mp4",
        scheduled_time: Optional[str] = None,
        privacy: str = "public",
        tags: Optional[list[str]] = None,
        category_id: Optional[str] = None,
        made_for_kids: bool = False,
        playlist: Optional[dict[str, str]] = None,
        thumbnail: Optional[dict[str, str]] = None,
    ) -> dict[str, Any]:
        """Run the full media-required YouTube flow in order.

        draft (create-post) -> get-upload-url -> PUT to S3 ->
        update-post (schedule + youtube settings).

        The video file is supplied by the user. Returns the postGroupId plus the
        uploaded media's fileUrl and mediaId.

        scheduled_time: ISO 8601 UTC. If omitted (the publish-now / default
            case), the final update-post carries the current UTC time as
            scheduledTime, which Publora treats as "send now". The final
            update-post always carries a scheduledTime so it never hits the
            "needs at least one field" guard and strand the uploaded video.

        thumbnail: optional {mediaId, url} for a custom thumbnail, set in the
            final update-post. The image must already be a Publora-tracked asset
            (mediaId + url) from Publora's dedicated YouTube thumbnail upload;
            this client does NOT upload the image (that step is out of band — do
            it in the Publora dashboard). Without that asset, leave thumbnail
            unset and set it later in YouTube Studio.
        """
        if len(title) > TITLE_MAX:
            raise PubloraError(
                f"title is {len(title)} characters; YouTube allows {TITLE_MAX}. "
                "Shorten it and re-approve rather than publishing a title the "
                "user did not see."
            )
        yt: dict[str, Any] = {"title": title, "privacy": privacy}
        if tags:
            yt["tags"] = tags
        if category_id:
            yt["categoryId"] = category_id
        yt["madeForKids"] = made_for_kids
        if playlist:
            yt["playlist"] = playlist

        # 1. draft
        draft = self.create_post(
            content=content,
            platforms=platforms,
            platform_settings={"youtube": yt},
        )
        post_group_id = draft["postGroupId"]

        # 2. pre-signed URL
        file_name = os.path.basename(video_path)
        up = self.get_upload_url(
            file_name=file_name,
            content_type=content_type,
            post_group_id=post_group_id,
            media_type="video",
        )

        # 3. upload to S3
        self.upload_to_s3(up["uploadUrl"], video_path, content_type)

        # 4. schedule (and optionally set thumbnail now that media exists).
        # Always carry a scheduledTime: with no explicit time this is a
        # publish-now (current UTC, which Publora sends immediately). This keeps
        # the final update-post from ever being an all-empty payload, which would
        # raise after the video already uploaded to S3.
        effective_time = scheduled_time or _utc_now_iso()
        update_settings: Optional[dict[str, Any]] = None
        if thumbnail:
            update_settings = {"youtube": {"thumbnail": thumbnail}}
        self.update_post(
            post_group_id,
            status="scheduled",
            scheduled_time=effective_time,
            platform_settings=update_settings,
        )
        return {
            "postGroupId": post_group_id,
            "fileUrl": up.get("fileUrl"),
            "mediaId": up.get("mediaId"),
        }

    def set_thumbnail(
        self, post_group_id: str, *, media_id: str, url: str
    ) -> dict[str, Any]:
        """Attach a custom YouTube thumbnail to an existing draft post group.

        This is the ATTACH step only (update-post with platformSettings.youtube
        .thumbnail). It does NOT upload the image. The `mediaId` and `url` must
        already exist: they come from Publora's dedicated YouTube thumbnail
        upload (which itself requires this postGroupId), and that upload is out
        of band for this client — do it in the Publora dashboard, or via the
        dedicated endpoint once available. The generic get-upload-url media flow
        is not accepted for thumbnails, and arbitrary URLs are rejected by
        YouTube. Best-effort: if YouTube rejects the image, the video still
        publishes and only the thumbnail is skipped. Requires a verified channel.
        """
        return self.update_post(
            post_group_id,
            platform_settings={"youtube": {"thumbnail": {"mediaId": media_id, "url": url}}},
        )

    # ---- Connections (read) -----------------------------------------------

    def list_connections(self) -> list[dict[str, Any]]:
        """List connected social accounts with token health.

        Returns the `connections` array from GET /platform-connections. Each
        entry has platformId, username, displayName, tokenStatus, etc. Use it to
        confirm a YouTube channel is connected and which `youtube-<id>` to pass.
        """
        r = self._session.get(
            self.BASE_URL + "/platform-connections", allow_redirects=False, timeout=self.timeout
        )
        data = self._handle(r)
        return data.get("connections", [])

    def youtube_connections(self) -> list[dict[str, Any]]:
        """Convenience filter: only the connected YouTube channels."""
        return [
            c
            for c in self.list_connections()
            if str(c.get("platformId", "")).startswith(PLATFORM_ID_PREFIX)
        ]

    # ---- Internals --------------------------------------------------------

    @_retry()
    def _post(self, path: str, json_body: dict[str, Any]) -> dict[str, Any]:
        r = self._session.post(
            self.BASE_URL + path, json=json_body, allow_redirects=False, timeout=self.timeout
        )
        return self._handle(r)

    @_retry()
    def _put(self, path: str, json_body: dict[str, Any]) -> dict[str, Any]:
        r = self._session.put(
            self.BASE_URL + path, json=json_body, allow_redirects=False, timeout=self.timeout
        )
        return self._handle(r)

    @staticmethod
    def _handle(r: requests.Response) -> dict[str, Any]:
        if r.status_code >= 400:
            try:
                body = r.json()
            except Exception:
                body = {"error": r.text[:500]}
            raise PubloraError(f"HTTP {r.status_code}: {body}")
        return r.json()
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall