esignbase-sdk 1.0.0__py3-none-any.whl

esignbase_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: esignbase-sdk
+Version: 1.0.0
+Summary: SDK Package for the eSignBase API
+Author-email: Matthias Meß <info@esignbase.com>
+Requires-Python: <4.0,>=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: requests<3.0.0,>=2.32.5
+Provides-Extra: dev
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: black; extra == "dev"
+
+# esignbase-python-sdk
+API Client for the [eSignBase](https://esignbase.com) API
+
+The package provides a small, synchronous client for interacting with the eSignBase API.
+
+Full REST API documentation is available at https://esignbase.com/en/api_documentation it also shows the format of the returned dictionary data.
+
+### Classes
+
+**GrantType** (Enum)
+
+Defines the available OAuth2 grant types:
+
+* CLIENT_CREDENTIALS: For server-to-server authentication
+* AUTHORIZATION_CODE: For user-specific authentication
+
+
+**Scope** (Enum)
+
+Defines the available API permission scopes:
+
+* ALL: Full access to all API endpoints
+* READ: Read-only access
+* CREATE_DOCUMENT: Permission to create documents
+* DELETE: Permission to delete documents
+* SANDBOX: Access to the sandbox environment, use this scope for testing
+
+**OAuth2Client**
+
+Main client class that stores authentication credentials and state.
+
+Attributes:
+```python
+id (str) # Client ID from ESignBase
+secret (str) # Client secret from ESignBase
+grant_type (GrantType) # OAuth2 grant type to use
+user_name (Optional[str]) # Username (required AUTHORIZATION_CODE)
+password (Optional[str]) # Password (required AUTHORIZATION_CODE)
+scope (list[Scope]) # List of requested API scopes
+```
+Retrieve your Client ID and Client Secret at https://app.esignbase.com/oauth2/client by creating an
+OAuth2 Client Configuration.
+
+**Recipient**
+
+Represents a document recipient/signer.
+`role_name` value is defined during template creation in the template editor.
+
+Attributes:
+```python
+email (str) # Recipient's email address
+first_name (str) # Recipient's first name
+last_name (str) # Recipient's last name
+role_name (str) # Role name (e.g., "Signer", "Viewer")
+locale (str) # Locale code ("de", "en", "es")
+```
+
+**ESignBaseSDKError** (Exception)
+
+Custom exception class for API-related errors.
+
+### Functions
+
+```python
+def connect(client: OAuth2Client) -> None
+```
+
+Authenticates with the ESignBase API
+
+Parameters:
+
+    client: Configured OAuth2Client instance
+
+Raises:
+
+    ESignBaseSDKError: If authentication fails or validation fails
+
+Example:
+```python
+client = OAuth2Client(
+    id="your_client_id",
+    secret="your_client_secret",
+    grant_type=GrantType.CLIENT_CREDENTIALS,
+    scope=[Scope.ALL],
+)
+connect(client)
+```
+---
+
+```python
+def get_templates(client: OAuth2Client) -> list[dict[str, Any]]
+```
+
+
+Retrieves a list of available document templates.
+
+Parameters:
+```
+client: Authenticated OAuth2Client instance
+```
+
+Returns A list of dictionaries containing template data.
+
+Raises:
+
+    ESignBaseSDKError: If the API request fails
+
+---
+
+```python
+def get_template(client: OAuth2Client, template_id: str) -> dict[str, Any]
+```
+
+Retrieves details of a specific template.
+
+Parameters:
+
+    client: Authenticated OAuth2Client instance
+    template_id: Unique identifier of the template
+
+Returns:
+    Dictionary containing template details
+
+Raises:
+    ESignBaseSDKError: If the API request fails
+
+---
+
+```python
+def get_documents(client: OAuth2Client, limit: int, offset: int) -> dict[str, Any]
+```
+Retrieves a paginated list of documents.
+
+Parameters:
+
+    client: Authenticated OAuth2Client instance
+    limit: Maximum number of documents to return
+    offset: Pagination offset
+
+Returns:
+
+    Dictionary containing document list and pagination info `{documents: [...]}`
+
+Raises:
+
+    ESignBaseSDKError: If the API request fails
+
+---
+
+```python
+def get_document(client: OAuth2Client, document_id: str) -> dict[str, Any]
+```
+
+Retrieves details of a specific document.
+
+Parameters:
+
+    client: Authenticated OAuth2Client instance
+    document_id: Unique identifier of the document
+
+Returns:
+
+    Dictionary containing document details
+
+Raises:
+
+    ESignBaseSDKError: If the API request fails
+
+---
+
+```python
+def create_document(
+    client: OAuth2Client,
+    template_id: str,
+    document_name: str,
+    recipients: list[Recipient],
+    user_defined_metadata: Optional[dict[str, str | int]] = None,
+    expiration_date: Optional[datetime] = None
+) -> dict[str, Any]
+```
+
+Creates a new document from a template.
+
+Parameters:
+
+    client: Authenticated OAuth2Client instance
+    template_id: ID of the template to use
+    document_name: Name for the new document
+    recipients: List of Recipient objects
+    user_defined_metadata: Optional metadata to attach to the document
+    expiration_date: Optional expiration date for the document
+
+Returns:
+
+    Dictionary containing the created document id and current document status
+
+Raises:
+
+    ESignBaseSDKError: If the API request fails
+
+Example:
+
+```python
+recipients = [
+    Recipient(
+        email="signer@example.com",
+        first_name="John",
+        last_name="Doe",
+        role_name="signer",
+        locale="de"
+    )
+]
+
+document = create_document(
+    client=client,
+    template_id="template_123",
+    document_name="Contract Agreement",
+    recipients=recipients,
+    user_defined_metadata={"contract_id": "CTR-2024-001"},
+    expiration_date=datetime(2024, 12, 31)
+)
+
+```
+
+---
+
+```python
+def delete_document(client: OAuth2Client, document_id: str) -> None
+```
+
+Deletes a specific document.
+
+Parameters:
+
+    client: Authenticated OAuth2Client instance
+    document_id: Unique identifier of the document to delete
+
+Raises:
+
+    ESignBaseSDKError: If the API request fails
+
+---
+
+```python
+def get_credits(client: OAuth2Client) -> dict[str, Any]
+```
+
+Retrieves credit balance information.
+
+Parameters:
+
+    client: Authenticated OAuth2Client instance
+
+Returns:
+
+    Dictionary containing credit balance data
+
+Raises:
+
+    ESignBaseSDKError: If the API request fails
+
+Error Handling
+
+All functions raise ESignBaseSDKError exceptions for API errors, network issues, or validation failures. Always wrap API calls in try-except blocks:
+
+```python
+try:
+    templates = get_templates(client)
+except ESignBaseSDKError as e:
+    print(f"API Error: {e}")
+```
+
+Complete Example
+
+
+```python
+
+from datetime import datetime
+
+# Setup client
+client = OAuth2Client(
+    id="your_client_id",
+    secret="your_client_secret",
+    grant_type=GrantType.CLIENT_CREDENTIALS,
+    scope=[Scope.CREATE_DOCUMENT, Scope.READ]
+)
+
+# Authenticate
+connect(client)
+
+# Get available templates
+templates = get_templates(client)
+
+# Create a document
+recipients = [
+    Recipient(
+        email="alice@example.com",
+        first_name="Alice",
+        last_name="Smith",
+        role_name="Signer",
+        locale="en"
+    )
+]
+template_id = templates[0]["id"]
+
+document = create_document(
+    client=client,
+    template_id=template_id,
+    document_name="NDA Agreement",
+    recipients=recipients
+)
+
+# Check document status
+document_details = get_document(client, document["id"])
+
+# Delete the document (if needed)
+delete_document(client, document["id"])
+```

esignbase_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+esignbase_sdk-1.0.0.dist-info/METADATA,sha256=M4gRi6cKF017_i5fOibZFr760EA4vJAJU-VCjiAHpbI,7085
+esignbase_sdk-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+esignbase_sdk-1.0.0.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+esignbase_sdk-1.0.0.dist-info/RECORD,,

esignbase_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

esignbase_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+