django-clerk-users 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

django_clerk_users/migrations/0001_initial.py

@@ -0,0 +1,174 @@
+# Generated by Django 5.2.8 on 2026-01-13 00:44
+
+import django.utils.timezone
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("auth", "0012_alter_user_first_name_max_length"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="ClerkUser",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("password", models.CharField(max_length=128, verbose_name="password")),
+                (
+                    "is_superuser",
+                    models.BooleanField(
+                        default=False,
+                        help_text="Designates that this user has all permissions without explicitly assigning them.",
+                        verbose_name="superuser status",
+                    ),
+                ),
+                (
+                    "uid",
+                    models.UUIDField(
+                        db_index=True,
+                        default=uuid.uuid4,
+                        editable=False,
+                        help_text="Public unique identifier for the user.",
+                    ),
+                ),
+                (
+                    "clerk_id",
+                    models.CharField(
+                        db_index=True,
+                        help_text="Unique identifier from Clerk.",
+                        max_length=255,
+                        unique=True,
+                    ),
+                ),
+                (
+                    "email",
+                    models.EmailField(
+                        db_index=True,
+                        help_text="User's email address.",
+                        max_length=254,
+                        unique=True,
+                    ),
+                ),
+                (
+                    "first_name",
+                    models.CharField(
+                        blank=True,
+                        default="",
+                        help_text="User's first name.",
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "last_name",
+                    models.CharField(
+                        blank=True,
+                        default="",
+                        help_text="User's last name.",
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "image_url",
+                    models.URLField(
+                        blank=True,
+                        default="",
+                        help_text="URL to user's profile image from Clerk.",
+                        max_length=500,
+                    ),
+                ),
+                (
+                    "is_active",
+                    models.BooleanField(
+                        default=True, help_text="Whether the user account is active."
+                    ),
+                ),
+                (
+                    "is_staff",
+                    models.BooleanField(
+                        default=False,
+                        help_text="Whether the user can access the admin site.",
+                    ),
+                ),
+                (
+                    "created_at",
+                    models.DateTimeField(
+                        default=django.utils.timezone.now,
+                        help_text="When the user was created.",
+                    ),
+                ),
+                (
+                    "updated_at",
+                    models.DateTimeField(
+                        auto_now=True, help_text="When the user was last updated."
+                    ),
+                ),
+                (
+                    "last_login",
+                    models.DateTimeField(
+                        blank=True,
+                        help_text="Last login timestamp (managed by Clerk).",
+                        null=True,
+                    ),
+                ),
+                (
+                    "last_logout",
+                    models.DateTimeField(
+                        blank=True,
+                        help_text="Last logout timestamp (managed by Clerk).",
+                        null=True,
+                    ),
+                ),
+                (
+                    "groups",
+                    models.ManyToManyField(
+                        blank=True,
+                        help_text="The groups this user belongs to. A user will get all permissions granted to each of their groups.",
+                        related_name="user_set",
+                        related_query_name="user",
+                        to="auth.group",
+                        verbose_name="groups",
+                    ),
+                ),
+                (
+                    "user_permissions",
+                    models.ManyToManyField(
+                        blank=True,
+                        help_text="Specific permissions for this user.",
+                        related_name="user_set",
+                        related_query_name="user",
+                        to="auth.permission",
+                        verbose_name="user permissions",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Clerk User",
+                "verbose_name_plural": "Clerk Users",
+                "ordering": ["-created_at"],
+                "abstract": False,
+                "swappable": "AUTH_USER_MODEL",
+                "indexes": [
+                    models.Index(
+                        fields=["clerk_id"], name="django_cler_clerk_i_d591b6_idx"
+                    ),
+                    models.Index(fields=["email"], name="django_cler_email_f1e649_idx"),
+                    models.Index(fields=["uid"], name="django_cler_uid_9f6a95_idx"),
+                    models.Index(
+                        fields=["is_active"], name="django_cler_is_acti_ceff9c_idx"
+                    ),
+                ],
+            },
+        ),
+    ]

django_clerk_users/models.py

@@ -0,0 +1,174 @@
+"""
+User models for django-clerk-users.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin
+from django.db import models
+from django.utils import timezone
+
+from django_clerk_users.managers import ClerkUserManager
+
+
+class AbstractClerkUser(AbstractBaseUser, PermissionsMixin):
+    """
+    Abstract base class for Clerk-authenticated users.
+
+    Extend this class to create a custom user model with additional fields
+    while maintaining Clerk integration.
+
+    Example:
+        class CustomUser(AbstractClerkUser):
+            company = models.CharField(max_length=255, blank=True)
+            phone = models.CharField(max_length=20, blank=True)
+
+            class Meta(AbstractClerkUser.Meta):
+                swappable = "AUTH_USER_MODEL"
+    """
+
+    # Public identifier (use this in URLs and APIs instead of pk)
+    uid = models.UUIDField(
+        default=uuid.uuid4,
+        editable=False,
+        db_index=True,
+        help_text="Public unique identifier for the user.",
+    )
+
+    # Clerk-specific fields
+    clerk_id = models.CharField(
+        max_length=255,
+        unique=True,
+        db_index=True,
+        help_text="Unique identifier from Clerk.",
+    )
+
+    # Standard user fields
+    email = models.EmailField(
+        unique=True,
+        db_index=True,
+        help_text="User's email address.",
+    )
+    first_name = models.CharField(
+        max_length=255,
+        blank=True,
+        default="",
+        help_text="User's first name.",
+    )
+    last_name = models.CharField(
+        max_length=255,
+        blank=True,
+        default="",
+        help_text="User's last name.",
+    )
+    image_url = models.URLField(
+        max_length=500,
+        blank=True,
+        default="",
+        help_text="URL to user's profile image from Clerk.",
+    )
+
+    # Status fields
+    is_active = models.BooleanField(
+        default=True,
+        help_text="Whether the user account is active.",
+    )
+    is_staff = models.BooleanField(
+        default=False,
+        help_text="Whether the user can access the admin site.",
+    )
+
+    # Timestamps
+    created_at = models.DateTimeField(
+        default=timezone.now,
+        help_text="When the user was created.",
+    )
+    updated_at = models.DateTimeField(
+        auto_now=True,
+        help_text="When the user was last updated.",
+    )
+    last_login = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Last login timestamp (managed by Clerk).",
+    )
+    last_logout = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Last logout timestamp (managed by Clerk).",
+    )
+
+    objects = ClerkUserManager()
+
+    USERNAME_FIELD = "email"
+    REQUIRED_FIELDS = ["clerk_id"]
+
+    class Meta:
+        abstract = True
+        ordering = ["-created_at"]
+        indexes = [
+            models.Index(fields=["clerk_id"]),
+            models.Index(fields=["email"]),
+            models.Index(fields=["uid"]),
+            models.Index(fields=["is_active"]),
+        ]
+
+    def __str__(self) -> str:
+        return self.email
+
+    @property
+    def public_id(self) -> str:
+        """Return the public UUID as a string for API responses."""
+        return str(self.uid)
+
+    @property
+    def full_name(self) -> str:
+        """Return the user's full name."""
+        return f"{self.first_name} {self.last_name}".strip()
+
+    def get_full_name(self) -> str:
+        """Return the user's full name (Django compatibility)."""
+        return self.full_name
+
+    def get_short_name(self) -> str:
+        """Return the user's first name (Django compatibility)."""
+        return self.first_name or self.email.split("@")[0]
+
+    def has_perm(self, perm: str, obj: Any = None) -> bool:
+        """
+        Return True if the user has the specified permission.
+
+        For Clerk users, permissions are typically managed through
+        Clerk's organization roles or custom metadata.
+        Superusers have all permissions.
+        """
+        if self.is_superuser:
+            return True
+        return super().has_perm(perm, obj)
+
+    def has_module_perms(self, app_label: str) -> bool:
+        """
+        Return True if the user has any permissions in the given app.
+
+        Superusers have all permissions.
+        """
+        if self.is_superuser:
+            return True
+        return super().has_module_perms(app_label)
+
+
+class ClerkUser(AbstractClerkUser):
+    """
+    Concrete user model for Clerk authentication.
+
+    Use this model directly by setting AUTH_USER_MODEL = "django_clerk_users.ClerkUser"
+    in your Django settings, or extend AbstractClerkUser for custom fields.
+    """
+
+    class Meta(AbstractClerkUser.Meta):
+        swappable = "AUTH_USER_MODEL"
+        verbose_name = "Clerk User"
+        verbose_name_plural = "Clerk Users"

django_clerk_users/organizations/__init__.py

@@ -0,0 +1,8 @@
+"""
+Organizations sub-app for django-clerk-users.
+
+This is an optional sub-app that provides organization support.
+To use it, add 'django_clerk_users.organizations' to INSTALLED_APPS.
+"""
+
+default_app_config = "django_clerk_users.organizations.apps.OrganizationsConfig"

django_clerk_users/organizations/admin.py

@@ -0,0 +1,81 @@
+"""
+Django admin configuration for organization models.
+"""
+
+from django.contrib import admin
+
+from django_clerk_users.organizations.models import (
+    Organization,
+    OrganizationInvitation,
+    OrganizationMember,
+)
+
+
+@admin.register(Organization)
+class OrganizationAdmin(admin.ModelAdmin):
+    list_display = [
+        "name",
+        "slug",
+        "clerk_id",
+        "members_count",
+        "is_active",
+        "created_at",
+    ]
+    list_filter = ["is_active", "created_at"]
+    search_fields = ["name", "slug", "clerk_id"]
+    readonly_fields = [
+        "uid",
+        "clerk_id",
+        "created_at",
+        "updated_at",
+        "members_count",
+        "pending_invitations_count",
+    ]
+    ordering = ["-created_at"]
+
+
+@admin.register(OrganizationMember)
+class OrganizationMemberAdmin(admin.ModelAdmin):
+    list_display = [
+        "user",
+        "organization",
+        "role",
+        "joined_at",
+    ]
+    list_filter = ["role", "joined_at"]
+    search_fields = [
+        "user__email",
+        "organization__name",
+        "clerk_membership_id",
+    ]
+    readonly_fields = [
+        "clerk_membership_id",
+        "joined_at",
+        "updated_at",
+    ]
+    raw_id_fields = ["user", "organization"]
+    ordering = ["-joined_at"]
+
+
+@admin.register(OrganizationInvitation)
+class OrganizationInvitationAdmin(admin.ModelAdmin):
+    list_display = [
+        "email_address",
+        "organization",
+        "role",
+        "status",
+        "created_at",
+    ]
+    list_filter = ["status", "role", "created_at"]
+    search_fields = [
+        "email_address",
+        "organization__name",
+        "clerk_invitation_id",
+    ]
+    readonly_fields = [
+        "clerk_invitation_id",
+        "created_at",
+        "updated_at",
+    ]
+    raw_id_fields = ["organization", "inviter"]
+    ordering = ["-created_at"]

django_clerk_users/organizations/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class OrganizationsConfig(AppConfig):
+    name = "django_clerk_users.organizations"
+    label = "clerk_organizations"
+    verbose_name = "Clerk Organizations"
+    default_auto_field = "django.db.models.BigAutoField"

django_clerk_users/organizations/middleware.py

@@ -0,0 +1,130 @@
+"""
+Organization middleware for django-clerk-users.
+
+This middleware resolves Clerk organization IDs to Organization model instances.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Callable
+
+from django_clerk_users.caching import (
+    get_cached_organization,
+    set_cached_organization,
+)
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse
+
+    from django_clerk_users.organizations.models import Organization
+
+logger = logging.getLogger(__name__)
+
+
+class ClerkOrganizationMiddleware:
+    """
+    Middleware that resolves organization context.
+
+    This middleware runs after ClerkAuthMiddleware and resolves the
+    organization ID (from request.org) to an Organization model instance.
+
+    After processing, the middleware sets:
+    - request.organization: The Organization model instance (or None)
+
+    The organization ID can come from:
+    1. request.org (set by ClerkAuthMiddleware from JWT payload)
+    2. X-Organization-Id header (for explicit org switching)
+    """
+
+    def __init__(self, get_response: Callable[["HttpRequest"], "HttpResponse"]):
+        self.get_response = get_response
+
+    def __call__(self, request: "HttpRequest") -> "HttpResponse":
+        # Process organization before the view
+        self.process_request(request)
+
+        # Call the next middleware/view
+        response = self.get_response(request)
+
+        return response
+
+    def process_request(self, request: "HttpRequest") -> None:
+        """
+        Resolve the organization context.
+
+        Sets request.organization to the Organization model instance
+        if an organization ID is present.
+        """
+        request.organization = None  # type: ignore
+
+        # Get organization ID from request
+        # Priority: request.org (from JWT) > X-Organization-Id header
+        org_id = getattr(request, "org", None)
+        if not org_id:
+            org_id = request.headers.get("X-Organization-Id")
+
+        if not org_id:
+            return
+
+        # Resolve to Organization model
+        organization = self._get_organization(org_id)
+        if organization:
+            if not self._is_member(request, organization):
+                logger.debug("User is not a member of org %s", org_id)
+                return
+            request.organization = organization  # type: ignore
+            # Update request.org in case it came from header
+            request.org = org_id  # type: ignore
+
+    def _is_member(self, request: "HttpRequest", organization: "Organization") -> bool:
+        """
+        Check whether the current user belongs to the organization.
+
+        Args:
+            request: The current HTTP request.
+            organization: The organization to check.
+
+        Returns:
+            True if the user is authenticated and a member.
+        """
+        if not hasattr(request, "user") or not request.user.is_authenticated:
+            return False
+
+        from django_clerk_users.organizations.models import OrganizationMember
+
+        return OrganizationMember.objects.filter(
+            organization=organization,
+            user=request.user,
+        ).exists()
+
+    def _get_organization(self, clerk_id: str) -> "Organization | None":
+        """
+        Get an Organization by Clerk ID, using cache.
+
+        Args:
+            clerk_id: The Clerk organization ID.
+
+        Returns:
+            The Organization instance or None if not found.
+        """
+        from django_clerk_users.organizations.models import Organization
+
+        # Check cache first
+        cached = get_cached_organization(clerk_id)
+        if cached is not None:
+            if cached is False:
+                return None  # Cached as "not found"
+            return cached
+
+        # Query database
+        try:
+            organization = Organization.objects.get(
+                clerk_id=clerk_id,
+                is_active=True,
+            )
+            set_cached_organization(clerk_id, organization)
+            return organization
+        except Organization.DoesNotExist:
+            set_cached_organization(clerk_id, None)
+            return None