chub-dev 0.1.0 → 0.1.2-beta.0

package/dist/clerk/docs/auth/python/DOC.md

@@ -0,0 +1,274 @@
+---
+name: auth
+description: "Clerk Backend API Python SDK for server-side authentication and user management operations"
+metadata:
+  languages: "python"
+  versions: "3.3.1"
+  updated-on: "2026-03-01"
+  source: maintainer
+  tags: "clerk,auth,authentication,user-management,backend"
+---
+
+# Clerk Backend API Python SDK Coding Guidelines
+
+You are a Clerk Backend API Python SDK expert. Help me with writing code using the Clerk Backend API Python SDK for authentication and user management operations.
+
+Please follow the following guidelines when generating code.
+
+## Golden Rule: Use the Correct and Current SDK
+
+Always use the official Clerk Backend API Python SDK, which is automatically generated from the Clerk Backend API OpenAPI specification using Speakeasy. 
+
+- **Library Name:** Clerk Backend API Python SDK
+- **Python Package:** `clerk-backend-api`
+- **Main Class:** `Clerk` 
+
+**Installation:**
+
+```bash
+pip install clerk-backend-api
+```
+
+**Basic Import:**
+
+```python
+from clerk_backend_api import Clerk
+```
+
+## Initialization and API Key
+
+The Clerk SDK requires a secret key for authentication. Always initialize the client with your Clerk secret key:
+
+```python
+from clerk_backend_api import Clerk
+
+# Initialize with secret key
+clerk = Clerk(bearer_auth="sk_test_your_secret_key_here")
+```
+
+Set your `CLERK_SECRET_KEY` environment variable for production use.
+
+## Core SDK Structure
+
+The SDK is organized into logical modules for different Clerk resources: 
+
+- **Users:** User management operations
+- **Organizations:** Organization and membership management  
+- **Sessions:** Session management and verification
+- **Email Addresses:** Email address operations
+- **Phone Numbers:** Phone number operations
+- **Invitations:** Organization invitations
+- **JWT Templates:** Custom JWT configuration
+- **OAuth Applications:** OAuth app management
+- **Webhooks:** Webhook management
+
+## Basic User Operations
+
+### Create a User
+
+```python
+from clerk_backend_api import Clerk
+
+clerk = Clerk(bearer_auth="sk_test_your_secret_key_here")
+
+# Create a new user
+response = clerk.users.create_user(
+    request_body={
+        "email_address": ["user@example.com"],
+        "password": "secure_password123",
+        "first_name": "John",
+        "last_name": "Doe"
+    }
+)
+
+user = response.object
+print(f"Created user: {user.id}")
+```
+
+### Get a User
+
+```python
+# Get user by ID
+response = clerk.users.get_user(user_id="user_123456789")
+user = response.object
+print(f"User email: {user.email_addresses[0].email_address}")
+```
+
+### List Users
+
+```python
+# List all users with pagination
+response = clerk.users.get_user_list(
+    limit=10,
+    offset=0,
+    order_by="-created_at"
+)
+
+for user in response.object:
+    print(f"User: {user.id} - {user.first_name} {user.last_name}")
+```
+
+### Update a User
+
+```python
+# Update user information
+response = clerk.users.update_user(
+    user_id="user_123456789",
+    request_body={
+        "first_name": "Jane",
+        "last_name": "Smith"
+    }
+)
+```
+
+## Session Management
+
+### Verify a Session
+
+```python
+# Verify a session token
+response = clerk.sessions.verify_session(
+    session_id="sess_123456789",
+    request_body={
+        "token": "session_token_here"
+    }
+)
+
+session = response.object
+print(f"Session status: {session.status}")
+```
+
+### Get Session List
+
+```python
+# Get all sessions for a client
+response = clerk.sessions.get_session_list(
+    client_id="client_123456789",
+    user_id="user_123456789"
+)
+```
+
+## Organization Management
+
+### Create an Organization
+
+```python
+# Create a new organization
+response = clerk.organizations.create_organization(
+    request_body={
+        "name": "Acme Corp",
+        "slug": "acme-corp",
+        "created_by": "user_123456789"
+    }
+)
+
+org = response.object
+print(f"Created organization: {org.id}")
+```
+
+### Add Organization Member
+
+```python
+# Add a user to an organization
+response = clerk.organization_memberships.create_organization_membership(
+    organization_id="org_123456789",
+    request_body={
+        "user_id": "user_123456789",
+        "role": "basic_member"
+    }
+)
+```
+
+## Email and Phone Number Management
+
+### Add Email Address
+
+```python
+# Add email address to user
+response = clerk.email_addresses.create_email_address(
+    request_body={
+        "user_id": "user_123456789",
+        "email_address": "new@example.com",
+        "verified": False,
+        "primary": False
+    }
+)
+```
+
+### Add Phone Number
+
+```python
+# Add phone number to user
+response = clerk.phone_numbers.create_phone_number(
+    request_body={
+        "user_id": "user_123456789",
+        "phone_number": "+1234567890",
+        "verified": False,
+        "primary": False
+    }
+)
+```
+
+## JWT Templates
+
+### Create JWT Template
+
+```python
+# Create custom JWT template
+response = clerk.jwt_templates.create_jwt_template(
+    request_body={
+        "name": "custom_template",
+        "claims": {
+            "custom_claim": "{{user.id}}"
+        },
+        "lifetime": 3600,
+        "allowed_clock_skew": 5
+    }
+)
+```
+
+## Webhook Management
+
+### Create Webhook Endpoint
+
+```python
+# Create webhook endpoint
+response = clerk.webhooks.create_webhook(
+    request_body={
+        "url": "https://your-app.com/webhooks/clerk",
+        "events": ["user.created", "user.updated", "session.created"]
+    }
+)
+```
+
+## Error Handling
+
+The SDK uses structured error responses. Always handle potential errors:
+
+```python
+from clerk_backend_api import Clerk
+from clerk_backend_api.models import ClerkErrors
+
+clerk = Clerk(bearer_auth="sk_test_your_secret_key_here")
+
+try:
+    response = clerk.users.get_user(user_id="invalid_user_id")
+    user = response.object
+except Exception as e:
+    if hasattr(e, 'errors'):
+        for error in e.errors:
+            print(f"Error: {error.message} (Code: {error.code})")
+    else:
+        print(f"Unexpected error: {e}")
+```
+
+## Dependencies and Requirements
+
+The SDK includes the following key dependencies: 
+
+- `cryptography ^43.0.1` - For cryptographic operations
+- `pyjwt ^2.9.0` - For JWT token handling
+
+## SDK Configuration
+
+The SDK is automatically generated and maintained using Speakeasy configuration. The current version is `2.0.2` and includes comprehensive type hints and documentation.