amazon-sp-cli 0.1.5__tar.gz → 0.2.1__tar.gz

{amazon_sp_cli-0.1.5/amazon_sp_cli.egg-info → amazon_sp_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amazon-sp-cli
-Version: 0.1.5
+Version: 0.2.1
 Summary: CLI tool for Amazon Selling Partner API (SP-API) operations
 Home-page: https://github.com/stellaraether/amazon-sp-cli
 Author: Lunan Li

amazon_sp_cli-0.2.1/README.md

@@ -0,0 +1,138 @@
+# Amazon SP-API CLI
+
+Command line interface for Amazon Selling Partner API (SP-API) operations.
+
+## Features
+
+- **Pricing Management** — Get/set prices, create discounts
+- **Listing Operations** — View and update listings
+- **Catalog Lookup** — Check competitor ASINs
+- **Inventory Checks** — View FBA inventory levels
+- **Feed Submissions** — Bulk updates via feeds API
+- **A+ Content** — Manage A+ Content documents and image uploads (requires Brand Registry)
+
+## Installation
+
+```bash
+pip install amazon-sp-cli
+```
+
+## Setup
+
+Create credentials file at `~/.config/amazon-sp-cli/credentials.yml`:
+
+```yaml
+version: '1.0'
+
+default:
+  refresh_token: "your-refresh-token"
+  client_id: "your-client-id"
+  client_secret: "your-client-secret"
+  aws_access_key_id: "your-aws-access-key"
+  aws_secret_access_key: "your-aws-secret-key"
+  seller_id: "your-seller-id"
+  marketplace_id: "ATVPDKIKX0DER"  # US marketplace
+```
+
+## Usage
+
+### Pricing
+
+```bash
+# Get current price
+amz-sp get-price PAW2603190101-BLU
+
+# Set new price
+amz-sp set-price PAW2603190101-BLU 11.99
+
+# Create sale price feed JSON
+amz-sp sale-price PAW2603190101-BLU 23
+
+# Create discount feed JSON (legacy)
+amz-sp create-discount PAW2603190101-BLU 23
+```
+
+### Catalog
+
+```bash
+# Check competitor
+amz-sp check-competitors B0GW72JGWK
+```
+
+### A+ Content
+
+Requires Brand Registry.
+
+```bash
+# Upload an image (returns uploadDestinationId)
+amz-sp a-plus upload-image banner.jpg
+
+# Create content from JSON
+amz-sp a-plus create my-content --data content.json
+
+# Validate without creating
+amz-sp a-plus validate my-content --data content.json
+
+# Get content details (includes approval status)
+amz-sp a-plus get my-content
+
+# List all content documents
+amz-sp a-plus list
+
+# Update content
+amz-sp a-plus update my-content --data content.json
+
+# Delete content
+amz-sp a-plus delete my-content
+
+# Associate ASINs
+amz-sp a-plus asin add my-content B123456789 B987654321
+
+# List associated ASINs
+amz-sp a-plus asin list my-content
+
+# Remove ASIN associations
+amz-sp a-plus asin remove my-content B123456789
+```
+
+## Development
+
+```bash
+# Clone repo
+git clone https://github.com/stellaraether/amazon-sp-cli.git
+cd amazon-sp-cli
+
+# One-shot setup (creates venv, installs deps, sets up pre-commit)
+./setup.sh
+source .venv/bin/activate
+
+# Or manually
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements-dev.txt
+pre-commit install
+
+# Run locally
+python3 -m amazon_sp_cli get-price PAW2603190101-BLU
+```
+
+## Releasing
+
+This repository uses automated releases. To publish a new version:
+
+1. Open a **standalone PR** that only bumps `version` in `setup.py`.
+2. The PR must not include code, test, or documentation changes — a CI check enforces this.
+3. Once the PR is merged to `main`, the `Auto Release` workflow detects the new version, creates a tag (e.g. `v0.2.1`), and pushes it.
+4. The tag push triggers the `Publish to PyPI` workflow, which runs the full test suite and publishes the package.
+
+Do not create tags manually.
+
+## Requirements
+
+- Python 3.8+
+- Amazon SP-API credentials
+- AWS IAM user with SP-API access
+
+## License
+
+MIT

amazon_sp_cli-0.2.1/amazon_sp_cli/cli.py

@@ -0,0 +1,92 @@
+"""Core CLI infrastructure and shared utilities."""
+
+import functools
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+from .auth import SPAPIAuth
+from .client import SPAPIClient
+
+DEFAULT_CREDENTIALS_PATH = os.path.expanduser("~/.config/amazon-sp-cli/credentials.yml")
+
+
+def _check_path():
+    """Check if the CLI is accessible in PATH and warn once per day."""
+    import shutil
+
+    if shutil.which("amz-sp"):
+        return
+
+    # Only warn once per day
+    flag_file = Path.home() / ".config" / "amazon-sp-cli" / ".path-warned"
+    flag_file.parent.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now(timezone.utc)
+    today = now.strftime("%Y-%m-%d")
+
+    if flag_file.exists():
+        last_warned = flag_file.read_text().strip()
+        if last_warned == today:
+            return
+
+    flag_file.write_text(today)
+
+    print(
+        "\n⚠️  Note: 'amz-sp' is not in your PATH.",
+        file=sys.stderr,
+    )
+    print(
+        "   You can still use: python3 -m amazon_sp_cli",
+        file=sys.stderr,
+    )
+    print(
+        "   To add to PATH, add this to your shell config:",
+        file=sys.stderr,
+    )
+    print(
+        f'   export PATH="{sys.prefix}/bin:$PATH"',
+        file=sys.stderr,
+    )
+    print("", file=sys.stderr)
+
+
+def _ensure_auth_client(ctx):
+    """Lazily create auth and client if not already present."""
+    if "client" not in ctx.obj:
+        auth = SPAPIAuth(ctx.obj.get("credentials_path"))
+        if auth.credentials is None:
+            click.echo("Error: No credentials found. Run 'amz-sp auth setup' first.", err=True)
+            raise click.Abort()
+        ctx.obj["auth"] = auth
+        ctx.obj["client"] = SPAPIClient(auth)
+    return ctx.obj["auth"], ctx.obj["client"]
+
+
+def handle_errors(f):
+    """Decorator to catch exceptions and emit consistent error messages."""
+
+    @functools.wraps(f)
+    def wrapper(*args, **kwargs):
+        try:
+            return f(*args, **kwargs)
+        except click.ClickException:
+            raise
+        except Exception as e:
+            click.echo(f"Error: {e}", err=True)
+            raise click.Abort()
+
+    return wrapper
+
+
+@click.group()
+@click.option("--credentials", "-c", help="Path to credentials YAML file")
+@click.pass_context
+def cli(ctx, credentials):
+    """Amazon SP-API CLI - Manage listings, pricing, inventory, and more."""
+    _check_path()
+    ctx.ensure_object(dict)
+    ctx.obj["credentials_path"] = credentials

amazon_sp_cli-0.2.1/amazon_sp_cli/client.py

@@ -0,0 +1,191 @@
+"""Amazon SP-API client with AWS SigV4 signing."""
+
+import json
+from urllib.parse import urlencode
+
+import requests
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+from botocore.credentials import Credentials
+
+
+class SPAPIClient:
+    """Client for making signed requests to Amazon SP-API."""
+
+    HOST = "sellingpartnerapi-na.amazon.com"
+    REGION = "us-east-1"
+    SERVICE = "execute-api"
+
+    def __init__(self, auth, aws_access_key: str = None, aws_secret_key: str = None):
+        self.auth = auth
+        self.credentials = auth.credentials
+        self.aws_access_key = aws_access_key or self.credentials.get("aws_access_key_id")
+        self.aws_secret_key = aws_secret_key or self.credentials.get("aws_secret_access_key")
+        self.marketplace_id = self.credentials.get("marketplace_id", "ATVPDKIKX0DER")
+        self.seller_id = self.credentials.get("seller_id")
+
+    def _sign_request(self, method: str, path: str, data: dict = None) -> dict:
+        """Create signed request headers."""
+        access_token = self.auth.get_access_token()
+
+        headers = {
+            "x-amz-access-token": access_token,
+            "accept": "application/json",
+        }
+
+        if data is not None:
+            headers["content-type"] = "application/json"
+
+        # Create the request
+        url = f"https://{self.HOST}{path}"
+        body = json.dumps(data) if data is not None else ""
+
+        # Create AWS request for signing
+        request = AWSRequest(method=method, url=url, headers=headers, data=body)
+
+        # Sign with SigV4
+        credentials = Credentials(self.aws_access_key, self.aws_secret_key)
+        signer = SigV4Auth(credentials, self.SERVICE, self.REGION)
+        signer.add_auth(request)
+
+        return dict(request.headers), request.url, body
+
+    def request(self, method: str, path: str, data: dict = None) -> dict:
+        """Make a signed request to SP-API."""
+        headers, url, body = self._sign_request(method, path, data)
+
+        response = requests.request(method, url, headers=headers, data=body)
+        response.raise_for_status()
+
+        return response.json() if response.text else {}
+
+    def get_listing(self, sku: str) -> dict:
+        """Get listing information for a SKU."""
+        path = f"/listings/2021-08-01/items/{self.seller_id}/{sku}"
+        params = {
+            "marketplaceIds": self.marketplace_id,
+            "includedData": "summaries,attributes",
+        }
+        path += "?" + urlencode(params)
+        return self.request("GET", path)
+
+    def update_price(self, sku: str, price: float, mode: str = "VALIDATION_PREVIEW") -> dict:
+        """Update listing price."""
+        path = f"/listings/2021-08-01/items/{self.seller_id}/{sku}"
+        params = {
+            "marketplaceIds": self.marketplace_id,
+        }
+        if mode:
+            params["mode"] = mode
+        path += "?" + urlencode(params)
+
+        data = {
+            "productType": "PET_TOY",
+            "requirements": "LISTING_OFFER_ONLY",
+            "attributes": {
+                "condition_type": [{"value": "new_new"}],
+                "item_name": [{"value": "Placeholder"}],
+                "list_price": [{"currency": "USD", "value": price}],
+                "purchasable_price": [{"currency": "USD", "value": price}],
+            },
+        }
+
+        return self.request("PUT", path, data)
+
+    def get_catalog_item(self, asin: str) -> dict:
+        """Get catalog item details."""
+        path = f"/catalog/2022-04-01/items/{asin}"
+        params = {
+            "marketplaceIds": self.marketplace_id,
+            "includedData": "attributes,salesRanks",
+        }
+        path += "?" + urlencode(params)
+        return self.request("GET", path)
+
+    # --- A+ Content API ---
+
+    def _add_marketplace_param(self, path: str) -> str:
+        """Append marketplaceId query param to A+ Content paths."""
+        separator = "&" if "?" in path else "?"
+        return f"{path}{separator}marketplaceId={self.marketplace_id}"
+
+    def create_a_plus_content(self, content_data: dict) -> dict:
+        """Create A+ Content document."""
+        path = self._add_marketplace_param("/aplus/2020-11-01/contentDocuments")
+        data = {"contentDocument": content_data}
+        return self.request("POST", path, data)
+
+    def validate_a_plus_content(self, content_data: dict) -> dict:
+        """Validate A+ Content without creating."""
+        path = "/aplus/2020-11-01/contentDocuments"
+        params = {"mode": "VALIDATION_PREVIEW", "marketplaceId": self.marketplace_id}
+        path += "?" + urlencode(params)
+        data = {"contentDocument": content_data}
+        return self.request("POST", path, data)
+
+    def update_a_plus_content(self, content_name: str, content_data: dict) -> dict:
+        """Update existing A+ Content document."""
+        path = self._add_marketplace_param(f"/aplus/2020-11-01/contentDocuments/{content_name}")
+        data = {"contentDocument": content_data}
+        return self.request("POST", path, data)
+
+    def get_a_plus_content(self, content_name: str) -> dict:
+        """Get A+ Content document by name."""
+        path = f"/aplus/2020-11-01/contentDocuments/{content_name}"
+        params = {"marketplaceId": self.marketplace_id, "includedDataSet": "CONTENTS"}
+        path += "?" + urlencode(params)
+        return self.request("GET", path)
+
+    def list_a_plus_content(self, **filters) -> dict:
+        """List A+ Content documents."""
+        path = "/aplus/2020-11-01/contentDocuments"
+        params = {"marketplaceId": self.marketplace_id}
+        params.update(filters)
+        path += "?" + urlencode(params)
+        return self.request("GET", path)
+
+    def suspend_a_plus_content(self, content_reference_key: str) -> dict:
+        """Suspend A+ Content document (API does not support delete)."""
+        path = f"/aplus/2020-11-01/contentDocuments/{content_reference_key}/suspendSubmissions"
+        params = {"marketplaceId": self.marketplace_id}
+        path += "?" + urlencode(params)
+        return self.request("POST", path)
+
+    def get_a_plus_content_asin_relations(self, content_name: str) -> dict:
+        """Get ASIN relations for a content document."""
+        path = self._add_marketplace_param(f"/aplus/2020-11-01/contentDocuments/{content_name}/asins")
+        return self.request("GET", path)
+
+    def post_a_plus_content_asin_relations(self, content_name: str, asin_set: list) -> dict:
+        """Associate ASINs with A+ Content document."""
+        path = self._add_marketplace_param("/aplus/2020-11-01/contentAsinRelations")
+        data = {"contentDocumentName": content_name, "asinSet": asin_set}
+        return self.request("POST", path, data)
+
+    def delete_a_plus_content_asin_relations(self, content_name: str, asin_set: list) -> dict:
+        """Remove ASIN associations from A+ Content document."""
+        path = "/aplus/2020-11-01/contentAsinRelations"
+        params = {"contentDocumentName": content_name, "marketplaceId": self.marketplace_id}
+        path += "?" + urlencode(params)
+        data = {"asinSet": asin_set}
+        return self.request("DELETE", path, data)
+
+    def create_upload_destination(
+        self,
+        marketplace_id: str,
+        content_md5: str,
+        content_type: str,
+        file_name: str = None,
+        resource: str = None,
+    ) -> dict:
+        """Create an upload destination for a file."""
+        path = f"/uploads/2020-11-01/uploadDestinations/{resource}"
+        params = {
+            "marketplaceIds": marketplace_id,
+            "contentMD5": content_md5,
+            "contentType": content_type,
+        }
+        if file_name:
+            params["fileName"] = file_name
+        path += "?" + urlencode(params)
+        return self.request("POST", path)

amazon_sp_cli-0.2.1/amazon_sp_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""

amazon_sp_cli-0.2.1/amazon_sp_cli/commands/a_plus.py

@@ -0,0 +1,239 @@
+"""A+ Content CLI commands."""
+
+import base64
+import hashlib
+import json
+import os
+import urllib.parse
+
+import click
+import requests
+
+from ..cli import handle_errors
+from ..models.a_plus import build_content_from_json
+
+
+def register_a_plus_commands(cli_group, ensure_auth_client):
+    """Register A+ Content CLI commands."""
+
+    @cli_group.group("a-plus")
+    def a_plus():
+        """A+ Content management (requires Brand Registry)."""
+        pass
+
+    @a_plus.command("create")
+    @click.argument("content-name")
+    @click.option("--data", "-d", type=click.Path(exists=True), required=True, help="JSON file with content data")
+    @click.option("--dry-run", is_flag=True, help="Validate without creating")
+    @click.pass_context
+    @handle_errors
+    def create_content(ctx, content_name, data, dry_run):
+        """Create A+ Content document from JSON file."""
+        _, client = ensure_auth_client(ctx)
+
+        with open(data, "r") as f:
+            content_data = json.load(f)
+
+        content = build_content_from_json(content_name, content_data)
+
+        issues = content.validate()
+        if issues:
+            click.echo("Validation issues:", err=True)
+            for issue in issues:
+                click.echo(f"  - {issue}", err=True)
+            raise click.Abort()
+
+        if dry_run:
+            click.echo("Content is valid (dry run)")
+            click.echo(json.dumps(content.to_dict(), indent=2))
+            return
+
+        response = client.create_a_plus_content(content.to_dict())
+        click.echo(f"A+ Content created: {content_name}")
+        click.echo(f"Modules: {len(content.content_module_list)}")
+        if response:
+            click.echo(json.dumps(response, indent=2))
+
+    @a_plus.command("validate")
+    @click.argument("content-name")
+    @click.option("--data", "-d", type=click.Path(exists=True), required=True, help="JSON file with content data")
+    @click.pass_context
+    @handle_errors
+    def validate_content(ctx, content_name, data):
+        """Validate A+ Content without creating."""
+        _, client = ensure_auth_client(ctx)
+
+        with open(data, "r") as f:
+            content_data = json.load(f)
+
+        content = build_content_from_json(content_name, content_data)
+
+        issues = content.validate()
+        if issues:
+            click.echo("Validation issues:", err=True)
+            for issue in issues:
+                click.echo(f"  - {issue}", err=True)
+            raise click.Abort()
+
+        response = client.validate_a_plus_content(content.to_dict())
+        click.echo("API validation passed")
+        if response:
+            click.echo(json.dumps(response, indent=2))
+
+    @a_plus.command("get")
+    @click.argument("content-reference-key")
+    @click.pass_context
+    @handle_errors
+    def get_content(ctx, content_reference_key):
+        """Get A+ Content document by contentReferenceKey."""
+        _, client = ensure_auth_client(ctx)
+        response = client.get_a_plus_content(content_reference_key)
+        click.echo(json.dumps(response, indent=2))
+
+    @a_plus.command("list")
+    @click.pass_context
+    @handle_errors
+    def list_content(ctx):
+        """List A+ Content documents."""
+        _, client = ensure_auth_client(ctx)
+        response = client.list_a_plus_content(marketplaceId=client.marketplace_id)
+        documents = response.get("contentDocumentList", [])
+        click.echo(f"\nA+ Content Documents ({len(documents)} found):\n")
+        for doc in documents:
+            click.echo(f"  Name: {doc.get('name')}")
+            click.echo(f"  Status: {doc.get('status', 'N/A')}")
+            click.echo(f"  Locale: {doc.get('locale', 'N/A')}")
+            asins = doc.get("asinSet", [])
+            if asins:
+                click.echo(f"  ASINs: {', '.join(asins)}")
+            click.echo()
+
+    @a_plus.command("update")
+    @click.argument("content-name")
+    @click.option("--data", "-d", type=click.Path(exists=True), required=True, help="JSON file with updated content")
+    @click.pass_context
+    @handle_errors
+    def update_content(ctx, content_name, data):
+        """Update existing A+ Content document."""
+        _, client = ensure_auth_client(ctx)
+
+        with open(data, "r") as f:
+            content_data = json.load(f)
+
+        content = build_content_from_json(content_name, content_data)
+
+        issues = content.validate()
+        if issues:
+            click.echo("Validation issues:", err=True)
+            for issue in issues:
+                click.echo(f"  - {issue}", err=True)
+            raise click.Abort()
+
+        response = client.update_a_plus_content(content_name, content.to_dict())
+        click.echo(f"A+ Content updated: {content_name}")
+        if response:
+            click.echo(json.dumps(response, indent=2))
+
+    @a_plus.command("suspend")
+    @click.argument("content-reference-key")
+    @click.confirmation_option(prompt="Suspend this A+ Content?")
+    @click.pass_context
+    @handle_errors
+    def suspend_content(ctx, content_reference_key):
+        """Suspend A+ Content document (API does not support delete)."""
+        _, client = ensure_auth_client(ctx)
+        client.suspend_a_plus_content(content_reference_key)
+        click.echo(f"A+ Content suspended: {content_reference_key}")
+
+    @a_plus.command("upload-image")
+    @click.argument("file-path", type=click.Path(exists=True))
+    @click.option("--content-type", default="image/jpeg", help="MIME type of the image")
+    @click.option(
+        "--resource", default="aplus/2020-11-01/contentDocuments", help="Resource type for upload destination"
+    )
+    @click.pass_context
+    @handle_errors
+    def upload_image(ctx, file_path, content_type, resource):
+        """Upload an image and return an uploadDestinationId for A+ Content."""
+        _, client = ensure_auth_client(ctx)
+
+        with open(file_path, "rb") as f:
+            file_data = f.read()
+
+        md5_hash = hashlib.md5(file_data).digest()
+        content_md5 = base64.b64encode(md5_hash).decode("ascii")
+        file_name = os.path.basename(file_path)
+
+        response = client.create_upload_destination(
+            marketplace_id=client.marketplace_id,
+            content_md5=content_md5,
+            content_type=content_type,
+            file_name=file_name,
+            resource=resource,
+        )
+
+        payload = response.get("payload", response)
+        upload_destination_id = payload.get("uploadDestinationId")
+        upload_url = payload.get("url")
+
+        if not upload_url:
+            click.echo("Error: No upload URL returned", err=True)
+            raise click.Abort()
+
+        parsed = urllib.parse.urlparse(upload_url)
+        base_url = f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
+        form_fields = {k: v[0] for k, v in urllib.parse.parse_qs(parsed.query).items()}
+
+        post_response = requests.post(
+            base_url,
+            data=form_fields,
+            files={"File": (file_name, file_data, content_type)},
+        )
+        post_response.raise_for_status()
+
+        click.echo(f"Upload successful: {file_name}")
+        click.echo(f"uploadDestinationId: {upload_destination_id}")
+
+    @a_plus.group("asin")
+    def asin():
+        """ASIN association commands."""
+        pass
+
+    @asin.command("add")
+    @click.argument("content-name")
+    @click.argument("asins", nargs=-1, required=True)
+    @click.pass_context
+    @handle_errors
+    def add_asins(ctx, content_name, asins):
+        """Associate ASINs with A+ Content."""
+        _, client = ensure_auth_client(ctx)
+        response = client.post_a_plus_content_asin_relations(content_name, list(asins))
+        click.echo(f"Associated {len(asins)} ASIN(s) with {content_name}")
+        if response:
+            click.echo(json.dumps(response, indent=2))
+
+    @asin.command("remove")
+    @click.argument("content-name")
+    @click.argument("asins", nargs=-1, required=True)
+    @click.pass_context
+    @handle_errors
+    def remove_asins(ctx, content_name, asins):
+        """Remove ASIN associations from A+ Content."""
+        _, client = ensure_auth_client(ctx)
+        response = client.delete_a_plus_content_asin_relations(content_name, list(asins))
+        click.echo(f"Removed {len(asins)} ASIN(s) from {content_name}")
+        if response:
+            click.echo(json.dumps(response, indent=2))
+
+    @asin.command("list")
+    @click.argument("content-name")
+    @click.pass_context
+    @handle_errors
+    def list_asins(ctx, content_name):
+        """List ASINs associated with A+ Content."""
+        _, client = ensure_auth_client(ctx)
+        response = client.get_a_plus_content_asin_relations(content_name)
+        asins = response.get("asinSet", [])
+        click.echo(f"\nASINs for '{content_name}' ({len(asins)} found):\n")
+        for asin in asins:
+            click.echo(f"  {asin}")