@spec create_new_version(String.t(), map(), map(), map() | keyword()) ::
  {:ok, map()} | {:error, any()}

Creates a new version of a slug-mode post by copying from the latest version.

The new version starts as draft with status: "draft". Content and metadata updates from params are applied to the new version.

Note: For more control over which version to branch from, use create_version_from/5.

@spec create_version_from(
  String.t(),
  String.t(),
  integer() | nil,
  map(),
  map() | keyword()
) ::
  {:ok, map()} | {:error, any()}

Creates a new version from an existing version or blank.

Parameters

• group_slug - The publishing group slug
• post_slug - The post slug
• source_version - Version to copy from, or nil for blank version
• params - Optional parameters for the new version
• opts - Options including :scope for audit metadata

Examples

# Create blank version
iex> Publishing.Versions.create_version_from("blog", "my-post", nil, %{}, scope: scope)
{:ok, %{version: 3, ...}}

# Branch from version 1
iex> Publishing.Versions.create_version_from("blog", "my-post", 1, %{}, scope: scope)
{:ok, %{version: 3, ...}}

@spec delete_version(String.t(), String.t(), integer(), keyword() | map()) ::
  :ok | {:error, term()}

Deletes an entire version of a post.

Archives the version instead of permanent deletion. Refuses to delete the last remaining version or the live version.

Returns :ok on success or {:error, reason} on failure.

Gets the published version number for a post.

Gets the status of a specific version/language.

Lists version numbers for a post.

@spec publish_version(String.t(), String.t(), integer(), keyword()) ::
  :ok | {:error, any()}

Publishes a version, making it the live version for the post.

• Sets the target version status to "published" and published_at (if not already set)
• Archives the previously published version (status -> "archived")
• Sets post.active_version_uuid to the target version's UUID

Options

• :source_id - ID of the source (e.g., socket.id) to include in broadcasts, allowing receivers to ignore their own messages

Examples

iex> Publishing.Versions.publish_version("blog", "my-post", 2)
:ok

iex> Publishing.Versions.publish_version("blog", "my-post", 2, source_id: "phx-abc123")
:ok

iex> Publishing.Versions.publish_version("blog", "nonexistent", 1)
{:error, :not_found}

@spec unpublish_post(String.t(), String.t(), keyword()) :: :ok | {:error, any()}

Unpublishes a post by clearing its active version.

• Clears post.active_version_uuid
• Sets the previously-active version status to "draft"

Options

• :source_id - ID of the source to include in broadcasts

Examples

iex> Publishing.Versions.unpublish_post("blog", post_uuid)
:ok

iex> Publishing.Versions.unpublish_post("blog", "nonexistent")
{:error, :not_found}