simple-module-pagebuilder 0.0.1__py3-none-any.whl

pagebuilder/contracts/schemas.py

@@ -0,0 +1,239 @@
+"""Pydantic request/response schemas for the pagebuilder API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from pagebuilder.models import PageStatus, RevisionEvent
+
+PuckData = dict[str, Any]
+
+
+class PageCreate(BaseModel):
+    title: str = Field(min_length=1, max_length=300)
+    slug: str = Field(min_length=1, max_length=200, pattern=r"^[a-z0-9][a-z0-9-]*$")
+    meta_description: str | None = Field(default=None, max_length=500)
+    og_image: str | None = Field(default=None, max_length=500)
+    canonical_url: str | None = Field(default=None, max_length=500)
+    index_in_search: bool = True
+    json_ld: dict[str, Any] | None = None
+    draft_data: PuckData = Field(default_factory=dict)
+    publish_at: datetime | None = None
+    unpublish_at: datetime | None = None
+
+
+class PageUpdate(BaseModel):
+    title: str | None = Field(default=None, min_length=1, max_length=300)
+    slug: str | None = Field(
+        default=None, min_length=1, max_length=200, pattern=r"^[a-z0-9][a-z0-9-]*$"
+    )
+    meta_description: str | None = Field(default=None, max_length=500)
+    og_image: str | None = Field(default=None, max_length=500)
+    canonical_url: str | None = Field(default=None, max_length=500)
+    index_in_search: bool | None = None
+    json_ld: dict[str, Any] | None = None
+    draft_data: PuckData | None = None
+
+
+class PageScheduleRequest(BaseModel):
+    """Schedule a future flip into / out of ``published``.
+
+    Both fields are optional and independent — set ``publish_at`` to flip
+    a draft live, set ``unpublish_at`` to take a published page down, or
+    set both for a bounded campaign. Send ``null`` to clear an existing
+    schedule. Sending ``{}`` is a no-op.
+    """
+
+    publish_at: datetime | None = None
+    unpublish_at: datetime | None = None
+
+
+class PageRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    slug: str
+    title: str
+    status: PageStatus
+    has_published: bool
+    meta_description: str | None
+    og_image: str | None
+    canonical_url: str | None = None
+    index_in_search: bool = True
+    rejection_note: str | None
+    publish_at: datetime | None = None
+    unpublish_at: datetime | None = None
+    created_at: datetime
+    updated_at: datetime | None
+
+
+class PageDetail(PageRead):
+    draft_data: PuckData
+    published_data: PuckData | None
+    json_ld: dict[str, Any] | None = None
+
+
+class PageListResponse(BaseModel):
+    items: list[PageRead]
+
+
+class PageRevisionRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    page_id: int
+    title: str
+    meta_description: str | None
+    og_image: str | None
+    event: RevisionEvent
+    note: str | None
+    created_at: datetime
+    created_by: str | None
+
+
+class PageRevisionDetail(PageRevisionRead):
+    data: PuckData
+
+
+class PageRevisionListResponse(BaseModel):
+    items: list[PageRevisionRead]
+
+
+class PageRejectRequest(BaseModel):
+    """Approver-supplied reason for sending a submission back to draft.
+
+    Required and non-empty so the editor history panel always has
+    actionable feedback — an empty rejection is a 422 from the API.
+    """
+
+    note: str = Field(min_length=1, max_length=2000)
+
+
+class PageNoteRequest(BaseModel):
+    """Optional author note attached to a publish / approve / unpublish.
+
+    Body is always required by FastAPI when the endpoint declares this
+    schema; clients send ``{}`` (or ``{"note": null}``) to opt out.
+    """
+
+    note: str | None = Field(default=None, max_length=2000)
+
+
+class BlockChange(BaseModel):
+    id: str
+    type: str | None = None
+    fields: list[str] = Field(default_factory=list)
+    type_before: str | None = None
+
+
+class MetadataChange(BaseModel):
+    before: Any = None
+    after: Any = None
+
+
+class RevisionDiffResponse(BaseModel):
+    """Block-level diff between two revisions.
+
+    ``metadata`` only contains keys whose value actually changed;
+    ``blocks`` is always present so the client can render an empty diff
+    ("no changes") deterministically.
+    """
+
+    before_id: int
+    after_id: int
+    metadata: dict[str, MetadataChange] = Field(default_factory=dict)
+    blocks: dict[str, list[BlockChange]] = Field(default_factory=dict)
+
+
+class LayoutUpdate(BaseModel):
+    """``None`` leaves a slot alone; an empty Puck doc clears it."""
+
+    header_data: PuckData | None = None
+    footer_data: PuckData | None = None
+    note: str | None = Field(default=None, max_length=2000)
+
+
+class LayoutRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    created_at: datetime
+    updated_at: datetime | None
+
+
+class LayoutDetail(LayoutRead):
+    header_data: PuckData
+    footer_data: PuckData
+
+
+class LayoutRevisionRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    layout_id: int
+    note: str | None
+    created_at: datetime
+    created_by: str | None
+
+
+class LayoutRevisionDetail(LayoutRevisionRead):
+    header_data: PuckData
+    footer_data: PuckData
+
+
+class LayoutRevisionListResponse(BaseModel):
+    items: list[LayoutRevisionRead]
+
+
+class MediaAssetVariant(BaseModel):
+    """One server-generated derivative of an uploaded image.
+
+    Width is the canonical key for ``srcset`` so it's required; height is
+    optional because some derivatives (e.g. a same-size webp transcode of
+    a non-decodable input) may not carry it back.
+    """
+
+    filename: str
+    url: str
+    content_type: str
+    width: int
+    height: int | None = None
+    size_bytes: int
+
+
+class MediaAssetRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    filename: str
+    original_filename: str
+    content_type: str
+    size_bytes: int
+    url: str
+    width: int | None = None
+    height: int | None = None
+    folder: str | None = None
+    variants: dict[str, MediaAssetVariant] = Field(default_factory=dict)
+    created_at: datetime
+
+
+class MediaAssetListResponse(BaseModel):
+    """Cursor-paginated page of media assets.
+
+    ``next_cursor`` is the ``id`` to pass back as the ``cursor`` query
+    param to fetch the next page (assets are returned newest-first, so
+    the cursor advances toward smaller ids). ``None`` when there are no
+    more rows. ``folders`` is the full set of distinct folder names in
+    the library — independent of the current filter so the sidebar
+    doesn't disappear when the user drills in.
+    """
+
+    items: list[MediaAssetRead]
+    next_cursor: int | None = None
+    folders: list[str] = Field(default_factory=list)
+    total: int | None = None
+    """Row count matching the filters. Only set for offset paging — cursor
+    paging deliberately avoids the extra COUNT query."""

pagebuilder/conversion/blocks-to-html.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+
+import { blocksToHtml } from './blocks-to-html';
+import type { PuckBlock } from './types';
+
+const b = (type: string, props: Record<string, unknown>): PuckBlock => ({
+  type,
+  props: { id: `${type}-1`, ...props },
+});
+
+describe('blocksToHtml', () => {
+  it('converts a heading, accepting either level spelling', () => {
+    expect(blocksToHtml([b('Heading', { text: 'Hi', level: 'h3' })]).html).toBe('<h3>Hi</h3>');
+    // Upstream's spelling, in case a document ever arrives from there.
+    expect(blocksToHtml([b('Heading', { text: 'Hi', level: '3' })]).html).toBe('<h3>Hi</h3>');
+  });
+
+  it('falls back to h2 for a level it cannot make sense of', () => {
+    expect(blocksToHtml([b('Heading', { text: 'Hi', level: 'h9' })]).html).toBe('<h2>Hi</h2>');
+    expect(blocksToHtml([b('Heading', { text: 'Hi', level: undefined })]).html).toBe(
+      '<h2>Hi</h2>',
+    );
+  });
+
+  it('escapes heading text', () => {
+    expect(blocksToHtml([b('Heading', { text: 'a < b & c', level: 'h2' })]).html).toBe(
+      '<h2>a &lt; b &amp; c</h2>',
+    );
+  });
+
+  it('renders Text as markdown rather than passing it through', () => {
+    // The block stores markdown, so `**x**` has to become an element. Passing
+    // it through verbatim — which is right for upstream, where the field holds
+    // HTML — would print the asterisks on the page.
+    expect(blocksToHtml([b('Text', { text: 'Hello **world**' })]).html).toBe(
+      '<p>Hello <strong>world</strong></p>',
+    );
+  });
+
+  it('escapes markup inside Text instead of emitting it', () => {
+    // The corollary of the above: because the field is markdown, anything
+    // tag-shaped in it is literal content and must not become an element.
+    expect(blocksToHtml([b('Text', { text: 'a<b are adjacent' })]).html).toBe(
+      '<p>a&lt;b are adjacent</p>',
+    );
+  });
+
+  it('converts a Markdown block', () => {
+    expect(blocksToHtml([b('Markdown', { content: '# T' })]).html).toBe('<h1>T</h1>');
+  });
+
+  it('converts images, escaping the alt and carrying known dimensions', () => {
+    expect(blocksToHtml([b('Image', { src: '/a.png', alt: 'an "image"' })]).html).toBe(
+      '<img src="/a.png" alt="an &quot;image&quot;">',
+    );
+    expect(
+      blocksToHtml([b('Image', { src: '/a.png', alt: '', width: 800, height: 600 })]).html,
+    ).toBe('<img src="/a.png" alt="" width="800" height="600">');
+  });
+
+  it('treats Html as lossy unless raw markup is explicitly asked for', () => {
+    // The Html widget renders its markup inside `<iframe sandbox>` because a
+    // ContentEditor's input isn't fully trusted. This function's output has no
+    // such boundary, so emitting it has to be a decision the caller makes.
+    const { html, lossyTypes } = blocksToHtml([b('Html', { html: '<section>raw</section>' })]);
+    expect(html).toBe('');
+    expect(lossyTypes).toEqual(['Html']);
+  });
+
+  it('passes raw Html through when opted in', () => {
+    expect(
+      blocksToHtml([b('Html', { html: '<section>raw</section>' })], { includeRawHtml: true }).html,
+    ).toBe('<section>raw</section>');
+  });
+
+  it('attributes a quote from whichever of author and source is filled in', () => {
+    expect(blocksToHtml([b('Quote', { quote: 'Q', author: 'A', source: 'S' })]).html).toBe(
+      '<blockquote><p>Q</p><footer>A, S</footer></blockquote>',
+    );
+    expect(blocksToHtml([b('Quote', { quote: 'Q', author: '', source: '' })]).html).toBe(
+      '<blockquote><p>Q</p></blockquote>',
+    );
+  });
+
+  it('names the types it could not convert, deduplicated and in order', () => {
+    const { html, lossyTypes } = blocksToHtml([
+      b('Grid', {}),
+      b('Heading', { text: 'Keep', level: 'h2' }),
+      b('Hero', {}),
+      b('Grid', {}),
+    ]);
+    expect(html).toBe('<h2>Keep</h2>');
+    expect(lossyTypes).toEqual(['Grid', 'Hero']);
+  });
+
+  it('reports a block with missing props as lossy rather than throwing', () => {
+    expect(blocksToHtml([{ type: 'Heading', props: { id: 'x' } }]).lossyTypes).toEqual([
+      'Heading',
+    ]);
+  });
+
+  it('returns empty output for no blocks', () => {
+    expect(blocksToHtml([])).toEqual({ html: '', lossyTypes: [] });
+  });
+});

pagebuilder/conversion/blocks-to-html.ts

@@ -0,0 +1,102 @@
+/**
+ * Render a page's blocks as a plain HTML string — for an export, a feed item,
+ * or an email, where the React tree isn't available.
+ *
+ * Only blocks with a meaningful HTML equivalent convert. A hero or a layout
+ * block has no honest flat representation, so rather than emit something
+ * lossy and quiet, they're skipped and named in `lossyTypes` — the caller can
+ * then say exactly what didn't come across.
+ */
+
+import { escapeHtml, markdownToHtml } from '../utils/markdown';
+import type { PuckBlock } from './types';
+
+export type BlocksToHtmlResult = { html: string; lossyTypes: string[] };
+
+export type BlocksToHtmlOptions = {
+  /**
+   * Emit `Html` blocks' stored markup verbatim. **Off by default.**
+   *
+   * The Html widget renders that markup inside `<iframe sandbox>` precisely
+   * because a ContentEditor's input is not fully trusted. This function's
+   * output has no such boundary — a caller inlining it into an email or a feed
+   * would run whatever the block contains in their own origin. Off by default,
+   * `Html` is reported in `lossyTypes` like any other block with no safe flat
+   * representation. Turn it on only where the output is going somewhere the
+   * markup is already trusted to run.
+   */
+  includeRawHtml?: boolean;
+};
+
+/** `h3` (what we store) and `3` (what upstream stores) both mean the same. */
+function headingLevel(raw: unknown): string {
+  const match = /^h?([1-6])$/.exec(String(raw ?? ''));
+  return match ? match[1] : '2';
+}
+
+export function blocksToHtml(
+  blocks: PuckBlock[],
+  options: BlocksToHtmlOptions = {},
+): BlocksToHtmlResult {
+  const parts: string[] = [];
+  const lossy = new Set<string>();
+
+  for (const block of blocks) {
+    const html = blockToHtml(block, options);
+    if (html === null) {
+      lossy.add(block.type);
+    } else if (html) {
+      parts.push(html);
+    }
+  }
+  return { html: parts.join('\n'), lossyTypes: [...lossy] };
+}
+
+function blockToHtml(block: PuckBlock, options: BlocksToHtmlOptions): string | null {
+  const props = block.props ?? {};
+  switch (block.type) {
+    case 'Html':
+      if (!options.includeRawHtml) return null;
+      return typeof props.html === 'string' ? props.html : null;
+
+    // Text and Markdown both hold markdown here — Text is the light inline
+    // subset, Markdown the full block syntax — so both go through the same
+    // converter, which escapes as it goes. Upstream has to sniff Text for a
+    // leading tag because its Text field stores HTML; ours never does.
+    case 'Text':
+      return typeof props.text === 'string' ? markdownToHtml(props.text) : null;
+    case 'Markdown':
+      return typeof props.content === 'string' ? markdownToHtml(props.content) : null;
+
+    case 'Heading': {
+      if (typeof props.text !== 'string') return null;
+      const level = headingLevel(props.level);
+      return `<h${level}>${escapeHtml(props.text)}</h${level}>`;
+    }
+
+    case 'Image': {
+      if (typeof props.src !== 'string') return null;
+      const alt = typeof props.alt === 'string' ? props.alt : '';
+      // `width`/`height` are carried through when known: without them a
+      // consumer laying the HTML out has to load the image to size it, which
+      // is the reflow the picker stores those numbers to avoid.
+      const dims = ['width', 'height']
+        .map((key) => (typeof props[key] === 'number' ? ` ${key}="${props[key]}"` : ''))
+        .join('');
+      return `<img src="${escapeHtml(props.src)}" alt="${escapeHtml(alt)}"${dims}>`;
+    }
+
+    case 'Quote': {
+      if (typeof props.quote !== 'string') return null;
+      const cite = ['author', 'source']
+        .map((key) => (typeof props[key] === 'string' ? props[key].trim() : ''))
+        .filter(Boolean)
+        .join(', ');
+      const attribution = cite ? `<footer>${escapeHtml(cite)}</footer>` : '';
+      return `<blockquote><p>${escapeHtml(props.quote)}</p>${attribution}</blockquote>`;
+    }
+
+    default:
+      return null;
+  }
+}

pagebuilder/conversion/index.ts

@@ -0,0 +1,2 @@
+export { blocksToHtml, type BlocksToHtmlResult } from './blocks-to-html';
+export type { PuckBlock } from './types';

pagebuilder/conversion/types.ts

@@ -0,0 +1,5 @@
+/** One entry of a Puck document's `content` array, as stored. */
+export type PuckBlock = {
+  type: string;
+  props: { id: string } & Record<string, unknown>;
+};

pagebuilder/deps.py

@@ -0,0 +1,26 @@
+"""FastAPI dependencies for the pagebuilder module.
+
+Centralised here so admin views and the JSON API share one source of
+truth for resolving module-scoped state without underscore-prefixed
+imports across endpoint files.
+"""
+
+from __future__ import annotations
+
+from fastapi import Depends, Request
+from simple_module_db import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from pagebuilder.media_service import MediaService
+from pagebuilder.settings import PagebuilderSettings
+
+
+def get_settings(request: Request) -> PagebuilderSettings:
+    return request.app.state.pagebuilder.settings
+
+
+def get_media_service(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> MediaService:
+    return MediaService(db, request.app.state.pagebuilder.settings)

pagebuilder/diff.py

@@ -0,0 +1,129 @@
+"""Structured diff between two ``PageRevision`` snapshots.
+
+Puck stores the page document as ``{content: [...blocks], root: {...}}``
+where every block carries a ``props.id`` Puck assigned. Diffing by id
+keeps the result stable when authors reorder blocks instead of
+rewriting them — and lets the editor render a per-block added /
+removed / changed summary without trying to read minds about field
+intent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pagebuilder.models import PageRevision
+
+_TRACKED_METADATA = ("title", "meta_description", "og_image")
+
+
+def _normalise_blocks(data: dict[str, Any] | None) -> list[dict[str, Any]]:
+    """Pull the block list out of a Puck document.
+
+    Returns an empty list for ``None`` / malformed input so the diff
+    treats "no doc" as "no blocks" instead of raising — a missing
+    snapshot is a 404 at the route layer.
+    """
+    if not isinstance(data, dict):
+        return []
+    content = data.get("content")
+    return content if isinstance(content, list) else []
+
+
+def _block_key(block: dict[str, Any]) -> str | None:
+    """Block identity used to pair entries across revisions.
+
+    Puck assigns ``props.id`` at insertion time; falling back to
+    positional indexing only when an id is missing avoids treating an
+    entire reorder as "remove all + add all".
+    """
+    if not isinstance(block, dict):
+        return None
+    props = block.get("props")
+    if isinstance(props, dict):
+        block_id = props.get("id")
+        if isinstance(block_id, str) and block_id:
+            return block_id
+    return None
+
+
+def _changed_fields(before: dict[str, Any], after: dict[str, Any]) -> list[str]:
+    keys = sorted(set(before) | set(after))
+    return [k for k in keys if before.get(k) != after.get(k)]
+
+
+def revision_diff(before: PageRevision, after: PageRevision) -> dict[str, Any]:
+    """Compute a block-level diff between two revision snapshots.
+
+    The result has two top-level keys:
+
+    - ``metadata`` lists per-field ``before``/``after`` tuples for the
+      page-level columns that survive in a revision row (title,
+      meta_description, og_image).
+    - ``blocks`` groups Puck blocks into ``added`` / ``removed`` /
+      ``changed``, keyed by ``props.id``. Changed entries include
+      ``fields`` — the list of prop names whose value differs.
+    """
+    metadata: dict[str, dict[str, Any]] = {}
+    for field in _TRACKED_METADATA:
+        before_value = getattr(before, field)
+        after_value = getattr(after, field)
+        if before_value != after_value:
+            metadata[field] = {"before": before_value, "after": after_value}
+
+    before_blocks = _normalise_blocks(before.data)
+    after_blocks = _normalise_blocks(after.data)
+
+    before_by_id = {key: b for b in before_blocks if (key := _block_key(b)) is not None}
+    after_by_id = {key: b for b in after_blocks if (key := _block_key(b)) is not None}
+
+    added: list[dict[str, Any]] = []
+    removed: list[dict[str, Any]] = []
+    changed: list[dict[str, Any]] = []
+
+    for block_id, block in after_by_id.items():
+        if block_id in before_by_id:
+            continue
+        added.append({"id": block_id, "type": block.get("type")})
+
+    for block_id, block in before_by_id.items():
+        if block_id in after_by_id:
+            continue
+        removed.append({"id": block_id, "type": block.get("type")})
+
+    for block_id, after_block in after_by_id.items():
+        before_block = before_by_id.get(block_id)
+        if before_block is None:
+            continue
+        type_changed = before_block.get("type") != after_block.get("type")
+        before_props = before_block.get("props") or {}
+        after_props = after_block.get("props") or {}
+        if not isinstance(before_props, dict):
+            before_props = {}
+        if not isinstance(after_props, dict):
+            after_props = {}
+        # ``id`` is the diff key itself — reporting it as a changed
+        # field would be noise on every entry that survives.
+        fields = [f for f in _changed_fields(before_props, after_props) if f != "id"]
+        if type_changed or fields:
+            changed.append(
+                {
+                    "id": block_id,
+                    "type": after_block.get("type"),
+                    "fields": fields,
+                    **(
+                        {"type_before": before_block.get("type")}
+                        if type_changed
+                        else {}
+                    ),
+                }
+            )
+
+    return {
+        "metadata": metadata,
+        "blocks": {
+            "added": added,
+            "removed": removed,
+            "changed": changed,
+        },
+    }

pagebuilder/endpoints/api/__init__.py

@@ -0,0 +1,21 @@
+"""JSON admin API for the pagebuilder module, split by resource.
+
+Mounted by ``PagebuilderModule.register_routes`` under ``/api/pagebuilder``.
+Sub-routers carry no prefix of their own, so every path is identical to the
+single-file version this replaced.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from pagebuilder.endpoints.api import layout, pages, revisions, uploads, workflow
+
+router = APIRouter()
+router.include_router(pages.router)
+router.include_router(workflow.router)
+router.include_router(revisions.router)
+router.include_router(layout.router)
+router.include_router(uploads.router)
+
+__all__ = ["router"]

pagebuilder/endpoints/api/_deps.py

@@ -0,0 +1,21 @@
+"""Permission dependencies shared by every admin API sub-router.
+
+Per-endpoint :class:`~pagebuilder.permissions.RequiresPermission` deps let
+hosts run the editor → publisher workflow without granting every editor
+publish rights.
+"""
+
+from __future__ import annotations
+
+from fastapi import Depends
+
+from pagebuilder.permissions import (
+    PERM_APPROVE,
+    PERM_EDIT,
+    PERM_PUBLISH,
+    RequiresPermission,
+)
+
+require_edit = Depends(RequiresPermission(PERM_EDIT))
+require_publish = Depends(RequiresPermission(PERM_PUBLISH))
+require_approve = Depends(RequiresPermission(PERM_APPROVE))