svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/apf_payments/provider/stripe.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from functools import partial
-from typing import Any, Optional
+from typing import Any
 
 import anyio
 
@@ -44,7 +44,7 @@ from .base import ProviderAdapter
 try:
     import stripe
 except Exception:  # pragma: no cover
-    stripe = None  # type: ignore
+    stripe = None  # type: ignore[assignment]
 
 
 async def _acall(fn, /, *args, **kwargs):
@@ -224,7 +224,7 @@ class StripeAdapter(ProviderAdapter):
             name=c.get("name"),
         )
 
-    async def get_customer(self, provider_customer_id: str) -> Optional[CustomerOut]:
+    async def get_customer(self, provider_customer_id: str) -> CustomerOut | None:
         c = await _acall(stripe.Customer.retrieve, provider_customer_id)
         return CustomerOut(
             id=c.id,
@@ -235,9 +235,14 @@ class StripeAdapter(ProviderAdapter):
         )
 
     async def list_customers(
-        self, *, provider: str | None, user_id: str | None, limit: int, cursor: str | None
+        self,
+        *,
+        provider: str | None,
+        user_id: str | None,
+        limit: int,
+        cursor: str | None,
     ) -> tuple[list[CustomerOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if cursor:
             params["starting_after"] = cursor
         # Stripe has no direct filter for our custom user_id; many teams store mapping in DB.
@@ -271,13 +276,21 @@ class StripeAdapter(ProviderAdapter):
                 invoice_settings={"default_payment_method": pm.id},
             )
             is_default = (
-                getattr(getattr(cust, "invoice_settings", None), "default_payment_method", None)
+                getattr(
+                    getattr(cust, "invoice_settings", None),
+                    "default_payment_method",
+                    None,
+                )
                 == pm.id
             )
         else:
             cust = await _acall(stripe.Customer.retrieve, data.customer_provider_id)
             is_default = (
-                getattr(getattr(cust, "invoice_settings", None), "default_payment_method", None)
+                getattr(
+                    getattr(cust, "invoice_settings", None),
+                    "default_payment_method",
+                    None,
+                )
                 == pm.id
             )
         return _pm_to_out(pm, is_default=is_default)
@@ -366,7 +379,7 @@ class StripeAdapter(ProviderAdapter):
     async def list_products(
         self, *, active: bool | None, limit: int, cursor: str | None
     ) -> tuple[list[ProductOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if active is not None:
             params["active"] = bool(active)
         if cursor:
@@ -390,12 +403,12 @@ class StripeAdapter(ProviderAdapter):
         return _product_to_out(p)
 
     async def create_price(self, data: PriceCreateIn) -> PriceOut:
-        kwargs: dict[str, Any] = dict(
-            product=data.provider_product_id,
-            currency=data.currency.lower(),
-            unit_amount=int(data.unit_amount),
-            active=bool(data.active),
-        )
+        kwargs: dict[str, Any] = {
+            "product": data.provider_product_id,
+            "currency": data.currency.lower(),
+            "unit_amount": int(data.unit_amount),
+            "active": bool(data.active),
+        }
         if data.interval:
             kwargs["recurring"] = {"interval": data.interval}
         if data.trial_days is not None:
@@ -415,7 +428,7 @@ class StripeAdapter(ProviderAdapter):
         limit: int,
         cursor: str | None,
     ) -> tuple[list[PriceOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if provider_product_id:
             params["product"] = provider_product_id
         if active is not None:
@@ -441,11 +454,11 @@ class StripeAdapter(ProviderAdapter):
 
     # -------- Subscriptions --------
     async def create_subscription(self, data: SubscriptionCreateIn) -> SubscriptionOut:
-        kwargs: dict[str, Any] = dict(
-            customer=data.customer_provider_id,
-            items=[{"price": data.price_provider_id, "quantity": int(data.quantity)}],
-            proration_behavior=data.proration_behavior,
-        )
+        kwargs: dict[str, Any] = {
+            "customer": data.customer_provider_id,
+            "items": [{"price": data.price_provider_id, "quantity": int(data.quantity)}],
+            "proration_behavior": data.proration_behavior,
+        }
         if data.trial_days is not None:
             kwargs["trial_period_days"] = int(data.trial_days)
         s = await _acall(stripe.Subscription.create, **kwargs)
@@ -493,7 +506,7 @@ class StripeAdapter(ProviderAdapter):
         limit: int,
         cursor: str | None,
     ) -> tuple[list[SubscriptionOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if customer_provider_id:
             params["customer"] = customer_provider_id
         if status:
@@ -530,19 +543,20 @@ class StripeAdapter(ProviderAdapter):
         self, provider_invoice_id: str, data: InvoiceLineItemIn
     ) -> InvoiceOut:
         # attach an item to a DRAFT invoice
-        kwargs: dict[str, Any] = dict(
-            invoice=provider_invoice_id,
-            customer=data.customer_provider_id,
-            quantity=int(data.quantity or 1),
-            currency=data.currency.lower(),
-            description=data.description or None,
-        )
+        kwargs: dict[str, Any] = {
+            "invoice": provider_invoice_id,
+            "customer": data.customer_provider_id,
+            "quantity": int(data.quantity or 1),
+            "currency": data.currency.lower(),
+            "description": data.description or None,
+        }
         if data.provider_price_id:
             kwargs["price"] = data.provider_price_id
         else:
             kwargs["unit_amount"] = int(data.unit_amount)
         await _acall(
-            stripe.InvoiceItem.create, **{k: v for k, v in kwargs.items() if v is not None}
+            stripe.InvoiceItem.create,
+            **{k: v for k, v in kwargs.items() if v is not None},
         )
         inv = await _acall(stripe.Invoice.retrieve, provider_invoice_id)
         return _inv_to_out(inv)
@@ -555,7 +569,7 @@ class StripeAdapter(ProviderAdapter):
         limit: int,
         cursor: str | None,
     ) -> tuple[list[InvoiceOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if customer_provider_id:
             params["customer"] = customer_provider_id
         if status:
@@ -577,13 +591,13 @@ class StripeAdapter(ProviderAdapter):
         params = {"customer": customer_provider_id}
         if subscription_id:
             params["subscription"] = subscription_id
-        inv = await _acall(stripe.Invoice.upcoming, **params)
+        inv = await _acall(stripe.Invoice.upcoming, **params)  # type: ignore[attr-defined]
         return _inv_to_out(inv)
 
     async def list_invoice_line_items(
         self, provider_invoice_id: str, *, limit: int, cursor: str | None
     ) -> tuple[list[InvoiceLineItemOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if cursor:
             params["starting_after"] = cursor
         res = await _acall(stripe.Invoice.list_lines, provider_invoice_id, **params)
@@ -607,17 +621,20 @@ class StripeAdapter(ProviderAdapter):
 
     # -------- Intents --------
     async def create_intent(self, data: IntentCreateIn, *, user_id: str | None) -> IntentOut:
-        kwargs: dict[str, Any] = dict(
-            amount=int(data.amount),
-            currency=data.currency.lower(),
-            description=data.description or None,
-            capture_method="manual" if data.capture_method == "manual" else "automatic",
-            automatic_payment_methods={"enabled": True} if not data.payment_method_types else None,
-        )
+        kwargs: dict[str, Any] = {
+            "amount": int(data.amount),
+            "currency": data.currency.lower(),
+            "description": data.description or None,
+            "capture_method": "manual" if data.capture_method == "manual" else "automatic",
+            "automatic_payment_methods": {"enabled": True}
+            if not data.payment_method_types
+            else None,
+        }
         if data.payment_method_types:
             kwargs["payment_method_types"] = data.payment_method_types
         pi = await _acall(
-            stripe.PaymentIntent.create, **{k: v for k, v in kwargs.items() if v is not None}
+            stripe.PaymentIntent.create,
+            **{k: v for k, v in kwargs.items() if v is not None},
         )
         return _pi_to_out(pi)
 
@@ -663,7 +680,7 @@ class StripeAdapter(ProviderAdapter):
         limit: int,
         cursor: str | None,
     ) -> tuple[list[IntentOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if customer_provider_id:
             params["customer"] = customer_provider_id
         if status:
@@ -678,7 +695,8 @@ class StripeAdapter(ProviderAdapter):
     # ---- Setup Intents (off-session readiness) ----
     async def create_setup_intent(self, data: SetupIntentCreateIn) -> SetupIntentOut:
         si = await _acall(
-            stripe.SetupIntent.create, payment_method_types=data.payment_method_types or ["card"]
+            stripe.SetupIntent.create,
+            payment_method_types=data.payment_method_types or ["card"],
         )
         return SetupIntentOut(
             id=si.id,
@@ -720,7 +738,7 @@ class StripeAdapter(ProviderAdapter):
     async def list_disputes(
         self, *, status: str | None, limit: int, cursor: str | None
     ) -> tuple[list[DisputeOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if status:
             params["status"] = status
         if cursor:
@@ -738,7 +756,7 @@ class StripeAdapter(ProviderAdapter):
         d = await _acall(stripe.Dispute.modify, provider_dispute_id, evidence=evidence)
         # Some disputes require explicit submit call:
         try:
-            d = await _acall(stripe.Dispute.submit, provider_dispute_id)
+            d = await _acall(stripe.Dispute.submit, provider_dispute_id)  # type: ignore[attr-defined]
         except Exception:
             pass
         return _dispute_to_out(d)
@@ -761,7 +779,7 @@ class StripeAdapter(ProviderAdapter):
     async def list_payouts(
         self, *, limit: int, cursor: str | None
     ) -> tuple[list[PayoutOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if cursor:
             params["starting_after"] = cursor
         res = await _acall(stripe.Payout.list, **params)
@@ -777,7 +795,7 @@ class StripeAdapter(ProviderAdapter):
     async def list_refunds(
         self, *, provider_payment_intent_id: str | None, limit: int, cursor: str | None
     ) -> tuple[list[RefundOut], str | None]:
-        params = {"limit": int(limit)}
+        params: dict[str, Any] = {"limit": int(limit)}
         if provider_payment_intent_id:
             params["payment_intent"] = provider_payment_intent_id
         if cursor:
@@ -810,7 +828,7 @@ class StripeAdapter(ProviderAdapter):
         }
         if data.timestamp:
             body["timestamp"] = int(data.timestamp)
-        rec = await _acall(stripe.UsageRecord.create, **body)
+        rec = await _acall(stripe.UsageRecord.create, **body)  # type: ignore[attr-defined]
         return UsageRecordOut(
             id=rec.id,
             quantity=int(rec.quantity),
@@ -829,15 +847,19 @@ class StripeAdapter(ProviderAdapter):
             sub_item = items.data[0].id if items.data else None
         if not sub_item:
             return [], None
-        params = {"limit": int(f.limit or 50)}
+        params: dict[str, Any] = {"limit": int(f.limit or 50)}
         if f.cursor:
             params["starting_after"] = f.cursor
-        res = await _acall(stripe.SubscriptionItem.list_usage_record_summaries, sub_item, **params)
-        items: list[UsageRecordOut] = []
+        res = await _acall(
+            stripe.SubscriptionItem.list_usage_record_summaries,  # type: ignore[attr-defined]
+            sub_item,
+            **params,
+        )
+        usage_records: list[UsageRecordOut] = []
         for s in res.data:
             # No record id in summaries—synthesize a stable id from period start.
             synthesized_id = f"{sub_item}:{getattr(s, 'period', {}).get('start')}"
-            items.append(
+            usage_records.append(
                 UsageRecordOut(
                     id=synthesized_id,
                     quantity=int(getattr(s, "total_usage", 0)),
@@ -851,7 +873,7 @@ class StripeAdapter(ProviderAdapter):
             if getattr(res, "has_more", False) and res.data and hasattr(res.data[-1], "id")
             else None
         )
-        return items, next_cursor
+        return usage_records, next_cursor
 
     async def get_usage_record(self, usage_record_id: str) -> UsageRecordOut:
         # Stripe has no direct "retrieve usage record by id" API.

svc_infra/apf_payments/schemas.py

@@ -1,38 +1,39 @@
 from __future__ import annotations
 
-from typing import Any, Literal, Optional
+from typing import Annotated, Any, Literal
 
-from pydantic import BaseModel, Field, conint, constr
+from pydantic import BaseModel, Field, StringConstraints
 
-Currency = constr(pattern=r"^[A-Z]{3}$")
-AmountMinor = conint(ge=0)  # minor units (cents)
+# Type aliases for payment fields using Annotated with proper type hints
+Currency = Annotated[str, StringConstraints(pattern=r"^[A-Z]{3}$")]
+AmountMinor = Annotated[int, Field(ge=0)]  # minor units (cents)
 
 
 class CustomerUpsertIn(BaseModel):
-    user_id: Optional[str] = None
-    email: Optional[str] = None
-    name: Optional[str] = None
+    user_id: str | None = None
+    email: str | None = None
+    name: str | None = None
 
 
 class CustomerOut(BaseModel):
     id: str
     provider: str
     provider_customer_id: str
-    email: Optional[str] = None
-    name: Optional[str] = None
+    email: str | None = None
+    name: str | None = None
 
 
 class IntentCreateIn(BaseModel):
     amount: AmountMinor = Field(..., description="Minor units (e.g., cents)")
     currency: Currency = Field(..., json_schema_extra={"example": "USD"})
-    description: Optional[str] = None
+    description: str | None = None
     capture_method: Literal["automatic", "manual"] = "automatic"
     payment_method_types: list[str] = Field(default_factory=list)  # let provider default
 
 
 class NextAction(BaseModel):
-    type: Optional[str] = None
-    data: Optional[dict[str, Any]] = None
+    type: str | None = None
+    data: dict[str, Any] | None = None
 
 
 class IntentOut(BaseModel):
@@ -42,13 +43,13 @@ class IntentOut(BaseModel):
     status: str
     amount: AmountMinor
     currency: Currency
-    client_secret: Optional[str] = None
-    next_action: Optional[NextAction] = None
+    client_secret: str | None = None
+    next_action: NextAction | None = None
 
 
 class RefundIn(BaseModel):
-    amount: Optional[AmountMinor] = None
-    reason: Optional[str] = None
+    amount: AmountMinor | None = None
+    reason: str | None = None
 
 
 class TransactionRow(BaseModel):
@@ -60,9 +61,9 @@ class TransactionRow(BaseModel):
     status: str
     provider: str
     provider_ref: str
-    user_id: Optional[str] = None
-    net: Optional[int] = None
-    fee: Optional[int] = None
+    user_id: str | None = None
+    net: int | None = None
+    fee: int | None = None
 
 
 class StatementRow(BaseModel):
@@ -87,10 +88,10 @@ class PaymentMethodOut(BaseModel):
     provider: str
     provider_customer_id: str
     provider_method_id: str
-    brand: Optional[str] = None
-    last4: Optional[str] = None
-    exp_month: Optional[int] = None
-    exp_year: Optional[int] = None
+    brand: str | None = None
+    last4: str | None = None
+    exp_month: int | None = None
+    exp_year: int | None = None
     is_default: bool = False
 
 
@@ -111,8 +112,8 @@ class PriceCreateIn(BaseModel):
     provider_product_id: str
     currency: Currency
     unit_amount: AmountMinor
-    interval: Optional[Literal["day", "week", "month", "year"]] = None
-    trial_days: Optional[int] = None
+    interval: Literal["day", "week", "month", "year"] | None = None
+    trial_days: int | None = None
     active: bool = True
 
 
@@ -123,8 +124,8 @@ class PriceOut(BaseModel):
     provider_product_id: str
     currency: Currency
     unit_amount: AmountMinor
-    interval: Optional[str] = None
-    trial_days: Optional[int] = None
+    interval: str | None = None
+    trial_days: int | None = None
     active: bool = True
 
 
@@ -132,14 +133,14 @@ class SubscriptionCreateIn(BaseModel):
     customer_provider_id: str
     price_provider_id: str
     quantity: int = 1
-    trial_days: Optional[int] = None
+    trial_days: int | None = None
     proration_behavior: Literal["create_prorations", "none", "always_invoice"] = "create_prorations"
 
 
 class SubscriptionUpdateIn(BaseModel):
-    price_provider_id: Optional[str] = None
-    quantity: Optional[int] = None
-    cancel_at_period_end: Optional[bool] = None
+    price_provider_id: str | None = None
+    quantity: int | None = None
+    cancel_at_period_end: bool | None = None
     proration_behavior: Literal["create_prorations", "none", "always_invoice"] = "create_prorations"
 
 
@@ -151,7 +152,7 @@ class SubscriptionOut(BaseModel):
     status: str
     quantity: int
     cancel_at_period_end: bool
-    current_period_end: Optional[str] = None
+    current_period_end: str | None = None
 
 
 class InvoiceCreateIn(BaseModel):
@@ -167,45 +168,45 @@ class InvoiceOut(BaseModel):
     status: str
     amount_due: AmountMinor
     currency: Currency
-    hosted_invoice_url: Optional[str] = None
-    pdf_url: Optional[str] = None
+    hosted_invoice_url: str | None = None
+    pdf_url: str | None = None
 
 
 class CaptureIn(BaseModel):
-    amount: Optional[AmountMinor] = None  # partial capture supported
+    amount: AmountMinor | None = None  # partial capture supported
 
 
 class IntentListFilter(BaseModel):
-    customer_provider_id: Optional[str] = None
-    status: Optional[str] = None
-    limit: Optional[int] = Field(default=50, ge=1, le=200)
-    cursor: Optional[str] = None  # opaque provider cursor when supported
+    customer_provider_id: str | None = None
+    status: str | None = None
+    limit: int | None = Field(default=50, ge=1, le=200)
+    cursor: str | None = None  # opaque provider cursor when supported
 
 
 class UsageRecordIn(BaseModel):
     # Stripe: subscription_item is the target for metered billing.
     # If provider doesn't use subscription_item, allow provider_price_id as fallback.
-    subscription_item: Optional[str] = None
-    provider_price_id: Optional[str] = None
-    quantity: conint(ge=0)
-    timestamp: Optional[int] = None  # Unix seconds; provider defaults to "now"
-    action: Optional[Literal["increment", "set"]] = "increment"
+    subscription_item: str | None = None
+    provider_price_id: str | None = None
+    quantity: Annotated[int, Field(ge=0)]
+    timestamp: int | None = None  # Unix seconds; provider defaults to "now"
+    action: Literal["increment", "set"] | None = "increment"
 
 
 class InvoiceLineItemIn(BaseModel):
     customer_provider_id: str
-    description: Optional[str] = None
+    description: str | None = None
     unit_amount: AmountMinor
     currency: Currency
-    quantity: Optional[int] = 1
-    provider_price_id: Optional[str] = None  # if linked to a price, unit_amount may be ignored
+    quantity: int | None = 1
+    provider_price_id: str | None = None  # if linked to a price, unit_amount may be ignored
 
 
 class InvoicesListFilter(BaseModel):
-    customer_provider_id: Optional[str] = None
-    status: Optional[str] = None
-    limit: Optional[int] = Field(default=50, ge=1, le=200)
-    cursor: Optional[str] = None
+    customer_provider_id: str | None = None
+    status: str | None = None
+    limit: int | None = Field(default=50, ge=1, le=200)
+    cursor: str | None = None
 
 
 class SetupIntentOut(BaseModel):
@@ -213,8 +214,8 @@ class SetupIntentOut(BaseModel):
     provider: str
     provider_setup_intent_id: str
     status: str
-    client_secret: Optional[str] = None
-    next_action: Optional[NextAction] = None
+    client_secret: str | None = None
+    next_action: NextAction | None = None
 
 
 class DisputeOut(BaseModel):
@@ -223,10 +224,10 @@ class DisputeOut(BaseModel):
     provider_dispute_id: str
     amount: AmountMinor
     currency: Currency
-    reason: Optional[str] = None
+    reason: str | None = None
     status: str
-    evidence_due_by: Optional[str] = None
-    created_at: Optional[str] = None
+    evidence_due_by: str | None = None
+    created_at: str | None = None
 
 
 class PayoutOut(BaseModel):
@@ -236,8 +237,8 @@ class PayoutOut(BaseModel):
     amount: AmountMinor
     currency: Currency
     status: str
-    arrival_date: Optional[str] = None
-    type: Optional[str] = None
+    arrival_date: str | None = None
+    type: str | None = None
 
 
 class BalanceAmount(BaseModel):
@@ -255,7 +256,7 @@ class SetupIntentCreateIn(BaseModel):
 
 
 class WebhookReplayIn(BaseModel):
-    event_ids: Optional[list[str]] = None
+    event_ids: list[str] | None = None
 
 
 class WebhookReplayOut(BaseModel):
@@ -269,36 +270,36 @@ class WebhookAckOut(BaseModel):
 class UsageRecordOut(BaseModel):
     id: str
     quantity: int
-    timestamp: Optional[int] = None
-    subscription_item: Optional[str] = None
-    provider_price_id: Optional[str] = None
-    action: Optional[Literal["increment", "set"]] = None
+    timestamp: int | None = None
+    subscription_item: str | None = None
+    provider_price_id: str | None = None
+    action: Literal["increment", "set"] | None = None
 
 
 # -------- Customers list filter ----------
 class CustomersListFilter(BaseModel):
-    provider: Optional[str] = None
-    user_id: Optional[str] = None
-    limit: Optional[int] = Field(default=50, ge=1, le=200)
-    cursor: Optional[str] = None  # we’ll paginate on provider_customer_id asc
+    provider: str | None = None
+    user_id: str | None = None
+    limit: int | None = Field(default=50, ge=1, le=200)
+    cursor: str | None = None  # we’ll paginate on provider_customer_id asc
 
 
 # -------- Products / Prices updates ----------
 class ProductUpdateIn(BaseModel):
-    name: Optional[str] = None
-    active: Optional[bool] = None
+    name: str | None = None
+    active: bool | None = None
 
 
 class PriceUpdateIn(BaseModel):
-    active: Optional[bool] = None
+    active: bool | None = None
 
 
 # -------- Payment Method update ----------
 class PaymentMethodUpdateIn(BaseModel):
     # keep minimal + commonly supported card fields
-    name: Optional[str] = None
-    exp_month: Optional[int] = None
-    exp_year: Optional[int] = None
+    name: str | None = None
+    exp_month: int | None = None
+    exp_year: int | None = None
     # extend here later with address fields (line1, city, etc.)
 
 
@@ -307,27 +308,27 @@ class RefundOut(BaseModel):
     id: str
     provider: str
     provider_refund_id: str
-    provider_payment_intent_id: Optional[str] = None
+    provider_payment_intent_id: str | None = None
     amount: AmountMinor
     currency: Currency
     status: str
-    reason: Optional[str] = None
-    created_at: Optional[str] = None
+    reason: str | None = None
+    created_at: str | None = None
 
 
 # -------- Invoice line items (list) ----------
 class InvoiceLineItemOut(BaseModel):
     id: str
-    description: Optional[str] = None
+    description: str | None = None
     amount: AmountMinor
     currency: Currency
-    quantity: Optional[int] = 1
-    provider_price_id: Optional[str] = None
+    quantity: int | None = 1
+    provider_price_id: str | None = None
 
 
 # -------- Usage records list/get ----------
 class UsageRecordListFilter(BaseModel):
-    subscription_item: Optional[str] = None
-    provider_price_id: Optional[str] = None
-    limit: Optional[int] = Field(default=50, ge=1, le=200)
-    cursor: Optional[str] = None
+    subscription_item: str | None = None
+    provider_price_id: str | None = None
+    limit: int | None = Field(default=50, ge=1, le=200)
+    cursor: str | None = None