plex_api.py

"""
Plex Connect REST API Client
Grace Engineering — CNC Tool Management
========================================
Base URL:  https://connect.plex.com/{collection}/{version}/{resource}
Auth:      X-Plex-Connect-Api-Key header (Consumer Key from Developer Portal)
Rate:      200 calls/minute
"""

# bootstrap MUST be imported before anything reads PLEX_API_KEY/SECRET from
# os.environ — it injects values from .env.local (if present) so the dev
# loop doesn't require setting env vars in every shell. Real shell env
# always wins via setdefault semantics.
import bootstrap  # noqa: F401

import requests
import json
import csv
import time
import os
from datetime import datetime

# ─────────────────────────────────────────────
# CONFIGURATION
# ─────────────────────────────────────────────
# All values come from environment variables (loaded via bootstrap.py
# from .env.local). Credentials are never hardcoded or committed.
#
#   PLEX_API_KEY      — Consumer Key from the Plex Developer Portal
#   PLEX_API_SECRET   — Consumer Secret (currently optional — Plex
#                       gateway authenticates on key alone)
#   PLEX_TENANT_ID    — Target tenant UUID. Default is the Grace
#                       Engineering production tenant. Tenant IDs
#                       are not secrets, safe to commit as defaults.
#   PLEX_USE_TEST     — "1" to hit test.connect.plex.com instead of
#                       connect.plex.com (production). Default is False
#                       because the current Fusion2Plex app only exists
#                       in the production environment.
#
# History note: an earlier version of this file hardcoded an old
# Consumer Key and the wrong Grace UUID (a6af9c99-...). Both are dead.
# The verified-working configuration is what's defaulted below.
GRACE_TENANT_ID = "58f781ba-1691-4f32-b1db-381cdb21300c"

API_KEY    = os.environ.get("PLEX_API_KEY", "")
API_SECRET = os.environ.get("PLEX_API_SECRET", "")
TENANT_ID  = os.environ.get("PLEX_TENANT_ID", GRACE_TENANT_ID)

BASE_URL = "https://connect.plex.com"
TEST_URL = "https://test.connect.plex.com"
# PLEX_BASE_URL — explicit override for the Plex base URL (e.g. the local
# mock at tools/plex_mock/server.py running on localhost:8080). Empty
# string means "no override"; BASE_URL / TEST_URL selection applies.
# Used by the write-validation workflow in issue #92 so the sync can
# dress-rehearse against a fake-Plex without touching connect.plex.com.
OVERRIDE_URL = os.environ.get("PLEX_BASE_URL", "").strip()
USE_TEST = os.environ.get("PLEX_USE_TEST", "").strip().lower() in (
    "1", "true", "yes", "on", "enabled",
)

OUTPUT_DIR   = "C:/projects/plex-api/outputs"
TOOL_LIB_DIR = "Z:\\Engineering\\Tooling\\Fusion_Libraries"  # Mapped drive path containing JSON files

# ─────────────────────────────────────────────
# BASE CLIENT
# ─────────────────────────────────────────────
class PlexClient:
    def __init__(self, api_key, api_secret="", tenant_id="", use_test=False, base_url=None):
        # Resolution order:
        #   1. explicit base_url kwarg (tests, ad-hoc scripts)
        #   2. PLEX_BASE_URL env var (deployment-time override — the mock)
        #   3. TEST_URL if use_test else BASE_URL (original behavior)
        explicit = (base_url or "").strip()
        if explicit:
            self.base = explicit
        elif OVERRIDE_URL:
            self.base = OVERRIDE_URL
        else:
            self.base = TEST_URL if use_test else BASE_URL
        self.headers = {
            "X-Plex-Connect-Api-Key": api_key,
            "Content-Type": "application/json",
            "Accept": "application/json",
        }
        if api_secret:
            self.headers["X-Plex-Connect-Api-Secret"] = api_secret
        if tenant_id:
            self.headers["X-Plex-Connect-Tenant-Id"] = tenant_id

        self._call_count = 0
        self._window_start = time.time()

    def _throttle(self):
        """Stay under 200 calls/minute rate limit"""
        self._call_count += 1
        elapsed = time.time() - self._window_start
        if elapsed < 60 and self._call_count >= 190:
            wait = 60 - elapsed
            print(f"  Rate limit approaching — waiting {wait:.1f}s...")
            time.sleep(wait)
            self._call_count = 0
            self._window_start = time.time()
        elif elapsed >= 60:
            self._call_count = 1
            self._window_start = time.time()

    def get(self, collection, version, resource, params=None):
        """
        GET request with auto-throttling.

        Returns the parsed JSON body on success, or None on any failure.
        Backward-compatible legacy interface — callers that need to know
        WHY a request failed (auth error vs network error vs 404 vs JSON
        parse failure) should use ``get_envelope()`` instead.
        """
        env = self.get_envelope(collection, version, resource, params)
        if not env["ok"]:
            # Preserve the historical "log to stdout" behaviour for the
            # legacy callers, then collapse to None.
            print(f"  HTTP Error {env['status']}: {env['url']}")
            if env["body"] is not None:
                snippet = str(env["body"])[:300]
                print(f"  Response: {snippet}")
            return None
        return env["body"]

    def get_envelope(self, collection, version, resource, params=None):
        """
        GET request returning a structured envelope.

        Unlike ``get()`` (which returns parsed JSON on success and None on
        any failure), this method returns a dict so callers can distinguish:

          - successful empty / null responses
          - authentication errors (401, 403)
          - other HTTP errors (404, 5xx, ...)
          - network failures (DNS, timeout, connection refused, ...)
          - JSON parse failures (response was text/html instead of JSON)

        Returns
        -------
        dict
            {
                "ok":         bool,        # True iff response was 2xx
                "status":     int,         # HTTP status; 0 if no response
                "reason":     str,         # HTTP reason phrase or
                                           # exception class name
                "body":       Any,         # parsed JSON if possible,
                                           # else text, else None
                "elapsed_ms": int,
                "url":        str,
                "error":      str | None,  # human-readable error if not ok
            }
        """
        self._throttle()
        url = f"{self.base}/{collection}/{version}/{resource}"
        started = time.perf_counter()

        try:
            r = requests.get(url, headers=self.headers, params=params, timeout=30)
        except requests.exceptions.RequestException as e:
            return {
                "ok": False,
                "status": 0,
                "reason": e.__class__.__name__,
                "body": None,
                "elapsed_ms": int((time.perf_counter() - started) * 1000),
                "url": url,
                "error": str(e),
            }

        elapsed_ms = int((time.perf_counter() - started) * 1000)

        # Try JSON first; fall back to text; fall back to None.
        try:
            body = r.json()
        except ValueError:
            body = r.text or None

        return {
            "ok": r.ok,
            "status": r.status_code,
            "reason": r.reason or "",
            "body": body,
            "elapsed_ms": elapsed_ms,
            "url": r.url,
            "error": None if r.ok else f"HTTP {r.status_code} {r.reason}".strip(),
        }

    def get_paginated(self, collection, version, resource, params=None, limit=100):
        """GET all pages of a paginated endpoint"""
        params = params or {}
        params["limit"] = limit
        params["offset"] = 0
        results = []

        while True:
            data = self.get(collection, version, resource, params)
            if not data:
                break

            # Handle both list and dict responses
            if isinstance(data, list):
                batch = data
            elif isinstance(data, dict):
                # Common Plex patterns: data["items"], data["rows"], or data itself
                batch = (data.get("items") or
                         data.get("rows") or
                         data.get("data") or
                         [data])
            else:
                break

            if not batch:
                break

            results.extend(batch)
            print(f"  Fetched {len(results)} records...")

            if len(batch) < limit:
                break  # last page

            params["offset"] += limit

        return results


# ─────────────────────────────────────────────
# ENDPOINT EXPLORER
# Helps discover what endpoints are available
# and what fields they return
# ─────────────────────────────────────────────
def explore_endpoint(client, collection, version, resource, params=None, max_records=3):
    """
    Fetch a small sample from an endpoint and pretty-print the structure.
    Use this to understand field names before writing extraction code.
    """
    print(f"\n{'='*60}")
    print(f"Exploring: {collection}/{version}/{resource}")
    print(f"{'='*60}")

    params = params or {}
    params["limit"] = max_records

    data = client.get(collection, version, resource, params)

    if data is None:
        print("  No response / endpoint may not exist or not be subscribed")
        return None

    print(f"  Response type: {type(data).__name__}")
    print(f"  Content:\n{json.dumps(data, indent=2)[:2000]}")
    return data


# ─────────────────────────────────────────────
# EXTRACTION FUNCTIONS
# ─────────────────────────────────────────────
def extract_purchase_orders(client, supplier=None, date_from=None):
    """
    Pull PO data — primary source for tool numbers already in system.
    Goal: find all tool-related POs to seed Tool Assembly records.
    """
    print("\nExtracting Purchase Orders...")
    params = {}
    if supplier:
        params["supplier"] = supplier
    if date_from:
        params["updatedAfter"] = f"{date_from}T00:00:00.000Z"

    # Try common Plex PO endpoint patterns
    # Actual endpoint confirmed from developer portal subscription
    results = client.get_paginated("purchasing", "v1", "purchase-orders", params)

    if results:
        out = os.path.join(OUTPUT_DIR, "plex_purchase_orders.csv")
        write_csv(results, out)
        print(f"  Saved {len(results)} POs -> {out}")
    return results


def extract_parts(client, part_type=None):
    """
    Pull part master records.
    Goal: confirm part numbers for Tool BOM linkage.
    """
    print("\nExtracting Parts...")
    params = {}
    if part_type:
        params["type"] = part_type

    results = client.get_paginated("mdm", "v1", "parts", params)

    if results:
        out = os.path.join(OUTPUT_DIR, "plex_parts.csv")
        write_csv(results, out)
        print(f"  Saved {len(results)} parts -> {out}")
    return results


def extract_workcenters(client):
    """
    Pull workcenter records.
    Goal: confirm workcenter codes for Tool BOM Station assignments.
    """
    print("\nExtracting Workcenters...")
    results = client.get_paginated("production", "v1/control", "workcenters")

    if results:
        out = os.path.join(OUTPUT_DIR, "plex_workcenters.csv")
        write_csv(results, out)
        print(f"  Saved {len(results)} workcenters -> {out}")
    return results


def extract_operations(client):
    """
    Pull operation codes.
    Goal: confirm operation codes for Tool BOM and routing linkage.
    """
    print("\nExtracting Operations...")
    results = client.get_paginated("manufacturing", "v1", "operations")

    if results:
        out = os.path.join(OUTPUT_DIR, "plex_operations.csv")
        write_csv(results, out)
        print(f"  Saved {len(results)} operations -> {out}")
    return results


# Category strings used by Plex Grace's supply-items records to identify
# cutting tools and inserts. Verified empirically against the live API
# on 2026-04-07. There are 1,109 such records on the Grace tenant.
TOOLING_CATEGORY = "Tools & Inserts"


def extract_supply_items(client, category=None):
    """
    Pull supply-items from Plex and (by default) filter to cutting tools.

    Issue #2 — read the baseline tooling inventory from Plex.

    Plex Grace stores cutting tools and inserts as ``supply-items`` under
    ``inventory/v1/inventory-definitions/supply-items``, NOT under
    ``mdm/v1/parts`` (which is finished products). The schema is
    identity-only — vendor part number, description, category, group —
    no geometry. Geometry stays in Fusion as the source of truth.

    Server-side query filters on this endpoint are silently ignored, so
    we always pull the full set (~614 KB / 2,516 records on Grace) and
    filter client-side.

    Parameters
    ----------
    client : PlexClient
    category : str | None
        If provided, keep only records whose ``category`` matches.
        Defaults to ``"Tools & Inserts"``. Pass ``""`` (empty string)
        to disable the filter and return everything.

    Returns
    -------
    list[dict] | None
        The matching supply-item records, or None on a network/auth
        failure. Records are also written to
        ``outputs/plex_supply_items.csv`` for diff/snapshot use.
    """
    if category is None:
        category = TOOLING_CATEGORY

    print("\nExtracting Supply Items...")
    raw = client.get("inventory", "v1", "inventory-definitions/supply-items")

    if raw is None:
        print("  No response — credentials, network, or subscription issue")
        return None

    # The response shape is a bare list of dicts (verified empirically)
    if isinstance(raw, dict):
        records = raw.get("data") or raw.get("items") or raw.get("rows") or []
    else:
        records = raw or []

    total = len(records)

    # Client-side filter
    if category:
        records = [r for r in records if r.get("category") == category]
        print(f"  Pulled {total} supply-items, filtered to {len(records)} "
              f"with category={category!r}")
    else:
        print(f"  Pulled {total} supply-items (no filter)")

    if records:
        out = os.path.join(OUTPUT_DIR, "plex_supply_items.csv")
        write_csv(records, out)
        print(f"  Saved {len(records)} supply-items -> {out}")

    return records


# ─────────────────────────────────────────────
# UTILITY
# ─────────────────────────────────────────────
def write_csv(records, filepath):
    """Write list of dicts to CSV, auto-detecting headers"""
    if not records:
        print("  Nothing to write")
        return
    os.makedirs(os.path.dirname(filepath), exist_ok=True)
    headers = list(records[0].keys()) if records else []
    with open(filepath, "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=headers, extrasaction="ignore")
        writer.writeheader()
        writer.writerows(records)


# ─────────────────────────────────────────────
# ENDPOINT DISCOVERY
# Run this first to see what's available
# ─────────────────────────────────────────────
ENDPOINTS_TO_PROBE = [
    # collection        version  resource
    ("purchasing",      "v1",    "purchase-orders"),
    ("purchasing",      "v1",    "purchase-order-lines"),
    ("mdm",             "v1",    "parts"),
    ("production",      "v1/control", "workcenters"),
    ("manufacturing",   "v1",    "operations"),
    ("manufacturing",   "v1",    "routings"),
    ("inventory",       "v1",    "inventory"),
    ("tooling",         "v1",    "tools"),
    ("tooling",         "v1",    "tool-assemblies"),
    ("tooling",         "v1",    "tool-inventory"),
]


def discover_all(client):
    """
    Probe all known endpoint patterns.
    Shows which ones your API subscription covers.
    Saves a discovery report.
    """
    print("\nDiscovering available endpoints...")
    report = []

    for collection, version, resource in ENDPOINTS_TO_PROBE:
        url = f"{client.base}/{collection}/{version}/{resource}"
        client._throttle()
        try:
            r = requests.get(
                url,
                headers=client.headers,
                params={"limit": 1},
                timeout=15
            )
            status = r.status_code
            note = ""
            if status == 200:
                note = "[OK] Available"
            elif status == 401:
                note = "[ERR] Auth error"
            elif status == 403:
                note = "[LOCK] Not subscribed"
            elif status == 404:
                note = "[?] Not found"
            else:
                note = f"[!] HTTP {status}"
        except Exception as e:
            status = 0
            note = f"[ERR] Exception: {e}"

        print(f"  {note:25s} {collection}/{version}/{resource}")
        report.append({
            "Collection": collection,
            "Version": version,
            "Resource": resource,
            "Status": status,
            "Note": note.strip(),
        })
        time.sleep(0.3)  # be polite

    out = os.path.join(OUTPUT_DIR, "plex_api_discovery.csv")
    write_csv(report, out)
    print(f"\nDiscovery report saved -> {out}")
    return report


# ─────────────────────────────────────────────
# MAIN — edit what you want to run
# ─────────────────────────────────────────────
def explore_parts(client):
    """
    Hit the Parts endpoint raw — no params — and dump everything.
    """
    print(f"\n{'='*60}")
    print("PARTS ENDPOINT — RAW RESPONSE")
    print(f"{'='*60}")

    url = f"{client.base}/mdm/v1/parts"
    print(f"\n  GET {url}")
    r = requests.get(url, headers=client.headers, timeout=30)
    print(f"  Status: {r.status_code}")
    print(f"  Content-Type: {r.headers.get('Content-Type')}")

    if r.status_code != 200:
        print(f"  Body: {r.text[:500]}")
        return

    data = r.json()

    # Dump full raw response
    raw = json.dumps(data, indent=2)
    print(f"  Response length: {len(raw)} chars")
    print(f"\n{raw[:5000]}")
    if len(raw) > 5000:
        print(f"\n  ... truncated ({len(raw)} total chars) ...")

    # Save full response to file for inspection
    out = os.path.join(OUTPUT_DIR, "plex_parts_raw.json")
    os.makedirs(os.path.dirname(out), exist_ok=True)
    with open(out, "w", encoding="utf-8") as f:
        json.dump(data, f, indent=2)
    print(f"\n  Full response saved -> {out}")

    return data


if __name__ == "__main__":
    if not API_KEY:
        raise SystemExit(
            "Missing PLEX_API_KEY. Set it in the environment or in .env.local."
        )

    client = PlexClient(
        api_key=API_KEY,
        api_secret=API_SECRET,
        tenant_id=TENANT_ID,
        use_test=USE_TEST,
    )

    print(f"Plex API Client — {'TEST' if USE_TEST else 'PRODUCTION'}")
    print(f"Base URL: {client.base}")
    print(f"Tenant:   {TENANT_ID or '(default)'}")
    print(f"Key:      {API_KEY[:8]}{'*' * 20}")
    print(f"Secret:   {'set' if API_SECRET else '(unset — Plex authenticates on key alone)'}")

    if not USE_TEST:
        print()
        print("WARNING: Connected to PRODUCTION Plex environment.")
        print("         Reads are safe. Writes are blocked at the proxy unless")
        print("         PLEX_ALLOW_WRITES=1 is also set in the environment.")

    # ── Focus: Parts endpoint exploration
    # explore_parts(client)  # NOTE: pulls 19 MB unfiltered — leave commented

    # ── Other exploration (uncomment as needed)
    # discover_all(client)
    # extract_parts(client)
    # explore_endpoint(client, "mdm", "v1", "parts", max_records=2)