traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/parts/providers/keyed.py

@@ -0,0 +1,661 @@
+"""Providers that need an account: Nexar (Octopart), DigiKey, Mouser.
+
+Each is skipped unless its credentials are in the environment (``.env`` is read
+by ``traceforge.config``):
+
+- Nexar / Octopart: ``NEXAR_CLIENT_ID`` + ``NEXAR_CLIENT_SECRET`` (or a ready
+  ``NEXAR_TOKEN``); GraphQL ``supSearchMpn`` / ``supSearch``.
+- DigiKey Product Information v4: ``DIGIKEY_CLIENT_ID`` + ``DIGIKEY_CLIENT_SECRET``
+  (OAuth2 client credentials); keyword search.
+- Mouser Search API v1: ``MOUSER_API_KEY``; part-number and keyword search.
+
+VERIFICATION STATUS: these three were written against the vendors' published API
+documentation and are exercised only against hand-written fixtures shaped like
+the documented responses (tests/fixtures/parts/{digikey,mouser,nexar}_*.json).
+They have never been run with real credentials. Field names that could not be
+confirmed against a live response are marked "unverified" below.
+
+Shared behaviour: the OAuth token is cached until shortly before it expires; a 401
+refreshes the token once and retries; 429 and "too many requests" answers wait
+(Retry-After, bounded) and retry a limited number of times, then raise
+:class:`RateLimited`; a client-side window keeps calls under the documented
+per-minute limits. Responses that are not valid JSON or that carry an error
+body raise :class:`ProviderError` with the vendor's message.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import threading
+import time
+from collections import deque
+from typing import Any
+
+from traceforge.parts.model import (
+    PartInfo,
+    PriceBreak,
+    SupplierOffer,
+    normalize_lifecycle,
+    pin_count_from_text,
+)
+from traceforge.parts.net import Offline, ProviderError
+from traceforge.parts.providers.base import PartProvider, SearchQuery, best_mpn_match
+
+
+class RateLimited(ProviderError):
+    """The supplier's rate limit (or daily quota) was hit and retries did not clear it."""
+
+
+def _env(*names: str) -> str:
+    for name in names:
+        value = os.environ.get(name, "").strip()
+        if value:
+            return value
+    return ""
+
+
+class Throttle:
+    """At most ``calls`` requests per ``per`` seconds (sliding window); clock and sleep injectable."""
+
+    def __init__(self, calls: int, per: float = 60.0, clock=time.monotonic, sleep=time.sleep):
+        self.calls, self.per, self.clock, self.sleep = calls, per, clock, sleep
+        self._stamps: deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def wait(self) -> None:
+        with self._lock:
+            now = self.clock()
+            while self._stamps and now - self._stamps[0] >= self.per:
+                self._stamps.popleft()
+            if len(self._stamps) >= self.calls:
+                delay = self.per - (now - self._stamps[0])
+                if delay > 0:
+                    self.sleep(delay)
+                self._stamps.popleft()
+            self._stamps.append(self.clock())
+
+
+MAX_RETRIES = 2
+MAX_WAIT = 30.0  # never sleep longer than this on a Retry-After
+
+
+def _retry_after(response) -> float:
+    try:
+        return max(0.0, min(float(response.headers.get("Retry-After", "")), MAX_WAIT))
+    except ValueError:
+        return 2.0
+
+
+class _KeyedProvider(PartProvider):
+    """Request plumbing shared by the three: throttle, retry on 429, error bodies."""
+
+    rate: tuple[int, float] = (60, 60.0)
+
+    def __init__(self, net, sleep=time.sleep):
+        super().__init__(net)
+        self.sleep = sleep
+        self.throttle = Throttle(self.rate[0], self.rate[1], sleep=sleep)
+
+    def refresh_auth(self) -> None:
+        """Drop the cached credential so the next call fetches a fresh one."""
+
+    def _is_rate_limited(self, response, body: Any) -> bool:
+        return response.status_code == 429
+
+    def _send(self, method: str, url: str, **kwargs: Any) -> Any:
+        """Send with throttling, a single auth refresh on 401 and bounded 429 retries."""
+        refreshed = False
+        attempt = 0
+        while True:
+            self.throttle.wait()
+            call_kwargs = dict(kwargs)
+            if callable(kwargs.get("headers")):
+                call_kwargs["headers"] = kwargs["headers"]()
+            response = self.net.request(method, url, **call_kwargs)
+            try:
+                body = response.json()
+            except ValueError:
+                body = None
+            where = url.split("?")[0]
+            if response.status_code == 401 and not refreshed:
+                refreshed = True
+                self.refresh_auth()
+                continue
+            if self._is_rate_limited(response, body):
+                if attempt >= MAX_RETRIES:
+                    raise RateLimited(f"{self.name}: rate limited, retries exhausted ({where})")
+                attempt += 1
+                self.sleep(_retry_after(response))
+                continue
+            if response.status_code in (401, 403):
+                raise ProviderError(
+                    f"{self.name}: HTTP {response.status_code} (check the credentials and that "
+                    f"the app is subscribed to this API): {self._message(body)}"
+                )
+            if response.status_code >= 500:
+                raise Offline(f"{where}: HTTP {response.status_code}")
+            if response.status_code >= 400:
+                raise ProviderError(
+                    f"{self.name}: HTTP {response.status_code}: {self._message(body)}"
+                )
+            if body is None:
+                raise ProviderError(f"{self.name}: response is not JSON ({where})")
+            return body
+
+    @staticmethod
+    def _message(body: Any) -> str:
+        if isinstance(body, dict):
+            for key in ("detail", "ErrorMessage", "error_description", "title", "message"):
+                if body.get(key):
+                    return str(body[key])[:200]
+            errors = body.get("Errors") or body.get("errors")
+            if isinstance(errors, list) and errors and isinstance(errors[0], dict):
+                return str(errors[0].get("Message") or errors[0].get("message") or "")[:200]
+        return ""
+
+
+class _OAuthProvider(_KeyedProvider):
+    token_url = ""
+    scope = ""
+    id_vars: tuple[str, ...] = ()
+    secret_vars: tuple[str, ...] = ()
+    token_var = ""
+
+    def __init__(self, net, sleep=time.sleep):
+        super().__init__(net, sleep)
+        self._token: tuple[str, float] | None = None
+
+    def configured(self) -> bool:
+        return bool(
+            (self.token_var and _env(self.token_var))
+            or (_env(*self.id_vars) and _env(*self.secret_vars))
+        )
+
+    def refresh_auth(self) -> None:
+        self._token = None
+
+    def token(self) -> str:
+        if self.token_var and _env(self.token_var):
+            return _env(self.token_var)
+        if self._token and self._token[1] > time.time() + 30:
+            return self._token[0]
+        form = {
+            "grant_type": "client_credentials",
+            "client_id": _env(*self.id_vars),
+            "client_secret": _env(*self.secret_vars),
+        }
+        if self.scope:
+            form["scope"] = self.scope
+        response = self.net.request("POST", self.token_url, data=form)
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+        if response.status_code >= 500:
+            raise Offline(f"{self.token_url}: HTTP {response.status_code}")
+        if response.status_code >= 400 or not isinstance(data, dict):
+            raise ProviderError(
+                f"{self.name}: token request failed (HTTP {response.status_code}): "
+                f"{self._message(data) or 'check the client id and secret'}"
+            )
+        token = data.get("access_token")
+        if not token:
+            raise ProviderError(f"{self.name}: no access token in the OAuth response")
+        self._token = (token, time.time() + float(data.get("expires_in") or 600))
+        return token
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.token()}"}
+
+
+# ------------------------------------------------------------------- Nexar
+
+
+class NexarProvider(_OAuthProvider):
+    """Octopart data through Nexar's GraphQL supply API (unverified against a live account)."""
+
+    name = "nexar"
+    mpns = True
+    searches = True
+    token_url = "https://identity.nexar.com/connect/token"
+    scope = "supply.domain"
+    id_vars = ("NEXAR_CLIENT_ID",)
+    secret_vars = ("NEXAR_CLIENT_SECRET",)
+    token_var = "NEXAR_TOKEN"
+    endpoint = "https://api.nexar.com/graphql"
+    rate = (20, 60.0)  # conservative; the plan's own limits apply server-side
+
+    # The field names below follow Nexar's published schema (supSearch / supSearchMpn, Part,
+    # Seller, Offer, Price). `moq`, `orderMultiple`, `factoryLeadDays`, `packaging`,
+    # `isAuthorized` and `clickUrl` are documented Offer/Seller fields; they were not checked
+    # against a live response.
+    QUERY = """
+    query Search($q: String!, $limit: Int!) {
+      %(op)s(q: $q, limit: $limit) {
+        results {
+          part {
+            mpn
+            manufacturer { name }
+            shortDescription
+            category { name }
+            bestDatasheet { url }
+            octopartUrl
+            specs { attribute { name shortname } displayValue }
+            sellers {
+              company { name }
+              isAuthorized
+              offers {
+                sku inventoryLevel moq orderMultiple packaging factoryLeadDays clickUrl
+                prices { quantity price currency }
+              }
+            }
+          }
+        }
+      }
+    }
+    """
+
+    def _search(self, op: str, text: str, limit: int) -> list[PartInfo]:
+        data = self._send(
+            "POST",
+            self.endpoint,
+            json={"query": self.QUERY % {"op": op}, "variables": {"q": text, "limit": limit}},
+            headers=self._auth_headers,
+        )
+        errors = (data or {}).get("errors")
+        if errors:
+            message = str(errors[0].get("message", "query failed"))
+            if re.search(r"too many|rate|limit|quota", message, re.I):
+                raise RateLimited(f"nexar: {message}")
+            raise ProviderError(f"nexar: {message}")
+        results = (((data or {}).get("data") or {}).get(op) or {}).get("results") or []
+        return [self.parse(r.get("part") or {}) for r in results]
+
+    def search(self, query: SearchQuery) -> list[PartInfo]:
+        text = f"{query.text} {query.package or ''}".strip()
+        parts = self._search("supSearch", text, min(query.limit, 20))
+        if query.in_stock:
+            parts = [p for p in parts if (p.stock or 0) > 0]
+        return parts
+
+    def lookup_mpn(self, mpn: str) -> PartInfo | None:
+        return best_mpn_match(mpn, self._search("supSearchMpn", mpn, 10))
+
+    @staticmethod
+    def parse(part: dict[str, Any]) -> PartInfo:
+        attributes = {
+            str((s.get("attribute") or {}).get("name")): str(s.get("displayValue"))
+            for s in part.get("specs") or []
+            if (s.get("attribute") or {}).get("name") and s.get("displayValue")
+        }
+        stock_by_source: dict[str, int] = {}
+        offers: list[SupplierOffer] = []
+        lcsc = ""
+        for seller in part.get("sellers") or []:
+            company = ((seller.get("company") or {}).get("name") or "").strip()
+            authorised = seller.get("isAuthorized")
+            for offer in seller.get("offers") or []:
+                level = offer.get("inventoryLevel")
+                level = level if isinstance(level, int) and level >= 0 else None
+                if level is not None:
+                    stock_by_source[company] = max(stock_by_source.get(company, 0), level)
+                sku = str(offer.get("sku") or "")
+                if company.upper() == "LCSC" and re.match(r"^C\d+$", sku):
+                    lcsc = sku
+                breaks = [
+                    PriceBreak(int(p["quantity"]), float(p["price"]), p.get("currency") or "USD")
+                    for p in offer.get("prices") or []
+                    if p.get("quantity") and p.get("price") is not None
+                ]
+                lead = offer.get("factoryLeadDays")
+                offers.append(
+                    SupplierOffer(
+                        supplier=company or "unknown seller",
+                        sku=sku,
+                        stock=level,
+                        price_breaks=sorted(breaks, key=lambda b: b.quantity),
+                        moq=offer.get("moq") if isinstance(offer.get("moq"), int) else None,
+                        multiple=(
+                            offer.get("orderMultiple")
+                            if isinstance(offer.get("orderMultiple"), int)
+                            else None
+                        ),
+                        lead_time_days=lead if isinstance(lead, int) and lead > 0 else None,
+                        packaging=str(offer.get("packaging") or ""),
+                        authorised=authorised if isinstance(authorised, bool) else None,
+                        url=str(offer.get("clickUrl") or ""),
+                        source="nexar",
+                    )
+                )
+        priced = next((o.price_breaks for o in offers if o.price_breaks), [])
+        package = attributes.get("Case/Package") or attributes.get("Package") or ""
+        lifecycle = normalize_lifecycle(
+            attributes.get("Lifecycle Status") or attributes.get("Lifecycle") or ""
+        )
+        return PartInfo(
+            lcsc=lcsc,
+            mpn=str(part.get("mpn") or ""),
+            manufacturer=str((part.get("manufacturer") or {}).get("name") or ""),
+            description=str(part.get("shortDescription") or ""),
+            package=package,
+            category=str((part.get("category") or {}).get("name") or ""),
+            pin_count=pin_count_from_text(attributes.get("Number of Pins", "")),
+            stock=sum(stock_by_source.values()) if stock_by_source else None,
+            stock_by_source=stock_by_source,
+            price_breaks=list(priced),
+            datasheet_url=str((part.get("bestDatasheet") or {}).get("url") or ""),
+            product_url=str(part.get("octopartUrl") or ""),
+            lifecycle=lifecycle,
+            attributes=attributes,
+            sources=["nexar"],
+            offers=offers,
+        )
+
+
+# ----------------------------------------------------------------- DigiKey
+
+
+def _lead_days(text: str) -> int | None:
+    """'14 weeks' / '84 Days' / '3 months' -> days."""
+    match = re.search(r"(\d+(?:\.\d+)?)\s*(day|week|wk|month)", str(text or ""), re.I)
+    if not match:
+        return None
+    unit = match.group(2).lower()
+    factor = 1 if unit.startswith("day") else (7 if unit.startswith(("week", "wk")) else 30)
+    return int(round(float(match.group(1)) * factor))
+
+
+class DigikeyProvider(_OAuthProvider):
+    """DigiKey Product Information API v4 (unverified against a live account)."""
+
+    name = "digikey"
+    mpns = True
+    searches = True
+    token_url = "https://api.digikey.com/v1/oauth2/token"
+    id_vars = ("DIGIKEY_CLIENT_ID",)
+    secret_vars = ("DIGIKEY_CLIENT_SECRET",)
+    endpoint = "https://api.digikey.com/products/v4/search/keyword"
+    rate = (100, 60.0)  # documented default is 120 requests/minute
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            **self._auth_headers(),
+            "X-DIGIKEY-Client-Id": _env(*self.id_vars),
+            "X-DIGIKEY-Locale-Site": os.environ.get("DIGIKEY_LOCALE_SITE", "US"),
+            "X-DIGIKEY-Locale-Language": os.environ.get("DIGIKEY_LOCALE_LANGUAGE", "en"),
+            "X-DIGIKEY-Locale-Currency": os.environ.get("DIGIKEY_CURRENCY", "USD"),
+        }
+
+    def _is_rate_limited(self, response, body) -> bool:
+        if response.status_code == 429:
+            return True
+        # DigiKey reports a spent quota as 429; some gateways answer 403 with a rate message.
+        return response.status_code == 403 and "rate limit" in self._message(body).lower()
+
+    def _keyword(self, text: str, limit: int, in_stock: bool) -> list[PartInfo]:
+        body: dict[str, Any] = {"Keywords": text, "Limit": min(limit, 50), "Offset": 0}
+        if in_stock:
+            body["FilterOptionsRequest"] = {"SearchOptions": ["InStock"]}
+        data = self._send("POST", self.endpoint, json=body, headers=self._headers)
+        products = list((data or {}).get("ExactMatches") or [])
+        products += list((data or {}).get("Products") or [])
+        seen: set[str] = set()
+        parts = []
+        for product in products:
+            part = self.parse(product, currency=os.environ.get("DIGIKEY_CURRENCY", "USD"))
+            if part.mpn and part.mpn not in seen:
+                seen.add(part.mpn)
+                parts.append(part)
+        return parts
+
+    def search(self, query: SearchQuery) -> list[PartInfo]:
+        text = f"{query.text} {query.package or ''}".strip()
+        return self._keyword(text, query.limit, query.in_stock)
+
+    def lookup_mpn(self, mpn: str) -> PartInfo | None:
+        return best_mpn_match(mpn, self._keyword(mpn, 10, False))
+
+    @staticmethod
+    def parse(product: dict[str, Any], currency: str = "USD") -> PartInfo:
+        attributes = {
+            str(p.get("ParameterText")): str(p.get("ValueText"))
+            for p in product.get("Parameters") or []
+            if p.get("ParameterText") and p.get("ValueText") not in (None, "", "-")
+        }
+        classes = product.get("Classifications") or {}
+        for key, label in (
+            ("HtsusCode", "HTSUS"),
+            ("ExportControlClassNumber", "ECCN"),
+            ("RohsStatus", "RoHS"),
+            ("MoistureSensitivityLevel", "MSL"),
+        ):
+            if classes.get(key):
+                attributes[label] = str(classes[key])
+        status = (product.get("ProductStatus") or {}).get("Status") or ""
+        lifecycle = normalize_lifecycle(status)
+        if product.get("Discontinued") and lifecycle in ("", "normal"):
+            lifecycle = "discontinued"
+        if product.get("EndOfLife") and lifecycle in ("", "normal"):
+            lifecycle = "obsolete"
+        total = product.get("QuantityAvailable")
+        total = int(total) if isinstance(total, int | float) else None
+        lead = _lead_days(product.get("ManufacturerLeadWeeks") or "") or (
+            int(product["ManufacturerLeadWeeks"]) * 7
+            if str(product.get("ManufacturerLeadWeeks") or "").isdigit()
+            else None
+        )
+        offers: list[SupplierOffer] = []
+        for variation in product.get("ProductVariations") or []:
+            breaks = [
+                PriceBreak(int(b["BreakQuantity"]), float(b["UnitPrice"]), currency)
+                for b in variation.get("StandardPricing") or []
+                if b.get("BreakQuantity") and b.get("UnitPrice") is not None
+            ]
+            at_package = variation.get("QuantityAvailableforPackageType")
+            note = ["Marketplace item (third-party seller)"] if variation.get("Marketplace") else []
+            if variation.get("TariffActive"):
+                note.append("DigiKey marks a tariff as active on this item")
+            offers.append(
+                SupplierOffer(
+                    supplier="DigiKey",
+                    sku=str(variation.get("DigiKeyProductNumber") or ""),
+                    stock=int(at_package) if isinstance(at_package, int | float) else total,
+                    price_breaks=sorted(breaks, key=lambda b: b.quantity),
+                    moq=variation.get("MinimumOrderQuantity"),
+                    multiple=None,  # StandardPackage is the pack size, not an order multiple
+                    lead_time_days=lead,
+                    packaging=str((variation.get("PackageType") or {}).get("Name") or ""),
+                    lifecycle=lifecycle,
+                    region=f"{os.environ.get('DIGIKEY_LOCALE_SITE', 'US')} site",
+                    authorised=True,
+                    url=str(product.get("ProductUrl") or ""),
+                    source="digikey",
+                    notes=note,
+                )
+            )
+        priced = next((o.price_breaks for o in offers if o.price_breaks), [])
+        description = product.get("Description") or {}
+        package = attributes.get("Supplier Device Package") or attributes.get("Package / Case", "")
+        mounting = attributes.get("Mounting Type", "").lower()
+        return PartInfo(
+            mpn=str(product.get("ManufacturerProductNumber") or ""),
+            manufacturer=str((product.get("Manufacturer") or {}).get("Name") or ""),
+            description=str(
+                description.get("DetailedDescription")
+                or description.get("ProductDescription")
+                or ""
+            ),
+            package=package,
+            category=str((product.get("Category") or {}).get("Name") or ""),
+            pin_count=pin_count_from_text(attributes.get("Number of Pins", ""), package),
+            stock=total,
+            stock_by_source={"digikey": total} if total is not None else {},
+            price_breaks=list(priced),
+            datasheet_url=str(product.get("DatasheetUrl") or ""),
+            product_url=str(product.get("ProductUrl") or ""),
+            lifecycle=lifecycle,
+            mounting="tht"
+            if "through hole" in mounting
+            else ("smd" if "surface" in mounting else ""),
+            attributes=attributes,
+            sources=["digikey"],
+            offers=offers,
+        )
+
+
+# ------------------------------------------------------------------ Mouser
+
+
+def parse_price(text: str, currency: str = "USD") -> float | None:
+    """'$1,234.50', '0,123 €', '1.234,50 EUR', '¥12' -> float; None when no number."""
+    raw = re.sub(r"[^\d.,]", "", str(text or ""))
+    if not raw:
+        return None
+    if "," in raw and "." in raw:
+        decimal = "," if raw.rfind(",") > raw.rfind(".") else "."
+        thousands = "." if decimal == "," else ","
+        raw = raw.replace(thousands, "").replace(decimal, ".")
+    elif "," in raw:
+        head, _, tail = raw.rpartition(",")
+        grouped = len(tail) == 3 and "," not in head and head not in ("0", "")
+        # "1,234" is a thousands group in dollar-style locales, a decimal in comma locales.
+        raw = (
+            raw.replace(",", "")
+            if grouped and currency in {"USD", "GBP", "JPY", "CNY", "INR"}
+            else raw.replace(",", ".")
+        )
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+class MouserProvider(_KeyedProvider):
+    """Mouser Search API v1 (unverified against a live key)."""
+
+    name = "mouser"
+    mpns = True
+    searches = True
+    base = "https://api.mouser.com/api/v1/search"
+    rate = (28, 60.0)  # documented limit: 30 calls per minute (and 1000 per day)
+
+    def configured(self) -> bool:
+        return bool(_env("MOUSER_API_KEY", "MOUSER_SEARCH_API_KEY"))
+
+    @staticmethod
+    def _errors(body: Any) -> list[dict]:
+        errors = (body or {}).get("Errors") if isinstance(body, dict) else None
+        return [e for e in errors or [] if isinstance(e, dict)]
+
+    def _is_rate_limited(self, response, body) -> bool:
+        if response.status_code == 429:
+            return True
+        return any(
+            re.search(
+                r"toomany|too many|maximum calls|exceeded",
+                f"{e.get('Code')} {e.get('Message')}",
+                re.I,
+            )
+            for e in self._errors(body)
+        )
+
+    def _post(self, path: str, body: dict[str, Any]) -> list[PartInfo]:
+        data = self._send(
+            "POST",
+            f"{self.base}/{path}",
+            params={"apiKey": _env("MOUSER_API_KEY", "MOUSER_SEARCH_API_KEY")},
+            json=body,
+        )
+        errors = self._errors(data)
+        if errors:
+            raise ProviderError(f"mouser: {errors[0].get('Message') or errors[0].get('Code')}")
+        return [self.parse(p) for p in ((data or {}).get("SearchResults") or {}).get("Parts") or []]
+
+    def lookup_mpn(self, mpn: str) -> PartInfo | None:
+        parts = self._post(
+            "partnumber",
+            {"SearchByPartRequest": {"mouserPartNumber": mpn, "partSearchOptions": "Exact"}},
+        )
+        return best_mpn_match(mpn, parts)
+
+    def search(self, query: SearchQuery) -> list[PartInfo]:
+        options = "InStock" if query.in_stock else "None"
+        return self._post(
+            "keyword",
+            {
+                "SearchByKeywordRequest": {
+                    "keyword": f"{query.text} {query.package or ''}".strip(),
+                    "records": min(query.limit, 50),
+                    "startingRecord": 0,
+                    "searchOptions": options,
+                }
+            },
+        )
+
+    @staticmethod
+    def parse(part: dict[str, Any]) -> PartInfo:
+        attributes = {
+            str(a.get("AttributeName")): str(a.get("AttributeValue"))
+            for a in part.get("ProductAttributes") or []
+            if a.get("AttributeName") and a.get("AttributeValue")
+        }
+        for item in part.get("ProductCompliance") or []:
+            name, value = item.get("ComplianceName"), item.get("ComplianceValue")
+            if name and value:
+                attributes[f"Compliance {name}"] = str(value)
+        breaks = []
+        for b in part.get("PriceBreaks") or []:
+            currency = b.get("Currency") or "USD"
+            price = parse_price(str(b.get("Price") or ""), currency)
+            if b.get("Quantity") and price is not None:
+                breaks.append(PriceBreak(int(b["Quantity"]), price, currency))
+        breaks.sort(key=lambda b: b.quantity)
+        raw_stock = part.get("AvailabilityInStock")
+        if raw_stock in (None, ""):
+            match = re.match(r"\s*([\d,]+)\s+In Stock", str(part.get("Availability") or ""))
+            raw_stock = match.group(1).replace(",", "") if match else None
+        stock = int(raw_stock) if raw_stock not in (None, "") and str(raw_stock).isdigit() else None
+        lifecycle = normalize_lifecycle(part.get("LifecycleStatus"))
+        if str(part.get("IsDiscontinued", "")).lower() == "true" and lifecycle in ("", "normal"):
+            lifecycle = "discontinued"
+        moq = str(part.get("Min") or "")
+        mult = str(part.get("Mult") or "")
+        notes = []
+        if part.get("SuggestedReplacement"):
+            notes.append(f"Mouser suggests replacement {part['SuggestedReplacement']}")
+        on_order = part.get("AvailabilityOnOrder") or []
+        if stock == 0 and on_order:
+            first = on_order[0]
+            notes.append(f"{first.get('Quantity')} on order, expected {first.get('Date')}")
+        offer = SupplierOffer(
+            supplier="Mouser",
+            sku=str(part.get("MouserPartNumber") or ""),
+            stock=stock,
+            price_breaks=breaks,
+            moq=int(moq) if moq.isdigit() else None,
+            multiple=int(mult) if mult.isdigit() else None,
+            lead_time_days=_lead_days(part.get("LeadTime") or ""),
+            packaging="Reel" if part.get("Reeling") else "",
+            lifecycle=lifecycle,
+            authorised=True,
+            url=str(part.get("ProductDetailUrl") or ""),
+            source="mouser",
+            notes=notes,
+        )
+        return PartInfo(
+            mpn=str(part.get("ManufacturerPartNumber") or ""),
+            manufacturer=str(part.get("Manufacturer") or ""),
+            description=str(part.get("Description") or ""),
+            package=attributes.get("Package / Case", ""),
+            category=str(part.get("Category") or ""),
+            stock=stock,
+            stock_by_source={"mouser": stock} if stock is not None else {},
+            price_breaks=breaks,
+            datasheet_url=str(part.get("DataSheetUrl") or ""),
+            product_url=str(part.get("ProductDetailUrl") or ""),
+            lifecycle=lifecycle,
+            attributes=attributes,
+            sources=["mouser"],
+            offers=[offer],
+        )