@manifoldxyz/dropkit 0.2.0 → 0.3.0

package/README.md

@@ -108,7 +108,7 @@ The adapter reads allowance and creates an approval leg when required. Manifold
 | `recipient` | Optional receiving address. Defaults to payer. |
 | `quantity` | Initial quantity, or controlled quantity with `onQuantityChange`. Defaults to 1. |
 | `onQuantityChange` | Receives the clamped requested quantity. The parent must update `quantity`. |
-| `connect` | Optional `{ walletConnectProjectId }` forwarded to the shared connect widget. |
+| `connect` | Optional `{ walletConnectProjectId }` forwarded to the shared connect widget. Defaults to Manifold's project id. |
 | `onEvent` | Optional event callback. No telemetry is sent by the package. |
 | `crossChain` | Manifold claims only. Default on. `false` turns cross-chain minting off; `{ chains: [8453] }` narrows the pay chains. |
 | `payChainId` | Forces the pay chain. The drop chain means a direct mint. Must be a pay chain. |
@@ -274,6 +274,58 @@ export function CrossChainMint({ config }: { config: MintConfig }) {
 
 Rows expose `data-chain`, `data-selected`, `data-loading` and `aria-pressed`. `renderRow` replaces the row content.
 
+## Cart checkout
+
+`@manifoldxyz/dropkit/cart` collects several Manifold claims in one cart and sends one mint transaction per item. Importing only `@manifoldxyz/dropkit` never loads the cart. The cart takes Manifold claims only, all on one chain.
+
+```tsx
+import { AddToCartButton, CartProvider, useCart, useCheckout } from '@manifoldxyz/dropkit/cart';
+import type { ManifoldClaimConfig } from '@manifoldxyz/dropkit';
+
+const claim: ManifoldClaimConfig = {
+  type: 'manifold-claim',
+  chainId: 1,
+  creatorContract: '0x0000000000000000000000000000000000000001',
+  instanceId: '1',
+  extension: '0x0000000000000000000000000000000000000002', // required in the cart
+};
+
+function Checkout() {
+  const cart = useCart();
+  const checkout = useCheckout();
+  return (
+    <div>
+      <p>{cart.count} in cart</p>
+      {checkout.state === 'idle' && <button onClick={checkout.checkout}>Check out</button>}
+      {checkout.state === 'ready' && <button onClick={checkout.confirm}>Confirm in wallet</button>}
+      {checkout.state === 'checking' && <button onClick={checkout.check}>Check again</button>}
+      {checkout.message && <p>{checkout.message}</p>}
+    </div>
+  );
+}
+
+export function Shop() {
+  return (
+    <CartProvider chainId={1} rpcUrls={{ 1: 'https://eth.example/rpc' }}>
+      <AddToCartButton config={claim} />
+      <Checkout />
+    </CartProvider>
+  );
+}
+```
+
+Things to know:
+
+- **`extension` is required** on every cart config. Without it `add()` throws `INVALID_CONFIG`.
+- **Pass `rpcUrls`.** Without an RPC URL for the cart's chain, the provider logs a console warning once: receipts, holdings and balance checks then use a public RPC that can be rate-limited during a sale.
+- **One `CartProvider` per `storageKey` per tab.** The default key is `dropkit-cart:<chainId>`. A second provider with the same key throws `INVALID_CONFIG`.
+- **What the cart keeps in `sessionStorage`:** one JSON value under the storage key holding the items (config and quantity), the mints that were sent and are not yet settled (payer, recipient, quantity, transaction hash and the holdings count taken before sending), and the results shown to the collector. It holds no keys and no signatures. It lives for the tab session. If `sessionStorage` is unavailable or full, checkout stops with `PERSISTENCE_UNAVAILABLE` before anything is sent.
+- **Each click makes one wallet request:** switch network, add network, or one mint. `confirm()` must run from a click handler.
+- **`useHoldings(configs, { wallet? })`** reads what a wallet holds of each drop, for "You own N" on a drop page: `get(config)` returns `{ kind, count }`: `owned` for an ERC-1155 drop (the token balance, transfers included), `minted` for an ERC-721 drop with a wallet limit (mints from that drop), and `owned-in-contract` for other ERC-721 drops (the balance on the whole contract, which equals `owned` when the contract holds only this drop). It reads the connected wallet by default, on mount, on a wallet change, after each collected mint and on `refresh()`, with no timer. Use it inside `CartProvider`.
+- **Links for collected items.** Each `cart.collected` entry has `tokens` (from the receipt) and `links`: `tx` (block explorer), `tokens` (one OpenSea item page each) and `profile`. Pass `openseaCollections={{ '0xYourContract': 'your-opensea-slug' }}` to `CartProvider` and `profile` opens the collector's OpenSea holdings filtered to your collection. Without a slug, `profile` is the plain OpenSea profile when no token id is known (a lost receipt on a 721), else null. OpenSea has no testnets, so Sepolia gets the explorer link only.
+- **A mint that cannot be confirmed** is never retried for you. It is listed in `cart.unconfirmed` until the collector dismisses it or adds the item back. Each entry has `wallet` (the wallet that sent it) and `message`, which names that wallet: "We couldn't confirm this. Check wallet 0x1234…abcd. If it didn't go through, add it again."
+- **Any wallet works**, smart accounts included. A wallet that returns a request id instead of a transaction hash (a Safe through WalletConnect, for example) shows "Still confirming", then settles from the collector's holdings: Collected if the mint landed, otherwise Unconfirmed. The cart never resends it.
+
 ## Local verification
 
 From the repository root, use Node 24 and pnpm 10.34.5: