sf-queue-sdk 0.1.0__tar.gz

sf_queue_sdk-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+
+# Go
+/bin/
+*.exe
+*.dll
+*.so
+*.dylib
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+.vscode/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Local testing (standalone project, uses npm not pnpm to avoid workspace conflicts)
+local-testing/node_modules/
+local-testing/.env
+local-testing/package-lock.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+*.log
+coverage/
+.nyc_output/
+
+# Lock files are committed
+# uv.lock
+# pnpm-lock.yaml
+
+# Generated files (committed for SDK distribution)
+# packages/go/proto-go/ -- committed
+# packages/ts/queue-sdk/src/generated/ -- committed
+# packages/py/queue-sdk/queue_sdk/generated/ -- committed

sf_queue_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: sf-queue-sdk
+Version: 0.1.0
+Summary: Python SDK for sf-queue - Redis-based queue system
+Requires-Python: >=3.11
+Requires-Dist: redis>=5.0.0

sf_queue_sdk-0.1.0/README.md

@@ -0,0 +1,202 @@
+# sf-queue-sdk
+
+Python SDK for sf-queue. Enqueues emails via Redis Streams with optional blocking confirmation from the Go consumer service.
+
+## Installation
+
+```bash
+pip install sf-queue-sdk
+```
+
+## Setup
+
+```python
+from queue_sdk import QueueClient
+
+client = QueueClient(
+    redis_url="redis://localhost:6379",
+    redis_password="your-password",
+    environment="staging",  # prefixes stream names: staging:{email}
+)
+```
+
+## Single Email
+
+### Fire and forget
+
+Enqueues the email and returns immediately. Does not wait for the consumer to process it.
+
+```python
+result = client.email.send(
+    to="user@example.com",
+    preview="Welcome to StudyFetch!",
+    subject="Welcome to StudyFetch!",
+    paragraphs=[
+        "Hey there,",
+        "Welcome to the StudyFetch community!",
+        "Thanks for joining us.",
+    ],
+    button={
+        "text": "Go to Platform",
+        "href": "https://www.studyfetch.com/platform",
+    },
+)
+
+print("Enqueued:", result.message_id)
+```
+
+### Send and wait for confirmation
+
+Enqueues the email and blocks until the Go consumer processes it (or timeout).
+
+```python
+result = client.email.send_and_wait(
+    to="user@example.com",
+    preview="Reset your password",
+    subject="StudyFetch: Reset Your Password",
+    paragraphs=[
+        "Hi There,",
+        "Click the button below to reset your password.",
+    ],
+    button={
+        "text": "Reset Password",
+        "href": "https://www.studyfetch.com/reset?token=abc",
+    },
+    timeout=30,  # optional, default 30s
+)
+
+print(result.success)     # True or False
+print(result.message_id)  # request ID
+print(result.error)       # error message if failed
+```
+
+## Batch Email
+
+Send the same email content to multiple recipients (up to 100). The Go consumer sends to each recipient individually.
+
+### Fire and forget
+
+```python
+result = client.email.send_batch(
+    to=[
+        "student1@example.com",
+        "student2@example.com",
+        "student3@example.com",
+    ],
+    preview="You have been invited to join a class!",
+    subject="StudyFetch: Class Invitation",
+    paragraphs=[
+        "Hi There,",
+        'You have been invited to join "Intro to CS" on StudyFetch!',
+        "Click the button below to accept the invite.",
+    ],
+    button={
+        "text": "Accept Invite",
+        "href": "https://www.studyfetch.com/invite/abc",
+    },
+)
+
+print("Enqueued:", result.message_id)
+```
+
+### Send and wait for confirmation
+
+```python
+result = client.email.send_batch_and_wait(
+    to=[
+        "student1@example.com",
+        "student2@example.com",
+        "student3@example.com",
+    ],
+    preview="You have been invited to join a class!",
+    subject="StudyFetch: Class Invitation",
+    paragraphs=[
+        "Hi There,",
+        'You have been invited to join "Intro to CS" on StudyFetch!',
+        "Click the button below to accept the invite.",
+    ],
+    button={
+        "text": "Accept Invite",
+        "href": "https://www.studyfetch.com/invite/abc",
+    },
+    timeout=30,
+)
+
+print(result.success)     # True if at least some sent
+print(result.message_id)  # request ID
+print(result.total)       # 3
+print(result.successful)  # number sent successfully
+print(result.failed)      # number that failed
+print(result.error)       # error message if all failed
+```
+
+## All Email Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `to` | `str` | Yes (single) | Recipient email address |
+| `to` | `list[str]` | Yes (batch) | List of recipient emails (max 100) |
+| `preview` | `str` | Yes | Preview text shown in email clients |
+| `subject` | `str` | Yes | Email subject line |
+| `paragraphs` | `list[str]` | Yes | Body content as paragraph strings |
+| `button` | `{"text": str, "href": str}` | No | Call-to-action button |
+| `reply_to` | `str` | No | Reply-to email address |
+| `image` | `{"src": str, "alt"?: str, "width"?: int, "height"?: int}` | No | Image in email body |
+
+## Optional Fields
+
+```python
+# With all optional fields
+client.email.send(
+    to="support@studyfetch.com",
+    preview="Support Request",
+    subject="StudyFetch: Support Request",
+    paragraphs=["Hi There,", "You received a support request.", issue],
+    reply_to="requester@example.com",
+    image={
+        "src": "https://example.com/logo.png",
+        "alt": "Logo",
+        "width": 150,
+        "height": 50,
+    },
+)
+```
+
+## Migrating from sendEmail / sendBatchEmail
+
+The SDK is a drop-in replacement. Field names match the existing functions:
+
+```python
+# BEFORE
+send_email(to=to, preview=preview, subject=subject, paragraphs=paragraphs, button=button)
+
+# AFTER (fire and forget)
+client.email.send(to=to, preview=preview, subject=subject, paragraphs=paragraphs, button=button)
+
+# AFTER (wait for confirmation)
+client.email.send_and_wait(to=to, preview=preview, subject=subject, paragraphs=paragraphs, button=button)
+
+# BEFORE (batch)
+send_batch_email(to=[...], preview=preview, subject=subject, paragraphs=paragraphs, button=button)
+
+# AFTER (batch, fire and forget)
+client.email.send_batch(to=[...], preview=preview, subject=subject, paragraphs=paragraphs, button=button)
+
+# AFTER (batch, wait for confirmation)
+client.email.send_batch_and_wait(to=[...], preview=preview, subject=subject, paragraphs=paragraphs, button=button)
+```
+
+## Methods and Response Types
+
+| Method | Return Type | Fields |
+|--------|-------------|--------|
+| `send()` | `SendResult` | `message_id` |
+| `send_and_wait()` | `EmailResponse` | `success`, `message_id`, `error?`, `processed_at?` |
+| `send_batch()` | `SendResult` | `message_id` |
+| `send_batch_and_wait()` | `BatchEmailResponse` | `success`, `message_id`, `error?`, `processed_at?`, `total`, `successful`, `failed` |
+
+## Cleanup
+
+```python
+client.disconnect()
+```

sf_queue_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "sf-queue-sdk"
+version = "0.1.0"
+description = "Python SDK for sf-queue - Redis-based queue system"
+requires-python = ">=3.11"
+dependencies = [
+    "redis>=5.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["queue_sdk"]

sf_queue_sdk-0.1.0/queue_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""sf-queue Python SDK - Redis-based queue system."""
+
+__version__ = "0.1.0"
+
+from queue_sdk.client import QueueClient
+from queue_sdk.types import (
+    BatchEmailResponse,
+    EmailButton,
+    EmailData,
+    EmailImage,
+    EmailResponse,
+    QueueClientConfig,
+    SendResult,
+)
+
+__all__ = [
+    "QueueClient",
+    "QueueClientConfig",
+    "EmailData",
+    "EmailButton",
+    "EmailImage",
+    "EmailResponse",
+    "BatchEmailResponse",
+    "SendResult",
+]

sf_queue_sdk-0.1.0/queue_sdk/client.py

@@ -0,0 +1,58 @@
+"""QueueClient - main entry point for the Python SDK."""
+
+from queue_sdk.queues.email_queue import EmailQueue
+from queue_sdk.redis_client import create_redis_client
+from queue_sdk.types import QueueClientConfig
+
+
+class QueueClient:
+    """Main entry point for the sf-queue Python SDK.
+
+    Initialize with Redis connection details and environment,
+    then use typed queue properties to send messages.
+
+    Usage:
+        client = QueueClient(
+            redis_url="redis://localhost:6379",
+            redis_password="your-password",
+            environment="staging",
+        )
+
+        # Fire and forget
+        result = client.email.send(
+            to="user@example.com",
+            preview="Welcome!",
+            subject="Welcome!",
+            paragraphs=["Hello!", "Welcome to our platform."],
+        )
+
+        # Send and wait for confirmation
+        response = client.email.send_and_wait(
+            to="user@example.com",
+            preview="Welcome!",
+            subject="Welcome!",
+            paragraphs=["Hello!"],
+            timeout=30,
+        )
+    """
+
+    def __init__(
+        self,
+        redis_url: str,
+        redis_password: str,
+        environment: str,
+    ):
+        config = QueueClientConfig(
+            redis_url=redis_url,
+            redis_password=redis_password,
+            environment=environment,
+        )
+        self._redis = create_redis_client(config)
+        self._environment = environment
+
+        # Initialize queue instances
+        self.email = EmailQueue(self._redis, self._environment)
+
+    def disconnect(self) -> None:
+        """Close the Redis connection."""
+        self._redis.close()

sf_queue_sdk-0.1.0/queue_sdk/generated/queue/email/v1/email_pb2.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: queue/email/v1/email.proto
+# Protobuf Python Version: 6.33.5
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    5,
+    '',
+    'queue/email/v1/email.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1aqueue/email/v1/email.proto\x12\x0equeue.email.v1\"5\n\x0b\x45mailButton\x12\x12\n\x04text\x18\x01 \x01(\tR\x04text\x12\x12\n\x04href\x18\x02 \x01(\tR\x04href\"^\n\nEmailImage\x12\x10\n\x03src\x18\x01 \x01(\tR\x03src\x12\x10\n\x03\x61lt\x18\x02 \x01(\tR\x03\x61lt\x12\x14\n\x05width\x18\x03 \x01(\x05R\x05width\x12\x16\n\x06height\x18\x04 \x01(\x05R\x06height\"\xf4\x01\n\x0c\x45mailRequest\x12\x0e\n\x02to\x18\x01 \x01(\tR\x02to\x12\x18\n\x07preview\x18\x02 \x01(\tR\x07preview\x12\x18\n\x07subject\x18\x03 \x01(\tR\x07subject\x12\x1e\n\nparagraphs\x18\x04 \x03(\tR\nparagraphs\x12\x33\n\x06\x62utton\x18\x05 \x01(\x0b\x32\x1b.queue.email.v1.EmailButtonR\x06\x62utton\x12\x19\n\x08reply_to\x18\x06 \x01(\tR\x07replyTo\x12\x30\n\x05image\x18\x07 \x01(\x0b\x32\x1a.queue.email.v1.EmailImageR\x05image\"\xf9\x01\n\x11\x42\x61tchEmailRequest\x12\x0e\n\x02to\x18\x01 \x03(\tR\x02to\x12\x18\n\x07preview\x18\x02 \x01(\tR\x07preview\x12\x18\n\x07subject\x18\x03 \x01(\tR\x07subject\x12\x1e\n\nparagraphs\x18\x04 \x03(\tR\nparagraphs\x12\x33\n\x06\x62utton\x18\x05 \x01(\x0b\x32\x1b.queue.email.v1.EmailButtonR\x06\x62utton\x12\x19\n\x08reply_to\x18\x06 \x01(\tR\x07replyTo\x12\x30\n\x05image\x18\x07 \x01(\x0b\x32\x1a.queue.email.v1.EmailImageR\x05image\"^\n\rEmailResponse\x12\x18\n\x07success\x18\x01 \x01(\x08R\x07success\x12\x1d\n\nmessage_id\x18\x02 \x01(\tR\tmessageId\x12\x14\n\x05\x65rror\x18\x03 \x01(\tR\x05\x65rrorBLZJgithub.com/StudyFetch/sf-queue/packages/go/proto-go/queue/email/v1;emailv1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'queue.email.v1.email_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'ZJgithub.com/StudyFetch/sf-queue/packages/go/proto-go/queue/email/v1;emailv1'
+  _globals['_EMAILBUTTON']._serialized_start=46
+  _globals['_EMAILBUTTON']._serialized_end=99
+  _globals['_EMAILIMAGE']._serialized_start=101
+  _globals['_EMAILIMAGE']._serialized_end=195
+  _globals['_EMAILREQUEST']._serialized_start=198
+  _globals['_EMAILREQUEST']._serialized_end=442
+  _globals['_BATCHEMAILREQUEST']._serialized_start=445
+  _globals['_BATCHEMAILREQUEST']._serialized_end=694
+  _globals['_EMAILRESPONSE']._serialized_start=696
+  _globals['_EMAILRESPONSE']._serialized_end=790
+# @@protoc_insertion_point(module_scope)

sf_queue_sdk-0.1.0/queue_sdk/generated/queue/email/v1/email_pb2.pyi

@@ -0,0 +1,73 @@
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Iterable as _Iterable, Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class EmailButton(_message.Message):
+    __slots__ = ("text", "href")
+    TEXT_FIELD_NUMBER: _ClassVar[int]
+    HREF_FIELD_NUMBER: _ClassVar[int]
+    text: str
+    href: str
+    def __init__(self, text: _Optional[str] = ..., href: _Optional[str] = ...) -> None: ...
+
+class EmailImage(_message.Message):
+    __slots__ = ("src", "alt", "width", "height")
+    SRC_FIELD_NUMBER: _ClassVar[int]
+    ALT_FIELD_NUMBER: _ClassVar[int]
+    WIDTH_FIELD_NUMBER: _ClassVar[int]
+    HEIGHT_FIELD_NUMBER: _ClassVar[int]
+    src: str
+    alt: str
+    width: int
+    height: int
+    def __init__(self, src: _Optional[str] = ..., alt: _Optional[str] = ..., width: _Optional[int] = ..., height: _Optional[int] = ...) -> None: ...
+
+class EmailRequest(_message.Message):
+    __slots__ = ("to", "preview", "subject", "paragraphs", "button", "reply_to", "image")
+    TO_FIELD_NUMBER: _ClassVar[int]
+    PREVIEW_FIELD_NUMBER: _ClassVar[int]
+    SUBJECT_FIELD_NUMBER: _ClassVar[int]
+    PARAGRAPHS_FIELD_NUMBER: _ClassVar[int]
+    BUTTON_FIELD_NUMBER: _ClassVar[int]
+    REPLY_TO_FIELD_NUMBER: _ClassVar[int]
+    IMAGE_FIELD_NUMBER: _ClassVar[int]
+    to: str
+    preview: str
+    subject: str
+    paragraphs: _containers.RepeatedScalarFieldContainer[str]
+    button: EmailButton
+    reply_to: str
+    image: EmailImage
+    def __init__(self, to: _Optional[str] = ..., preview: _Optional[str] = ..., subject: _Optional[str] = ..., paragraphs: _Optional[_Iterable[str]] = ..., button: _Optional[_Union[EmailButton, _Mapping]] = ..., reply_to: _Optional[str] = ..., image: _Optional[_Union[EmailImage, _Mapping]] = ...) -> None: ...
+
+class BatchEmailRequest(_message.Message):
+    __slots__ = ("to", "preview", "subject", "paragraphs", "button", "reply_to", "image")
+    TO_FIELD_NUMBER: _ClassVar[int]
+    PREVIEW_FIELD_NUMBER: _ClassVar[int]
+    SUBJECT_FIELD_NUMBER: _ClassVar[int]
+    PARAGRAPHS_FIELD_NUMBER: _ClassVar[int]
+    BUTTON_FIELD_NUMBER: _ClassVar[int]
+    REPLY_TO_FIELD_NUMBER: _ClassVar[int]
+    IMAGE_FIELD_NUMBER: _ClassVar[int]
+    to: _containers.RepeatedScalarFieldContainer[str]
+    preview: str
+    subject: str
+    paragraphs: _containers.RepeatedScalarFieldContainer[str]
+    button: EmailButton
+    reply_to: str
+    image: EmailImage
+    def __init__(self, to: _Optional[_Iterable[str]] = ..., preview: _Optional[str] = ..., subject: _Optional[str] = ..., paragraphs: _Optional[_Iterable[str]] = ..., button: _Optional[_Union[EmailButton, _Mapping]] = ..., reply_to: _Optional[str] = ..., image: _Optional[_Union[EmailImage, _Mapping]] = ...) -> None: ...
+
+class EmailResponse(_message.Message):
+    __slots__ = ("success", "message_id", "error")
+    SUCCESS_FIELD_NUMBER: _ClassVar[int]
+    MESSAGE_ID_FIELD_NUMBER: _ClassVar[int]
+    ERROR_FIELD_NUMBER: _ClassVar[int]
+    success: bool
+    message_id: str
+    error: str
+    def __init__(self, success: _Optional[bool] = ..., message_id: _Optional[str] = ..., error: _Optional[str] = ...) -> None: ...

sf_queue_sdk-0.1.0/queue_sdk/queues/base_queue.py

@@ -0,0 +1,71 @@
+"""Base queue class with send/send_and_wait mechanics."""
+
+import json
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import redis as redis_lib
+
+from queue_sdk.redis_client import response_key, stream_name
+from queue_sdk.types import EmailResponse
+
+DEFAULT_TIMEOUT = 30  # seconds
+
+
+class BaseQueue:
+    """Base queue providing core send/send_and_wait mechanics for any queue type."""
+
+    def __init__(self, redis_client: redis_lib.Redis, environment: str, queue_name: str):
+        self._redis = redis_client
+        self._environment = environment
+        self._queue_name = queue_name
+        # Use hash tags for Redis Cluster slot compatibility
+        self._stream = stream_name(environment, "{" + queue_name + "}")
+
+    def _enqueue(self, payload: dict[str, Any]) -> str:
+        """Add a message to the stream and return the request ID."""
+        request_id = str(uuid.uuid4())
+        message = {
+            "requestId": request_id,
+            "payload": json.dumps(payload),
+            "createdAt": datetime.now(timezone.utc).isoformat(),
+        }
+
+        self._redis.xadd(self._stream, message)
+        return request_id
+
+    def _enqueue_and_wait(
+        self, payload: dict[str, Any], timeout: Optional[int] = None
+    ) -> EmailResponse:
+        """Add a message and wait for the response."""
+        request_id = self._enqueue(payload)
+        wait_timeout = timeout if timeout is not None else DEFAULT_TIMEOUT
+
+        key = response_key(self._environment, self._queue_name, request_id)
+
+        # BRPOP blocks until a response is pushed or timeout
+        result = self._redis.brpop(key, timeout=wait_timeout)
+
+        if result is None:
+            return EmailResponse(
+                success=False,
+                message_id=request_id,
+                error=f"Timeout waiting for response after {wait_timeout}s",
+            )
+
+        try:
+            # result is (key, value) tuple
+            response_data = json.loads(result[1])
+            return EmailResponse(
+                success=response_data.get("success", False),
+                message_id=response_data.get("messageId", request_id),
+                error=response_data.get("error"),
+                processed_at=response_data.get("processedAt"),
+            )
+        except (json.JSONDecodeError, KeyError):
+            return EmailResponse(
+                success=False,
+                message_id=request_id,
+                error="Failed to parse response from queue",
+            )

sf_queue_sdk-0.1.0/queue_sdk/queues/email_queue.py

@@ -0,0 +1,161 @@
+"""Email queue with typed methods."""
+
+from typing import Any, Optional
+
+import redis as redis_lib
+
+from queue_sdk.queues.base_queue import BaseQueue
+from queue_sdk.sanitize import sanitize, sanitize_list
+from queue_sdk.types import (
+    BatchEmailResponse,
+    EmailResponse,
+    SendResult,
+)
+
+
+class EmailQueue(BaseQueue):
+    """Typed methods for sending emails via the queue."""
+
+    def __init__(self, redis_client: redis_lib.Redis, environment: str):
+        super().__init__(redis_client, environment, "email")
+
+    def send(
+        self,
+        to: str,
+        preview: str,
+        subject: str,
+        paragraphs: list[str],
+        button: Optional[dict[str, str]] = None,
+        reply_to: Optional[str] = None,
+        image: Optional[dict[str, Any]] = None,
+    ) -> SendResult:
+        """Enqueue an email for processing (fire and forget)."""
+        payload = self._build_payload(to, preview, subject, paragraphs, button, reply_to, image)
+        message_id = self._enqueue(payload)
+        return SendResult(message_id=message_id)
+
+    def send_and_wait(
+        self,
+        to: str,
+        preview: str,
+        subject: str,
+        paragraphs: list[str],
+        button: Optional[dict[str, str]] = None,
+        reply_to: Optional[str] = None,
+        image: Optional[dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+    ) -> EmailResponse:
+        """Enqueue an email and wait for processing confirmation."""
+        payload = self._build_payload(to, preview, subject, paragraphs, button, reply_to, image)
+        return self._enqueue_and_wait(payload, timeout)
+
+    def send_batch(
+        self,
+        to: list[str],
+        preview: str,
+        subject: str,
+        paragraphs: list[str],
+        button: Optional[dict[str, str]] = None,
+        reply_to: Optional[str] = None,
+        image: Optional[dict[str, Any]] = None,
+    ) -> SendResult:
+        """Enqueue a batch email for processing (fire and forget)."""
+        self._validate_batch(to)
+        payload = self._build_batch_payload(to, preview, subject, paragraphs, button, reply_to, image)
+        message_id = self._enqueue(payload)
+        return SendResult(message_id=message_id)
+
+    def send_batch_and_wait(
+        self,
+        to: list[str],
+        preview: str,
+        subject: str,
+        paragraphs: list[str],
+        button: Optional[dict[str, str]] = None,
+        reply_to: Optional[str] = None,
+        image: Optional[dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+    ) -> BatchEmailResponse:
+        """Enqueue a batch email and wait for processing confirmation."""
+        self._validate_batch(to)
+        payload = self._build_batch_payload(to, preview, subject, paragraphs, button, reply_to, image)
+        response = self._enqueue_and_wait(payload, timeout)
+
+        return BatchEmailResponse(
+            success=response.success,
+            message_id=response.message_id,
+            error=response.error,
+            processed_at=response.processed_at,
+            total=getattr(response, "total", len(to)),
+            successful=getattr(response, "successful", len(to) if response.success else 0),
+            failed=getattr(response, "failed", 0 if response.success else len(to)),
+        )
+
+    def _build_payload(
+        self,
+        to: str,
+        preview: str,
+        subject: str,
+        paragraphs: list[str],
+        button: Optional[dict[str, str]],
+        reply_to: Optional[str],
+        image: Optional[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Build and sanitize the email payload."""
+        payload: dict[str, Any] = {
+            "to": to,
+            "preview": sanitize(preview),
+            "subject": sanitize(subject),
+            "paragraphs": sanitize_list(paragraphs),
+        }
+
+        if button:
+            payload["button"] = {
+                "text": sanitize(button["text"]),
+                "href": button["href"],
+            }
+
+        if reply_to:
+            payload["replyTo"] = reply_to
+
+        if image:
+            payload["image"] = {
+                "src": image.get("src", ""),
+                "alt": image.get("alt", ""),
+                "width": image.get("width"),
+                "height": image.get("height"),
+            }
+
+        return payload
+
+    def _build_batch_payload(
+        self,
+        to: list[str],
+        preview: str,
+        subject: str,
+        paragraphs: list[str],
+        button: Optional[dict[str, str]],
+        reply_to: Optional[str],
+        image: Optional[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Build and sanitize the batch email payload."""
+        payload = self._build_payload(
+            to="",  # not used for batch
+            preview=preview,
+            subject=subject,
+            paragraphs=paragraphs,
+            button=button,
+            reply_to=reply_to,
+            image=image,
+        )
+        payload["to"] = to
+        payload["batch"] = True
+        return payload
+
+    @staticmethod
+    def _validate_batch(to: list[str]) -> None:
+        """Validate batch constraints."""
+        if len(to) > 100:
+            raise ValueError("Maximum 100 recipients allowed per batch request")
+        if len(to) == 0:
+            raise ValueError("At least one recipient is required")

sf_queue_sdk-0.1.0/queue_sdk/redis_client.py

@@ -0,0 +1,51 @@
+"""Redis connection factory."""
+
+from urllib.parse import urlparse
+
+import redis
+
+from queue_sdk.types import QueueClientConfig
+
+
+def create_redis_client(config: QueueClientConfig) -> redis.Redis:
+    """Create a Redis client from the SDK config."""
+    url = config.redis_url
+    password = config.redis_password
+
+    # Full URL format (redis://... or rediss://...)
+    if url.startswith("redis://") or url.startswith("rediss://"):
+        parsed = urlparse(url)
+        effective_password = password or parsed.password or None
+        return redis.Redis(
+            host=parsed.hostname or "localhost",
+            port=parsed.port or 6379,
+            password=effective_password,
+            decode_responses=True,
+        )
+
+    # Simple host:port format
+    parts = url.split(":")
+    host = parts[0] if parts[0] else "localhost"
+    port = int(parts[1]) if len(parts) > 1 else 6379
+
+    return redis.Redis(
+        host=host,
+        port=port,
+        password=password or None,
+        decode_responses=True,
+    )
+
+
+def stream_name(env: str, base: str) -> str:
+    """Return the full stream name with environment prefix."""
+    if not env:
+        return base
+    return f"{env}:{base}"
+
+
+def response_key(env: str, queue: str, request_id: str) -> str:
+    """Return the response list key for a given queue and request ID."""
+    key = f"{queue}:response:{request_id}"
+    if not env:
+        return key
+    return f"{env}:{key}"

sf_queue_sdk-0.1.0/queue_sdk/sanitize.py

@@ -0,0 +1,15 @@
+"""Basic HTML sanitization for email content."""
+
+import re
+
+_HTML_TAG_REGEX = re.compile(r"<[^>]*>")
+
+
+def sanitize(text: str) -> str:
+    """Strip HTML tags from a string."""
+    return _HTML_TAG_REGEX.sub("", text)
+
+
+def sanitize_list(texts: list[str]) -> list[str]:
+    """Sanitize each string in a list."""
+    return [sanitize(t) for t in texts]

sf_queue_sdk-0.1.0/queue_sdk/types.py

@@ -0,0 +1,87 @@
+"""Type definitions for the queue SDK."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class QueueClientConfig:
+    """Configuration for the QueueClient."""
+
+    redis_url: str
+    redis_password: str
+    environment: str
+
+
+@dataclass
+class EmailButton:
+    """CTA button for email."""
+
+    text: str
+    href: str
+
+
+@dataclass
+class EmailImage:
+    """Optional image for email."""
+
+    src: str
+    alt: str = ""
+    width: Optional[int] = None
+    height: Optional[int] = None
+
+
+@dataclass
+class EmailData:
+    """Data for a single email."""
+
+    to: str
+    preview: str
+    subject: str
+    paragraphs: list[str]
+    button: Optional[EmailButton] = None
+    reply_to: Optional[str] = None
+    image: Optional[EmailImage] = None
+
+
+@dataclass
+class BatchEmailData:
+    """Data for a batch email (same content to multiple recipients)."""
+
+    to: list[str]
+    preview: str
+    subject: str
+    paragraphs: list[str]
+    button: Optional[EmailButton] = None
+    reply_to: Optional[str] = None
+    image: Optional[EmailImage] = None
+
+
+@dataclass
+class SendResult:
+    """Result of a fire-and-forget send."""
+
+    message_id: str
+
+
+@dataclass
+class EmailResponse:
+    """Response from a processed email."""
+
+    success: bool
+    message_id: str
+    error: Optional[str] = None
+    processed_at: Optional[str] = None
+
+
+@dataclass
+class BatchEmailResponse:
+    """Response from a processed batch email."""
+
+    success: bool
+    message_id: str
+    total: int
+    successful: int
+    failed: int
+    error: Optional[str] = None
+    processed_at: Optional[str] = None