smx-commerce 0.1.0__tar.gz

smx_commerce-0.1.0/MANIFEST.in

@@ -0,0 +1,30 @@
+include README.md
+include LICENSE
+include pyproject.toml
+
+recursive-include src/smx_commerce/templates *.html
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]
+recursive-exclude * .DS_Store
+recursive-exclude * Thumbs.db
+
+exclude .env
+exclude .env.*
+exclude *.db
+exclude *.sqlite
+exclude *.sqlite3
+
+exclude patch_*.py
+exclude repair_*.py
+exclude fix_*.py
+exclude inspect_*.py
+exclude _tmp_*.py
+
+prune .venv
+prune venv
+prune env
+prune build
+prune dist
+prune data
+prune tests/__pycache__

smx_commerce-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: smx-commerce
+Version: 0.1.0
+Summary: Independent commerce package for Flask and SyntaxMatrix-style applications.
+Requires-Python: >=3.10
+Requires-Dist: Flask>=2.3
+Requires-Dist: SQLAlchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: stripe
+Requires-Dist: stripe>=8.0; extra == "stripe"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"

smx_commerce-0.1.0/README.md

@@ -0,0 +1,88 @@
+# smx-commerce
+
+This is a minimal customer-facing demo app showing how a client project can install and initialize `smx-commerce`.
+
+## Admin token and private admin entry point
+
+Public visitors should not see an Admin button or Admin navigation on the commerce pages.
+
+Admins enter the panel directly through:
+
+```text
+/commerce/admin
+```
+
+If the project has an admin key configured, the system redirects the admin to:
+
+```text
+/commerce/admin/login
+```
+
+The admin must then enter the configured admin key.
+
+### Who creates the admin key?
+
+The project owner creates the admin key. `smx-commerce` does not invent a hidden token.
+
+For local development, copy:
+
+```text
+.env.smx-commerce.example
+```
+
+to:
+
+```text
+.env.smx-commerce
+```
+
+Then set:
+
+```text
+SMX_COMMERCE_ADMIN_API_KEY=<your-admin-token>
+SMX_COMMERCE_FLASK_SECRET_KEY=<your-session-secret>
+```
+
+Generate strong values with:
+
+```powershell
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+Use one generated value for `SMX_COMMERCE_ADMIN_API_KEY` and another generated value for `SMX_COMMERCE_FLASK_SECRET_KEY`.
+
+### Local demo example
+
+For this local demo, the admin page is:
+
+```text
+http://127.0.0.1:5055/commerce/admin
+```
+
+The local key is whatever you set in:
+
+```text
+.env.smx-commerce
+```
+
+### Cloud deployment
+
+For cloud deployment, set the same values as environment variables or secrets in the hosting platform.
+
+Example names:
+
+```text
+SMX_COMMERCE_ADMIN_API_KEY
+SMX_COMMERCE_FLASK_SECRET_KEY
+```
+
+Recommended practice:
+
+```text
+- Store them in a secret manager.
+- Do not hardcode them in source code.
+- Do not commit them to Git.
+- Rotate the admin key if it is exposed.
+```
+
+After changing secrets, restart the app or service so the new values are loaded.

smx_commerce-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smx-commerce"
+version = "0.1.0"
+description = "Independent commerce package for Flask and SyntaxMatrix-style applications."
+requires-python = ">=3.10"
+dependencies = [
+    "Flask>=2.3",
+    "SQLAlchemy>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+stripe = [
+    "stripe>=8.0",
+]
+postgres = [
+    "psycopg[binary]>=3.1",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+smx-commerce = "smx_commerce.cli:main"
+
+[tool.setuptools.package-data]
+smx_commerce = ["templates/**/*.html"]

smx_commerce-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smx_commerce-0.1.0/src/smx_commerce/__init__.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from flask import Blueprint, render_template
+
+from smx_commerce.admin import apply_admin_api_key_guard, create_admin_auth_blueprint, create_admin_home_blueprint, create_settings_admin_blueprint, create_product_edit_admin_blueprint, create_price_edit_admin_blueprint, create_category_edit_admin_blueprint, create_safe_delete_admin_blueprint, create_order_edit_admin_blueprint, create_product_edit_admin_blueprint
+from smx_commerce.catalog.routes_admin import (
+    create_category_admin_blueprint,
+    create_price_admin_blueprint,
+    create_product_admin_blueprint,
+)
+from smx_commerce.catalog.routes_public import create_public_catalog_blueprint
+from smx_commerce.checkout.routes import create_checkout_blueprint
+from smx_commerce.checkout.routes_admin import create_order_admin_blueprint
+from smx_commerce.core import CommerceRuntime
+from smx_commerce.env_config import build_commerce_config_from_env, load_env_file
+from smx_commerce.notifications import (
+    MemoryEmailSender,
+    OrderConfirmationEmailService,
+    SMTPEmailSender,
+)
+from smx_commerce.payments import (
+    LocalCheckoutProvider,
+    PaymentCheckoutProvider,
+    StaticSignatureWebhookVerifier,
+    StripeCheckoutProvider,
+)
+from smx_commerce.payments.routes import create_payment_webhook_blueprint
+from smx_commerce.payments.verifiers import PaymentWebhookVerifier
+
+
+def create_commerce_blueprint(
+    config=None,
+    runtime: CommerceRuntime | None = None,
+    init_schema: bool = False,
+    payment_webhook_verifier: PaymentWebhookVerifier | None = None,
+    payment_checkout_provider: PaymentCheckoutProvider | None = None,
+    order_confirmation_service: OrderConfirmationEmailService | None = None,
+    admin_api_key: str | None = None,
+):
+    commerce_runtime = runtime or CommerceRuntime.from_mapping(config)
+
+    if init_schema:
+        commerce_runtime.init_schema()
+
+    resolved_admin_api_key = admin_api_key
+    if resolved_admin_api_key is None:
+        resolved_admin_api_key = commerce_runtime.config.admin_api_key
+
+    bp = Blueprint("smx_commerce", __name__)
+
+    @bp.get("/commerce/health")
+    def commerce_health():
+        return {
+            "status": "ok",
+            "package": "smx-commerce",
+        }
+
+    @bp.get("/commerce")
+    def commerce_home():
+        return render_template("public/commerce_home.html")
+
+    bp.register_blueprint(create_public_catalog_blueprint(commerce_runtime))
+    bp.register_blueprint(
+        create_checkout_blueprint(
+            commerce_runtime,
+            payment_checkout_provider=payment_checkout_provider,
+        )
+    )
+    bp.register_blueprint(
+        create_payment_webhook_blueprint(
+            commerce_runtime,
+            verifier=payment_webhook_verifier,
+            order_confirmation_service=order_confirmation_service,
+        )
+    )
+
+    admin_bp = Blueprint("smx_commerce_admin", __name__)
+    apply_admin_api_key_guard(admin_bp, resolved_admin_api_key)
+
+    admin_bp.register_blueprint(create_admin_auth_blueprint(resolved_admin_api_key))
+    admin_bp.register_blueprint(create_admin_home_blueprint())
+    admin_bp.register_blueprint(create_category_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_category_edit_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_safe_delete_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_product_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_product_edit_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_price_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_price_edit_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_order_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_order_edit_admin_blueprint(commerce_runtime))
+    admin_bp.register_blueprint(create_settings_admin_blueprint(commerce_runtime))
+
+    bp.register_blueprint(admin_bp, url_prefix="/commerce/admin")
+
+    return bp
+
+
+def init_commerce(app, *, config=None, init_schema: bool = False):
+    resolved_config = config or {}
+
+    if resolved_config.get("flask_secret_key") and not app.secret_key:
+        app.config["SECRET_KEY"] = resolved_config["flask_secret_key"]
+
+    app.register_blueprint(
+        create_commerce_blueprint(
+            config=resolved_config,
+            init_schema=init_schema,
+            payment_checkout_provider=_build_checkout_provider(resolved_config),
+            payment_webhook_verifier=_build_webhook_verifier(resolved_config),
+            order_confirmation_service=_build_order_confirmation_service(resolved_config),
+        )
+    )
+
+    return app
+
+
+def init_commerce_from_env(
+    app,
+    *,
+    env_file: str = ".env.smx-commerce",
+    init_schema: bool = False,
+    prefix: str = "SMX_COMMERCE_",
+):
+    config = build_commerce_config_from_env(
+        env_file=env_file,
+        prefix=prefix,
+    )
+
+    return init_commerce(
+        app,
+        config=config,
+        init_schema=init_schema,
+    )
+
+
+def _build_checkout_provider(config: dict):
+    provider = config.get("payment_provider")
+
+    if provider in {None, "", "none"}:
+        return None
+
+    if provider == "local":
+        return LocalCheckoutProvider(
+            checkout_base_url=config.get(
+                "local_checkout_base_url",
+                "https://local-payments.invalid/checkout",
+            )
+        )
+
+    if provider == "stripe":
+        return StripeCheckoutProvider(
+            api_key=config["stripe_secret_key"],
+        )
+
+    raise ValueError(f"unsupported payment_provider: {provider}")
+
+
+def _build_webhook_verifier(config: dict):
+    provider = config.get("payment_provider")
+
+    if provider in {None, "", "none"}:
+        return None
+
+    if provider == "local":
+        return StaticSignatureWebhookVerifier(
+            expected_signature=config.get("local_webhook_signature", "local-signature"),
+        )
+
+    if provider == "stripe":
+        return __import__(
+            "smx_commerce.payments",
+            fromlist=["StripeWebhookVerifier"],
+        ).StripeWebhookVerifier(
+            webhook_secret=config["stripe_webhook_secret"],
+        )
+
+    raise ValueError(f"unsupported payment_provider: {provider}")
+
+
+def _build_order_confirmation_service(config: dict):
+    email_provider = config.get("email_provider")
+
+    if email_provider in {None, "", "none"}:
+        return None
+
+    if email_provider == "memory":
+        sender = MemoryEmailSender()
+    elif email_provider == "smtp":
+        sender = SMTPEmailSender(
+            host=config["smtp_host"],
+            port=int(config.get("smtp_port", 587)),
+            default_from_email=config.get("default_from_email"),
+            username=config.get("smtp_username"),
+            password=config.get("smtp_password"),
+            use_tls=bool(config.get("smtp_use_tls", True)),
+            use_ssl=bool(config.get("smtp_use_ssl", False)),
+        )
+    else:
+        raise ValueError(f"unsupported email_provider: {email_provider}")
+
+    return OrderConfirmationEmailService(
+        sender,
+        from_email=config.get("default_from_email"),
+        brand_name=config.get("brand_name", "smx-commerce"),
+    )
+
+
+__all__ = [
+    "build_commerce_config_from_env",
+    "create_commerce_blueprint",
+    "init_commerce",
+    "init_commerce_from_env",
+    "load_env_file",
+]

smx_commerce-0.1.0/src/smx_commerce/admin/__init__.py

@@ -0,0 +1,31 @@
+from .home import create_admin_home_blueprint
+from .auth import (
+    ADMIN_KEY_HEADER,
+    ADMIN_SESSION_KEY,
+    apply_admin_api_key_guard,
+    create_admin_auth_blueprint,
+)
+from .routes import create_settings_admin_blueprint
+from .product_edit import create_product_edit_admin_blueprint
+
+__all__ = [
+    "create_order_edit_admin_blueprint",
+    "create_safe_delete_admin_blueprint",
+    "create_category_edit_admin_blueprint",
+    "create_price_edit_admin_blueprint",
+    "ADMIN_KEY_HEADER",
+    "ADMIN_SESSION_KEY",
+    "apply_admin_api_key_guard",
+    "create_admin_auth_blueprint",
+    "create_admin_home_blueprint",
+    "create_settings_admin_blueprint",
+    "create_product_edit_admin_blueprint",
+]
+
+from .price_edit import create_price_edit_admin_blueprint
+
+from .category_edit import create_category_edit_admin_blueprint
+
+from .safe_delete import create_safe_delete_admin_blueprint
+
+from .order_edit import create_order_edit_admin_blueprint

smx_commerce-0.1.0/src/smx_commerce/admin/amounts.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
+
+
+def parse_admin_amount_to_cents(value: str, *, field_name: str = "amount") -> int:
+    raw_value = str(value or "").strip()
+
+    if not raw_value:
+        raise ValueError(f"{field_name} is required")
+
+    try:
+        amount = Decimal(raw_value)
+    except InvalidOperation as exc:
+        raise ValueError(f"{field_name} must be a valid currency amount") from exc
+
+    if amount < 0:
+        raise ValueError(f"{field_name} cannot be negative")
+
+    cents = (amount * Decimal("100")).quantize(
+        Decimal("1"),
+        rounding=ROUND_HALF_UP,
+    )
+
+    return int(cents)
+
+
+def parse_admin_price_amount_from_payload(payload: dict, *, is_form: bool) -> int:
+    """
+    Browser forms should send amount_major, for example:
+      1     -> 100
+      1.50  -> 150
+      299   -> 29900
+
+    JSON/API callers keep using amount_cents.
+
+    For temporary backwards compatibility, form submissions that still send
+    amount_cents are also accepted.
+    """
+    if is_form:
+        amount_major = payload.get("amount_major")
+
+        if amount_major not in {None, ""}:
+            return parse_admin_amount_to_cents(amount_major, field_name="amount")
+
+        if payload.get("amount_cents") not in {None, ""}:
+            return int(payload.get("amount_cents", 0) or 0)
+
+        return parse_admin_amount_to_cents("", field_name="amount")
+
+    return int(payload.get("amount_cents", 0) or 0)

smx_commerce-0.1.0/src/smx_commerce/admin/auth.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from hmac import compare_digest
+
+from flask import Blueprint, current_app, jsonify, redirect, render_template, request, session, url_for
+
+
+ADMIN_KEY_HEADER = "X-SMX-Commerce-Admin-Key"
+ADMIN_SESSION_KEY = "smx_commerce_admin_authenticated"
+
+
+def apply_admin_api_key_guard(bp: Blueprint, admin_api_key: str | None) -> None:
+    """
+    Protect admin routes when admin_api_key is configured.
+
+    Accepted auth methods:
+    1. X-SMX-Commerce-Admin-Key header, useful for API clients/tests.
+    2. Session login through /commerce/admin/login, useful for browser admin UX.
+
+    If no key is configured, the guard is inactive.
+    """
+    if not admin_api_key:
+        return
+
+    expected_key = admin_api_key.strip()
+
+    @bp.before_request
+    def require_admin_auth():
+        if _is_auth_route():
+            return None
+
+        supplied_key = request.headers.get(ADMIN_KEY_HEADER, "")
+
+        if supplied_key and compare_digest(supplied_key, expected_key):
+            return None
+
+        if session.get(ADMIN_SESSION_KEY) is True:
+            return None
+
+        if _wants_html():
+            return redirect(url_for("smx_commerce.smx_commerce_admin.smx_commerce_admin_auth.login"))
+
+        return jsonify({"error": "admin authentication required"}), 401
+
+    return None
+
+
+def create_admin_auth_blueprint(admin_api_key: str | None) -> Blueprint:
+    bp = Blueprint(
+        "smx_commerce_admin_auth",
+        __name__,
+        template_folder="../templates",
+    )
+
+    @bp.get("/login")
+    def login():
+        if not admin_api_key:
+            return jsonify({"status": "ok", "message": "admin authentication is not configured"})
+
+        if request.accept_mimetypes.best_match(["text/html", "application/json"]) == "text/html":
+            return render_template("admin/login.html")
+
+        return jsonify({"status": "ok", "message": "admin login is available"})
+
+    @bp.post("/login")
+    def submit_login():
+        if not admin_api_key:
+            return jsonify({"status": "ok", "message": "admin authentication is not configured"})
+
+        if not current_app.secret_key:
+            return jsonify({"error": "Flask secret_key is required for admin session login"}), 500
+
+        payload = request.get_json(silent=True) or {}
+        supplied_key = request.form.get("admin_api_key") or payload.get("admin_api_key") or ""
+
+        if not compare_digest(supplied_key, admin_api_key):
+            if _wants_html():
+                return render_template("admin/login.html", error="Invalid admin key"), 401
+
+            return jsonify({"error": "invalid admin key"}), 401
+
+        session[ADMIN_SESSION_KEY] = True
+
+        if _wants_html():
+            return redirect("/commerce/admin/products", code=303)
+
+        return jsonify({"status": "ok", "authenticated": True})
+
+    @bp.post("/logout")
+    def logout():
+        session.pop(ADMIN_SESSION_KEY, None)
+
+        if _wants_html():
+            return redirect("/commerce/admin/login", code=303)
+
+        return jsonify({"status": "ok", "authenticated": False})
+
+    return bp
+
+
+def _is_auth_route() -> bool:
+    path = request.path.rstrip("/")
+    return path.endswith("/commerce/admin/login") or path.endswith("/commerce/admin/logout")
+
+
+def _wants_html() -> bool:
+    content_type = request.content_type or ""
+
+    if "application/x-www-form-urlencoded" in content_type:
+        return True
+
+    if "multipart/form-data" in content_type:
+        return True
+
+    return request.accept_mimetypes.best_match(["text/html", "application/json"]) == "text/html"

smx_commerce-0.1.0/src/smx_commerce/admin/category_edit.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from flask import Blueprint, jsonify, redirect, render_template, request
+
+from smx_commerce.catalog import CatalogService
+from smx_commerce.core import CommerceRuntime
+
+
+def create_category_edit_admin_blueprint(runtime: CommerceRuntime) -> Blueprint:
+    bp = Blueprint("smx_commerce_category_edit_admin", __name__)
+
+    @bp.get("/categories/<slug>/edit")
+    def edit_category(slug: str):
+        with runtime.session_scope() as session:
+            catalog = CatalogService(session)
+            category = catalog.get_category(slug)
+            categories = catalog.list_categories(include_archived=False)
+
+        if category is None:
+            return jsonify({"error": f"category not found: {slug}"}), 404
+
+        parent_options = [
+            item for item in categories
+            if item.slug != category.slug
+        ]
+
+        return render_template(
+            "admin/category_edit.html",
+            category=category,
+            parent_options=parent_options,
+        )
+
+    @bp.post("/categories/<slug>/update")
+    def update_category_from_form(slug: str):
+        payload = request.form
+
+        parent_slug = payload.get("parent_slug") or None
+
+        if parent_slug == slug:
+            parent_slug = None
+
+        changes = {
+            "name": payload.get("name", ""),
+            "description": payload.get("description", ""),
+            "status": payload.get("status", "active"),
+            "parent_slug": parent_slug,
+            "sort_order": int(payload.get("sort_order", 0) or 0),
+        }
+
+        try:
+            with runtime.session_scope() as session:
+                catalog = CatalogService(session)
+                updated = catalog.update_category(slug, **changes)
+
+            return redirect("/commerce/admin/categories", code=303)
+
+        except (TypeError, ValueError) as exc:
+            with runtime.session_scope() as session:
+                catalog = CatalogService(session)
+                category = catalog.get_category(slug)
+                categories = catalog.list_categories(include_archived=False)
+
+            if category is None:
+                return jsonify({"error": f"category not found: {slug}"}), 404
+
+            parent_options = [
+                item for item in categories
+                if item.slug != category.slug
+            ]
+
+            return render_template(
+                "admin/category_edit.html",
+                category=category,
+                parent_options=parent_options,
+                error=str(exc),
+            ), 400
+
+    return bp

smx_commerce-0.1.0/src/smx_commerce/admin/home.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from flask import Blueprint, redirect
+
+
+def create_admin_home_blueprint() -> Blueprint:
+    bp = Blueprint("smx_commerce_admin_home", __name__)
+
+    @bp.get("/", strict_slashes=False)
+    def admin_home():
+        return redirect("/commerce/admin/products", code=303)
+
+    return bp