shelfshift 1.0.0__py3-none-any.whl

shelfshift/__init__.py

@@ -0,0 +1,48 @@
+"""Public package entrypoint for the Shelfshift engine.
+
+This package provides a stable import surface for core e-commerce catalog
+import/export logic, plus optional frontend adapters (CLI and FastAPI server).
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "Product": ("shelfshift.core", "Product"),
+    "app": ("shelfshift.server.main", "app"),
+    "create_app": ("shelfshift.server.main", "create_app"),
+    "detect_csv_platform": ("shelfshift.core", "detect_csv_platform"),
+    "detect_product_url": ("shelfshift.core", "detect_product_url"),
+    "export_csv_for_target": ("shelfshift.core", "export_csv_for_target"),
+    "import_product_from_csv": ("shelfshift.core", "import_product_from_csv"),
+    "import_product_from_url": ("shelfshift.core", "import_product_from_url"),
+}
+
+try:
+    __version__ = version("shelfshift")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Product",
+    "__version__",
+    "app",
+    "create_app",
+    "detect_csv_platform",
+    "detect_product_url",
+    "export_csv_for_target",
+    "import_product_from_csv",
+    "import_product_from_url",
+]
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY_EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attribute_name = target
+    module = __import__(module_name, fromlist=[attribute_name])
+    value = getattr(module, attribute_name)
+    globals()[name] = value
+    return value

shelfshift/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI frontend for the Shelfshift core engine."""

shelfshift/cli/main.py

@@ -0,0 +1,190 @@
+"""Command-line frontend for the Shelfshift core engine."""
+
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from dotenv import load_dotenv
+
+from shelfshift.core.config import resolve_rapidapi_key
+from shelfshift.core import (
+    convert_csv,
+    detect_csv,
+    detect_url,
+    export_csv,
+    import_csv,
+    import_url,
+    parse_product_payload,
+    validate,
+)
+
+load_dotenv(Path(__file__).resolve().parents[2] / ".env")
+
+
+def _json_dump(data: Any) -> None:
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def _cmd_detect_url(args: argparse.Namespace) -> int:
+    _json_dump(detect_url(args.input).__dict__)
+    return 0
+
+
+def _cmd_detect_csv(args: argparse.Namespace) -> int:
+    _json_dump(detect_csv(args.input).__dict__)
+    return 0
+
+
+def _cmd_import_url(args: argparse.Namespace) -> int:
+    resolved_rapidapi_key = resolve_rapidapi_key(args.rapidapi_key)
+    result = import_url(
+        args.url,
+        strict=args.strict,
+        rapidapi_key=resolved_rapidapi_key,
+    )
+    _json_dump(
+        {
+            "products": [p.to_dict(include_raw=args.include_raw) for p in result.products],
+            "errors": result.errors,
+        }
+    )
+    return 0
+
+
+def _cmd_import_csv(args: argparse.Namespace) -> int:
+    result = import_csv(
+        args.input,
+        platform=args.source_platform,
+        strict=args.strict,
+        source_weight_unit=args.source_weight_unit,
+    )
+    _json_dump(
+        {
+            "products": [p.to_dict(include_raw=args.include_raw) for p in result.products],
+            "errors": result.errors,
+        }
+    )
+    return 0
+
+
+def _cmd_convert(args: argparse.Namespace) -> int:
+    csv_bytes, report = convert_csv(
+        args.input,
+        target=args.to,
+        source=args.source,
+        strict=args.strict,
+        source_weight_unit=args.source_weight_unit,
+        export_options={"weight_unit": args.weight_unit},
+    )
+    out_path = Path(args.out)
+    out_path.write_bytes(csv_bytes)
+    if args.report:
+        Path(args.report).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    _json_dump({"output": str(out_path), "report": report})
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    result = import_csv(
+        args.input,
+        platform=args.platform,
+        strict=args.strict,
+        source_weight_unit=args.source_weight_unit,
+    )
+    reports = validate(result.products)
+    payload = [
+        {
+            "valid": report.valid,
+            "issues": [issue.__dict__ for issue in report.issues],
+        }
+        for report in reports
+    ]
+    if args.report:
+        Path(args.report).write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    _json_dump(payload)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="shelfshift", description="Shelfshift core engine CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    detect = subparsers.add_parser("detect", help="Detect input kind/platform from URL or CSV path")
+    detect.add_argument("input", help="URL or CSV file path")
+    detect.set_defaults(func=lambda args: _cmd_detect_csv(args) if Path(args.input).exists() else _cmd_detect_url(args))
+
+    import_url_cmd = subparsers.add_parser("import-url", help="Import canonical products from one or more URLs")
+    import_url_cmd.add_argument("url", nargs="+", help="One or more product URLs")
+    import_url_cmd.add_argument("--rapidapi-key", default=None)
+    import_url_cmd.add_argument("--include-raw", action="store_true")
+    import_url_cmd.add_argument("--strict", action="store_true")
+    import_url_cmd.set_defaults(func=lambda args: _cmd_import_url(argparse.Namespace(**{**vars(args), "url": args.url if len(args.url) > 1 else args.url[0]})))
+
+    convert = subparsers.add_parser("convert", help="Convert source CSV to target platform CSV")
+    convert.add_argument("input", help="Source CSV file path")
+    convert.add_argument("--to", required=True, choices=["shopify", "bigcommerce", "wix", "squarespace", "woocommerce"])
+    convert.add_argument("--source", default=None)
+    convert.add_argument("--source-weight-unit", default="")
+    convert.add_argument("--weight-unit", default="")
+    convert.add_argument("--strict", action="store_true")
+    convert.add_argument("--out", required=True)
+    convert.add_argument("--report", default="")
+    convert.set_defaults(func=_cmd_convert)
+
+    validate_cmd = subparsers.add_parser("validate", help="Validate canonicalized products imported from source CSV")
+    validate_cmd.add_argument("input", help="Source CSV file path")
+    validate_cmd.add_argument("--platform", default=None)
+    validate_cmd.add_argument("--source-weight-unit", default="")
+    validate_cmd.add_argument("--strict", action="store_true")
+    validate_cmd.add_argument("--report", default="")
+    validate_cmd.set_defaults(func=_cmd_validate)
+
+    import_csv_cmd = subparsers.add_parser("import-csv", help="Import canonical products from source CSV")
+    import_csv_cmd.add_argument("input", help="Source CSV file path")
+    import_csv_cmd.add_argument("--source-platform", default=None)
+    import_csv_cmd.add_argument("--source-weight-unit", default="")
+    import_csv_cmd.add_argument("--include-raw", action="store_true")
+    import_csv_cmd.add_argument("--strict", action="store_true")
+    import_csv_cmd.set_defaults(func=_cmd_import_csv)
+
+    export_csv_cmd = subparsers.add_parser("export-csv", help="Export canonical JSON payload to target CSV")
+    export_csv_cmd.add_argument("input", help="Canonical product JSON path")
+    export_csv_cmd.add_argument("--to", required=True, choices=["shopify", "bigcommerce", "wix", "squarespace", "woocommerce"])
+    export_csv_cmd.add_argument("--weight-unit", default="")
+    export_csv_cmd.add_argument("--out", required=True)
+    export_csv_cmd.add_argument("--report", default="")
+    export_csv_cmd.set_defaults(func=_cmd_export_csv)
+
+    return parser
+
+
+def _cmd_export_csv(args: argparse.Namespace) -> int:
+    payload = json.loads(Path(args.input).read_text(encoding="utf-8"))
+    products = parse_product_payload(payload)
+
+    exported = export_csv(
+        products,
+        target=args.to,
+        options={"weight_unit": args.weight_unit},
+    )
+    Path(args.out).write_bytes(exported.csv_bytes)
+    report = {"filename": exported.filename, "target_platform": args.to}
+    if args.report:
+        Path(args.report).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    _json_dump({"output": args.out, "report": report})
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args) or 0)
+    except Exception as exc:
+        parser.exit(status=2, message=f"error: {exc}\n")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shelfshift/config.py

@@ -0,0 +1,72 @@
+"""Shared runtime settings for server/web adapters.
+
+This module owns environment-backed application settings. It is intentionally
+separate from ``shelfshift.core.config`` because core config stays minimal and
+framework-agnostic.
+"""
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Settings:
+    app_name: str
+    app_tagline: str
+    brand_primary: str
+    brand_secondary: str
+    brand_ink: str
+    debug: bool
+    log_verbosity: str
+    rapidapi_key: str | None
+    cors_allow_origins: tuple[str, ...]
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    val = os.getenv(name)
+    if val is None:
+        return default
+    return val.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _env_choice(name: str, default: str, *, allowed: set[str]) -> str:
+    val = os.getenv(name)
+    if val is None:
+        return default
+    normalized = val.strip().lower()
+    if normalized in allowed:
+        return normalized
+    return default
+
+
+def settings_from_env() -> Settings:
+    origins = tuple(
+        origin.strip()
+        for origin in os.getenv("CORS_ALLOW_ORIGINS", "*").split(",")
+        if origin.strip()
+    )
+    return Settings(
+        app_name=os.getenv("APP_NAME", "ShelfShift"),
+        app_tagline=os.getenv(
+            "APP_TAGLINE",
+            "Developer toolkit for ecommerce catalog translation.",
+        ),
+        brand_primary=os.getenv("BRAND_PRIMARY", "#18d9b6"),
+        brand_secondary=os.getenv("BRAND_SECONDARY", "#27c6f5"),
+        brand_ink=os.getenv("BRAND_INK", "#020b1a"),
+        debug=_env_bool("DEBUG", default=False),
+        log_verbosity=_env_choice(
+            "LOG_VERBOSITY",
+            default="medium",
+            allowed={"low", "medium", "high", "extrahigh"},
+        ),
+        rapidapi_key=os.getenv("RAPIDAPI_KEY"),
+        cors_allow_origins=origins or ("*",),
+    )
+
+
+def get_settings() -> Settings:
+    return settings_from_env()
+
+
+__all__ = ["Settings", "get_settings", "settings_from_env"]

shelfshift/core/__init__.py

@@ -0,0 +1,79 @@
+"""Core engine API.
+
+The core layer is framework-agnostic and safe to import from scripts, tests,
+CLI commands, and web frontends.
+"""
+
+from typing import Any
+
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "CoreConfig": ("shelfshift.core.config", "CoreConfig"),
+    "DetectResult": ("shelfshift.core.api", "DetectResult"),
+    "ExportResult": ("shelfshift.core.api", "ExportResult"),
+    "ImportResult": ("shelfshift.core.api", "ImportResult"),
+    "Product": ("shelfshift.core.canonical.entities", "Product"),
+    "config_from_env": ("shelfshift.core.config", "config_from_env"),
+    "convert_csv": ("shelfshift.core.api", "convert_csv"),
+    "detect_csv": ("shelfshift.core.api", "detect_csv"),
+    "detect_csv_platform": ("shelfshift.core.detect.csv", "detect_csv_platform"),
+    "detect_product_url": ("shelfshift.core.detect.url", "detect_product_url"),
+    "detect_url": ("shelfshift.core.api", "detect_url"),
+    "export_csv": ("shelfshift.core.api", "export_csv"),
+    "export_csv_for_target": ("shelfshift.core.exporters", "export_csv_for_target"),
+    "get_exporter": ("shelfshift.core.registry", "get_exporter"),
+    "get_importer": ("shelfshift.core.registry", "get_importer"),
+    "import_csv": ("shelfshift.core.api", "import_csv"),
+    "import_product_from_csv": ("shelfshift.core.importers.csv", "import_product_from_csv"),
+    "import_product_from_url": ("shelfshift.core.importers.url", "import_product_from_url"),
+    "import_products_from_csv": ("shelfshift.core.importers.csv", "import_products_from_csv"),
+    "import_products_from_urls": ("shelfshift.core.importers.url", "import_products_from_urls"),
+    "import_url": ("shelfshift.core.api", "import_url"),
+    "list_exporters": ("shelfshift.core.registry", "list_exporters"),
+    "list_importers": ("shelfshift.core.registry", "list_importers"),
+    "parse_product_payload": ("shelfshift.core.api", "parse_product_payload"),
+    "register_exporter": ("shelfshift.core.registry", "register_exporter"),
+    "register_importer": ("shelfshift.core.registry", "register_importer"),
+    "validate": ("shelfshift.core.api", "validate"),
+}
+
+__all__ = [
+    "CoreConfig",
+    "DetectResult",
+    "ExportResult",
+    "ImportResult",
+    "Product",
+    "config_from_env",
+    "convert_csv",
+    "detect_csv",
+    "detect_csv_platform",
+    "detect_url",
+    "detect_product_url",
+    "export_csv",
+    "export_csv_for_target",
+    "get_exporter",
+    "get_importer",
+    "import_csv",
+    "import_product_from_csv",
+    "import_product_from_url",
+    "import_products_from_csv",
+    "import_products_from_urls",
+    "import_url",
+    "list_exporters",
+    "list_importers",
+    "parse_product_payload",
+    "register_exporter",
+    "register_importer",
+    "validate",
+]
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY_EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attribute_name = target
+    module = __import__(module_name, fromlist=[attribute_name])
+    value = getattr(module, attribute_name)
+    globals()[name] = value
+    return value

shelfshift/core/api.py

@@ -0,0 +1,227 @@
+"""Stable public API facade for the Shelfshift core engine."""
+
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .canonical.entities import Product
+from .config import CoreConfig, config_from_env, resolve_rapidapi_key
+from .detect import detect_csv_platform as _detect_csv_platform
+from .detect import detect_product_url as _detect_product_url
+from .importers.csv.common import parse_canonical_product_payload
+from .importers.csv import import_product_from_csv, import_products_from_csv
+from .importers.url import import_product_from_url, import_products_from_urls
+from .registry import get_exporter
+from .validate import ValidationReport, validate_product
+
+
+@dataclass(frozen=True)
+class DetectResult:
+    kind: str
+    platform: str | None
+    is_product: bool
+    product_id: str | None = None
+    slug: str | None = None
+
+
+@dataclass
+class ImportResult:
+    products: list[Product] = field(default_factory=list)
+    errors: list[dict[str, str]] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ExportResult:
+    csv_bytes: bytes
+    filename: str
+
+
+def detect_url(url: str) -> DetectResult:
+    payload = _detect_product_url(url)
+    return DetectResult(
+        kind="url",
+        platform=payload.get("platform"),
+        is_product=bool(payload.get("is_product", False)),
+        product_id=payload.get("product_id"),
+        slug=payload.get("slug"),
+    )
+
+
+def detect_csv(csv_input: bytes | str | Path) -> DetectResult:
+    csv_bytes = _coerce_bytes(csv_input)
+    platform = _detect_csv_platform(csv_bytes)
+    return DetectResult(kind="csv", platform=platform, is_product=False)
+
+
+def import_url(
+    urls: str | list[str],
+    *,
+    strict: bool = False,
+    debug: bool = False,
+    rapidapi_key: str | None = None,
+) -> ImportResult:
+    config = config_from_env(strict=strict, debug=debug)
+    resolved_rapidapi_key = resolve_rapidapi_key(rapidapi_key)
+
+    if isinstance(urls, str):
+        product = import_product_from_url(urls, rapidapi_key=resolved_rapidapi_key)
+        return ImportResult(products=[product], errors=[])
+
+    products, errors = import_products_from_urls(
+        list(urls),
+        rapidapi_key=resolved_rapidapi_key,
+    )
+    if config.strict and errors:
+        raise ValueError(f"Strict mode failed with {len(errors)} URL import error(s).")
+    return ImportResult(products=products, errors=errors)
+
+
+def import_csv(
+    csv_input: bytes | str | Path,
+    *,
+    platform: str | None = None,
+    strict: bool = False,
+    source_weight_unit: str | None = None,
+) -> ImportResult:
+    csv_bytes = _coerce_bytes(csv_input)
+    source_platform = (platform or _detect_csv_platform(csv_bytes)).strip().lower()
+    products = import_products_from_csv(
+        source_platform=source_platform,
+        csv_bytes=csv_bytes,
+        source_weight_unit=source_weight_unit,
+    )
+    if strict and not products:
+        raise ValueError("Strict mode failed: no products imported from CSV.")
+    return ImportResult(products=products, errors=[])
+
+
+def export_csv(
+    products: Product | list[Product],
+    *,
+    target: str,
+    options: dict[str, Any] | None = None,
+) -> ExportResult:
+    normalized_target = str(target).strip().lower()
+    opts = dict(options or {})
+
+    publish = bool(opts.get("publish", False))
+    weight_unit = str(opts.get("weight_unit", ""))
+    bigcommerce_csv_format = str(opts.get("bigcommerce_csv_format", "modern"))
+    squarespace_product_page = str(opts.get("squarespace_product_page", ""))
+    squarespace_product_url = str(opts.get("squarespace_product_url", ""))
+
+    try:
+        exporter = get_exporter(normalized_target)
+    except KeyError as exc:
+        raise ValueError(
+            "target_platform must be one of: shopify, bigcommerce, wix, squarespace, woocommerce"
+        ) from exc
+
+    if isinstance(products, list):
+        from .exporters.shared.batch import (
+            products_to_bigcommerce_csv,
+            products_to_shopify_csv,
+            products_to_squarespace_csv,
+            products_to_wix_csv,
+            products_to_woocommerce_csv,
+        )
+
+        if normalized_target == "shopify":
+            csv_text, filename = products_to_shopify_csv(products, publish=publish, weight_unit=weight_unit)
+        elif normalized_target == "bigcommerce":
+            csv_text, filename = products_to_bigcommerce_csv(
+                products,
+                publish=publish,
+                csv_format=bigcommerce_csv_format,
+                weight_unit=weight_unit,
+            )
+        elif normalized_target == "wix":
+            csv_text, filename = products_to_wix_csv(products, publish=publish, weight_unit=weight_unit)
+        elif normalized_target == "squarespace":
+            csv_text, filename = products_to_squarespace_csv(
+                products,
+                publish=publish,
+                product_page=squarespace_product_page,
+                product_url=squarespace_product_url,
+                weight_unit=weight_unit,
+            )
+        elif normalized_target == "woocommerce":
+            csv_text, filename = products_to_woocommerce_csv(products, publish=publish, weight_unit=weight_unit)
+        else:
+            raise ValueError(f"Unsupported target platform: {normalized_target}")
+        return ExportResult(csv_bytes=csv_text.encode("utf-8"), filename=filename)
+
+    csv_text, filename = exporter(
+        products,
+        target_platform=normalized_target,
+        publish=publish,
+        weight_unit=weight_unit,
+        bigcommerce_csv_format=bigcommerce_csv_format,
+        squarespace_product_page=squarespace_product_page,
+        squarespace_product_url=squarespace_product_url,
+    )
+    return ExportResult(csv_bytes=csv_text.encode("utf-8"), filename=filename)
+
+
+def convert_csv(
+    csv_input: bytes | str | Path,
+    *,
+    target: str,
+    source: str | None = None,
+    strict: bool = False,
+    source_weight_unit: str | None = None,
+    export_options: dict[str, Any] | None = None,
+) -> tuple[bytes, dict[str, Any]]:
+    imported = import_csv(
+        csv_input,
+        platform=source,
+        strict=strict,
+        source_weight_unit=source_weight_unit,
+    )
+    exported = export_csv(imported.products, target=target, options=export_options)
+
+    report = {
+        "source_platform": source or _detect_csv_platform(_coerce_bytes(csv_input)),
+        "target_platform": str(target).strip().lower(),
+        "product_count": len(imported.products),
+        "errors": imported.errors,
+        "filename": exported.filename,
+    }
+    return exported.csv_bytes, report
+
+
+def validate(products: Product | list[Product]) -> list[ValidationReport]:
+    if isinstance(products, list):
+        return [validate_product(product) for product in products]
+    return [validate_product(products)]
+
+
+def parse_product_payload(payload: dict[str, Any] | list[dict[str, Any]]) -> Product | list[Product]:
+    if isinstance(payload, list):
+        return [parse_canonical_product_payload(item) for item in payload]
+    return parse_canonical_product_payload(payload)
+
+
+def _coerce_bytes(value: bytes | str | Path) -> bytes:
+    if isinstance(value, bytes):
+        return value
+    path = Path(value)
+    return path.read_bytes()
+
+
+__all__ = [
+    "CoreConfig",
+    "DetectResult",
+    "ExportResult",
+    "ImportResult",
+    "config_from_env",
+    "convert_csv",
+    "detect_csv",
+    "detect_url",
+    "export_csv",
+    "import_csv",
+    "import_url",
+    "parse_product_payload",
+    "validate",
+]

shelfshift/core/canonical/__init__.py

@@ -0,0 +1,60 @@
+from .entities import (
+    CategorySet,
+    Currency,
+    Identifiers,
+    Inventory,
+    Media,
+    MediaType,
+    Money,
+    OptionDef,
+    OptionValue,
+    Price,
+    Product,
+    Seo,
+    SourceRef,
+    Variant,
+    Weight,
+    WeightUnit,
+)
+from .helpers import (
+    format_decimal,
+    normalize_currency,
+    parse_decimal_money,
+    resolve_all_image_urls,
+    resolve_current_money,
+    resolve_option_defs,
+    resolve_primary_image_url,
+    resolve_taxonomy_paths,
+    resolve_variant_option_values,
+)
+from .serialization import serialize_product_for_api, serialize_variant_for_api
+
+__all__ = [
+    "Currency",
+    "CategorySet",
+    "Identifiers",
+    "Inventory",
+    "Media",
+    "MediaType",
+    "Money",
+    "OptionDef",
+    "OptionValue",
+    "Price",
+    "Product",
+    "Seo",
+    "SourceRef",
+    "Variant",
+    "Weight",
+    "WeightUnit",
+    "format_decimal",
+    "normalize_currency",
+    "parse_decimal_money",
+    "resolve_all_image_urls",
+    "resolve_current_money",
+    "resolve_option_defs",
+    "resolve_primary_image_url",
+    "resolve_taxonomy_paths",
+    "resolve_variant_option_values",
+    "serialize_product_for_api",
+    "serialize_variant_for_api",
+]