huntrecht-sdk 0.1.0__tar.gz

huntrecht_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: huntrecht-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Huntrecht Platform API v1
+Author-email: Huntrecht <dev@huntrecht.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/huntrecht/sdk-python
+Project-URL: Documentation, https://docs.huntrecht.com/guide/
+Project-URL: Repository, https://github.com/huntrecht/sdk-python
+Keywords: huntrecht,api,sdk,b2b,ecommerce,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# GraphQL Data Connect SDK - Python Implementation
+
+Complete GraphQL server for ingesting customer credit history from external data providers and feeding it to the RAG pipeline with automatic Shopify B2B company mapping.
+
+## Features
+
+✅ **GraphQL Server** with Strawberry GraphQL  
+✅ **Data Provider Connectors** for external GraphQL APIs  
+✅ **Shopify B2B Company Registry** with auto-creation  
+✅ **RAG Pipeline Integration** with LangChain documents  
+✅ **PostgreSQL Storage** with optimized indexes  
+✅ **Credit History Analytics** with aggregated views  
+✅ **Multi-Provider Support** with connector framework  
+
+## Quick Start
+
+### 1. Access GraphiQL IDE
+
+Navigate to http://localhost:5000/graphql/credit-history in your browser to access the interactive GraphQL playground.
+
+### 2. Example Queries
+
+#### Fetch Credit History
+```graphql
+query GetCreditHistory {
+  creditHistory(
+    companyId: "ext_company_123"
+    startDate: "2025-01-01T00:00:00Z"
+    limit: 50
+  ) {
+    totalCount
+    edges {
+      node {
+        id
+        companyId
+        shopifyCompanyId
+        email
+        date
+        inflow
+        outflow
+        reference
+        bank
+        currency
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+#### Get Company Summary
+```graphql
+query GetCompanySummary {
+  companyCreditSummary(
+    shopifyCompanyId: "gid://shopify/Company/12345"
+  )
+}
+```
+
+### 3. Example Mutations
+
+#### Ingest Credit History
+```graphql
+mutation IngestCreditHistory {
+  ingestCreditHistory(
+    providerId: "provider_1"
+    companyId: "ext_company_123"
+    enrichShopify: true
+    records: [
+      {
+        companyId: "ext_company_123"
+        email: "finance@acmecorp.com"
+        date: "2025-01-15T10:30:00Z"
+        reference: "Invoice payment - INV-2025-001"
+        inflow: 50000.00
+        outflow: 0.00
+        accountName: "Acme Corporation Ltd"
+        accountNumber: "****1234"
+        bank: "First National Bank"
+        currency: "USD"
+      }
+    ]
+  ) {
+    success
+    recordsProcessed
+    recordsEnriched
+    shopifyCompaniesCreated
+    errors
+  }
+}
+```
+
+#### Trigger Provider Sync
+```graphql
+mutation TriggerSync {
+  triggerProviderSync(
+    providerId: "provider_1"
+    companyId: "ext_company_123"
+    startDate: "2025-01-01T00:00:00Z"
+  ) {
+    success
+    recordsProcessed
+    recordsEnriched
+    shopifyCompaniesCreated
+    errors
+  }
+}
+```
+
+## Architecture
+
+```
+┌──────────────────────┐
+│  External Provider   │
+│   GraphQL API        │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Data Provider       │
+│  Connector           │
+│  (Extract & Transform)
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Shopify Company     │
+│  Registry            │
+│  (Map/Create)        │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Credit History      │
+│  RAG Loader          │
+│  (LangChain Docs)    │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Analytics RAG       │
+│  Pipeline            │
+│  (Groq LLM)          │
+└──────────────────────┘
+```
+
+## Components
+
+### 1. GraphQL Schema (`credit_history_schema.py`)
+- Strawberry GraphQL types and schema
+- Queries: `creditHistory`, `companyCreditSummary`
+- Mutations: `ingestCreditHistory`, `triggerProviderSync`
+
+### 2. Data Provider Connector (`data_provider_connector.py`)
+- Abstract connector framework
+- Generic GraphQL provider implementation
+- Provider registry for multi-source support
+
+### 3. Shopify Company Registry (`shopify_company_registry.py`)
+- External ID → Shopify B2B company ID mapping
+- Auto-creation of missing companies
+- Database caching with 1-hour TTL
+
+### 4. RAG Loader (`credit_history_rag_loader.py`)
+- PostgreSQL storage with deduplication
+- LangChain document creation
+- Credit history analytics summaries
+
+### 5. GraphQL Resolvers (`credit_history_resolvers.py`)
+- Query and mutation resolvers
+- ETL pipeline orchestration
+- Error handling and validation
+
+## Database Schema
+
+### Tables
+
+**company_id_mappings**
+- Maps external company IDs to Shopify B2B company GIDs
+- Prevents duplicate company creation
+
+**credit_history**
+- Stores all credit transactions
+- Indexed by company, date, provider
+- JSONB metadata for provider-specific fields
+
+**data_provider_configs**
+- Registry of configured data providers
+- Encrypted API keys
+- Active/inactive status
+
+### Views
+
+**credit_history_summary**
+- Aggregated metrics by company and currency
+- Total inflow, outflow, net position
+- Transaction counts and date ranges
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/graphql/credit-history` | POST | GraphQL API endpoint |
+| `/graphql/credit-history` | GET | GraphiQL IDE |
+
+## Security
+
+🔒 **Data Protection**
+- TLS 1.2+ for all API connections
+- Encrypted API keys in database
+- Field-level encryption for account numbers
+- Audit logs for data access
+
+🔐 **Authentication**
+- API key authentication for data providers
+- OAuth client credentials support
+- Session-based auth for GraphiQL
+
+## Environment Variables
+
+```bash
+# Database
+DATABASE_URL=postgresql://user:pass@host:5432/db
+
+# Shopify
+SHOPIFY_ADMIN_API_KEY=your_admin_api_key
+SHOPIFY_SHOP_NAME=your-shop.myshopify.com
+
+# Data Provider (example)
+PROVIDER_API_URL=https://provider.example.com/graphql
+PROVIDER_API_KEY=your_provider_api_key
+```
+
+## Next Steps
+
+1. **Register Data Provider**
+   ```python
+   from sdk.python.data_provider_connector import DataProviderRegistry
+   
+   registry = DataProviderRegistry()
+   registry.register_provider(
+       provider_id="my_provider",
+       api_url="https://provider.example.com/graphql",
+       api_key="your_api_key"
+   )
+   ```
+
+2. **Query Credit History via GraphQL**
+   - Use GraphiQL IDE or POST to `/graphql/credit-history`
+
+3. **Integrate with Analytics Agent**
+   - Credit history automatically available in RAG pipeline
+   - Query via analytics_agent for AI-powered insights
+
+## Troubleshooting
+
+**Issue**: GraphQL queries return empty results  
+**Solution**: Check that records have been ingested and `shopify_company_id` is enriched
+
+**Issue**: Company auto-creation fails  
+**Solution**: Verify Shopify Admin API credentials and `write_companies` scope
+
+**Issue**: Provider sync fails  
+**Solution**: Validate provider GraphQL schema matches expected structure
+
+## Support
+
+For issues or questions:
+1. Check GraphiQL IDE error messages
+2. Review database logs in PostgreSQL
+3. Verify provider API connectivity
+4. Ensure Shopify B2B company exists
+
+---
+
+Built with ❤️ using Strawberry GraphQL, LangChain, and FastAPI

huntrecht_sdk-0.1.0/README.md

@@ -0,0 +1,279 @@
+# GraphQL Data Connect SDK - Python Implementation
+
+Complete GraphQL server for ingesting customer credit history from external data providers and feeding it to the RAG pipeline with automatic Shopify B2B company mapping.
+
+## Features
+
+✅ **GraphQL Server** with Strawberry GraphQL  
+✅ **Data Provider Connectors** for external GraphQL APIs  
+✅ **Shopify B2B Company Registry** with auto-creation  
+✅ **RAG Pipeline Integration** with LangChain documents  
+✅ **PostgreSQL Storage** with optimized indexes  
+✅ **Credit History Analytics** with aggregated views  
+✅ **Multi-Provider Support** with connector framework  
+
+## Quick Start
+
+### 1. Access GraphiQL IDE
+
+Navigate to http://localhost:5000/graphql/credit-history in your browser to access the interactive GraphQL playground.
+
+### 2. Example Queries
+
+#### Fetch Credit History
+```graphql
+query GetCreditHistory {
+  creditHistory(
+    companyId: "ext_company_123"
+    startDate: "2025-01-01T00:00:00Z"
+    limit: 50
+  ) {
+    totalCount
+    edges {
+      node {
+        id
+        companyId
+        shopifyCompanyId
+        email
+        date
+        inflow
+        outflow
+        reference
+        bank
+        currency
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+#### Get Company Summary
+```graphql
+query GetCompanySummary {
+  companyCreditSummary(
+    shopifyCompanyId: "gid://shopify/Company/12345"
+  )
+}
+```
+
+### 3. Example Mutations
+
+#### Ingest Credit History
+```graphql
+mutation IngestCreditHistory {
+  ingestCreditHistory(
+    providerId: "provider_1"
+    companyId: "ext_company_123"
+    enrichShopify: true
+    records: [
+      {
+        companyId: "ext_company_123"
+        email: "finance@acmecorp.com"
+        date: "2025-01-15T10:30:00Z"
+        reference: "Invoice payment - INV-2025-001"
+        inflow: 50000.00
+        outflow: 0.00
+        accountName: "Acme Corporation Ltd"
+        accountNumber: "****1234"
+        bank: "First National Bank"
+        currency: "USD"
+      }
+    ]
+  ) {
+    success
+    recordsProcessed
+    recordsEnriched
+    shopifyCompaniesCreated
+    errors
+  }
+}
+```
+
+#### Trigger Provider Sync
+```graphql
+mutation TriggerSync {
+  triggerProviderSync(
+    providerId: "provider_1"
+    companyId: "ext_company_123"
+    startDate: "2025-01-01T00:00:00Z"
+  ) {
+    success
+    recordsProcessed
+    recordsEnriched
+    shopifyCompaniesCreated
+    errors
+  }
+}
+```
+
+## Architecture
+
+```
+┌──────────────────────┐
+│  External Provider   │
+│   GraphQL API        │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Data Provider       │
+│  Connector           │
+│  (Extract & Transform)
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Shopify Company     │
+│  Registry            │
+│  (Map/Create)        │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Credit History      │
+│  RAG Loader          │
+│  (LangChain Docs)    │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Analytics RAG       │
+│  Pipeline            │
+│  (Groq LLM)          │
+└──────────────────────┘
+```
+
+## Components
+
+### 1. GraphQL Schema (`credit_history_schema.py`)
+- Strawberry GraphQL types and schema
+- Queries: `creditHistory`, `companyCreditSummary`
+- Mutations: `ingestCreditHistory`, `triggerProviderSync`
+
+### 2. Data Provider Connector (`data_provider_connector.py`)
+- Abstract connector framework
+- Generic GraphQL provider implementation
+- Provider registry for multi-source support
+
+### 3. Shopify Company Registry (`shopify_company_registry.py`)
+- External ID → Shopify B2B company ID mapping
+- Auto-creation of missing companies
+- Database caching with 1-hour TTL
+
+### 4. RAG Loader (`credit_history_rag_loader.py`)
+- PostgreSQL storage with deduplication
+- LangChain document creation
+- Credit history analytics summaries
+
+### 5. GraphQL Resolvers (`credit_history_resolvers.py`)
+- Query and mutation resolvers
+- ETL pipeline orchestration
+- Error handling and validation
+
+## Database Schema
+
+### Tables
+
+**company_id_mappings**
+- Maps external company IDs to Shopify B2B company GIDs
+- Prevents duplicate company creation
+
+**credit_history**
+- Stores all credit transactions
+- Indexed by company, date, provider
+- JSONB metadata for provider-specific fields
+
+**data_provider_configs**
+- Registry of configured data providers
+- Encrypted API keys
+- Active/inactive status
+
+### Views
+
+**credit_history_summary**
+- Aggregated metrics by company and currency
+- Total inflow, outflow, net position
+- Transaction counts and date ranges
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/graphql/credit-history` | POST | GraphQL API endpoint |
+| `/graphql/credit-history` | GET | GraphiQL IDE |
+
+## Security
+
+🔒 **Data Protection**
+- TLS 1.2+ for all API connections
+- Encrypted API keys in database
+- Field-level encryption for account numbers
+- Audit logs for data access
+
+🔐 **Authentication**
+- API key authentication for data providers
+- OAuth client credentials support
+- Session-based auth for GraphiQL
+
+## Environment Variables
+
+```bash
+# Database
+DATABASE_URL=postgresql://user:pass@host:5432/db
+
+# Shopify
+SHOPIFY_ADMIN_API_KEY=your_admin_api_key
+SHOPIFY_SHOP_NAME=your-shop.myshopify.com
+
+# Data Provider (example)
+PROVIDER_API_URL=https://provider.example.com/graphql
+PROVIDER_API_KEY=your_provider_api_key
+```
+
+## Next Steps
+
+1. **Register Data Provider**
+   ```python
+   from sdk.python.data_provider_connector import DataProviderRegistry
+   
+   registry = DataProviderRegistry()
+   registry.register_provider(
+       provider_id="my_provider",
+       api_url="https://provider.example.com/graphql",
+       api_key="your_api_key"
+   )
+   ```
+
+2. **Query Credit History via GraphQL**
+   - Use GraphiQL IDE or POST to `/graphql/credit-history`
+
+3. **Integrate with Analytics Agent**
+   - Credit history automatically available in RAG pipeline
+   - Query via analytics_agent for AI-powered insights
+
+## Troubleshooting
+
+**Issue**: GraphQL queries return empty results  
+**Solution**: Check that records have been ingested and `shopify_company_id` is enriched
+
+**Issue**: Company auto-creation fails  
+**Solution**: Verify Shopify Admin API credentials and `write_companies` scope
+
+**Issue**: Provider sync fails  
+**Solution**: Validate provider GraphQL schema matches expected structure
+
+## Support
+
+For issues or questions:
+1. Check GraphiQL IDE error messages
+2. Review database logs in PostgreSQL
+3. Verify provider API connectivity
+4. Ensure Shopify B2B company exists
+
+---
+
+Built with ❤️ using Strawberry GraphQL, LangChain, and FastAPI

huntrecht_sdk-0.1.0/huntrecht/__init__.py

@@ -0,0 +1,96 @@
+"""
+Huntrecht Platform SDK for Python
+
+Official Python client for the Huntrecht Platform API v1.
+Provides typed access to authentication, orders, subscriptions,
+credit risk, KYC, quotes, storefront, and payments.
+
+Usage:
+    from huntrecht import HuntrechtClient
+
+    client = HuntrechtClient(
+        base_url="https://api.huntrecht.com",
+        client_id="hnt_your_client_id",
+        client_secret="your_secret"
+    )
+
+    # Authenticate
+    tokens = client.auth.token()
+    print(f"Access token expires in {tokens.expires_in}s")
+
+    # List orders
+    orders = client.orders.list()
+    for order in orders.data:
+        print(f"Order {order.id}: {order.commodity}")
+"""
+
+from huntrecht.client import HuntrechtClient
+from huntrecht.exceptions import (
+    HuntrechtError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    PermissionError,
+)
+from huntrecht.types_ import (
+    TokenResponse,
+    ApiClientResponse,
+    ApiClientWithSecret,
+    UserProfile,
+    Order,
+    OrderListResponse,
+    Payment,
+    PaymentListResponse,
+    Subscription,
+    SubscriptionListResponse,
+    CreditScoreData,
+    CreditAssessmentData,
+    KycSubmission,
+    KycListResponse,
+    CommodityQuote,
+    QuoteListResponse,
+    CollectionResponse,
+    ProductResponse,
+    PriceDropEvent,
+    PriceDropListResponse,
+    PaymentEligibilityResponse,
+    LinkedWallet,
+    LinkedBank,
+    LinkedAccountsResponse,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "HuntrechtClient",
+    "HuntrechtError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "PermissionError",
+    "TokenResponse",
+    "ApiClientResponse",
+    "ApiClientWithSecret",
+    "UserProfile",
+    "Order",
+    "OrderListResponse",
+    "Payment",
+    "PaymentListResponse",
+    "Subscription",
+    "SubscriptionListResponse",
+    "CreditScoreData",
+    "CreditAssessmentData",
+    "KycSubmission",
+    "KycListResponse",
+    "CommodityQuote",
+    "QuoteListResponse",
+    "CollectionResponse",
+    "ProductResponse",
+    "PriceDropEvent",
+    "PriceDropListResponse",
+    "PaymentEligibilityResponse",
+    "LinkedWallet",
+    "LinkedBank",
+    "LinkedAccountsResponse",
+]