sf-queue-sdk 0.2.0b23__tar.gz → 0.2.0b25__tar.gz

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sf-queue-sdk
-Version: 0.2.0b23
+Version: 0.2.0b25
 Summary: Python SDK for sf-queue - Redis-based queue system
 Requires-Python: >=3.11
 Requires-Dist: redis>=5.0.0
@@ -150,6 +150,8 @@ print(result.error)       # error message if all failed
 | `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 |
+| `service` | `str` | No | Service name for routing (e.g. `"sparkles"`). Routes to service-specific credentials, from address, and template. Defaults to the base config when omitted. |
+| `template` | `str` | No | Template name override (e.g. `"sparkles"`). Overrides the service's default template. Falls back to `"studyfetch"` when omitted. |
 
 ## Optional Fields
 
@@ -170,6 +172,31 @@ client.email.send(
 )
 ```
 
+## Multi-Service Routing
+
+Use `service` to route emails through a different service's credentials and branding. The consumer resolves the service name to its configured Resend API key, from address, and default template. Use `template` to override the template for a specific email.
+
+```python
+# Send via a different service's email account and template
+client.email.send(
+    to="user@example.com",
+    preview="Welcome!",
+    subject="Welcome!",
+    paragraphs=["Welcome to the platform!"],
+    service="sparkles",
+)
+
+# Override the template for a specific email
+client.email.send(
+    to="user@example.com",
+    preview="Welcome!",
+    subject="Welcome!",
+    paragraphs=["Welcome to the platform!"],
+    service="sparkles",
+    template="sparkles",
+)
+```
+
 ## Migrating from sendEmail / sendBatchEmail
 
 The SDK is a drop-in replacement. Field names match the existing functions:
@@ -384,6 +411,32 @@ print(result.success)
 print(result.message_id)
 ```
 
+### Batch (fire and forget)
+
+```python
+result = client.recommendations.create_batch([
+    {"user_id": "user_1", "topic_id": "topic_1", "limit": 10},
+    {"user_id": "user_2", "topic_id": "topic_2"},
+])
+print("Enqueued:", result.message_id)
+```
+
+### Batch (wait for confirmation)
+
+```python
+result = client.recommendations.create_batch_and_wait(
+    [
+        {"user_id": "user_1", "topic_id": "topic_1"},
+        {"user_id": "user_2", "topic_id": "topic_2"},
+    ],
+    timeout=60,
+)
+print(result.success)
+print(result.total)
+print(result.successful)
+print(result.failed)
+```
+
 ### Recommendation Fields
 
 | Field | Type | Required | Description |
@@ -392,6 +445,31 @@ print(result.message_id)
 | `topic_id` | `str` | Yes | Topic context for recommendations |
 | `limit` | `Optional[int]` | No | Max recommendations to return |
 
+## Query (Direct Key Lookups)
+
+Read values directly from Redis by key. These are plain `GET` / `MGET` calls, not queue operations.
+
+### Get a single key
+
+```python
+value = client.query.get("mykey")
+print(value)  # str or None
+```
+
+### Get multiple keys
+
+```python
+values = client.query.get_many(["key1", "key2", "key3"])
+print(values)  # list[str | None]
+```
+
+### Query Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `get(key)` | `Optional[str]` | Fetch a single key via Redis GET |
+| `get_many(keys)` | `list[Optional[str]]` | Fetch multiple keys via Redis MGET |
+
 ## Cleanup
 
 ```python

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/README.md

@@ -142,6 +142,8 @@ print(result.error)       # error message if all failed
 | `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 |
+| `service` | `str` | No | Service name for routing (e.g. `"sparkles"`). Routes to service-specific credentials, from address, and template. Defaults to the base config when omitted. |
+| `template` | `str` | No | Template name override (e.g. `"sparkles"`). Overrides the service's default template. Falls back to `"studyfetch"` when omitted. |
 
 ## Optional Fields
 
@@ -162,6 +164,31 @@ client.email.send(
 )
 ```
 
+## Multi-Service Routing
+
+Use `service` to route emails through a different service's credentials and branding. The consumer resolves the service name to its configured Resend API key, from address, and default template. Use `template` to override the template for a specific email.
+
+```python
+# Send via a different service's email account and template
+client.email.send(
+    to="user@example.com",
+    preview="Welcome!",
+    subject="Welcome!",
+    paragraphs=["Welcome to the platform!"],
+    service="sparkles",
+)
+
+# Override the template for a specific email
+client.email.send(
+    to="user@example.com",
+    preview="Welcome!",
+    subject="Welcome!",
+    paragraphs=["Welcome to the platform!"],
+    service="sparkles",
+    template="sparkles",
+)
+```
+
 ## Migrating from sendEmail / sendBatchEmail
 
 The SDK is a drop-in replacement. Field names match the existing functions:
@@ -376,6 +403,32 @@ print(result.success)
 print(result.message_id)
 ```
 
+### Batch (fire and forget)
+
+```python
+result = client.recommendations.create_batch([
+    {"user_id": "user_1", "topic_id": "topic_1", "limit": 10},
+    {"user_id": "user_2", "topic_id": "topic_2"},
+])
+print("Enqueued:", result.message_id)
+```
+
+### Batch (wait for confirmation)
+
+```python
+result = client.recommendations.create_batch_and_wait(
+    [
+        {"user_id": "user_1", "topic_id": "topic_1"},
+        {"user_id": "user_2", "topic_id": "topic_2"},
+    ],
+    timeout=60,
+)
+print(result.success)
+print(result.total)
+print(result.successful)
+print(result.failed)
+```
+
 ### Recommendation Fields
 
 | Field | Type | Required | Description |
@@ -384,6 +437,31 @@ print(result.message_id)
 | `topic_id` | `str` | Yes | Topic context for recommendations |
 | `limit` | `Optional[int]` | No | Max recommendations to return |
 
+## Query (Direct Key Lookups)
+
+Read values directly from Redis by key. These are plain `GET` / `MGET` calls, not queue operations.
+
+### Get a single key
+
+```python
+value = client.query.get("mykey")
+print(value)  # str or None
+```
+
+### Get multiple keys
+
+```python
+values = client.query.get_many(["key1", "key2", "key3"])
+print(values)  # list[str | None]
+```
+
+### Query Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `get(key)` | `Optional[str]` | Fetch a single key via Redis GET |
+| `get_many(keys)` | `list[Optional[str]]` | Fetch multiple keys via Redis MGET |
+
 ## Cleanup
 
 ```python

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sf-queue-sdk"
-version = "0.2.0b23"
+version = "0.2.0b25"
 description = "Python SDK for sf-queue - Redis-based queue system"
 readme = "README.md"
 requires-python = ">=3.11"

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/queue_sdk/__init__.py

@@ -1,11 +1,14 @@
 """sf-queue Python SDK - Redis-based queue system."""
 
-__version__ = "0.2.0b23"
+__version__ = "0.2.0b25"
 
 from queue_sdk.client import QueueClient
+from queue_sdk.query import QueryClient
 from queue_sdk.types import (
     BatchEmailResponse,
     BatchQueueResponse,
+    BatchRecommendationRequestData,
+    BatchRecommendationResponse,
     BatchToolAssignmentData,
     BatchTopicAssignmentData,
     ConvertData,
@@ -25,6 +28,7 @@ from queue_sdk.types import (
 
 __all__ = [
     "QueueClient",
+    "QueryClient",
     "QueueClientConfig",
     "EmailData",
     "EmailButton",
@@ -35,6 +39,8 @@ __all__ = [
     "BatchQueueResponse",
     "RecommendationRequestData",
     "RecommendationResponse",
+    "BatchRecommendationRequestData",
+    "BatchRecommendationResponse",
     "TopicAssignmentData",
     "BatchTopicAssignmentData",
     "ToolAssignmentData",

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/queue_sdk/client.py

@@ -1,5 +1,6 @@
 """QueueClient - main entry point for the Python SDK."""
 
+from queue_sdk.query import QueryClient
 from queue_sdk.queues.email_queue import EmailQueue
 from queue_sdk.queues.pdf_to_image_queue import PdfToImageQueue
 from queue_sdk.queues.recommendation_queue import RecommendationQueue
@@ -67,6 +68,7 @@ class QueueClient:
         self.tool_assignment = ToolAssignmentQueue(self._redis, self._environment)
         self.pdf_to_image = PdfToImageQueue(self._redis, self._environment)
         self.recommendations = RecommendationQueue(self._redis, self._environment)
+        self.query = QueryClient(self._redis)
 
     def disconnect(self) -> None:
         """Close the Redis connection."""

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/queue_sdk/generated/queue/email/v1/email_pb2.py

@@ -2,7 +2,7 @@
 # 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
+# Protobuf Python Version: 7.34.0
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
@@ -11,9 +11,9 @@ 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,
+    7,
+    34,
+    0,
     '',
     'queue/email/v1/email.proto'
 )
@@ -24,7 +24,7 @@ _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')
+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\"\xaa\x02\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\x12\x18\n\x07service\x18\x08 \x01(\tR\x07service\x12\x1a\n\x08template\x18\t \x01(\tR\x08template\"\xaf\x02\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\x12\x18\n\x07service\x18\x08 \x01(\tR\x07service\x12\x1a\n\x08template\x18\t \x01(\tR\x08template\"^\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)
@@ -37,9 +37,9 @@ if not _descriptor._USE_C_DESCRIPTORS:
   _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
+  _globals['_EMAILREQUEST']._serialized_end=496
+  _globals['_BATCHEMAILREQUEST']._serialized_start=499
+  _globals['_BATCHEMAILREQUEST']._serialized_end=802
+  _globals['_EMAILRESPONSE']._serialized_start=804
+  _globals['_EMAILRESPONSE']._serialized_end=898
 # @@protoc_insertion_point(module_scope)

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/queue_sdk/generated/queue/email/v1/email_pb2.pyi

@@ -27,7 +27,7 @@ class EmailImage(_message.Message):
     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")
+    __slots__ = ("to", "preview", "subject", "paragraphs", "button", "reply_to", "image", "service", "template")
     TO_FIELD_NUMBER: _ClassVar[int]
     PREVIEW_FIELD_NUMBER: _ClassVar[int]
     SUBJECT_FIELD_NUMBER: _ClassVar[int]
@@ -35,6 +35,8 @@ class EmailRequest(_message.Message):
     BUTTON_FIELD_NUMBER: _ClassVar[int]
     REPLY_TO_FIELD_NUMBER: _ClassVar[int]
     IMAGE_FIELD_NUMBER: _ClassVar[int]
+    SERVICE_FIELD_NUMBER: _ClassVar[int]
+    TEMPLATE_FIELD_NUMBER: _ClassVar[int]
     to: str
     preview: str
     subject: str
@@ -42,10 +44,12 @@ class EmailRequest(_message.Message):
     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: ...
+    service: str
+    template: str
+    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]] = ..., service: _Optional[str] = ..., template: _Optional[str] = ...) -> None: ...
 
 class BatchEmailRequest(_message.Message):
-    __slots__ = ("to", "preview", "subject", "paragraphs", "button", "reply_to", "image")
+    __slots__ = ("to", "preview", "subject", "paragraphs", "button", "reply_to", "image", "service", "template")
     TO_FIELD_NUMBER: _ClassVar[int]
     PREVIEW_FIELD_NUMBER: _ClassVar[int]
     SUBJECT_FIELD_NUMBER: _ClassVar[int]
@@ -53,6 +57,8 @@ class BatchEmailRequest(_message.Message):
     BUTTON_FIELD_NUMBER: _ClassVar[int]
     REPLY_TO_FIELD_NUMBER: _ClassVar[int]
     IMAGE_FIELD_NUMBER: _ClassVar[int]
+    SERVICE_FIELD_NUMBER: _ClassVar[int]
+    TEMPLATE_FIELD_NUMBER: _ClassVar[int]
     to: _containers.RepeatedScalarFieldContainer[str]
     preview: str
     subject: str
@@ -60,7 +66,9 @@ class BatchEmailRequest(_message.Message):
     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: ...
+    service: str
+    template: str
+    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]] = ..., service: _Optional[str] = ..., template: _Optional[str] = ...) -> None: ...
 
 class EmailResponse(_message.Message):
     __slots__ = ("success", "message_id", "error")

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/queue_sdk/generated/queue/tool_assignment/v1/tool_assignment_pb2.py

@@ -2,7 +2,7 @@
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # NO CHECKED-IN PROTOBUF GENCODE
 # source: queue/tool_assignment/v1/tool_assignment.proto
-# Protobuf Python Version: 6.33.5
+# Protobuf Python Version: 7.34.0
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
@@ -11,9 +11,9 @@ 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,
+    7,
+    34,
+    0,
     '',
     'queue/tool_assignment/v1/tool_assignment.proto'
 )

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/queue_sdk/generated/queue/topic_assignment/v1/topic_assignment_pb2.py

@@ -2,7 +2,7 @@
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # NO CHECKED-IN PROTOBUF GENCODE
 # source: queue/topic_assignment/v1/topic_assignment.proto
-# Protobuf Python Version: 6.33.5
+# Protobuf Python Version: 7.34.0
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
@@ -11,9 +11,9 @@ 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,
+    7,
+    34,
+    0,
     '',
     'queue/topic_assignment/v1/topic_assignment.proto'
 )

sf_queue_sdk-0.2.0b25/queue_sdk/query.py

@@ -0,0 +1,22 @@
+"""QueryClient - direct Redis key lookups."""
+
+from typing import Optional
+
+import redis as redis_lib
+
+
+class QueryClient:
+    """Direct Redis key lookups (GET, MGET)."""
+
+    def __init__(self, redis_client: redis_lib.Redis):
+        self._redis = redis_client
+
+    def get(self, key: str) -> Optional[str]:
+        """Fetch a single key from Redis."""
+        return self._redis.get(key)
+
+    def get_many(self, keys: list[str]) -> list[Optional[str]]:
+        """Fetch multiple keys from Redis in a single MGET call."""
+        if not keys:
+            return []
+        return self._redis.mget(*keys)

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/queue_sdk/queues/email_queue.py

@@ -28,9 +28,13 @@ class EmailQueue(BaseQueue):
         button: Optional[dict[str, str]] = None,
         reply_to: Optional[str] = None,
         image: Optional[dict[str, Any]] = None,
+        service: Optional[str] = None,
+        template: Optional[str] = None,
     ) -> SendResult:
         """Enqueue an email for processing (fire and forget)."""
-        payload = self._build_payload(to, preview, subject, paragraphs, button, reply_to, image)
+        payload = self._build_payload(
+            to, preview, subject, paragraphs, button, reply_to, image, service, template
+        )
         message_id = self._enqueue(payload)
         return SendResult(message_id=message_id)
 
@@ -44,9 +48,13 @@ class EmailQueue(BaseQueue):
         reply_to: Optional[str] = None,
         image: Optional[dict[str, Any]] = None,
         timeout: Optional[int] = None,
+        service: Optional[str] = None,
+        template: Optional[str] = None,
     ) -> EmailResponse:
         """Enqueue an email and wait for processing confirmation."""
-        payload = self._build_payload(to, preview, subject, paragraphs, button, reply_to, image)
+        payload = self._build_payload(
+            to, preview, subject, paragraphs, button, reply_to, image, service, template
+        )
         return self._enqueue_and_wait(payload, timeout)
 
     def send_batch(
@@ -58,10 +66,14 @@ class EmailQueue(BaseQueue):
         button: Optional[dict[str, str]] = None,
         reply_to: Optional[str] = None,
         image: Optional[dict[str, Any]] = None,
+        service: Optional[str] = None,
+        template: Optional[str] = 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)
+        payload = self._build_batch_payload(
+            to, preview, subject, paragraphs, button, reply_to, image, service, template
+        )
         message_id = self._enqueue(payload)
         return SendResult(message_id=message_id)
 
@@ -75,10 +87,14 @@ class EmailQueue(BaseQueue):
         reply_to: Optional[str] = None,
         image: Optional[dict[str, Any]] = None,
         timeout: Optional[int] = None,
+        service: Optional[str] = None,
+        template: Optional[str] = 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)
+        payload = self._build_batch_payload(
+            to, preview, subject, paragraphs, button, reply_to, image, service, template
+        )
         response = self._enqueue_and_wait(payload, timeout)
 
         return BatchEmailResponse(
@@ -100,6 +116,8 @@ class EmailQueue(BaseQueue):
         button: Optional[dict[str, str]],
         reply_to: Optional[str],
         image: Optional[dict[str, Any]],
+        service: Optional[str] = None,
+        template: Optional[str] = None,
     ) -> dict[str, Any]:
         """Build and sanitize the email payload."""
         payload: dict[str, Any] = {
@@ -126,6 +144,12 @@ class EmailQueue(BaseQueue):
                 "height": image.get("height"),
             }
 
+        if service:
+            payload["service"] = service
+
+        if template:
+            payload["template"] = template
+
         return payload
 
     def _build_batch_payload(
@@ -137,16 +161,20 @@ class EmailQueue(BaseQueue):
         button: Optional[dict[str, str]],
         reply_to: Optional[str],
         image: Optional[dict[str, Any]],
+        service: Optional[str] = None,
+        template: Optional[str] = None,
     ) -> dict[str, Any]:
         """Build and sanitize the batch email payload."""
         payload = self._build_payload(
-            to="",  # not used for batch
+            to="",
             preview=preview,
             subject=subject,
             paragraphs=paragraphs,
             button=button,
             reply_to=reply_to,
             image=image,
+            service=service,
+            template=template,
         )
         payload["to"] = to
         payload["batch"] = True

sf_queue_sdk-0.2.0b25/queue_sdk/queues/recommendation_queue.py

@@ -0,0 +1,136 @@
+"""Recommendation queue with typed methods."""
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import redis as redis_lib
+
+from queue_sdk.queues.base_queue import BaseQueue
+from queue_sdk.types import (
+    BatchRecommendationResponse,
+    RecommendationResponse,
+    SendResult,
+)
+
+
+class RecommendationQueue(BaseQueue):
+    """Typed methods for creating recommendation requests via the queue."""
+
+    def __init__(self, redis_client: redis_lib.Redis, environment: str):
+        super().__init__(redis_client, environment, "recommendation-requests")
+
+    def create(
+        self,
+        user_id: str,
+        topic_id: str,
+        limit: Optional[int] = None,
+    ) -> SendResult:
+        """Enqueue a recommendation request (fire and forget)."""
+        self._validate(user_id, topic_id)
+        payload = self._build_payload(user_id, topic_id, limit)
+        message_id = self._enqueue(payload)
+        return SendResult(message_id=message_id)
+
+    def create_and_wait(
+        self,
+        user_id: str,
+        topic_id: str,
+        limit: Optional[int] = None,
+        timeout: Optional[int] = None,
+    ) -> RecommendationResponse:
+        """Enqueue a recommendation request and wait for the result."""
+        self._validate(user_id, topic_id)
+        payload = self._build_payload(user_id, topic_id, limit)
+        response = self._enqueue_and_wait(payload, timeout)
+
+        return RecommendationResponse(
+            success=response.success,
+            message_id=response.message_id,
+            error=response.error,
+            processed_at=response.processed_at,
+        )
+
+    def create_batch(
+        self,
+        requests: list[dict[str, Any]],
+    ) -> SendResult:
+        """Enqueue multiple recommendation requests (fire and forget)."""
+        self._validate_batch(requests)
+        payload = self._build_batch_payload(requests)
+        message_id = self._enqueue(payload)
+        return SendResult(message_id=message_id)
+
+    def create_batch_and_wait(
+        self,
+        requests: list[dict[str, Any]],
+        timeout: Optional[int] = None,
+    ) -> BatchRecommendationResponse:
+        """Enqueue multiple recommendation requests and wait for confirmation."""
+        self._validate_batch(requests)
+        payload = self._build_batch_payload(requests)
+        response = self._enqueue_and_wait(payload, timeout)
+
+        return BatchRecommendationResponse(
+            success=response.success,
+            message_id=response.message_id,
+            error=response.error,
+            processed_at=response.processed_at,
+            total=getattr(response, "total", len(requests)),
+            successful=getattr(
+                response, "successful", len(requests) if response.success else 0
+            ),
+            failed=getattr(response, "failed", 0 if response.success else len(requests)),
+        )
+
+    def _build_payload(
+        self,
+        user_id: str,
+        topic_id: str,
+        limit: Optional[int],
+    ) -> dict[str, Any]:
+        """Build the recommendation request payload."""
+        payload: dict[str, Any] = {
+            "userId": user_id,
+            "topicId": topic_id,
+            "requestedAt": datetime.now(timezone.utc).isoformat(),
+            "key": f"{user_id}-{topic_id}",
+        }
+        if limit is not None:
+            payload["limit"] = limit
+        return payload
+
+    def _build_batch_payload(
+        self, requests: list[dict[str, Any]]
+    ) -> dict[str, Any]:
+        """Build the batch recommendation request payload."""
+        return {
+            "batch": True,
+            "requests": [
+                self._build_payload(
+                    r.get("user_id", ""),
+                    r.get("topic_id", ""),
+                    r.get("limit"),
+                )
+                for r in requests
+            ],
+        }
+
+    @staticmethod
+    def _validate(user_id: str, topic_id: str) -> None:
+        """Validate the recommendation request."""
+        if not user_id:
+            raise ValueError("user_id is required")
+        if not topic_id:
+            raise ValueError("topic_id is required")
+
+    def _validate_batch(self, requests: list[dict[str, Any]]) -> None:
+        """Validate the batch of recommendation requests."""
+        if len(requests) == 0:
+            raise ValueError("At least one request is required")
+        if len(requests) > 100:
+            raise ValueError("Maximum 100 requests allowed per batch")
+        for r in requests:
+            self._validate(
+                r.get("user_id", ""),
+                r.get("topic_id", ""),
+            )

{sf_queue_sdk-0.2.0b23 → sf_queue_sdk-0.2.0b25}/queue_sdk/types.py

@@ -42,6 +42,8 @@ class EmailData:
     button: Optional[EmailButton] = None
     reply_to: Optional[str] = None
     image: Optional[EmailImage] = None
+    service: Optional[str] = None
+    template: Optional[str] = None
 
 
 @dataclass
@@ -55,6 +57,8 @@ class BatchEmailData:
     button: Optional[EmailButton] = None
     reply_to: Optional[str] = None
     image: Optional[EmailImage] = None
+    service: Optional[str] = None
+    template: Optional[str] = None
 
 
 @dataclass
@@ -147,6 +151,26 @@ class RecommendationResponse:
     processed_at: Optional[str] = None
 
 
+@dataclass
+class BatchRecommendationRequestData:
+    """Data for multiple recommendation requests."""
+
+    requests: list[dict]
+
+
+@dataclass
+class BatchRecommendationResponse:
+    """Response from a processed batch of recommendation requests."""
+
+    success: bool
+    message_id: str
+    total: int
+    successful: int
+    failed: int
+    error: Optional[str] = None
+    processed_at: Optional[str] = None
+
+
 @dataclass
 class ConvertData:
     """Data for a PDF/video to image conversion request."""

sf_queue_sdk-0.2.0b23/queue_sdk/queues/recommendation_queue.py

@@ -1,72 +0,0 @@
-"""Recommendation queue with typed methods."""
-
-from datetime import datetime, timezone
-from typing import Any, Optional
-
-import redis as redis_lib
-
-from queue_sdk.queues.base_queue import BaseQueue
-from queue_sdk.types import RecommendationResponse, SendResult
-
-
-class RecommendationQueue(BaseQueue):
-    """Typed methods for creating recommendation requests via the queue."""
-
-    def __init__(self, redis_client: redis_lib.Redis, environment: str):
-        super().__init__(redis_client, environment, "recommendation-requests")
-
-    def create(
-        self,
-        user_id: str,
-        topic_id: str,
-        limit: Optional[int] = None,
-    ) -> SendResult:
-        """Enqueue a recommendation request (fire and forget)."""
-        self._validate(user_id, topic_id)
-        payload = self._build_payload(user_id, topic_id, limit)
-        message_id = self._enqueue(payload)
-        return SendResult(message_id=message_id)
-
-    def create_and_wait(
-        self,
-        user_id: str,
-        topic_id: str,
-        limit: Optional[int] = None,
-        timeout: Optional[int] = None,
-    ) -> RecommendationResponse:
-        """Enqueue a recommendation request and wait for the result."""
-        self._validate(user_id, topic_id)
-        payload = self._build_payload(user_id, topic_id, limit)
-        response = self._enqueue_and_wait(payload, timeout)
-
-        return RecommendationResponse(
-            success=response.success,
-            message_id=response.message_id,
-            error=response.error,
-            processed_at=response.processed_at,
-        )
-
-    def _build_payload(
-        self,
-        user_id: str,
-        topic_id: str,
-        limit: Optional[int],
-    ) -> dict[str, Any]:
-        """Build the recommendation request payload."""
-        payload: dict[str, Any] = {
-            "userId": user_id,
-            "topicId": topic_id,
-            "requestedAt": datetime.now(timezone.utc).isoformat(),
-            "key": f"{user_id}-{topic_id}",
-        }
-        if limit is not None:
-            payload["limit"] = limit
-        return payload
-
-    @staticmethod
-    def _validate(user_id: str, topic_id: str) -> None:
-        """Validate the recommendation request."""
-        if not user_id:
-            raise ValueError("user_id is required")
-        if not topic_id:
-            raise ValueError("topic_id is required")