blueink-client-python 1.0.0__tar.gz → 1.0.1__tar.gz

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: blueink-client-python
-Version: 1.0.0
+Version: 1.0.1
 Summary: Python Client for Blueink eSignature API
 Home-page: https://github.com/blueinkhq/blueink-client-python
 Author: Blueink
@@ -19,11 +19,11 @@ Requires-Dist: email-validator
 Provides-Extra: munch
 Requires-Dist: munch>=2.5; extra == "munch"
 Provides-Extra: requests
-Requires-Dist: requests>=2.27; extra == "requests"
+Requires-Dist: requests>=2.31; extra == "requests"
 Provides-Extra: pydantic
 Requires-Dist: pydantic>=1.9; extra == "pydantic"
 Provides-Extra: email-validator
-Requires-Dist: 1.2; extra == "email-validator"
+Requires-Dist: email-validator>=1.2; extra == "email-validator"
 
 # blueink-client-python
 ![Tests](https://github.com/blueinkhq/blueink-client-python/actions/workflows/helper-tests.yml/badge.svg)
@@ -400,6 +400,56 @@ with open("/path/to/file/example.pdf", 'rb') as file:
     doc04_key = bh.add_document_by_file(file)
 ```
 
+#### Auto-Placement Fields
+
+Auto-placement fields allow you to automatically search for text in documents and place
+signature/input fields at those locations with optional offsets. This eliminates the need
+to manually specify exact coordinates for fields.
+
+```python
+from blueink import BundleHelper, Client
+
+bh = BundleHelper(
+    label="Auto-Placement Example",
+    email_subject="Please sign",
+    is_test=True,
+)
+
+signer_key = bh.add_signer(name="John Doe", email="john@example.com")
+doc_key = bh.add_document_by_url("https://www.irs.gov/pub/irs-pdf/fw9.pdf")
+
+# Add auto-placement field that searches for "Signature" text
+bh.add_auto_placement(
+    document_key=doc_key,
+    kind="sig",              # Field type: signature
+    search="Signature",      # Text to search for
+    w=20,                    # Width
+    h=5,                     # Height
+    offset_x=-5,             # Move 5 units left from found text
+    offset_y=2,              # Move 2 units down from found text
+    editors=[signer_key],
+)
+
+# Add auto-placement for an input field
+bh.add_auto_placement(
+    document_key=doc_key,
+    kind="inp",              # Field type: input
+    search="Address",        # Text to search for
+    w=20,
+    h=2,
+    offset_x=8,              # Move 8 units right from found text
+    editors=[signer_key],
+)
+
+client = Client()
+response = client.bundles.create_from_bundle_helper(bh)
+```
+
+**Key benefits of auto-placement:**
+- No need to manually find exact coordinates
+- Works with template documents that have consistent text labels
+- Automatically adjusts to text position in the document
+- Can be combined with regular manually-positioned fields
 
 #### Retrieval
 

blueink-client-python-1.0.0/src/blueink_client_python.egg-info/PKG-INFO → blueink_client_python-1.0.1/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.1
-Name: blueink-client-python
-Version: 1.0.0
-Summary: Python Client for Blueink eSignature API
-Home-page: https://github.com/blueinkhq/blueink-client-python
-Author: Blueink
-Author-email: pypi@blueink.com
-Project-URL: Bug Tracker, https://github.com/blueinkhq/blueink-client-python/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: munch
-Requires-Dist: requests
-Requires-Dist: pydantic
-Requires-Dist: email-validator
-Provides-Extra: munch
-Requires-Dist: munch>=2.5; extra == "munch"
-Provides-Extra: requests
-Requires-Dist: requests>=2.27; extra == "requests"
-Provides-Extra: pydantic
-Requires-Dist: pydantic>=1.9; extra == "pydantic"
-Provides-Extra: email-validator
-Requires-Dist: 1.2; extra == "email-validator"
-
 # blueink-client-python
 ![Tests](https://github.com/blueinkhq/blueink-client-python/actions/workflows/helper-tests.yml/badge.svg)
 ![Style Checks](https://github.com/blueinkhq/blueink-client-python/actions/workflows/style-checks.yml/badge.svg)
@@ -400,6 +373,56 @@ with open("/path/to/file/example.pdf", 'rb') as file:
     doc04_key = bh.add_document_by_file(file)
 ```
 
+#### Auto-Placement Fields
+
+Auto-placement fields allow you to automatically search for text in documents and place
+signature/input fields at those locations with optional offsets. This eliminates the need
+to manually specify exact coordinates for fields.
+
+```python
+from blueink import BundleHelper, Client
+
+bh = BundleHelper(
+    label="Auto-Placement Example",
+    email_subject="Please sign",
+    is_test=True,
+)
+
+signer_key = bh.add_signer(name="John Doe", email="john@example.com")
+doc_key = bh.add_document_by_url("https://www.irs.gov/pub/irs-pdf/fw9.pdf")
+
+# Add auto-placement field that searches for "Signature" text
+bh.add_auto_placement(
+    document_key=doc_key,
+    kind="sig",              # Field type: signature
+    search="Signature",      # Text to search for
+    w=20,                    # Width
+    h=5,                     # Height
+    offset_x=-5,             # Move 5 units left from found text
+    offset_y=2,              # Move 2 units down from found text
+    editors=[signer_key],
+)
+
+# Add auto-placement for an input field
+bh.add_auto_placement(
+    document_key=doc_key,
+    kind="inp",              # Field type: input
+    search="Address",        # Text to search for
+    w=20,
+    h=2,
+    offset_x=8,              # Move 8 units right from found text
+    editors=[signer_key],
+)
+
+client = Client()
+response = client.bundles.create_from_bundle_helper(bh)
+```
+
+**Key benefits of auto-placement:**
+- No need to manually find exact coordinates
+- Works with template documents that have consistent text labels
+- Automatically adjusts to text position in the document
+- Can be combined with regular manually-positioned fields
 
 #### Retrieval
 

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = blueink-client-python
-version = 1.0.0
+version = 1.0.1
 author = Blueink
 author_email = pypi@blueink.com
 description = Python Client for Blueink eSignature API
@@ -26,10 +26,14 @@ install_requires =
 	email-validator
 
 [options.extras_require]
-munch = munch>=2.5;
-requests = requests>=2.27;
-pydantic = pydantic>=1.9
-email-validator> = 1.2
+munch = 
+	munch>=2.5
+requests = 
+	requests>=2.31
+pydantic = 
+	pydantic>=1.9
+email-validator = 
+	email-validator>=1.2
 
 [options.packages.find]
 where = src

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/bundle_helper.py

@@ -4,8 +4,11 @@ from os.path import basename
 from typing import List
 
 from blueink.model.bundles import (
+    AutoPlacement,
     Bundle,
     Document,
+    EnvelopeTemplate,
+    EnvelopeTemplateFieldValue,
     Field,
     Packet,
     TemplateRef,
@@ -49,6 +52,7 @@ class BundleHelper:
         self._packets = {}
         self._custom_key = custom_key
         self._team = team
+        self._envelope_template = None
 
         # for file uploads, index should match those in the document "file_index" field
         self.file_names = []
@@ -252,6 +256,72 @@ class BundleHelper:
         self._documents[document_key].add_field(field)
         return field.key
 
+    def add_auto_placement(
+        self,
+        document_key: str,
+        kind: str,
+        search: str,
+        w: int,
+        h: int,
+        offset_x: int = 0,
+        offset_y: int = 0,
+        editors: List[str] = None,
+        page: int = None,
+        **additional_data,
+    ):
+        """Add an auto-placement field to a document.
+
+        Auto-placement fields automatically search for text in the document and place
+        the field at the found location with optional offsets.
+
+        Args:
+            document_key: Key of the document to add the auto-placement to
+            kind: Field type (e.g., 'sig' for signature, 'inp' for input, 'ini' for initials)
+            search: Text to search for in the document
+            w: Width of the field
+            h: Height of the field
+            offset_x: Horizontal offset from the search text (default: 0)
+            offset_y: Vertical offset from the search text (default: 0)
+            editors: List of signer keys who can edit this field
+            page: Optional page number to limit search to
+            additional_data: Optional additional kwargs to append to the auto-placement
+
+        Returns:
+            None (auto-placements don't have keys like regular fields)
+
+        Example:
+            # Add a signature field that searches for "Signature" text
+            bh.add_auto_placement(
+                document_key=doc_key,
+                kind='sig',
+                search='Signature',
+                w=20,
+                h=5,
+                offset_x=-5,
+                offset_y=2,
+                editors=['signer-1']
+            )
+        """
+        if document_key not in self._documents:
+            raise RuntimeError(f"No document found with key {document_key}!")
+
+        auto_placement = AutoPlacement.create(
+            kind=kind,
+            search=search,
+            w=w,
+            h=h,
+            offset_x=offset_x,
+            offset_y=offset_y,
+            page=page,
+            **additional_data,
+        )
+
+        if editors:
+            for editor_key in editors:
+                auto_placement.add_editor(editor_key)
+
+        self._documents[document_key].add_auto_placement(auto_placement)
+
     def add_signer(
         self,
         name: str,
@@ -347,6 +417,64 @@ class BundleHelper:
         field_val = TemplateRefFieldValue.create(key, value, **additional_data)
         self._documents[document_key].field_values.append(field_val)
 
+    def set_envelope_template(
+        self, template_id: str, field_values: dict = None, **additional_data
+    ):
+        """Set the envelope template for this bundle.
+
+        When using an envelope template, the template contains the complete envelope
+        configuration including documents, signers, and field assignments.
+
+        Args:
+            template_id: Envelope template ID (format: T-xxxxxxxxxxx)
+            field_values: Optional dict mapping field keys to initial values
+            additional_data: Optional additional kwargs to append to the envelope template
+
+        Example:
+            bh = BundleHelper(label="Contract", is_test=True)
+            bh.add_signer(name="John Doe", email="john@example.com", key="signer-1")
+            bh.set_envelope_template(
+                template_id="T-abc123",
+                field_values={"company_name": "ACME Corp"}
+            )
+        """
+        vals = []
+        if field_values:
+            for field_key, init_val in field_values.items():
+                fieldval = EnvelopeTemplateFieldValue.create(
+                    key=field_key, initial_value=init_val
+                )
+                vals.append(fieldval)
+
+        self._envelope_template = EnvelopeTemplate.create(
+            template_id=template_id,
+            field_values=vals if vals else None,
+            **additional_data,
+        )
+
+    def add_envelope_template_field_value(
+        self, key: str, initial_value: str, **additional_data
+    ):
+        """Add a field value to the envelope template.
+
+        Args:
+            key: Field key in the envelope template
+            initial_value: Initial value for the field
+            additional_data: Optional additional kwargs
+
+        Raises:
+            RuntimeError: If no envelope template has been set
+        """
+        if self._envelope_template is None:
+            raise RuntimeError(
+                "No envelope template set. Call set_envelope_template() first."
+            )
+
+        field_val = EnvelopeTemplateFieldValue.create(
+            key=key, initial_value=initial_value, **additional_data
+        )
+        self._envelope_template.add_field_value(field_val)
+
     def _compile_bundle(self, **additional_data) -> Bundle:
         """
         Builds a Bundle object complete with all the packets (signers) and documents added through the course
@@ -384,6 +512,61 @@ class BundleHelper:
         bundle = self._compile_bundle(**additional_data)
         return bundle.dict(exclude_unset=True, exclude_none=True)
 
+    def as_data_for_envelope_template(self, **additional_data):
+        """Return data for creating a bundle from an envelope template.
+
+        This method is used when creating a bundle from an envelope template.
+        It returns a dictionary with packets and envelope_template fields.
+
+        Args:
+            additional_data: extra data to append to the request, as a dict
+
+        Returns:
+            Dictionary suitable for create_from_envelope_template endpoint
+
+        Raises:
+            RuntimeError: If no envelope template has been set
+
+        Example:
+            bh = BundleHelper(label="Contract", is_test=True)
+            bh.add_signer(name="John Doe", email="john@example.com", key="signer-1")
+            bh.set_envelope_template("T-abc123", {"company_name": "ACME"})
+            data = bh.as_data_for_envelope_template()
+        """
+        if self._envelope_template is None:
+            raise RuntimeError(
+                "No envelope template set. Call set_envelope_template() first."
+            )
+
+        packets = list(self._packets.values())
+        result = {
+            "packets": [p.dict(exclude_unset=True, exclude_none=True) for p in packets],
+            "envelope_template": self._envelope_template.dict(
+                exclude_unset=True, exclude_none=True
+            ),
+        }
+
+        # Add optional bundle fields
+        if self._label:
+            result["label"] = self._label
+        if self._is_test is not None:
+            result["is_test"] = self._is_test
+        if self._email_subj:
+            result["email_subject"] = self._email_subj
+        if self._email_msg:
+            result["email_message"] = self._email_msg
+        if self._cc_emails:
+            result["cc_emails"] = self._cc_emails
+        if self._custom_key:
+            result["custom_key"] = self._custom_key
+        if self._team:
+            result["team"] = self._team
+
+        # Add any additional data
+        result.update(additional_data)
+
+        return result
+
     def as_json(self, **additional_data):
         """Return a Bundle as a json
 

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/client.py

@@ -7,6 +7,7 @@ from blueink.constants import (
 )
 from blueink.request_helper import RequestHelper
 from blueink.subclients.bundle import BundleSubClient
+from blueink.subclients.envelope_template import EnvelopeTemplateSubClient
 from blueink.subclients.packet import PacketSubClient
 from blueink.subclients.person import PersonSubClient
 from blueink.subclients.template import TemplateSubClient
@@ -19,6 +20,7 @@ class Client:
         private_api_key: str = None,
         base_url: str = None,
         raise_exceptions: bool = True,
+        security_headers: dict = None,
     ):
         """Initialize a Client instance to access the Blueink eSignature API
 
@@ -29,6 +31,7 @@ class Client:
             base_url: override the API base URL. If not supplied, we check the
                 environment variable BLUEINK_API_URL. If that is empty, the default
                 value of "https://api.blueink.com/api/v2" is used.
+            security_headers: Place for additional security headers, likely unnecessary
             raise_exceptions (Default True): raise HTTPError if code != 200. Otherwise
             return as NormalizedResponse objects.
 
@@ -44,9 +47,9 @@ class Client:
 
         if not private_api_key:
             raise ValueError(
-                "A Blueink Private API Key must be provided on Client initialization"
-                " or specified via the environment variable"
-                " {ENV_BLUEINK_PRIVATE_API_KEY}"
+                f"A Blueink Private API Key must be provided on Client initialization"
+                f" or specified via the environment variable"
+                f" {ENV_BLUEINK_PRIVATE_API_KEY}"
             )
 
         if not base_url:
@@ -57,10 +60,17 @@ class Client:
 
         self._base_url = base_url
 
-        self._request_helper = RequestHelper(private_api_key, raise_exceptions)
+        self._request_helper = RequestHelper(
+            private_api_key,
+            raise_exceptions,
+            security_headers=security_headers,
+        )
 
         self.bundles = BundleSubClient(self._base_url, self._request_helper)
         self.persons = PersonSubClient(self._base_url, self._request_helper)
         self.packets = PacketSubClient(self._base_url, self._request_helper)
         self.templates = TemplateSubClient(self._base_url, self._request_helper)
+        self.envelope_templates = EnvelopeTemplateSubClient(
+            self._base_url, self._request_helper
+        )
         self.webhooks = WebhookSubClient(self._base_url, self._request_helper)

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/endpoints.py

@@ -8,6 +8,7 @@ from string import Template
 
 class BUNDLES:
     CREATE = "/bundles/"
+    CREATE_FROM_ENVELOPE_TEMPLATE = "/bundles/create_from_envelope_template/"
     LIST = "/bundles/"
     RETRIEVE = "/bundles/${bundle_id}/"
     CANCEL = "/bundles/${bundle_id}/cancel/"
@@ -36,6 +37,11 @@ class TEMPLATES:
     RETRIEVE = "/templates/${template_id}/"
 
 
+class ENVELOPE_TEMPLATES:
+    LIST = "/envelope-templates/"
+    RETRIEVE = "/envelope-templates/${envelope_template_id}/"
+
+
 class WEBHOOKS:
     CREATE = "/webhooks/"
     LIST = "/webhooks/"

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/model/bundles.py

@@ -17,6 +17,70 @@ def generate_key(type, length=5):
     return f"{type}_{slug}"
 
 
+class AutoPlacement(BaseModel):
+    """Model for auto-placement fields that automatically find and place fields on documents"""
+
+    kind: str = ...
+    search: str = ...
+    w: int = ...
+    h: int = ...
+    offset_x: Optional[int] = 0
+    offset_y: Optional[int] = 0
+    editors: Optional[List[str]]
+    page: Optional[int]
+
+    class Config:
+        extra = "allow"
+
+    @classmethod
+    def create(
+        cls,
+        kind: str,
+        search: str,
+        w: int,
+        h: int,
+        offset_x: int = 0,
+        offset_y: int = 0,
+        **kwargs,
+    ):
+        """Create an AutoPlacement instance
+
+        Args:
+            kind: Field type (e.g., 'sig', 'inp', 'ini', etc.)
+            search: Text to search for in the document
+            w: Width of the field
+            h: Height of the field
+            offset_x: Horizontal offset from the search text (default: 0)
+            offset_y: Vertical offset from the search text (default: 0)
+            **kwargs: Additional parameters like editors, page, etc.
+
+        Returns:
+            AutoPlacement instance
+        """
+        obj = AutoPlacement(
+            kind=kind,
+            search=search,
+            w=w,
+            h=h,
+            offset_x=offset_x,
+            offset_y=offset_y,
+            **kwargs,
+        )
+        return obj
+
+    @validator("kind")
+    def kind_is_allowed(cls, v):
+        assert (
+            v in FIELD_KIND.values()
+        ), f"AutoPlacement Kind '{v}' not allowed. Must be one of {FIELD_KIND.values()}"
+        return v
+
+    def add_editor(self, editor: str):
+        if self.editors is None:
+            self.editors = []
+        self.editors.append(editor)
+
+
 class Field(BaseModel):
     kind: str = ...
     key: str = ...
@@ -112,6 +176,43 @@ class TemplateRefFieldValue(BaseModel):
         return obj
 
 
+class EnvelopeTemplateFieldValue(BaseModel):
+    """Model for field values in envelope templates"""
+
+    key: str = ...
+    initial_value: str = ...
+
+    class Config:
+        extra = "allow"
+
+    @classmethod
+    def create(cls, key, initial_value, **kwargs):
+        obj = EnvelopeTemplateFieldValue(key=key, initial_value=initial_value, **kwargs)
+        return obj
+
+
+class EnvelopeTemplate(BaseModel):
+    """Model for envelope template reference"""
+
+    template_id: str = ...
+    field_values: Optional[List[EnvelopeTemplateFieldValue]]
+
+    class Config:
+        extra = "allow"
+
+    @classmethod
+    def create(cls, template_id, field_values=None, **kwargs):
+        obj = EnvelopeTemplate(
+            template_id=template_id, field_values=field_values, **kwargs
+        )
+        return obj
+
+    def add_field_value(self, field_value: EnvelopeTemplateFieldValue):
+        if self.field_values is None:
+            self.field_values = []
+        self.field_values.append(field_value)
+
+
 class TemplateRef(BaseModel):
     template_id: Optional[str]
     assignments: Optional[List[TemplateRefAssignment]]
@@ -147,6 +248,7 @@ class Document(BaseModel):
     file_b64: Optional[str]
     file_index: Optional[int]
     fields: Optional[List[Field]]
+    auto_placements: Optional[List[AutoPlacement]]
 
     class Config:
         extra = "allow"
@@ -163,6 +265,16 @@ class Document(BaseModel):
             self.fields = []
         self.fields.append(field)
 
+    def add_auto_placement(self, auto_placement: AutoPlacement):
+        """Add an auto-placement to this document
+
+        Args:
+            auto_placement: AutoPlacement instance to add
+        """
+        if self.auto_placements is None:
+            self.auto_placements = []
+        self.auto_placements.append(auto_placement)
+
     def add_assignment(self, assignment: TemplateRefAssignment):
         if self.assignments is None:
             self.assignments = []

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/request_helper.py

@@ -54,9 +54,13 @@ class NormalizedResponse:
 
 
 class RequestHelper:
-    def __init__(self, private_api_key, raise_exceptions=False):
+    def __init__(
+        self, private_api_key, raise_exceptions=False, security_headers: dict = None
+    ):
+
         self._private_api_key = private_api_key
         self._raise_exceptions = raise_exceptions
+        self._security_headers = security_headers
 
     def delete(self, url, **kwargs):
         return self._make_request("delete", url, **kwargs)
@@ -87,6 +91,9 @@ class RequestHelper:
         if more_headers:
             hdrs.update(more_headers)
 
+        if self._security_headers:
+            hdrs.update(self._security_headers)
+
         hdrs["Authorization"] = f"Token {self._private_api_key}"
 
         if content_type is not None:
@@ -120,4 +127,5 @@ class RequestHelper:
 
         if self._raise_exceptions:
             response.raise_for_status()
+
         return NormalizedResponse(response)

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/subclients/bundle.py

@@ -103,6 +103,78 @@ class BundleSubClient(SubClient):
         files = bdl_helper.files
         return self.create(data=data, files=files)
 
+    def create_from_envelope_template(self, data: dict) -> NormalizedResponse:
+        """Create a Bundle from an envelope template.
+
+        This method creates a bundle using a pre-configured envelope template.
+        The envelope template contains complete envelope configurations including
+        documents, signers, and field assignments.
+
+        Args:
+            data: raw data for Bundle creation from envelope template, expressed as a python dict.
+                  Must include:
+                  - packets: list of signer information with keys matching template packet keys
+                  - envelope_template: dict with template_id and optional field_values
+                  Optional fields:
+                  - label: envelope label
+                  - is_test: whether this is a test envelope (default: False)
+
+        Returns:
+            NormalizedResponse object
+
+        Example:
+            data = {
+                "label": "Contract from Envelope Template",
+                "is_test": True,
+                "packets": [
+                    {
+                        "key": "signer-1",
+                        "name": "John Doe",
+                        "email": "john@example.com"
+                    }
+                ],
+                "envelope_template": {
+                    "template_id": "T-xxxxxxxxxxx",
+                    "field_values": [
+                        {
+                            "key": "company_name",
+                            "initial_value": "ACME Corporation"
+                        }
+                    ]
+                }
+            }
+            response = client.bundles.create_from_envelope_template(data)
+        """
+        if not data:
+            raise ValueError("data is required")
+
+        url = self.build_url(endpoints.BUNDLES.CREATE_FROM_ENVELOPE_TEMPLATE)
+        response = self._requests.post(url, json=data)
+
+        return response
+
+    def create_from_envelope_template_helper(
+        self, bdl_helper: BundleHelper
+    ) -> NormalizedResponse:
+        """Create a Bundle from an envelope template using BundleHelper.
+
+        Provided as a convenience to simplify creating a Bundle from an envelope template.
+
+        Args:
+            bdl_helper: BundleHelper that has been configured with envelope template.
+
+        Returns:
+            NormalizedResponse object
+
+        Example:
+            bh = BundleHelper(label="Contract", is_test=True)
+            bh.add_signer(name="John Doe", email="john@example.com", key="signer-1")
+            bh.set_envelope_template("T-abc123", {"company_name": "ACME"})
+            response = client.bundles.create_from_envelope_template_helper(bh)
+        """
+        data = bdl_helper.as_data_for_envelope_template()
+        return self.create_from_envelope_template(data=data)
+
     def paged_list(
         self,
         page: int = 1,

blueink_client_python-1.0.1/src/blueink/subclients/envelope_template.py

@@ -0,0 +1,64 @@
+from blueink import endpoints
+from blueink.paginator import PaginatedIterator
+from blueink.request_helper import NormalizedResponse
+from blueink.subclients.subclient import SubClient
+
+
+class EnvelopeTemplateSubClient(SubClient):
+    def paged_list(
+        self, page: int = 1, per_page: int = 50, **query_params
+    ) -> PaginatedIterator:
+        """Return an iterable object containing a list of envelope templates
+
+        Typical Usage:
+            for page in client.envelope_templates.paged_list():
+                page.body -> munch of json
+
+        Args:
+            page: start page (default 1)
+            per_page: max # of results per page (default 50)
+            query_params: Additional query params to be put onto the request
+
+        Returns:
+            PaginatedIterator object
+        """
+        iterator = PaginatedIterator(
+            paged_api_function=self.list, page=page, per_page=per_page, **query_params
+        )
+        return iterator
+
+    def list(
+        self, page: int = None, per_page: int = None, **query_params
+    ) -> NormalizedResponse:
+        """Return a list of Envelope Templates.
+
+        Envelope Templates are reusable document workflows that contain predefined
+        documents, field layouts, signer roles, and configuration settings.
+
+        Args:
+            page: which page to fetch
+            per_page: how many templates to fetch
+            query_params: Additional query params to be put onto the request
+
+        Returns:
+            NormalizedResponse object
+        """
+        url = self.build_url(endpoints.ENVELOPE_TEMPLATES.LIST)
+        return self._requests.get(
+            url, params=self.build_params(page, per_page, **query_params)
+        )
+
+    def retrieve(self, envelope_template_id: str) -> NormalizedResponse:
+        """Return a singular Envelope Template by id.
+
+        Args:
+            envelope_template_id: The ID that uniquely identifies the Envelope Template
+
+        Returns:
+            NormalizedResponse object
+        """
+        url = self.build_url(
+            endpoints.ENVELOPE_TEMPLATES.RETRIEVE,
+            envelope_template_id=envelope_template_id,
+        )
+        return self._requests.get(url)

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/subclients/person.py

@@ -45,7 +45,7 @@ class PersonSubClient(SubClient):
 
         Typical Usage:
             for page in client.persons.paged_list():
-                page.body -> munch of json
+                page.data -> response data
 
         Args:
             page: start page (default 1)

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/subclients/template.py

@@ -5,9 +5,6 @@ from blueink.subclients.subclient import SubClient
 
 
 class TemplateSubClient(SubClient):
-    def __init__(self, base_url, private_api_key):
-        super().__init__(base_url, private_api_key)
-
     def paged_list(
         self, page: int = 1, per_page: int = 50, **query_params
     ) -> PaginatedIterator:

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/subclients/webhook.py

@@ -4,9 +4,6 @@ from blueink.subclients.subclient import SubClient
 
 
 class WebhookSubClient(SubClient):
-    def __init__(self, base_url, private_api_key):
-        super().__init__(base_url, private_api_key)
-
     # ----------
     # Webhooks
     # ----------

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/tests/test_bundle_helper.py

@@ -186,3 +186,133 @@ class TestBundleHelper(TestCase):
             self.assert_equal(compiled_bundle["packets"][0][k], v)
         for k, v in signer02_data.items():
             self.assert_equal(compiled_bundle["packets"][1][k], v)
+
+    def test_adding_auto_placements(self):
+        """Test adding auto-placement fields to a document"""
+        input_data = copy.deepcopy(self.BUNDLE_INIT_DATA)
+        url01 = self.DOCUMENT_01_URL
+        signer01_data = copy.deepcopy(self.SIGNER_01_DATA)
+
+        bh = BundleHelper(**input_data)
+        doc01_key = bh.add_document_by_url(url01)
+        signer01_key = bh.add_signer(**signer01_data)
+
+        # Add auto-placement for signature
+        bh.add_auto_placement(
+            document_key=doc01_key,
+            kind="sig",
+            search="Signature",
+            w=20,
+            h=5,
+            offset_x=-5,
+            offset_y=2,
+            editors=[signer01_key],
+        )
+
+        # Add auto-placement for input field
+        bh.add_auto_placement(
+            document_key=doc01_key,
+            kind="inp",
+            search="Address",
+            w=20,
+            h=2,
+            offset_x=8,
+            offset_y=0,
+            editors=[signer01_key],
+        )
+
+        compiled_bundle = bh.as_data()
+
+        # Verify document exists
+        self.assert_in("documents", compiled_bundle)
+        self.assert_len(compiled_bundle["documents"], 1)
+
+        # Verify auto_placements exist
+        self.assert_in("auto_placements", compiled_bundle["documents"][0])
+        self.assert_len(compiled_bundle["documents"][0]["auto_placements"], 2)
+
+        # Verify first auto-placement (signature)
+        auto_placement_1 = compiled_bundle["documents"][0]["auto_placements"][0]
+        self.assert_equal(auto_placement_1["kind"], "sig")
+        self.assert_equal(auto_placement_1["search"], "Signature")
+        self.assert_equal(auto_placement_1["w"], 20)
+        self.assert_equal(auto_placement_1["h"], 5)
+        self.assert_equal(auto_placement_1["offset_x"], -5)
+        self.assert_equal(auto_placement_1["offset_y"], 2)
+        self.assert_in(signer01_key, auto_placement_1["editors"])
+
+        # Verify second auto-placement (input)
+        auto_placement_2 = compiled_bundle["documents"][0]["auto_placements"][1]
+        self.assert_equal(auto_placement_2["kind"], "inp")
+        self.assert_equal(auto_placement_2["search"], "Address")
+        self.assert_equal(auto_placement_2["w"], 20)
+        self.assert_equal(auto_placement_2["h"], 2)
+        self.assert_equal(auto_placement_2["offset_x"], 8)
+        self.assert_equal(auto_placement_2["offset_y"], 0)
+        self.assert_in(signer01_key, auto_placement_2["editors"])
+
+    def test_auto_placements_with_regular_fields(self):
+        """Test that auto-placements and regular fields can coexist"""
+        input_data = copy.deepcopy(self.BUNDLE_INIT_DATA)
+        url01 = self.DOCUMENT_01_URL
+        signer01_data = copy.deepcopy(self.SIGNER_01_DATA)
+        field01_data = copy.deepcopy(self.FIELD_01_DATA)
+
+        bh = BundleHelper(**input_data)
+        doc01_key = bh.add_document_by_url(url01)
+        signer01_key = bh.add_signer(**signer01_data)
+
+        # Add a regular field
+        field01_data["document_key"] = doc01_key
+        field01_data["editors"].append(signer01_key)
+        bh.add_field(**field01_data)
+
+        # Add an auto-placement
+        bh.add_auto_placement(
+            document_key=doc01_key,
+            kind="sig",
+            search="Sign Here",
+            w=25,
+            h=6,
+            offset_x=0,
+            offset_y=3,
+            editors=[signer01_key],
+        )
+
+        compiled_bundle = bh.as_data()
+
+        # Verify both fields and auto_placements exist
+        self.assert_in("documents", compiled_bundle)
+        doc = compiled_bundle["documents"][0]
+
+        self.assert_in("fields", doc)
+        self.assert_len(doc["fields"], 1)
+
+        self.assert_in("auto_placements", doc)
+        self.assert_len(doc["auto_placements"], 1)
+
+    def test_auto_placement_with_page_restriction(self):
+        """Test auto-placement with page number restriction"""
+        input_data = copy.deepcopy(self.BUNDLE_INIT_DATA)
+        url01 = self.DOCUMENT_01_URL
+        signer01_data = copy.deepcopy(self.SIGNER_01_DATA)
+
+        bh = BundleHelper(**input_data)
+        doc01_key = bh.add_document_by_url(url01)
+        signer01_key = bh.add_signer(**signer01_data)
+
+        # Add auto-placement restricted to page 2
+        bh.add_auto_placement(
+            document_key=doc01_key,
+            kind="sig",
+            search="Page 2 Signature",
+            w=20,
+            h=5,
+            page=2,
+            editors=[signer01_key],
+        )
+
+        compiled_bundle = bh.as_data()
+        auto_placement = compiled_bundle["documents"][0]["auto_placements"][0]
+
+        self.assert_equal(auto_placement["page"], 2)

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink/tests/test_client.py

@@ -503,3 +503,29 @@ class TestClientWebhook(TestCase):
     # -----------------
     # Secret testing not implemented, will tamper with whoever runs this test suite
     # -----------------
+
+
+# -----------------
+# Envelope Template Subclient Tests
+# -----------------
+class TestClientEnvelopeTemplate(TestCase):
+    def test_envelope_template_listing(self):
+        client = Client(raise_exceptions=False)
+        resp = client.envelope_templates.list()
+        self.assert_equal(resp.status, 200)
+        self.assert_not_none(resp.data)
+
+    def test_envelope_template_retrieval(self):
+        client = Client(raise_exceptions=False)
+
+        # First get a list to find a valid template ID
+        resp_list = client.envelope_templates.list()
+        self.assert_equal(resp_list.status, 200)
+
+        # If there are templates, test retrieval
+        if len(resp_list.data) > 0:
+            template_id = resp_list.data[0]["id"]
+            resp = client.envelope_templates.retrieve(template_id)
+            self.assert_equal(resp.status, 200)
+            self.assert_not_none(resp.data)
+            self.assert_equal(resp.data["id"], template_id)

blueink-client-python-1.0.0/README.md → blueink_client_python-1.0.1/src/blueink_client_python.egg-info/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.1
+Name: blueink-client-python
+Version: 1.0.1
+Summary: Python Client for Blueink eSignature API
+Home-page: https://github.com/blueinkhq/blueink-client-python
+Author: Blueink
+Author-email: pypi@blueink.com
+Project-URL: Bug Tracker, https://github.com/blueinkhq/blueink-client-python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: munch
+Requires-Dist: requests
+Requires-Dist: pydantic
+Requires-Dist: email-validator
+Provides-Extra: munch
+Requires-Dist: munch>=2.5; extra == "munch"
+Provides-Extra: requests
+Requires-Dist: requests>=2.31; extra == "requests"
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=1.9; extra == "pydantic"
+Provides-Extra: email-validator
+Requires-Dist: email-validator>=1.2; extra == "email-validator"
+
 # blueink-client-python
 ![Tests](https://github.com/blueinkhq/blueink-client-python/actions/workflows/helper-tests.yml/badge.svg)
 ![Style Checks](https://github.com/blueinkhq/blueink-client-python/actions/workflows/style-checks.yml/badge.svg)
@@ -373,6 +400,56 @@ with open("/path/to/file/example.pdf", 'rb') as file:
     doc04_key = bh.add_document_by_file(file)
 ```
 
+#### Auto-Placement Fields
+
+Auto-placement fields allow you to automatically search for text in documents and place
+signature/input fields at those locations with optional offsets. This eliminates the need
+to manually specify exact coordinates for fields.
+
+```python
+from blueink import BundleHelper, Client
+
+bh = BundleHelper(
+    label="Auto-Placement Example",
+    email_subject="Please sign",
+    is_test=True,
+)
+
+signer_key = bh.add_signer(name="John Doe", email="john@example.com")
+doc_key = bh.add_document_by_url("https://www.irs.gov/pub/irs-pdf/fw9.pdf")
+
+# Add auto-placement field that searches for "Signature" text
+bh.add_auto_placement(
+    document_key=doc_key,
+    kind="sig",              # Field type: signature
+    search="Signature",      # Text to search for
+    w=20,                    # Width
+    h=5,                     # Height
+    offset_x=-5,             # Move 5 units left from found text
+    offset_y=2,              # Move 2 units down from found text
+    editors=[signer_key],
+)
+
+# Add auto-placement for an input field
+bh.add_auto_placement(
+    document_key=doc_key,
+    kind="inp",              # Field type: input
+    search="Address",        # Text to search for
+    w=20,
+    h=2,
+    offset_x=8,              # Move 8 units right from found text
+    editors=[signer_key],
+)
+
+client = Client()
+response = client.bundles.create_from_bundle_helper(bh)
+```
+
+**Key benefits of auto-placement:**
+- No need to manually find exact coordinates
+- Works with template documents that have consistent text labels
+- Automatically adjusts to text position in the document
+- Can be combined with regular manually-positioned fields
 
 #### Retrieval
 

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink_client_python.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ src/blueink/model/persons.py
 src/blueink/model/webhook.py
 src/blueink/subclients/__init__.py
 src/blueink/subclients/bundle.py
+src/blueink/subclients/envelope_template.py
 src/blueink/subclients/packet.py
 src/blueink/subclients/person.py
 src/blueink/subclients/subclient.py

{blueink-client-python-1.0.0 → blueink_client_python-1.0.1}/src/blueink_client_python.egg-info/requires.txt

@@ -3,8 +3,8 @@ requests
 pydantic
 email-validator
 
-[email-validator>]
-1.2
+[email-validator]
+email-validator>=1.2
 
 [munch]
 munch>=2.5
@@ -13,4 +13,4 @@ munch>=2.5
 pydantic>=1.9
 
 [requests]
-requests>=2.27
+requests>=2.31