Authenticated. Prefer **OAuth**: connect once via the consent flow on
claude.ai (or any MCP client that supports OAuth) and the bearer token
is attached automatically — no `api_key` parameter needed. **Fallback**:
pass an `api_key` (prefix `pk_`, generate at /account) for programmatic
or non-OAuth clients.

Required OAuth scope: `products:write`.

Use when the user wants to add an item for sale. For edits to an
existing product, use `update_product` instead.

**Images.** This tool creates text fields only — no image arg. Do
**not** try to pass image bytes through a tool argument; phone-sized
payloads blow past conversation context limits.

The response includes a one-shot ``upload_url`` (signed, ~15 min TTL,
bound to this product and your authenticated user). To attach an
image from your code-execution sandbox, do **one** PUT request — no
auth headers needed, the URL itself carries the credential:

  requests.put(result["upload_url"],
               data=open("/path/to/photo.jpg", "rb").read(),
               headers={"Content-Type": "image/jpeg"})

The bytes flow Python → HTTP body → Partle, never through the
conversation. The URL works once and expires fast.

Alternative if you don't have local bytes but have a public image URL:
call ``upload_product_image(product_id, image_url=...)`` instead.

**Duplicate prevention.** Same user, same product name (case- and
whitespace-insensitive) returns 409 with `existing.id`, `existing.url`,
**and a fresh `upload_url`** for that existing product — so if the
user is just retrying with a photo, you can attach it directly to the
existing listing without having to create or pick anything new. You
can also call `update_product` to change fields. Don't retry blindly.

**Idempotency.** Pass `idempotency_key` (any unique string per logical
create — UUID or hash of the source listing) and a retry after a
network failure returns the original response instead of creating a
duplicate. Reusing a key with a different payload is a 422.

Args:
    name: Product name. Required, 1–200 chars.
    description: Long-form product description. Optional.
    price: Price in whole currency units, **not** cents (e.g. ``15.99``
        means €15.99). Max 100000. Omit for "ask the seller".
    currency: Currency symbol. Defaults to `€`. Use `$`, `£`, etc.
    url: Link to the merchant's product page. Optional but recommended.
    store_id: ID of the store this product belongs to. Omit for a
        personal listing not tied to any store.
    listing_type: ``in_stock`` (default) when the seller has the item
        and it can be bought now. ``tentative`` when they do not stock
        it and want to measure interest first — such a listing is kept
        out of normal search results and instead collects "I need this"
        presses. Only use ``tentative`` if the user explicitly said they
        are gauging demand; an item that is merely out of stock today is
        still ``in_stock``. If the user is looking to *buy* something
        nobody sells, use `create_buy_request` instead — that is the
        demand side and it is a different tool.
    idempotency_key: Optional retry-safety token. Unique per logical
        create. Send the same key on retries to get the same response.
    api_key: Optional API key (`pk_*`, generate at /account).
        Used when there is no OAuth token, and also when the OAuth
        token lacks the required scope — an explicitly passed key
        overrides an ambient token that is scoped too narrowly.
        An invalid or revoked token still fails regardless. Omit when using OAuth.

Returns:
    The created product record including its new `id` and canonical
    `partle_url`. Share `partle_url` with the user. Returns
    ``{"error": ...}`` on auth, dedup, or validation failure (dedup
    also returns ``{"existing": {"id", "name", "url"}}``).