paymenthub 0.1.0__py3-none-any.whl

paymenthub/__init__.py

@@ -0,0 +1,32 @@
+"""PaymentHub Python SDK — typed client + webhook verification."""
+
+from ._models import (
+    PaymentCreate,
+    PaymentDetailResponse,
+    PaymentResponse,
+    SandboxSeedResponse,
+)
+from .client import DEFAULT_BASE_URL, PaymentHubClient, PaymentHubError
+from .webhook import (
+    WebhookProvider,
+    verify_paymob_hmac,
+    verify_stripe_signature,
+    verify_webhook,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "PaymentCreate",
+    "PaymentDetailResponse",
+    "PaymentHubClient",
+    "PaymentHubError",
+    "PaymentResponse",
+    "SandboxSeedResponse",
+    "WebhookProvider",
+    "__version__",
+    "verify_paymob_hmac",
+    "verify_stripe_signature",
+    "verify_webhook",
+]

paymenthub/_models.py

@@ -0,0 +1,678 @@
+# generated by datamodel-codegen:
+#   filename:  openapi.json
+#   timestamp: 2026-06-06T11:49:38+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import AwareDatetime, BaseModel, EmailStr, Field, conint, constr
+
+
+class AccountDeleteResponse(BaseModel):
+    closed_at: AwareDatetime = Field(..., title='Closed At')
+    merchant_id: str = Field(..., title='Merchant Id')
+    status: Literal['closed'] = Field(..., title='Status')
+
+
+class Env(Enum):
+    test = 'test'
+    live = 'live'
+
+
+class Scope(Enum):
+    payments_read = 'payments:read'
+    payments_write = 'payments:write'
+    refunds_write = 'refunds:write'
+    webhooks_read = 'webhooks:read'
+    disputes_read = 'disputes:read'
+    disputes_write = 'disputes:write'
+    settings_read = 'settings:read'
+    all = 'all'
+
+
+class ApiKeyCreateRequest(BaseModel):
+    allowed_ips: list[str] | None = Field(None, title='Allowed Ips')
+    env: Env | None = Field('test', title='Env')
+    label: constr(min_length=1, max_length=120) = Field(..., title='Label')
+    scopes: list[Scope] | None = Field(None, title='Scopes')
+
+
+class ApiKeySummary(BaseModel):
+    allowed_ips: list[str] | None = Field(..., title='Allowed Ips')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    env: Env = Field(..., title='Env')
+    id: str = Field(..., title='Id')
+    label: str = Field(..., title='Label')
+    last_used_at: AwareDatetime | None = Field(..., title='Last Used At')
+    prefix: str = Field(..., title='Prefix')
+    scopes: list[str] = Field(..., title='Scopes')
+
+
+class ApiKeyUpdateRequest(BaseModel):
+    allowed_ips: list[str] | None = Field(None, title='Allowed Ips')
+    scopes: list[Scope] | None = Field(None, title='Scopes')
+
+
+class ApiKeyWithSecret(BaseModel):
+    allowed_ips: list[str] | None = Field(..., title='Allowed Ips')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    env: Env = Field(..., title='Env')
+    id: str = Field(..., title='Id')
+    label: str = Field(..., title='Label')
+    prefix: str = Field(..., title='Prefix')
+    scopes: list[str] = Field(..., title='Scopes')
+    secret: str = Field(..., title='Secret')
+
+
+class ActorType(Enum):
+    api_key = 'api_key'
+    dashboard_session = 'dashboard_session'
+    system = 'system'
+
+
+class AuditLogResponse(BaseModel):
+    action: str = Field(..., title='Action')
+    actor_id: str | None = Field(..., title='Actor Id')
+    actor_type: ActorType = Field(..., title='Actor Type')
+    after: dict[str, Any] | None = Field(..., title='After')
+    before: dict[str, Any] | None = Field(..., title='Before')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    id: str = Field(..., title='Id')
+    ip: str | None = Field(..., title='Ip')
+    request_id: str | None = Field(..., title='Request Id')
+    target_id: str | None = Field(..., title='Target Id')
+    target_type: str | None = Field(..., title='Target Type')
+    user_agent: str | None = Field(..., title='User Agent')
+
+
+class Status(Enum):
+    pending = 'pending'
+    running = 'running'
+    ready = 'ready'
+    failed = 'failed'
+
+
+class DataExportResponse(BaseModel):
+    byte_size: int | None = Field(None, title='Byte Size')
+    completed_at: AwareDatetime | None = Field(None, title='Completed At')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    error: str | None = Field(None, title='Error')
+    expires_at: AwareDatetime | None = Field(None, title='Expires At')
+    id: str = Field(..., title='Id')
+    status: Status = Field(..., title='Status')
+
+
+class Provider(Enum):
+    stripe = 'stripe'
+    paymob = 'paymob'
+    fawry = 'fawry'
+
+
+class Status1(Enum):
+    open = 'open'
+    resolved = 'resolved'
+    noted = 'noted'
+
+
+class Type(Enum):
+    missing_in_db = 'missing_in_db'
+    missing_in_settlement = 'missing_in_settlement'
+    amount_mismatch = 'amount_mismatch'
+    under_dispute = 'under_dispute'
+
+
+class DiscrepancyResponse(BaseModel):
+    created_at: AwareDatetime = Field(..., title='Created At')
+    currency: str | None = Field(..., title='Currency')
+    delta_amount_minor: int | None = Field(..., title='Delta Amount Minor')
+    id: str = Field(..., title='Id')
+    payment_id: str | None = Field(..., title='Payment Id')
+    provider: Provider = Field(..., title='Provider')
+    resolution_note: str | None = Field(..., title='Resolution Note')
+    resolved_at: AwareDatetime | None = Field(..., title='Resolved At')
+    run_id: str = Field(..., title='Run Id')
+    settlement_line_id: str | None = Field(..., title='Settlement Line Id')
+    status: Status1 = Field(..., title='Status')
+    type: Type = Field(..., title='Type')
+
+
+class DisputeEvidenceRequest(BaseModel):
+    customer_communication: str | None = Field(None, title='Customer Communication')
+    extra: dict[str, Any] | None = Field(None, title='Extra')
+    receipt: str | None = Field(None, title='Receipt')
+    refund_policy: str | None = Field(None, title='Refund Policy')
+    refund_refusal_explanation: str | None = Field(
+        None, title='Refund Refusal Explanation'
+    )
+    service_documentation: str | None = Field(None, title='Service Documentation')
+    shipping_documentation: str | None = Field(None, title='Shipping Documentation')
+    uncategorized_text: str | None = Field(None, title='Uncategorized Text')
+
+
+class Reason(Enum):
+    fraudulent = 'fraudulent'
+    duplicate = 'duplicate'
+    product_not_received = 'product_not_received'
+    product_unacceptable = 'product_unacceptable'
+    subscription_canceled = 'subscription_canceled'
+    credit_not_processed = 'credit_not_processed'
+    general = 'general'
+    other = 'other'
+
+
+class Status2(Enum):
+    needs_response = 'needs_response'
+    under_review = 'under_review'
+    won = 'won'
+    lost = 'lost'
+    accepted = 'accepted'
+    charge_refunded = 'charge_refunded'
+
+
+class DisputeResponse(BaseModel):
+    amount_minor: int = Field(..., title='Amount Minor')
+    currency: str = Field(..., title='Currency')
+    evidence_due_by: AwareDatetime | None = Field(..., title='Evidence Due By')
+    id: str = Field(..., title='Id')
+    opened_at: AwareDatetime = Field(..., title='Opened At')
+    payment_id: str = Field(..., title='Payment Id')
+    provider: str = Field(..., title='Provider')
+    provider_dispute_id: str = Field(..., title='Provider Dispute Id')
+    reason: Reason | None = Field(..., title='Reason')
+    resolved_at: AwareDatetime | None = Field(..., title='Resolved At')
+    status: Status2 = Field(..., title='Status')
+
+
+class InviteAcceptRequest(BaseModel):
+    password: constr(min_length=8, max_length=128) = Field(..., title='Password')
+    token: constr(min_length=1, max_length=256) = Field(..., title='Token')
+
+
+class Role(Enum):
+    owner = 'owner'
+    admin = 'admin'
+    operator = 'operator'
+    viewer = 'viewer'
+
+
+class InviteCreateRequest(BaseModel):
+    email: EmailStr = Field(..., title='Email')
+    role: Role | None = Field('operator', title='Role')
+
+
+class LoginRequest(BaseModel):
+    email: EmailStr = Field(..., title='Email')
+    password: str = Field(..., title='Password')
+    totp_code: constr(max_length=32) | None = Field(None, title='Totp Code')
+
+
+class Status3(Enum):
+    pending = 'pending'
+    succeeded = 'succeeded'
+    failed = 'failed'
+
+
+class PaymentAttemptResponse(BaseModel):
+    created_at: AwareDatetime = Field(..., title='Created At')
+    error_code: str | None = Field(..., title='Error Code')
+    error_message: str | None = Field(..., title='Error Message')
+    failover_from: str | None = Field(None, title='Failover From')
+    id: str = Field(..., title='Id')
+    payment_id: str = Field(..., title='Payment Id')
+    provider: Provider = Field(..., title='Provider')
+    provider_payment_id: str | None = Field(..., title='Provider Payment Id')
+    status: Status3 = Field(..., title='Status')
+
+
+class PaymentCustomer(BaseModel):
+    email: EmailStr | None = Field(None, title='Email')
+    name: str | None = Field(None, title='Name')
+    phone: str | None = Field(None, title='Phone')
+
+
+class Status4(Enum):
+    pending = 'pending'
+    pending_unknown = 'pending_unknown'
+    requires_action = 'requires_action'
+    succeeded = 'succeeded'
+    failed = 'failed'
+    refunded = 'refunded'
+    partially_refunded = 'partially_refunded'
+    cancelled = 'cancelled'
+    disputed = 'disputed'
+
+
+class Status5(Enum):
+    pending = 'pending'
+    succeeded = 'succeeded'
+    failed = 'failed'
+
+
+class PaymentRefundSummary(BaseModel):
+    amount_minor: int = Field(..., title='Amount Minor')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    currency: str = Field(..., title='Currency')
+    id: str = Field(..., title='Id')
+    note: str | None = Field(..., title='Note')
+    payment_id: str = Field(..., title='Payment Id')
+    provider_refund_id: str | None = Field(..., title='Provider Refund Id')
+    reason: str | None = Field(..., title='Reason')
+    status: Status5 = Field(..., title='Status')
+
+
+class Status6(Enum):
+    pending = 'pending'
+    pending_unknown = 'pending_unknown'
+    requires_action = 'requires_action'
+    succeeded = 'succeeded'
+    failed = 'failed'
+    refunded = 'refunded'
+    partially_refunded = 'partially_refunded'
+    cancelled = 'cancelled'
+    disputed = 'disputed'
+
+
+class PaymentResponse(BaseModel):
+    amount_minor: int = Field(..., title='Amount Minor')
+    checkout_url: str | None = Field(..., title='Checkout Url')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    currency: str = Field(..., title='Currency')
+    customer: PaymentCustomer | None = None
+    description: str | None = Field(None, title='Description')
+    id: str = Field(..., title='Id')
+    merchant_id: str = Field(..., title='Merchant Id')
+    metadata: dict[str, str] | None = Field(None, title='Metadata')
+    provider: Provider = Field(..., title='Provider')
+    provider_payment_id: str | None = Field(None, title='Provider Payment Id')
+    refundable_minor: int | None = Field(0, title='Refundable Minor')
+    refunded_minor: int | None = Field(0, title='Refunded Minor')
+    status: Status6 = Field(..., title='Status')
+    updated_at: AwareDatetime = Field(..., title='Updated At')
+
+
+class PaymentWebhookDeliverySummary(BaseModel):
+    attempts: int = Field(..., title='Attempts')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    event_id: str = Field(..., title='Event Id')
+    event_type: str = Field(..., title='Event Type')
+    id: str = Field(..., title='Id')
+    last_latency_ms: int | None = Field(..., title='Last Latency Ms')
+    last_status_code: int | None = Field(..., title='Last Status Code')
+    max_attempts: int = Field(..., title='Max Attempts')
+    next_retry_at: AwareDatetime | None = Field(..., title='Next Retry At')
+    payment_id: str | None = Field(..., title='Payment Id')
+    signature: str | None = Field('', title='Signature')
+    status: str = Field(..., title='Status')
+    updated_at: AwareDatetime = Field(..., title='Updated At')
+    url: str = Field(..., title='Url')
+
+
+class ProfileResponse(BaseModel):
+    contact_email: str = Field(..., title='Contact Email')
+    contact_phone: str | None = Field(None, title='Contact Phone')
+    display_name: str = Field(..., title='Display Name')
+    merchant_id: str = Field(..., title='Merchant Id')
+    merchant_name: str = Field(..., title='Merchant Name')
+    timezone: str | None = Field('UTC', title='Timezone')
+    two_factor_enabled: bool | None = Field(False, title='Two Factor Enabled')
+
+
+class ProfileUpdateRequest(BaseModel):
+    contact_email: EmailStr | None = Field(None, title='Contact Email')
+    contact_phone: constr(max_length=32) | None = Field(None, title='Contact Phone')
+    display_name: constr(min_length=1, max_length=255) | None = Field(
+        None, title='Display Name'
+    )
+    timezone: constr(max_length=64) | None = Field(None, title='Timezone')
+
+
+class Status7(Enum):
+    running = 'running'
+    succeeded = 'succeeded'
+    failed = 'failed'
+
+
+class ReconciliationRunResponse(BaseModel):
+    discrepancies_open: int = Field(..., title='Discrepancies Open')
+    discrepancies_resolved: int = Field(..., title='Discrepancies Resolved')
+    finished_at: AwareDatetime | None = Field(..., title='Finished At')
+    id: str = Field(..., title='Id')
+    provider: Provider = Field(..., title='Provider')
+    records_matched: int = Field(..., title='Records Matched')
+    started_at: AwareDatetime = Field(..., title='Started At')
+    status: Status7 = Field(..., title='Status')
+
+
+class RefundCreate(BaseModel):
+    amount_minor: conint(ge=1) | None = Field(
+        None, description='Omit for full refund.', title='Amount Minor'
+    )
+    payment_id: str = Field(..., title='Payment Id')
+    reason: str | None = Field(None, title='Reason')
+
+
+class Status8(Enum):
+    pending = 'pending'
+    succeeded = 'succeeded'
+    failed = 'failed'
+
+
+class RefundResponse(BaseModel):
+    amount_minor: int = Field(..., title='Amount Minor')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    currency: str = Field(..., title='Currency')
+    id: str = Field(..., title='Id')
+    note: str | None = Field(None, title='Note')
+    payment_id: str = Field(..., title='Payment Id')
+    provider_refund_id: str | None = Field(None, title='Provider Refund Id')
+    reason: str | None = Field(..., title='Reason')
+    status: Status8 = Field(..., title='Status')
+    updated_at: AwareDatetime = Field(..., title='Updated At')
+
+
+class ResolveBody(BaseModel):
+    note: str | None = Field(None, title='Note')
+
+
+class RetryTickResponse(BaseModel):
+    due: int = Field(..., title='Due')
+    forwarded: int = Field(..., title='Forwarded')
+
+
+class RoleUpdateRequest(BaseModel):
+    role: Role = Field(..., title='Role')
+
+
+class SandboxSeedResponse(BaseModel):
+    api_key: str = Field(..., title='Api Key')
+    merchant_id: str = Field(..., title='Merchant Id')
+    sample_payment_ids: list[str] = Field(..., title='Sample Payment Ids')
+
+
+class SessionListEntry(BaseModel):
+    created_at: AwareDatetime = Field(..., title='Created At')
+    current: bool = Field(..., title='Current')
+    id: str = Field(..., title='Id')
+    ip: str | None = Field(..., title='Ip')
+    last_seen_at: AwareDatetime = Field(..., title='Last Seen At')
+    user_agent: str | None = Field(..., title='User Agent')
+
+
+class SessionListResponse(BaseModel):
+    data: list[SessionListEntry] = Field(..., title='Data')
+
+
+class SessionResponse(BaseModel):
+    access_token: str = Field(..., title='Access Token')
+    expires_in: int = Field(..., title='Expires In')
+    merchant_id: str = Field(..., title='Merchant Id')
+    merchant_name: str | None = Field(None, title='Merchant Name')
+    role: str | None = Field(None, title='Role')
+
+
+class SignupRequest(BaseModel):
+    email: EmailStr = Field(..., title='Email')
+    name: constr(min_length=1, max_length=255) = Field(
+        ..., description='Merchant / business name', title='Name'
+    )
+    password: constr(min_length=8, max_length=128) = Field(..., title='Password')
+
+
+class TeamInviteOut(BaseModel):
+    created_at: AwareDatetime = Field(..., title='Created At')
+    email: str = Field(..., title='Email')
+    expires_at: AwareDatetime = Field(..., title='Expires At')
+    id: str = Field(..., title='Id')
+    role: Role = Field(..., title='Role')
+
+
+class TeamMember(BaseModel):
+    created_at: AwareDatetime = Field(..., title='Created At')
+    disabled_at: AwareDatetime | None = Field(..., title='Disabled At')
+    email: str = Field(..., title='Email')
+    id: str = Field(..., title='Id')
+    last_seen_at: AwareDatetime | None = Field(..., title='Last Seen At')
+    role: Role = Field(..., title='Role')
+
+
+class Kind(Enum):
+    payment_created = 'payment.created'
+    payment_requires_action = 'payment.requires_action'
+    payment_succeeded = 'payment.succeeded'
+    payment_failed = 'payment.failed'
+    payment_refunded = 'payment.refunded'
+    webhook_delivered = 'webhook.delivered'
+    webhook_failed = 'webhook.failed'
+
+
+class Tone(Enum):
+    success = 'success'
+    warn = 'warn'
+    danger = 'danger'
+    info = 'info'
+    neutral = 'neutral'
+
+
+class TimelineEventResponse(BaseModel):
+    at: AwareDatetime = Field(..., title='At')
+    id: str = Field(..., title='Id')
+    kind: Kind = Field(..., title='Kind')
+    meta: str | None = Field(None, title='Meta')
+    title: str = Field(..., title='Title')
+    tone: Tone = Field(..., title='Tone')
+
+
+class TotpCodeRequest(BaseModel):
+    code: constr(min_length=1, max_length=32) = Field(
+        ..., description='TOTP or backup code', title='Code'
+    )
+
+
+class TotpEnrollResponse(BaseModel):
+    backup_codes: list[str] = Field(..., title='Backup Codes')
+    otpauth_uri: str = Field(..., title='Otpauth Uri')
+    qr_svg: str = Field(..., title='Qr Svg')
+    secret: str = Field(..., title='Secret')
+
+
+class ValidationError(BaseModel):
+    ctx: dict[str, Any] | None = Field(None, title='Context')
+    input: Any | None = Field(None, title='Input')
+    loc: list[str | int] = Field(..., title='Location')
+    msg: str = Field(..., title='Message')
+    type: str = Field(..., title='Error Type')
+
+
+class Status9(Enum):
+    pending = 'pending'
+    retrying = 'retrying'
+    delivered = 'delivered'
+    dead_letter = 'dead_letter'
+
+
+class WebhookDeliveryResponse(BaseModel):
+    attempts: int = Field(..., title='Attempts')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    delivered_at: AwareDatetime | None = Field(..., title='Delivered At')
+    event_id: str = Field(..., title='Event Id')
+    event_type: str = Field(..., title='Event Type')
+    id: str = Field(..., title='Id')
+    last_error: str | None = Field(..., title='Last Error')
+    last_latency_ms: int | None = Field(..., title='Last Latency Ms')
+    last_status_code: int | None = Field(..., title='Last Status Code')
+    max_attempts: int = Field(..., title='Max Attempts')
+    next_retry_at: AwareDatetime | None = Field(..., title='Next Retry At')
+    payment_id: str | None = Field(..., title='Payment Id')
+    signature: str | None = Field(..., title='Signature')
+    status: Status9 = Field(..., title='Status')
+    updated_at: AwareDatetime = Field(..., title='Updated At')
+    url: str = Field(..., title='Url')
+
+
+class Status11(Enum):
+    delivered = 'delivered'
+    failed = 'failed'
+    scheduled = 'scheduled'
+
+
+class WebhookDeliveryRetryEntry(BaseModel):
+    at: AwareDatetime = Field(..., title='At')
+    attempt: int = Field(..., title='Attempt')
+    error: str | None = Field(None, title='Error')
+    latency_ms: int | None = Field(None, title='Latency Ms')
+    status: Status11 = Field(..., title='Status')
+    status_code: int | None = Field(None, title='Status Code')
+
+
+class WebhookSecretRotateResponse(BaseModel):
+    previous_secret_revoked_at: AwareDatetime = Field(
+        ..., title='Previous Secret Revoked At'
+    )
+    secret: str = Field(..., title='Secret')
+
+
+class LastTestStatus(Enum):
+    succeeded = 'succeeded'
+    failed = 'failed'
+
+
+class SubscribedEvent(Enum):
+    payment_succeeded = 'payment.succeeded'
+    payment_failed = 'payment.failed'
+    payment_refunded = 'payment.refunded'
+    refund_succeeded = 'refund.succeeded'
+    refund_failed = 'refund.failed'
+    dispute_created = 'dispute.created'
+    dispute_updated = 'dispute.updated'
+    dispute_closed = 'dispute.closed'
+
+
+class WebhookSettingsResponse(BaseModel):
+    endpoint_url: str | None = Field(..., title='Endpoint Url')
+    last_test_at: AwareDatetime | None = Field(None, title='Last Test At')
+    last_test_status: LastTestStatus | None = Field(None, title='Last Test Status')
+    secret_preview: str | None = Field(..., title='Secret Preview')
+    subscribed_events: list[SubscribedEvent] = Field(..., title='Subscribed Events')
+
+
+class WebhookSettingsUpdateRequest(BaseModel):
+    endpoint_url: constr(max_length=2048) | None = Field(None, title='Endpoint Url')
+    subscribed_events: list[SubscribedEvent] | None = Field(
+        None, title='Subscribed Events'
+    )
+
+
+class WebhookTestResponse(BaseModel):
+    error: str | None = Field(None, title='Error')
+    latency_ms: int | None = Field(None, title='Latency Ms')
+    ok: bool = Field(..., title='Ok')
+    status_code: int | None = Field(None, title='Status Code')
+
+
+class ApiKeyListResponse(BaseModel):
+    data: list[ApiKeySummary] = Field(..., title='Data')
+
+
+class AuditLogListResponse(BaseModel):
+    data: list[AuditLogResponse] = Field(..., title='Data')
+    next_cursor: str | None = Field(..., title='Next Cursor')
+
+
+class DiscrepancyListResponse(BaseModel):
+    data: list[DiscrepancyResponse] = Field(..., title='Data')
+    next_cursor: str | None = Field(..., title='Next Cursor')
+
+
+class DisputeListResponse(BaseModel):
+    data: list[DisputeResponse] = Field(..., title='Data')
+    next_cursor: str | None = Field(..., title='Next Cursor')
+
+
+class HTTPValidationError(BaseModel):
+    detail: list[ValidationError] | None = Field(None, title='Detail')
+
+
+class PaymentCreate(BaseModel):
+    amount_minor: conint(ge=1) = Field(
+        ..., description='Amount in minor units (cents/piasters).', title='Amount Minor'
+    )
+    bin_hint: constr(pattern=r'^\d+$', min_length=6, max_length=8) | None = Field(
+        None,
+        description='First 6-8 digits of the card BIN, used for routing.',
+        title='Bin Hint',
+    )
+    cancel_url: str = Field(..., title='Cancel Url')
+    currency: constr(min_length=3, max_length=3) = Field(..., title='Currency')
+    customer: PaymentCustomer | None = None
+    description: str | None = Field(None, title='Description')
+    metadata: dict[str, str] | None = Field(None, title='Metadata')
+    success_url: str = Field(..., title='Success Url')
+
+
+class PaymentDetailResponse(BaseModel):
+    amount_minor: int = Field(..., title='Amount Minor')
+    attempts: list[PaymentAttemptResponse] | None = Field(None, title='Attempts')
+    checkout_url: str | None = Field(..., title='Checkout Url')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    currency: str = Field(..., title='Currency')
+    customer: PaymentCustomer | None = None
+    description: str | None = Field(None, title='Description')
+    id: str = Field(..., title='Id')
+    merchant_id: str = Field(..., title='Merchant Id')
+    metadata: dict[str, str] | None = Field(None, title='Metadata')
+    provider: Provider = Field(..., title='Provider')
+    provider_payment_id: str | None = Field(None, title='Provider Payment Id')
+    raw_provider_response: dict[str, Any] | None = Field(
+        None, title='Raw Provider Response'
+    )
+    refundable_minor: int | None = Field(0, title='Refundable Minor')
+    refunded_minor: int | None = Field(0, title='Refunded Minor')
+    refunds: list[PaymentRefundSummary] | None = Field(None, title='Refunds')
+    status: Status4 = Field(..., title='Status')
+    timeline: list[TimelineEventResponse] | None = Field(None, title='Timeline')
+    updated_at: AwareDatetime = Field(..., title='Updated At')
+    webhook_deliveries: list[PaymentWebhookDeliverySummary] | None = Field(
+        None, title='Webhook Deliveries'
+    )
+
+
+class PaymentListResponse(BaseModel):
+    data: list[PaymentResponse] = Field(..., title='Data')
+    next_cursor: str | None = Field(..., title='Next Cursor')
+
+
+class ReconciliationRunListResponse(BaseModel):
+    data: list[ReconciliationRunResponse] = Field(..., title='Data')
+
+
+class TeamListResponse(BaseModel):
+    invites: list[TeamInviteOut] = Field(..., title='Invites')
+    members: list[TeamMember] = Field(..., title='Members')
+
+
+class WebhookDeliveryDetailResponse(BaseModel):
+    attempts: int = Field(..., title='Attempts')
+    created_at: AwareDatetime = Field(..., title='Created At')
+    delivered_at: AwareDatetime | None = Field(..., title='Delivered At')
+    event_id: str = Field(..., title='Event Id')
+    event_type: str = Field(..., title='Event Type')
+    id: str = Field(..., title='Id')
+    last_error: str | None = Field(..., title='Last Error')
+    last_latency_ms: int | None = Field(..., title='Last Latency Ms')
+    last_status_code: int | None = Field(..., title='Last Status Code')
+    max_attempts: int = Field(..., title='Max Attempts')
+    next_retry_at: AwareDatetime | None = Field(..., title='Next Retry At')
+    payload: dict[str, Any] | None = Field(..., title='Payload')
+    payment_id: str | None = Field(..., title='Payment Id')
+    retry_history: list[WebhookDeliveryRetryEntry] = Field(..., title='Retry History')
+    signature: str | None = Field(..., title='Signature')
+    status: Status9 = Field(..., title='Status')
+    updated_at: AwareDatetime = Field(..., title='Updated At')
+    url: str = Field(..., title='Url')
+
+
+class WebhookDeliveryListResponse(BaseModel):
+    data: list[WebhookDeliveryResponse] = Field(..., title='Data')
+    next_cursor: str | None = Field(..., title='Next Cursor')

paymenthub/client.py

@@ -0,0 +1,89 @@
+"""Typed PaymentHub client (httpx)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._models import (
+    PaymentCreate,
+    PaymentDetailResponse,
+    PaymentResponse,
+    SandboxSeedResponse,
+)
+
+#: The hosted production gateway. Override via ``base_url`` for local/staging.
+DEFAULT_BASE_URL = "https://paymenthub-be.onrender.com"
+
+
+class PaymentHubError(Exception):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, message: str, status_code: int, detail: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class PaymentHubClient:
+    """A typed PaymentHub client.
+
+    Use as a context manager (``with PaymentHubClient(key) as ph: ...``) or call
+    :meth:`close` when done. Pass ``http_client`` to inject a custom/mocked
+    ``httpx.Client`` (e.g. in tests).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._client = http_client or httpx.Client(base_url=base_url, timeout=timeout)
+        self._owns_client = http_client is None
+        self._headers = {"Authorization": f"Bearer {api_key}"}
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        resp = self._client.request(method, path, headers=self._headers, **kwargs)
+        if resp.status_code >= 400:
+            detail: Any
+            try:
+                detail = resp.json()
+            except Exception:
+                detail = resp.text
+            raise PaymentHubError(
+                f"{method} {path} -> {resp.status_code}", resp.status_code, detail
+            )
+        return resp.json()
+
+    def seed_sandbox(self) -> SandboxSeedResponse:
+        """Bootstrap a sandbox dataset (test-mode keys only)."""
+        return SandboxSeedResponse.model_validate(self._request("POST", "/v1/sandbox/seed"))
+
+    def create_payment(self, payment: PaymentCreate | dict[str, Any]) -> PaymentResponse:
+        """Create a payment."""
+        body = (
+            payment.model_dump(exclude_none=True, mode="json")
+            if isinstance(payment, PaymentCreate)
+            else payment
+        )
+        return PaymentResponse.model_validate(self._request("POST", "/v1/payments", json=body))
+
+    def get_payment(self, payment_id: str) -> PaymentDetailResponse:
+        """Fetch a single payment (with attempts / refunds / timeline)."""
+        return PaymentDetailResponse.model_validate(
+            self._request("GET", f"/v1/payments/{payment_id}")
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> PaymentHubClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

paymenthub/webhook.py

@@ -0,0 +1,83 @@
+"""Webhook signature verification.
+
+Webhooks are verified server-side (you hold the signing secret). Two schemes:
+  - Stripe-style: a ``t=<unix>,v1=<hex>`` header; HMAC-SHA256 over ``f"{t}.{body}"``.
+  - Paymob-style: a raw HMAC-SHA256 hex digest over the raw request body.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from collections.abc import Callable
+from typing import Literal
+
+WebhookProvider = Literal["stripe", "paymob"]
+
+
+def _to_body(payload: str | bytes) -> str:
+    return payload.decode("utf-8") if isinstance(payload, bytes) else payload
+
+
+def verify_stripe_signature(
+    payload: str | bytes,
+    header: str,
+    secret: str,
+    *,
+    tolerance_seconds: int = 300,
+    now: Callable[[], int] | None = None,
+) -> bool:
+    """Verify a Stripe-style ``t=<unix>,v1=<hex>`` signature header.
+
+    Recomputes HMAC-SHA256 over ``f"{t}.{body}"`` and (optionally) enforces a
+    timestamp tolerance to blunt replay. Set ``tolerance_seconds=0`` to skip the
+    timestamp check.
+    """
+    fields: dict[str, str] = {}
+    for part in header.split(","):
+        key, sep, value = part.partition("=")
+        if sep:
+            fields[key.strip()] = value.strip()
+    t = fields.get("t")
+    v1 = fields.get("v1")
+    if not t or not v1:
+        return False
+
+    expected = hmac.new(
+        secret.encode(), f"{t}.{_to_body(payload)}".encode(), hashlib.sha256
+    ).hexdigest()
+    if not hmac.compare_digest(expected, v1):
+        return False
+
+    if tolerance_seconds > 0:
+        current = now() if now is not None else int(time.time())
+        try:
+            if abs(current - int(t)) > tolerance_seconds:
+                return False
+        except ValueError:
+            return False
+    return True
+
+
+def verify_paymob_hmac(payload: str | bytes, signature_hex: str, secret: str) -> bool:
+    """Verify a raw HMAC-SHA256 hex signature (Paymob-style) over the raw body."""
+    expected = hmac.new(secret.encode(), _to_body(payload).encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature_hex.strip().lower())
+
+
+def verify_webhook(
+    *,
+    provider: WebhookProvider,
+    payload: str | bytes,
+    signature: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+) -> bool:
+    """Provider-agnostic webhook verification. ``True`` iff the signature is
+    valid for the given raw body + secret."""
+    if provider == "stripe":
+        return verify_stripe_signature(
+            payload, signature, secret, tolerance_seconds=tolerance_seconds
+        )
+    return verify_paymob_hmac(payload, signature, secret)

paymenthub-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: paymenthub
+Version: 0.1.0
+Summary: Typed Python client + webhook verification for the PaymentHub API.
+Project-URL: Repository, https://github.com/ahmeddmohamed-noon/paymenthub-sdk-python
+Author: PaymentHub
+License-Expression: MIT
+Keywords: paymenthub,payments,paymob,sdk,stripe
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic[email]>=2.7
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.26; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# paymenthub (Python SDK)
+
+Typed Python client + webhook verification for the [PaymentHub](https://github.com/ahmeddmohamed-noon/paymenthub-be) API. Models are generated from PaymentHub's published OpenAPI spec with `datamodel-code-generator`, so responses are validated pydantic models.
+
+> Sandbox-only portfolio project.
+
+## Install
+
+```bash
+pip install paymenthub
+```
+
+## Quickstart
+
+```python
+from paymenthub import PaymentHubClient, PaymentCreate
+
+with PaymentHubClient(api_key="sk_test_…") as ph:
+    # One-call sandbox bootstrap (test-mode keys only):
+    demo = ph.seed_sandbox()  # -> SandboxSeedResponse(api_key, merchant_id, sample_payment_ids)
+
+    payment = ph.create_payment(PaymentCreate(
+        amount_minor=1500,
+        currency="USD",
+        success_url="https://example.com/success",
+        cancel_url="https://example.com/cancel",
+    ))
+    print(payment.checkout_url)
+
+    detail = ph.get_payment(payment.id)
+```
+
+`PaymentHubClient` defaults to the hosted gateway; pass `base_url=` to point elsewhere, or `http_client=` to inject a custom/mocked `httpx.Client`.
+
+## Webhook verification
+
+Verify the **raw** request body server-side (don't re-serialize):
+
+```python
+from paymenthub import verify_webhook
+
+ok = verify_webhook(
+    provider="stripe",        # or "paymob"
+    payload=raw_body,         # str | bytes
+    signature=request.headers["x-paymenthub-signature"],
+    secret=WEBHOOK_SECRET,
+)
+```
+
+- **Stripe-style** (`verify_stripe_signature`): `t=<unix>,v1=<hex>` header; HMAC-SHA256 over `f"{t}.{body}"` with a replay tolerance (default 5 min).
+- **Paymob-style** (`verify_paymob_hmac`): raw HMAC-SHA256 hex digest over the body.
+
+All comparisons use `hmac.compare_digest` (constant-time).
+
+## Development
+
+```bash
+uv run --extra dev ruff check .
+uv run --extra dev mypy src
+uv run --extra dev pytest
+uv build
+```
+
+Models live in `src/paymenthub/_models.py`, generated from the vendored `openapi.json`:
+
+```bash
+uv run --with datamodel-code-generator datamodel-codegen \
+  --input openapi.json --input-file-type openapi \
+  --output src/paymenthub/_models.py \
+  --output-model-type pydantic_v2.BaseModel \
+  --target-python-version 3.10 --use-standard-collections --use-union-operator
+```
+
+Refresh `openapi.json` from the backend and re-run when the API changes.
+
+## Releasing
+
+`release.yml` publishes to PyPI on a `v*` tag (or a `repository_dispatch` from the backend) via **Trusted Publishing (OIDC)** — no token stored. It runs the test suite and **completes a sandbox payment against prod** before publishing. Configure a PyPI trusted publisher for this repo + workflow, and add a `PAYMENTHUB_TEST_KEY` repo secret for the smoke test.

paymenthub-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+paymenthub/__init__.py,sha256=_UUWg0rW1_0zu2tazWTdS1lEcHWxfMWgxZMSOHHBmnU,708
+paymenthub/_models.py,sha256=gtK0D2cIhtyfr1OS_c38_icmlOUgGEUXn9-Zv8eDYQw,24806
+paymenthub/client.py,sha256=XTr9PJb0RxgajblHsQXyS9Tz4LpbH1Ng0gpubn-F6xg,2897
+paymenthub/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+paymenthub/webhook.py,sha256=NBIgMdt1BNjCSVFQoBUjLAisa2qa3B-kC5hZNlg32uo,2600
+paymenthub-0.1.0.dist-info/METADATA,sha256=YAXkEYr8r4LwWB57f60wdfygiighTyZYWi8uX4z9xwE,3319
+paymenthub-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+paymenthub-0.1.0.dist-info/RECORD,,

paymenthub-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any