docwal 1.0.0__tar.gz

docwal-1.0.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to the DocWal Python SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-01-10
+
+### Added
+- Initial release of DocWal Python SDK
+- Credentials resource with full CRUD operations
+- Template management (create, list, update, delete)
+- Team member management (invite, list, update roles, deactivate, remove)
+- API key management (generate, regenerate, revoke, info)
+- Batch credential issuance (JSON array and ZIP upload)
+- File upload support for PDF documents
+- Comprehensive error handling with custom exceptions
+- Full documentation with examples
+- Type hints throughout the codebase
+
+### Features
+- Issue single credentials with optional PDF attachments
+- Batch issue up to 1000 credentials at once
+- Batch upload with ZIP files (CSV/JSON + PDFs)
+- List and filter credentials with pagination
+- Revoke credentials with audit trail
+- Resend claim links with configurable expiration
+- Download credential files
+- Manage credential templates with schema validation
+- Team collaboration with role-based permissions
+- Secure API key authentication
+
+### Security
+- API key-based authentication
+- HTTPS-only communication
+- Input validation for all requests
+- Proper error handling without leaking sensitive data

docwal-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DocWal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docwal-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+recursive-include docwal *.py
+exclude examples/*
+exclude tests/*
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

docwal-1.0.0/PKG-INFO

@@ -0,0 +1,388 @@
+Metadata-Version: 2.4
+Name: docwal
+Version: 1.0.0
+Summary: Official Python SDK for DocWal API - Issue and manage verifiable digital credentials
+Home-page: https://github.com/docwal/docwal-python
+Author: DocWal
+Author-email: support@docwal.com
+Project-URL: Bug Tracker, https://github.com/docwal/docwal-python/issues
+Project-URL: Documentation, https://docs.docwal.com
+Project-URL: Source Code, https://github.com/docwal/docwal-python
+Keywords: docwal credentials verifiable digital education blockchain
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# DocWal Python SDK
+
+Official Python SDK for DocWal API - Issue and manage verifiable digital credentials.
+
+## Installation
+
+```bash
+pip install docwal
+```
+
+## Quick Start
+
+```python
+from docwal import DocWalClient
+
+# Initialize client with your API key
+client = DocWalClient(api_key="docwal_live_xxxxx")
+
+# Issue a credential
+result = client.credentials.issue(
+    template_id="template-123",
+    individual_email="student@example.com",
+    credential_data={
+        "student_name": "John Doe",
+        "degree": "Bachelor of Science",
+        "major": "Computer Science",
+        "graduation_date": "2024-05-15",
+        "gpa": "3.8"
+    }
+)
+
+print(f"Credential issued! Doc ID: {result['doc_id']}")
+print(f"Claim token: {result['claim_token']}")
+```
+
+## Authentication
+
+Get your API key from your DocWal dashboard:
+1. Login to https://docwal.com
+2. Navigate to Settings → API Keys
+3. Click "Generate API Key"
+4. Copy and store securely
+
+**Requirements:**
+- Pilot tier or above
+- Owner or Admin role
+
+## Environment Configuration
+
+```python
+# Production (default)
+client = DocWalClient(api_key="docwal_live_xxxxx")
+
+# Staging
+client = DocWalClient(
+    api_key="docwal_test_xxxxx",
+    base_url="https://sandbox.docwal.com/api"
+)
+
+# Custom timeout
+client = DocWalClient(
+    api_key="docwal_live_xxxxx",
+    timeout=60  # seconds
+)
+```
+
+## Usage Examples
+
+### Issue Single Credential
+
+```python
+# Basic credential
+result = client.credentials.issue(
+    template_id="template-123",
+    individual_email="student@example.com",
+    credential_data={
+        "student_name": "John Doe",
+        "degree": "Bachelor of Science",
+        "graduation_date": "2024-05-15"
+    }
+)
+
+# With PDF attachment
+with open("certificate.pdf", "rb") as f:
+    result = client.credentials.issue(
+        template_id="template-123",
+        individual_email="student@example.com",
+        credential_data={"student_name": "John Doe"},
+        document_file=f,
+        claim_token_expires_hours=168  # 7 days
+    )
+```
+
+### Batch Issue Credentials
+
+```python
+credentials_list = [
+    {
+        "individual_email": "student1@example.com",
+        "credential_data": {
+            "student_name": "Alice Smith",
+            "degree": "Bachelor of Arts",
+            "graduation_date": "2024-05-15"
+        }
+    },
+    {
+        "individual_email": "student2@example.com",
+        "credential_data": {
+            "student_name": "Bob Johnson",
+            "degree": "Bachelor of Science",
+            "graduation_date": "2024-05-15"
+        }
+    }
+]
+
+result = client.credentials.batch_issue(
+    template_id="template-123",
+    credentials=credentials_list,
+    send_notifications=True
+)
+
+print(f"Success: {result['success_count']}/{result['total_rows']}")
+```
+
+### Batch Upload with ZIP
+
+```python
+# ZIP structure:
+# batch_credentials.zip
+# ├── credentials.csv
+# └── documents/
+#     ├── student001.pdf
+#     ├── student002.pdf
+#     └── student003.pdf
+
+with open("batch_credentials.zip", "rb") as f:
+    result = client.credentials.batch_upload(
+        template_id="template-123",
+        file=f,
+        send_notifications=True
+    )
+
+print(f"Processed: {result['total_rows']}")
+print(f"Success: {result['success_count']}")
+print(f"Failed: {result['failure_count']}")
+
+for item in result['results']:
+    if item['status'] == 'success':
+        print(f"Row {item['row']}: {item['doc_id']}")
+    else:
+        print(f"Row {item['row']}: {item['error']}")
+```
+
+### List and Get Credentials
+
+```python
+# List all credentials
+credentials = client.credentials.list(limit=50, offset=0)
+
+for cred in credentials:
+    print(f"{cred['doc_id']}: {cred['template_name']}")
+
+# Get specific credential
+credential = client.credentials.get("DOC123456")
+print(f"Issued to: {credential['ownership']['individual_email']}")
+print(f"Status: {'Claimed' if credential['ownership']['is_claimed'] else 'Pending'}")
+```
+
+### Revoke Credential
+
+```python
+result = client.credentials.revoke(
+    doc_id="DOC123456",
+    reason="Student expelled for academic misconduct"
+)
+print(result['message'])
+```
+
+### Resend Claim Link
+
+```python
+result = client.credentials.resend_claim_link(
+    doc_id="DOC123456",
+    claim_token_expires_hours=168  # 7 days
+)
+
+print(f"Sent to: {result['recipient_email']}")
+print(f"Expires: {result['claim_token_expires']}")
+```
+
+### Download Credential File
+
+```python
+# Download PDF file
+pdf_content = client.credentials.download("DOC123456")
+
+with open("credential.pdf", "wb") as f:
+    f.write(pdf_content)
+```
+
+## Template Management
+
+```python
+# List templates
+templates = client.templates.list()
+
+# Get template
+template = client.templates.get("template-123")
+
+# Create template
+template = client.templates.create(
+    name="Bachelor Degree Certificate",
+    description="Template for bachelor degree graduation certificates",
+    credential_type="certificate",
+    schema={
+        "student_name": {
+            "type": "string",
+            "required": True,
+            "label": "Student Name"
+        },
+        "degree": {
+            "type": "string",
+            "required": True,
+            "label": "Degree Program"
+        },
+        "graduation_date": {
+            "type": "date",
+            "required": True,
+            "label": "Graduation Date"
+        }
+    },
+    version="1.0"
+)
+
+# Update template
+client.templates.update(
+    "template-123",
+    description="Updated description"
+)
+
+# Delete template (soft delete)
+client.templates.delete("template-123")
+```
+
+## API Key Management
+
+```python
+# Generate new API key (Owner/Admin only)
+result = client.api_keys.generate()
+print(f"New API key: {result['api_key']}")
+print("⚠️  Store securely - shown only once!")
+
+# Get API key info
+info = client.api_keys.info()
+print(f"Masked key: {info['api_key_masked']}")
+print(f"Created: {info['created_at']}")
+print(f"Last used: {info['last_used_at']}")
+
+# Regenerate API key
+result = client.api_keys.regenerate()
+print(f"New API key: {result['api_key']}")
+
+# Revoke API key
+client.api_keys.revoke()
+```
+
+## Team Management
+
+```python
+# List team members
+team = client.team.list()
+print(f"Active members: {team['stats']['active_members']}")
+print(f"Pending invitations: {team['stats']['pending_invitations']}")
+
+# Check email before inviting
+check = client.team.check_email("newmember@university.edu")
+if check['recommendation'] == 'add_directly':
+    print("User exists - can add directly")
+elif check['recommendation'] == 'send_invitation':
+    print("User doesn't exist - must send invitation")
+
+# Invite team member
+result = client.team.invite(
+    email="newmember@university.edu",
+    role="issuer",
+    send_email=True
+)
+
+# Update member role
+client.team.update_role(
+    member_id="member-123",
+    role="admin"
+)
+
+# Deactivate member
+client.team.deactivate(
+    member_id="member-123",
+    reason="Employee on leave"
+)
+
+# Reactivate member
+client.team.reactivate("member-123")
+
+# Remove member permanently
+client.team.remove("member-123")
+```
+
+## Error Handling
+
+```python
+from docwal import DocWalClient, DocWalError, AuthenticationError, ValidationError
+
+client = DocWalClient(api_key="docwal_live_xxxxx")
+
+try:
+    result = client.credentials.issue(
+        template_id="invalid-template",
+        individual_email="student@example.com",
+        credential_data={}
+    )
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+    print("Check your API key")
+except ValidationError as e:
+    print(f"Validation error: {e}")
+    print("Check required fields")
+except DocWalError as e:
+    print(f"API error: {e}")
+    print(f"Status code: {e.status_code}")
+```
+
+## Rate Limits
+
+- **Pilot**: 500 requests/hour
+- **Standard**: 1,000 requests/hour
+- **Enterprise**: Unlimited
+
+When rate limit is exceeded, `RateLimitError` is raised.
+
+## Support
+
+- **Email**: support@docwal.com
+- **Documentation**: https://docs.docwal.com
+- **API Reference**: https://docwal.com/api/docs
+- **GitHub**: https://github.com/docwal/docwal-python
+
+## License
+
+MIT License - see LICENSE file for details.