arcane-mct 2.1.0
Package description
Requires Python: <3.14,>=3.9

# Arcane MCT

Internal package for **Merchant Center (MCT)** access. It talks to Google Shopping via **Content API for Shopping v2.1** by default, with an optional migration path to the **Merchant API** (Accounts + Products client libraries).

---

## Installation

Install from the monorepo (Poetry):

```bash
poetry add ../arcane-mct   # or your path to this package
```

Dependencies include `arcane-core`, `arcane-datastore`, `arcane-credentials`, and the Google Shopping client libraries (see `pyproject.toml`).

---

## Usage

### MctClient (service account only)

Use a GCP service account JSON to create a client and call MCT:

```python
from arcane.mct import MctClient

client = MctClient(
    gcp_service_account="/path/to/service-account.json",
    user_email="user@example.com",  # optional; needed for user-delegated credentials
    secret_key_file="/path/to/secret.key",  # required when user_email is set
    gcp_project="my-gcp-project",
)

# Get the account display name for a merchant ID
name = client.get_mct_account_details(merchant_id=123456789)
print(name)  # e.g. "My Store"

# Check that the account is not a multi-client account (MCA); raises if it is
client.check_if_multi_client_account(merchant_id=123456789)
```

When you already have an MCT account dict (e.g. from your API), you can pass it instead of `user_email`:

```python
client = MctClient(
    gcp_service_account="/path/to/service-account.json",
    mct_account={"creator_email": "user@example.com", ...},
    secret_key_file="/path/to/secret.key",
    gcp_project="my-gcp-project",
)
name = client.get_mct_account_details(merchant_id=123456789)
```

Using only the service account (no user credentials):

```python
client = MctClient(
    gcp_service_account="/path/to/service-account.json",
)
name = client.get_mct_account_details(merchant_id=123456789)
```

### check_access_before_creation

Before linking or creating an MCT account, you can verify that the user has access and that the account is not an MCA:

```python
from arcane.mct import check_access_before_creation

should_use_user_access = check_access_before_creation(
    mct_account_id=123456789,
    user_email="user@example.com",
    gcp_service_account="/path/to/arcane-service-account.json",
    secret_key_file="/path/to/secret.key",
    gcp_project="my-gcp-project",
)
# Returns True if the user's credentials have access (use user access when linking).
# Raises MctAccountLostAccessException or MerchantCenterServiceDownException on failure.
```

### Exceptions

- **`MctAccountLostAccessException`** — The account is not accessible (e.g. wrong merchant ID, revoked access, or MCA when only sub-accounts are allowed).
- **`MerchantCenterServiceDownException`** — The Merchant Center API is unavailable or returned a server error.

---

## Merchant API migration

Content API for Shopping is being sunset (August 2026). You can switch to the **Merchant API** in two ways:

1. **Environment**: set `USE_MERCHANT_API=true` (or `1`) so all clients use the Merchant API when no explicit flag is passed.
2. **In code**: pass `use_merchant_api=True` (or `False`) where supported:
   - `MctClient(..., use_merchant_api=True)`
   - `check_access_before_creation(..., use_merchant_api=True)`

If you omit `use_merchant_api` (or pass `None`), the backend is chosen from the `USE_MERCHANT_API` environment variable. Default is Content API (with a deprecation warning).