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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: blueink-client-python
-Version: 1.0.0
+Version: 1.2.0
 Summary: Python Client for Blueink eSignature API
 Home-page: https://github.com/blueinkhq/blueink-client-python
 Author: Blueink
@@ -19,11 +19,12 @@ 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"
+Dynamic: license-file
 
 # blueink-client-python
 ![Tests](https://github.com/blueinkhq/blueink-client-python/actions/workflows/helper-tests.yml/badge.svg)
@@ -400,6 +401,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.2.0/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.2.0}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = blueink-client-python
-version = 1.0.0
+version = 1.2.0
 author = Blueink
 author_email = pypi@blueink.com
 description = Python Client for Blueink eSignature API
@@ -27,7 +27,7 @@ install_requires =
 
 [options.extras_require]
 munch = munch>=2.5;
-requests = requests>=2.27;
+requests = requests>=2.31;
 pydantic = pydantic>=1.9
 email-validator> = 1.2
 

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

@@ -4,9 +4,13 @@ from os.path import basename
 from typing import List
 
 from blueink.model.bundles import (
+    AutoPlacement,
     Bundle,
     Document,
+    EnvelopeTemplate,
+    EnvelopeTemplateFieldValue,
     Field,
+    ImportedDocument,
     Packet,
     TemplateRef,
     TemplateRefAssignment,
@@ -25,6 +29,9 @@ class BundleHelper:
         is_test: bool = False,
         custom_key: str = None,
         team: str = None,
+        signing_brand: str = None,
+        expires: str = None,
+        tag_values: dict = None,
     ):
         """Helper class to aid building a Bundle.
 
@@ -38,6 +45,9 @@ class BundleHelper:
             is_test:
             custom_key:
             team:
+            signing_brand:
+            expires:
+            tag_values: Optional dict mapping data flow tags to pre-filled values
         """
         self._label = label
         self._in_order = in_order
@@ -49,6 +59,10 @@ class BundleHelper:
         self._packets = {}
         self._custom_key = custom_key
         self._team = team
+        self._signing_brand = signing_brand
+        self._expires = expires
+        self._tag_values = tag_values
+        self._envelope_template = None
 
         # for file uploads, index should match those in the document "file_index" field
         self.file_names = []
@@ -107,6 +121,20 @@ class BundleHelper:
 
         return self.add_document_by_b64(filename, b64str, **additional_data)
 
+    def add_document_by_html(self, html_content: str, **additional_data) -> str:
+        """Add a document using an HTML string for HTML-to-PDF conversion.
+
+        Args:
+            html_content: HTML content string
+            additional_data: Optional additional kwargs (e.g., filename, html_fields_mode)
+
+        Returns:
+            Document Key
+        """
+        document = Document.create(file_html=html_content, **additional_data)
+        self._documents[document.key] = document
+        return document.key
+
     def add_document_by_b64(self, filename: str, b64str: str, **additional_data):
         """Add a file using a b64 string; utf-8 encoded
 
@@ -205,6 +233,10 @@ class BundleHelper:
         v_pattern: str = None,
         v_min: int = None,
         v_max: int = None,
+        v_regex: str = None,
+        v_regex_msg: str = None,
+        v_attachment_types: List[str] = None,
+        data_flow_tag: str = None,
         key=None,
         **additional_data,
     ):
@@ -222,6 +254,10 @@ class BundleHelper:
             v_pattern: Optional
             v_min: Optional
             v_max: Optional
+            v_regex: Optional regular expression for field validation
+            v_regex_msg: Optional error message shown when v_regex validation fails
+            v_attachment_types: Optional list of allowed attachment file extensions (only for kind='att')
+            data_flow_tag: Optional data flow tag to associate with the field
             editors: Optional
             key: Optional
             additional_data: Optional and will append any additional kwargs to the json of the field
@@ -243,6 +279,10 @@ class BundleHelper:
             v_pattern=v_pattern,
             v_min=v_min,
             v_max=v_max,
+            v_regex=v_regex,
+            v_regex_msg=v_regex_msg,
+            v_attachment_types=v_attachment_types,
+            data_flow_tag=data_flow_tag,
             key=key,
             **additional_data,
         )
@@ -252,6 +292,75 @@ 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,
+        v_attachment_types: List[str] = 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
+            v_attachment_types: Optional list of allowed attachment file extensions (only for kind='att')
+            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,
+            v_attachment_types=v_attachment_types,
+            **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,
@@ -264,6 +373,8 @@ class BundleHelper:
         auth_id: bool = False,
         order: int = None,
         key=None,
+        requires_witness: bool = None,
+        witness_nominated_by: str = None,
         **additional_data,
     ):
         """Create and add a signer. With at least an email xor phone number.
@@ -279,6 +390,8 @@ class BundleHelper:
             auth_id: Optional
             deliver_via: Optional
             order: Optional
+            requires_witness: Optional
+            witness_nominated_by: Optional
             additional_data: Optional and will append any additional kwargs to the json of the signer
 
         Returns:
@@ -298,6 +411,8 @@ class BundleHelper:
             deliver_via=deliver_via,
             order=order,
             key=key,
+            requires_witness=requires_witness,
+            witness_nominated_by=witness_nominated_by,
             **additional_data,
         )
         self._packets[packet.key] = packet
@@ -347,6 +462,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
@@ -368,6 +541,9 @@ class BundleHelper:
             cc_emails=self._cc_emails,
             custom_key=self._custom_key,
             team=self._team,
+            signing_brand=self._signing_brand,
+            expires=self._expires,
+            tag_values=self._tag_values,
             **additional_data,
         )
         return bundle_out
@@ -384,6 +560,63 @@ 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
+        if self._signing_brand:
+            result["signing_brand"] = self._signing_brand
+
+        # 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.2.0}/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.2.0}/src/blueink/endpoints.py

@@ -8,6 +8,8 @@ from string import Template
 
 class BUNDLES:
     CREATE = "/bundles/"
+    CREATE_FROM_ENVELOPE_TEMPLATE = "/bundles/create_from_envelope_template/"
+    CREATE_PREPARATION_SESSION = "/bundles/preparation_session/"
     LIST = "/bundles/"
     RETRIEVE = "/bundles/${bundle_id}/"
     CANCEL = "/bundles/${bundle_id}/cancel/"
@@ -34,6 +36,13 @@ class PACKETS:
 class TEMPLATES:
     LIST = "/templates/"
     RETRIEVE = "/templates/${template_id}/"
+    UPDATE = "/templates/${template_id}/"
+    CREATE_PREPARATION_SESSION = "/templates/preparation_session/"
+
+
+class ENVELOPE_TEMPLATES:
+    LIST = "/envelope-templates/"
+    RETRIEVE = "/envelope-templates/${envelope_template_id}/"
 
 
 class WEBHOOKS: