aitbc/enterprise-connectors/python-sdk/docs/README.md

AITBC Enterprise Connectors SDK

Python SDK for integrating AITBC with enterprise systems including payment processors, ERP systems, and other business applications.

Quick Start

Installation

pip install aitbc-enterprise

Basic Usage

import asyncio
from aitbc_enterprise import AITBCClient, ConnectorConfig
from aitbc_enterprise.payments import StripeConnector

async def main():
    # Configure AITBC client
    config = ConnectorConfig(
        base_url="https://api.aitbc.io",
        api_key="your-api-key",
        enterprise_id="enterprise-123"
    )
    
    # Create client and connector
    async with AITBCClient(config) as client:
        stripe = StripeConnector(
            client=client,
            config=config,
            stripe_api_key="sk_test_your-stripe-key"
        )
        
        await stripe.initialize()
        
        # Create a charge
        charge = await stripe.create_charge(
            amount=2000,  # $20.00
            currency="usd",
            source="pm_card_visa",
            description="AITBC service"
        )
        
        print(f"Charge created: {charge.id}")
        
        await stripe.cleanup()

asyncio.run(main())

Features

• Async/Await Support: Full async implementation for high performance
• Enterprise Ready: Built-in rate limiting, metrics, and error handling
• Extensible: Plugin architecture for custom connectors
• Secure: HSM-backed key management and audit logging
• Compliant: GDPR, SOC 2, and PCI DSS compliant

Supported Systems

Payment Processors

• ✅ Stripe
• ⏳ PayPal (Coming soon)
• ⏳ Square (Coming soon)

ERP Systems

• ⏳ SAP (IDOC/BAPI)
• ⏳ Oracle (REST/SOAP)
• ⏳ NetSuite (SuiteTalk)

Architecture

The SDK uses a modular architecture with dependency injection:

AITBCClient
├── Core Components
│   ├── AuthHandler (Bearer, OAuth2, HMAC, etc.)
│   ├── RateLimiter (Token bucket, Sliding window)
│   ├── MetricsCollector (Performance tracking)
│   └── WebhookHandler (Event processing)
├── BaseConnector
│   ├── Validation
│   ├── Error Handling
│   ├── Batch Operations
│   └── Event Handlers
└── Specific Connectors
    ├── PaymentConnector
    └── ERPConnector

Configuration

Basic Configuration

config = ConnectorConfig(
    base_url="https://api.aitbc.io",
    api_key="your-api-key",
    timeout=30.0,
    max_retries=3
)

Enterprise Features

config = ConnectorConfig(
    base_url="https://api.aitbc.io",
    api_key="your-api-key",
    enterprise_id="enterprise-123",
    tenant_id="tenant-456",
    region="us-east-1",
    rate_limit=100,  # requests per second
    enable_metrics=True,
    webhook_secret="whsec_your-secret"
)

Authentication

The SDK supports multiple authentication methods:

# Bearer token (default)
config = ConnectorConfig(
    auth_type="bearer",
    api_key="your-token"
)

# OAuth 2.0
config = ConnectorConfig(
    auth_type="oauth2",
    auth_config={
        "client_id": "your-client-id",
        "client_secret": "your-secret",
        "token_url": "https://oauth.example.com/token"
    }
)

# HMAC signature
config = ConnectorConfig(
    auth_type="hmac",
    api_key="your-key",
    auth_config={
        "secret": "your-secret",
        "algorithm": "sha256"
    }
)

Error Handling

The SDK provides comprehensive error handling:

from aitbc_enterprise.exceptions import (
    AITBCError,
    AuthenticationError,
    RateLimitError,
    PaymentError,
    ValidationError
)

try:
    charge = await stripe.create_charge(...)
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except PaymentError as e:
    print(f"Payment failed: {e}")
except AITBCError as e:
    print(f"AITBC error: {e}")

Webhooks

Handle webhooks with built-in verification:

from aitbc_enterprise.webhooks import StripeWebhookHandler

# Create webhook handler
webhook_handler = StripeWebhookHandler(
    secret="whsec_your-webhook-secret"
)

# Add custom handler
async def handle_charge(event):
    print(f"Charge: {event.data}")

webhook_handler.add_handler("charge.succeeded", handle_charge)

# Process webhook
result = await webhook_handler.handle(payload, signature)

Batch Operations

Process multiple operations efficiently:

# Batch charges
operations = [
    {
        "operation": "create_charge",
        "data": {"amount": 1000, "currency": "usd", "source": "pm_123"}
    },
    {
        "operation": "create_charge",
        "data": {"amount": 2000, "currency": "usd", "source": "pm_456"}
    }
]

results = await stripe.batch_execute(operations)
successful = sum(1 for r in results if r.success)

Metrics and Monitoring

Enable metrics collection:

config = ConnectorConfig(
    enable_metrics=True,
    metrics_endpoint="https://your-metrics.example.com"
)

# Metrics are automatically collected
# Access metrics summary
print(stripe.metrics)

Testing

Use the test mode for development:

# Use test API keys
config = ConnectorConfig(
    base_url="https://api-test.aitbc.io",
    api_key="test-key"
)

stripe = StripeConnector(
    client=client,
    config=config,
    stripe_api_key="sk_test_key"  # Stripe test key
)

Examples

See the examples/ directory for complete examples:

• stripe_example.py - Payment processing
• webhook_example.py - Webhook handling
• enterprise_example.py - Enterprise features

Support

• Documentation: https://docs.aitbc.io/enterprise-sdk
• Issues: https://github.com/aitbc/enterprise-sdk/issues
• Support: enterprise@aitbc.io
• Security: security@aitbc.io

License

Copyright © 2024 AITBC. All rights reserved.