Merge pull request #78 from FireBird-Technologies/develop

Develop

Author: Muhammad-Mehdi-Changazi

backend/alembic/versions/0019_add_featured_slots.py

@@ -0,0 +1,70 @@
+"""add featured_slots (paid featured publication bookings)
+
+Revision ID: 0019
+Revises: 0018
+Create Date: 2026-07-13 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0019"
+down_revision: Union[str, None] = "0018"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "featured_slots",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "publication_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("publications.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "user_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("start_date", sa.Date(), nullable=False),
+        sa.Column("end_date", sa.Date(), nullable=False),
+        sa.Column("duration_days", sa.Integer(), server_default="7", nullable=False),
+        sa.Column("status", sa.String(length=16), server_default="pending", nullable=False),
+        sa.Column("is_active", sa.Boolean(), server_default="false", nullable=False),
+        sa.Column("hold_expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("stripe_session_id", sa.String(length=255), nullable=True),
+        sa.Column("stripe_payment_intent_id", sa.String(length=255), nullable=True),
+        sa.Column("amount_cents", sa.Integer(), nullable=False),
+        sa.Column("currency", sa.String(length=8), server_default="usd", nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("paid_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_index("ix_featured_slots_publication_id", "featured_slots", ["publication_id"])
+    op.create_index("ix_featured_slots_user_id", "featured_slots", ["user_id"])
+    op.create_index("ix_featured_slots_start_date", "featured_slots", ["start_date"])
+    op.create_index("ix_featured_slots_end_date", "featured_slots", ["end_date"])
+    op.create_index("ix_featured_slots_status", "featured_slots", ["status"])
+    op.create_index("ix_featured_slots_is_active", "featured_slots", ["is_active"])
+    op.create_index("ix_featured_slots_created_at", "featured_slots", ["created_at"])
+    op.create_index(
+        "ix_featured_slots_stripe_session_id", "featured_slots", ["stripe_session_id"], unique=True
+    )
+    # At most one featured publication may be active at any time.
+    op.create_index(
+        "ix_featured_slots_one_active",
+        "featured_slots",
+        ["is_active"],
+        unique=True,
+        postgresql_where=sa.text("is_active = true"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("featured_slots")

backend/alembic/versions/0020_add_featured_slot_click_count.py

@@ -0,0 +1,30 @@
+"""add click_count to featured_slots
+
+Counts outbound clicks from BlogHub to the featured publication's own links during
+its run — the traffic the buyer actually paid for.
+
+Revision ID: 0020
+Revises: 0019
+Create Date: 2026-07-13 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0020"
+down_revision: Union[str, None] = "0019"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "featured_slots",
+        sa.Column("click_count", sa.Integer(), server_default="0", nullable=False),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("featured_slots", "click_count")

backend/alembic/versions/0021_add_featured_slot_approval.py

@@ -0,0 +1,44 @@
+"""add approval_status/approved_at to featured_slots
+
+Paying reserves the dates but no longer puts the publication on the site: a booking
+must be approved by an admin before the reconcile job will activate it.
+
+Revision ID: 0021
+Revises: 0020
+Create Date: 2026-07-13 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0021"
+down_revision: Union[str, None] = "0020"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "featured_slots",
+        sa.Column("approval_status", sa.String(length=16), server_default="pending", nullable=False),
+    )
+    op.add_column(
+        "featured_slots",
+        sa.Column("approved_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_index("ix_featured_slots_approval_status", "featured_slots", ["approval_status"])
+
+    # Any booking that predates this migration was live under the old "paying is
+    # enough" rule — grandfather it in rather than silently un-featuring it.
+    op.execute(
+        "UPDATE featured_slots SET approval_status = 'approved', approved_at = now() "
+        "WHERE status = 'paid'"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_featured_slots_approval_status", table_name="featured_slots")
+    op.drop_column("featured_slots", "approved_at")
+    op.drop_column("featured_slots", "approval_status")

backend/alembic/versions/0022_add_featured_emails.py

@@ -0,0 +1,53 @@
+"""add featured_emails (marketing email for a featured publication)
+
+Revision ID: 0022
+Revises: 0021
+Create Date: 2026-07-13 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0022"
+down_revision: Union[str, None] = "0021"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "featured_emails",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "slot_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("featured_slots.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "publication_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("publications.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("subject", sa.String(length=200), nullable=False),
+        sa.Column("body", sa.Text(), nullable=False),
+        sa.Column("author_approved", sa.Boolean(), server_default="false", nullable=False),
+        sa.Column("admin_approved", sa.Boolean(), server_default="false", nullable=False),
+        sa.Column("status", sa.String(length=16), server_default="draft", nullable=False),
+        sa.Column("scheduled_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("sent_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("recipient_count", sa.Integer(), server_default="0", nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+    )
+    # One draft per booking — this is what makes draft creation idempotent.
+    op.create_index("ix_featured_emails_slot_id", "featured_emails", ["slot_id"], unique=True)
+    op.create_index("ix_featured_emails_status", "featured_emails", ["status"])
+    op.create_index("ix_featured_emails_created_at", "featured_emails", ["created_at"])
+
+
+def downgrade() -> None:
+    op.drop_table("featured_emails")

backend/alembic/versions/0023_add_featured_email_timezone.py

@@ -0,0 +1,31 @@
+"""add author_timezone to featured_emails
+
+The author now picks when their announcement is sent. `scheduled_at` already stores a
+true UTC instant; this records the IANA zone they chose it in, so we can show the time
+back to them exactly as they entered it.
+
+Revision ID: 0023
+Revises: 0022
+Create Date: 2026-07-14 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0023"
+down_revision: Union[str, None] = "0022"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "featured_emails",
+        sa.Column("author_timezone", sa.String(length=64), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("featured_emails", "author_timezone")

backend/alembic/versions/0024_add_featured_email_button_text.py

@@ -0,0 +1,32 @@
+"""add button_text to featured_emails
+
+The publication link is rendered as a single button rather than a linked title, and
+the author now chooses the button's label in the announcement step (e.g. "Read the
+article", "Visit the site"). Falls back to a generic label for rows drafted before
+this existed.
+
+Revision ID: 0024
+Revises: 0023
+Create Date: 2026-07-14 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0024"
+down_revision: Union[str, None] = "0023"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "featured_emails",
+        sa.Column("button_text", sa.String(length=60), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("featured_emails", "button_text")

backend/alembic/versions/0025_add_featured_email_recipients.py

@@ -0,0 +1,67 @@
+"""add featured_email_recipients, and a "sending" status for featured_emails
+
+Per-recipient send tracking for the marketing blast. Previously an email was marked
+`sent` the instant it was claimed, before a single message went out — a crash
+mid-blast then meant no way to tell who had actually received it, so a retry would
+either resend to everyone or (as chosen at the time) silently skip the rest.
+
+Now each successful send is recorded as its own row, committed immediately after
+that recipient's email leaves. `status` gains a `sending` value: claiming an email
+moves it there (not to `sent`), and it only becomes `sent` once every subscribed
+user as of that pass has a recorded row. A crash mid-blast leaves the row at
+`sending`, which the scheduler picks back up on its next tick (or on restart) and
+resumes — skipping anyone already recorded, so nobody receives it twice.
+
+Revision ID: 0025
+Revises: 0024
+Create Date: 2026-07-14 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0025"
+down_revision: Union[str, None] = "0024"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "featured_email_recipients",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "email_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("featured_emails.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "user_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("sent_at", sa.DateTime(timezone=True), nullable=False),
+    )
+    # The whole point of this table: a retry checks "has this (email, user) pair
+    # already been recorded" before sending again. Unique makes that check race-safe
+    # even if two scheduler ticks somehow overlapped.
+    op.create_index(
+        "ix_featured_email_recipients_email_user",
+        "featured_email_recipients",
+        ["email_id", "user_id"],
+        unique=True,
+    )
+    op.create_index(
+        "ix_featured_email_recipients_email_id",
+        "featured_email_recipients",
+        ["email_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("featured_email_recipients")

backend/alembic/versions/0026_add_publication_is_unlisted.py

@@ -0,0 +1,35 @@
+"""add is_unlisted to publications
+
+Backs the "feature any link" flow: a publication created from an arbitrary URL
+(rather than a normal submission) to fill a paid featured slot. It's a real,
+queryable Publication row — same table, same pipeline — just excluded from public
+browsing (home feed, search, categories, tags, roundups, other users' view of the
+owner's profile) via this flag. The owner can still see their own.
+
+Revision ID: 0026
+Revises: 0025
+Create Date: 2026-07-14 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0026"
+down_revision: Union[str, None] = "0025"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "publications",
+        sa.Column("is_unlisted", sa.Boolean(), nullable=False, server_default="false"),
+    )
+    op.create_index("ix_publications_is_unlisted", "publications", ["is_unlisted"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_publications_is_unlisted", table_name="publications")
+    op.drop_column("publications", "is_unlisted")