Metadata-Version: 2.5
Name: kifly-storefront-backend
Version: 0.1.0
Summary: Kifly as the StorefrontBackend for Anthropic's commerce-agents blueprint
Project-URL: Homepage, https://kifly.ai
Project-URL: Documentation, https://kifly.ai/docs/commerce-agents
Project-URL: Commerce-agents blueprint, https://github.com/anthropics/commerce-agents
Author-email: Kifly <hello@kifly.ai>
License: MIT License
        
        Copyright (c) 2026 Kifly
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Kifly backend for Anthropic's commerce-agents blueprint

[`anthropics/commerce-agents`](https://github.com/anthropics/commerce-agents) ships a
shopping agent with one interface left deliberately empty: `StorefrontBackend`.
It expects you to already have a catalog API, a cart, inventory, and a payment
provider — and it says so plainly: *"the blueprint leaves payment to you."*

Most merchants have none of those. This package fills the interface with Kifly,
so a fork of the blueprint works against a real catalog, real carts, and a real
payment link on the first run.

```bash
pip install kifly-storefront-backend
```

```python
import os
from kifly_storefront_backend import KiflyStorefrontBackend

backend = KiflyStorefrontBackend(os.environ["KIFLY_API_KEY"])
```

That is the whole integration. Point one merchant's deployment at their own store:

```python
backend = KiflyStorefrontBackend(api_key, seller_handle="mayas-coffee")
```

…or leave `seller_handle` off and the agent shops the whole Kifly network.

## What this actually connects you to

This package doesn't stand up a backend for you — it's a client for one that
already exists. The catalog, cart, and checkout your agent talks to are the
same hosted platform every Kifly seller already runs on; installing this just
lets your blueprint deployment speak to it.

One consequence: **the merchant needs a Kifly seller account before this does
anything.** `api_key` above comes from that account, not from this package, and
it's how Kifly knows whose catalog to serve. See "Getting a key" below — it's
a couple of clicks, not a project.

There are three ways to implement the blueprint, and they trade off differently:

| | Blueprint alone | Blueprint + this adapter | Kifly direct |
| --- | --- | --- | --- |
| Who does the work | You build the backend | You write this thin adapter | Merchant connects their store, no code |
| Setup time | Weeks | An afternoon | Minutes |
| Catalog import from any platform | You build the sync | ✅ Shopify, WooCommerce, Square, or a URL | ✅ |
| Semantic / multilingual search | You build it | ✅ | ✅ |
| Checkout: human-confirmed link | Bring your own | ✅ | ✅ |
| Checkout: fully autonomous (USDC/x402) | Bring your own | ❌ deliberately unreachable — see "Nothing here settles" below | ✅ on Kifly's own REST/UCP surface, for non-Claude agents |
| Findable inside Claude | ❌ | ✅ — the merchant's catalog joins Kifly's network | ✅ |
| Sells across multiple sellers | ❌ one store | ✅ | ✅ |
| Needs a developer at all | Yes | Yes | No |

The middle column is what this package gives you. The right column is for a
merchant who doesn't need a custom agent deployment at all — just Kifly's own,
already-listed Claude connector.

## What you get without writing it

| `StorefrontBackend` method | Backed by |
| --- | --- |
| `search_products` | Multilingual semantic search across the catalog |
| `get_product_details` | Full record with the seller's option matrix and purchasable variants |
| `get_cart` / `add_to_cart` / `update_cart_item` / `remove_from_cart` | Kifly carts |
| `checkout_handoff` | A payment link per seller, or a handoff to their own store |
| `get_preferences` / `get_orders` / `get_order` | Kifly buyer identity and order history |
| `get_fulfillment_options` | Per-seller delivery coverage, fees, and pickup |
| `search_policies` | **Not provided** — see below |

## Two things worth knowing before you deploy

**One session holds several carts.** The blueprint models a session as holding
one cart. A Kifly cart is scoped to one seller, so a shopper buying across the
network holds several. This backend merges them into one basket for the model and
splits them again at checkout, giving each seller its own confirmation link —
which is what the blueprint's `CheckoutHandoff.seller` field exists for.

**Nothing here settles.** `checkout_handoff` returns links a person opens and
confirms. This connector never sends an `X-Payment` or `Authorization: Payment`
header and holds no reusable mandate. Autonomous x402 settlement stays on Kifly's
own REST surface for non-Claude agents; it is deliberately unreachable from an
agent harness a person is talking to.

**`search_policies` returns nothing, on purpose.** Kifly holds no per-seller
policy corpus. The blueprint's own rule is that a store-terms question may only be
answered from a `search_policies` result — so an empty list makes the agent say
the store does not offer that here, rather than answering a returns question from
the model's guesses about a shop it has never seen. If you have a policy corpus,
subclass and override that one method.

## Units

Kifly speaks two money formats and this package converts between them so you
never have to:

- **Catalog** (JSON-LD) carries **major units** — `offers.price` is `28.0`.
- **Cart** carries **cents** — `unit_price_cents` is `2800`.

Dividing the first by 100 prices a $28 bag at 28 cents, and the number stays
internally consistent all the way to the shopper, so no grounding rule catches
it. `tests/test_mapping.py::TestUnits` pins both directions.

## Install and test

```bash
# The blueprint itself, from your checkout of anthropics/commerce-agents:
pip install ./commerce-agents/commerce-common ./commerce-agents/shopping-agent/core

# This package — from PyPI (above), or from source for local development:
pip install -e '.[dev]' && pytest
```

Tests run entirely against a fake Kifly speaking the real wire format — no API
key, no network. The behaviour they cover is written as scenarios in
[`features/storefront_backend.feature`](features/storefront_backend.feature).

## Getting a key

An agent API key (`kfa_live_...` / `kfa_test_...`) comes from the Kifly seller
portal at [kifly.ai](https://kifly.ai). Sign up, then bring in the merchant's
existing catalog — Shopify connects with one click; anything else (WooCommerce,
Square, a plain storefront URL) imports from that URL directly, with dedicated
handling already built for the common ones. Either way it's indexed and
agent-readable within minutes. If a platform doesn't import cleanly, tell
Kifly which one; new sources get added fast.
