@markee_team/sdk 0.1.0-alpha.2 → 0.1.0-alpha.21

package/README.md

@@ -1,13 +1,15 @@
-# @markee_team/sdk
+# Markee SDK
 
 An ESM JavaScript SDK with a self-contained, Shadow DOM modal and an optional React entry point. The SDK knows the Markee API endpoint; the host only supplies its placement and, optionally, its current wallet provider. No Alchemy, Redis, Privy, or bridge-provider key belongs in the consuming app.
 
-This is an experimental `0.1.0-alpha.2` release for wallet-funded For Sale and For Rent flows. Hosted card checkout and incoming cross-chain funding are not included.
+Embed a Markee leaderboard in your app with wallet-funded For Sale and For Rent flows, automatic strategy detection, and a configurable theme. Eligible Base For Sale boards can also offer Markee-hosted card checkout when enabled by Markee. Incoming cross-chain funding is not included.
 
-Install the alpha:
+The package also includes a standalone **Markee sign button**. It shows the board's current winner, follows Markee's moderation decisions, and opens the payment modal when clicked.
+
+## Installation
 
 ```sh
-npm install @markee_team/sdk@alpha
+npm install @markee_team/sdk@latest
 ```
 
 Use React 18 or 19 for the optional React entry point. The plain JavaScript entry point does not require React. Both TypeScript bundler and NodeNext resolution are supported.
@@ -19,6 +21,31 @@ npm ci --prefix packages/sdk
 npm run build --prefix packages/sdk
 ```
 
+## Create and connect your leaderboard
+
+The SDK connects to an existing leaderboard; installing it does not create one.
+
+1. Open [Create a Markee](https://www.markee.xyz/create-a-markee) and complete the leaderboard setup on Markee. Choose For Sale or For Rent there. If you already have a leaderboard, use it instead.
+2. Copy the resulting Markee page link: `https://www.markee.xyz/markee/<address>`.
+3. Extract the `0x…` address from that link and use it in the SDK placement: `{ kind: 'board', chainId: 8453, address: yourLeaderboardAddress }`.
+4. Open the modal to display your leaderboard. If using a coding assistant, give it the Markee page link along with the LLM implementation prompt below.
+
+The SDK reads the leaderboard's strategy from Markee and automatically renders the appropriate For Sale or For Rent flow. You do not configure a strategy in your app.
+
+## Automatic site verification
+
+Pass your public page URL or domain as `siteUrl` to `MarkeeModal` or `createMarkee`, for example `siteUrl="https://your-app.example"`. The React component registers the site when mounted, even while closed; the JavaScript modal registers when opened. No API key is required. Use `onSiteVerification` to inspect success or setup errors; verification does not block browsing or payments.
+
+Markee fetches the public page and verifies that its HTML contains the matching board marker before adding it to **Served on**. The React component renders this marker for server-rendered apps. For client-rendered apps such as Vite, include it in the deployed `index.html` (replace the address with your board):
+
+```html
+<span hidden data-markee-address="0xYOUR_BOARD_ADDRESS"></span>
+```
+
+The marker must be present in the HTML returned by the server, not only injected by JavaScript. The supplied URL must use HTTPS, match the app's origin, and return the final HTML page without redirects. Localhost and private-network sites cannot be publicly verified. Registration currently supports Base boards. It verifies the board's presence, not legal domain ownership.
+
+For an explicit retry after deployment, call `new MarkeeClient().verifySite(placement, siteUrl)`. The endpoint is `POST /api/sdk/v1/sites/verify` with `{ placement, siteUrl }`. Unverified sites are never added to the verified list.
+
 ## Plain JavaScript
 
 ```ts
@@ -44,7 +71,7 @@ markee.open({
 // markee.close();
 ```
 
-Without a wallet adapter, browsing works without a wallet. On a connect click the modal discovers installed wallets using EIP-6963, with an EIP-1193 fallback. Multiple discovered wallets are offered for explicit selection. An adapter always takes precedence over injected discovery. Hosted login/card checkout is not part of milestones 1–4.
+Without a wallet adapter, browsing works without a wallet. On a connect click the modal discovers installed wallets using EIP-6963, with an EIP-1193 fallback. Multiple discovered wallets are offered for explicit selection. An adapter always takes precedence over injected discovery. Eligible boards also offer hosted login and card checkout when enabled by Markee; the host app does not need its own wallet integration.
 
 ## React
 
@@ -61,9 +88,24 @@ import { MarkeeModal } from '@markee_team/sdk/react';
 
 See [`examples/connectkit`](https://github.com/1Hive/markee/tree/feature/markee-sdk/examples/connectkit) for a complete adapter. Its connection promise resolves only once ConnectKit has selected a provider and rejects when the picker is dismissed. The SDK does not install a second wallet context.
 
+## Embed the current Markee sign
+
+```tsx
+import { MarkeeSign } from '@markee_team/sdk/react';
+
+const placement = { kind: 'board', chainId: 8453, address: '0x2768BC6e90266248BD8bCF5401C36D8049CdF671' } as const;
+<MarkeeSign placement={placement} theme={{ mode: 'dark' }} />;
+```
+
+`MarkeeSign` is a compact, clickable sign with the winner's message, view count, and a suggested monthly rate on For Rent boards. By default, clicking it opens the SDK modal. Pass `onOpen={() => setOpen(true)}` to open your own controlled `MarkeeModal` instead, or `showAction={false}` to render a non-clickable sign. The sign and modal accept separate `theme` values. No app-side moderation database, RPC key, or moderation provider is needed. To render from plain JavaScript, call `createMarkeeSign(containerElement, { placement })`; its return value has `refresh()`, `setTheme()`, and `destroy()`.
+
+The sign fades in the real MARKEE logo behind the message on hover and keyboard focus, following the Gardens sign treatment. It selects the light or dark logo with the sign's theme, including system-mode changes. Set `theme={{ mode: 'dark', sign: { hoverLogo: false } }}` to disable the watermark. `sign.hoverBackground` remains available for an optional hover surface color; otherwise the sign keeps its normal surface. These options apply only to the sign, so the modal can use its own theme.
+
+The SDK snapshot API reads **board moderation flags** from Markee's database. A flagged winner is blurred with a notice. The sign does not offer a reveal action or count a view for flagged content. If moderation data cannot be loaded, it withholds the message until the status is known. Visible, unflagged signs record one view per message. The sign refreshes every 30 seconds while mounted and can be refreshed on demand. Markee-only site flags intentionally apply only on markee.xyz; they do not censor a partner's embedded sign. Moderators still manage flags on Markee; moderation writes invalidate SDK snapshots so embedded signs can pick up changes on their next refresh.
+
 ## Modal layout
 
-Both strategies follow Gardens' For Rent modal: a compact, 512px panel with a fixed header/footer, a collapsible leaderboard, the selected message or editor, and a prominent amount card. The leaderboard pins your loaded messages and offers inline funding selection. Your active rental message is selected when available; otherwise an owned message or the creation form is shown.
+Both strategies use a consistent, compact 512px panel with a fixed header/footer, a collapsible leaderboard, the selected message or editor, and a prominent amount card. The leaderboard pins your loaded messages and offers inline funding selection. Your active rental message is selected when available; otherwise an owned message or the creation form is shown.
 
 For Sale uses the same arrangement with a one-time ETH amount. For Rent uses an ETHx monthly rate and links to Deposit manager. Wallet balances, rewards, refunds, edits, and community treasury actions remain accessible without top-level tabs. The footer holds the review/confirmation actions and Stop streaming when applicable.
 
@@ -79,7 +121,9 @@ import { createMarkee, type MarkeeTheme } from '@markee_team/sdk';
 const theme: MarkeeTheme = {
   mode: 'system',
   fontFamily: '"DM Sans", system-ui, sans-serif',
-  radius: 12,
+  radius: 16,
+  cardRadius: 12,
+  controlRadius: 8,
   colors: {
     primary: '#743a84',
     primaryText: '#ffffff',
@@ -101,11 +145,17 @@ Theme changes update styles in place: drafts, focus, scroll, wallet sessions, an
 | --- | --- |
 | `mode` | `light`, `dark`, or `system` |
 | `fontFamily` | CSS font stack; the app supplies any custom font |
-| `radius` | Panel radius in pixels, 0–48 (default 22); card and control corners scale with it |
+| `radius` | Panel radius in pixels, 0–48 (default 22) |
+| `cardRadius` | Card radius in pixels, 0–48; defaults to 64% of panel radius |
+| `controlRadius` | Button and input radius in pixels, 0–48; defaults to 45% of panel radius |
 | `colors` | Partial overrides for the semantic tokens below |
+| `sign.hoverLogo` | Show the theme-matched MARKEE logo on hover/focus (default `true`) |
+| `sign.hoverBackground` | Optional sign hover surface color; defaults to the normal surface |
 
 Color tokens: `background`, `surface`, `text`, `muted`, `border`, `inputBackground`, `inputText`, `primary`, `primaryText`, `accent`, `accentText`, `accentSurface`, `accentSurfaceText`, `accentBorder`, `selected`, `selectedText`, `info`, `infoText`, `error`, `errorText`, `success`, `successText`, `link`, `focusRing`, and `overlay`. Set foreground/background pairs together and check your brand's contrast in both modes. Overrides apply over either selected palette; omitted values use that palette's defaults. Invalid CSS color/font values fall back to defaults.
 
+To match an app completely, override `link`, `focusRing`, `border`, `selected`/`selectedText`, and the accent colors as well as the primary button colors. Otherwise those elements retain the SDK palette. Use the typed theme options; arbitrary custom CSS is not currently supported. The sign’s price badge appears on hover or keyboard focus, and stays visible on touch devices.
+
 Styles are scoped to the modal's Shadow DOM and do not change the host app or its wallet picker. The ConnectKit sample includes light, dark, device, and custom Plum presets.
 
 ## Headless API
@@ -125,6 +175,14 @@ For Sale supports create/fund/edit. New message ownership belongs to the caller.
 
 For Rent supports message creation, starting/updating/switching/stopping a stream, wrap/unwrap, pool connection/refunds, board-buffer recovery, ranking refresh and settlement. The server builds the complete Superfluid batch, including exact ETHx approval and pool connection. Wallet runway uses the combined CFA and GDA net flow across the wallet, not only the current board. Rental MARKEE comes from actual settled rent, never merely from wrapping or depositing ETH.
 
+Payment reviews remain visible while the wallet requests confirmation, including network switches. If a review expires when confirming, the modal shows **Refreshing payment details…**, prepares an updated review, and requires another confirmation click. It never automatically sends the refreshed transaction.
+
+For Sale reviews are disabled when the entered payment exceeds the loaded ETH balance; the balance uses the error color and the button explains the shortfall. The API also checks network fees before wallet confirmation.
+
+For Rent reviews show estimated **MARKEE/month while winning**, using the selected monthly stream rate and current on-chain reward settings. The estimate is not based on the ETH deposit and is not guaranteed; if quoting is unavailable, the modal shows a qualitative reward description. Rental transaction details contain only Network, Recipient, and Wallet; fees stay in the payment summary.
+
+Refunds flow automatically when connected to the message’s refund pool. **Collect refund** appears only when the loaded wallet snapshot reports a positive claimable balance for that message’s pool. Board-buffer recovery is separate. Community revenue actions are accessed through **Community accumulated revenue**.
+
 Community activation supports the current council Safe, a current Safe owner, or the configured authorized keeper. Revenue claims support the current Safe or its current owners and always pay the council treasury. Existing outbound Across, Squid and LI.FI routing lives on Markee's server.
 
 ## Integration boundaries
@@ -135,49 +193,135 @@ Community activation supports the current council Safe, a current Safe owner, or
 - The modal renders escaped text, uses isolated CSS, and supports keyboard focus, Escape, mobile sizing and reduced motion. A host CSP must permit the SDK's inline styles and connections to its configured Markee API. No external font or image is needed by the modal.
 - API failures are explicit. Without moderation data, message text is withheld. No mock balances or fabricated rewards are returned by production handlers.
 
-Backend configuration, endpoint details, and verification evidence: [`docs/sdk/implementation.md`](https://github.com/1Hive/markee/blob/feature/markee-sdk/docs/sdk/implementation.md).
+Backend configuration and API reference: [`docs/sdk/implementation.md`](https://github.com/1Hive/markee/blob/feature/markee-sdk/docs/sdk/implementation.md).
 
 ## API endpoint
 
-No API URL configuration is required. This alpha uses the Markee staging API at `https://markee-git-feature-markee-sdk-1hive.vercel.app/api/sdk/v1`. For local development or testing only, pass an optional `apiUrl` override to `createMarkee`, `MarkeeClient`, or the React modal. The current default is also exported as `DEFAULT_MARKEE_API_URL`.
+No API URL or Markee API key is required. The SDK default is:
+
+```text
+https://staging.markee.xyz/api/sdk/v1
+```
+
+Markee hosts this API and centralizes on-chain reads, metadata, and transaction preparation. Staging does not imply test funds: Base placements use real funds. For local development or testing, pass an optional `apiUrl` override to `createMarkee`, `MarkeeClient`, or the React modal. The endpoint used by your installed release is exported as `DEFAULT_MARKEE_API_URL`.
 
 ## LLM implementation prompt
 
-Copy this prompt into your coding assistant. These are existing Base demo boards; replace the placements with your own when integrating your product.
+Copy this prompt into your coding assistant. It gathers missing requirements before implementing the integration.
 
 ```text
-Integrate @markee_team/sdk@0.1.0-alpha.2 into this app. Inspect the app first and
-follow its existing framework, styling, and wallet patterns.
-
-- Install @markee_team/sdk@0.1.0-alpha.2. The SDK knows its API endpoint. Do not
-  request an API URL, build an API proxy, or add RPC/database/provider keys.
-- For React 18/19, import MarkeeModal from @markee_team/sdk/react in a client
-  component and supply open, onClose, and placement. For other apps, import
-  createMarkee from @markee_team/sdk, call createMarkee(), then open({ placement }).
-  Close the instance on teardown. Reuse the built-in modal UI.
-- Add buttons for these existing demo placements:
-  For Sale: { kind: 'board', chainId: 8453,
-    address: '0x2768BC6e90266248BD8bCF5401C36D8049CdF671' }
-  For Rent: { kind: 'board', chainId: 8453,
-    address: '0x82cbe3BdFC4e01940D186Ac5EA151355647DE0d3' }
-- Wallet integration is optional. Reuse the app's selected EIP-1193 provider via
-  wallet.getProvider(): Promise<provider | null> and optional
-  wallet.connect(): Promise<provider>. For ConnectKit/wagmi, use the active
-  connector's provider, resolve connect after selection, and reject cancellation.
-  Do not create a second wallet context or silently select another injected wallet.
-  If there is no existing wallet integration, omit wallet for SDK wallet discovery.
-- Match the app using theme: mode ('light', 'dark', 'system'), fontFamily, radius,
-  and semantic colors such as primary and primaryText. Preserve the built-in
-  layout and its isolated Shadow DOM styles.
-- Optionally handle onEvent and show success only for a confirmed event. Let the
-  SDK handle payment review, chain switching, submission, and verification.
-  Do not advertise card checkout or incoming bridging: this alpha lacks those
-  features. The demo boards use real Base funds.
-- Run typecheck/build and verify both modals load without API configuration,
-  open/close correctly, and match the theme. Verify host wallet reuse if available.
-  Do not sign or submit transactions during automated verification. Report changed
-  files, checks, and remaining limitations.
-
-This alpha automatically uses Markee's temporary staging backend. Read the installed
-package README for exact types and configuration details.
+Integrate @markee_team/sdk@latest into this app. Inspect the codebase first and
+follow its existing framework, styling, and wallet patterns. Read the installed
+package README and types for current capabilities.
+
+Before implementing, ask me to create my leaderboard on Markee at
+https://www.markee.xyz/create-a-markee, then provide its resulting Markee page link.
+If I already have a leaderboard, ask for that link instead; do not create a duplicate.
+Example link format:
+https://www.markee.xyz/markee/0x6ceBC87DE40519Fa52fc40a1d49f16FF968bb439
+Never silently substitute a demo board. Wait for my link before wiring the placement.
+
+Extract the board address from the /markee/<address> path. Validate the Markee URL
+and the address (0x followed by 40 hexadecimal characters). Markee website boards
+currently use Base, chain ID 8453. Verify the board through the SDK snapshot API;
+if verification fails, explain the error and ask for a corrected link.
+
+Do not ask me to choose For Sale or For Rent in the host app. That choice is made
+when creating the leaderboard on Markee. The API returns strategy and the SDK
+adapts the modal automatically. Do not add a strategy prop, toggle, or hardcoded mode.
+
+Ask only the remaining unanswered requirements in one concise group:
+- Where should Markee appear, what opens the modal, and what should the button say?
+- Should it reuse the app's existing wallet, use SDK wallet discovery, or use
+  Markee-hosted card checkout without an app wallet (For Sale on Base only)? Inspect
+  existing connectors first; do not add a second wallet context or install a new
+  connector without agreement.
+- Should the modal match the app theme or use specific colors, font, panel/card/
+  control radii, and light/dark/system mode? Include links, focus rings, borders,
+  and selected states when matching the host palette.
+- What public domain/page will host this integration? Use it as siteUrl for
+  automatic verification. For Vite/client rendering, add the board marker to the
+  static HTML as documented; do not claim localhost is verified.
+- What should happen after a confirmed transaction: notification, refresh,
+  navigation, or callback? Are there additional mobile/accessibility requirements?
+
+Then implement the agreed scope:
+1. Install @markee_team/sdk@latest. No API URL or Markee API key is required.
+   Do not create an API proxy or add RPC/database credentials.
+2. Use placement = { kind: 'board', chainId: 8453, address: extractedAddress }.
+   Use new MarkeeClient().snapshot(placement) to verify the board and read strategy,
+   name, minimum, and other metadata. The modal performs its own snapshot loading;
+   do not recreate that loading or strategy logic in the host app.
+3. For React, use MarkeeModal from @markee_team/sdk/react in a client component
+   with open, onClose, and placement. Otherwise use createMarkee() from
+   @markee_team/sdk, then open({ placement }); close it on teardown.
+4. If a host wallet exists, pass its selected EIP-1193 provider through the wallet
+   adapter. For ConnectKit/wagmi use the active connector. Resolve connect after
+   selection, reject cancellation, and do not silently switch wallet providers.
+   Otherwise omit wallet. Without a connected app account, the modal shows only
+   Pay, opening Markee-hosted checkout for supported boards. Do not install
+   Privy or collect card details in the host app.
+5. Apply theme options (including radius, cardRadius, and controlRadius) while
+   preserving the built-in modal layout. Handle onEvent
+   if needed; show success only for a confirmed event. Let the SDK manage review,
+   network switching, submission, and verification.
+6. Verify build/types, loading of the supplied board, automatic strategy selection,
+   open/close behavior, theme, and wallet reuse. Do not sign or send transactions
+   during automated verification. Report changed files, checks, and limitations.
+
+Check the installed release's supported features before promising functionality.
+Wallet-funded flows are supported. Hosted card checkout requires Markee's backend
+capability to be enabled; do not promise availability when it is disabled. Incoming
+bridging is not available. Transactions and card funding use real funds.
 ```
+
+## Pay by card without an app wallet
+
+Without a connected app wallet, the modal shows **Pay** as its only payment action
+and hides wallet balances and wallet-management sections. For Sale boards on Base
+with MARKEE rewards support this flow
+when the Markee backend enables hosted checkout. No Privy provider, payment keys or
+API configuration is needed in the integrating app. Omit the `wallet` adapter.
+
+The SDK opens Markee, where the user signs in, receives a Privy embedded wallet,
+funds it through Stripe (Base USDC converted to ETH) or MoonPay (Base ETH), and confirms
+the Markee payment. The contract sends MARKEE directly to that user's paying
+wallet. The host receives `onEvent({ type: 'confirmed', hash })` only after
+server-side receipt verification. Card funding alone is not a successful payment.
+
+The checkout can resume after closing or refreshing. If a wallet submission has an
+unknown result, it asks the user to check the existing transaction instead of
+sending again. On browsers that block popups, it navigates to Markee in the same
+tab. Reopen Pay after returning to recover the confirmed result.
+
+Card availability, fees, minimum purchase amounts and identity checks depend on
+the funding provider and user eligibility. Any unused USDC or ETH remains in the
+user's wallet. Conversion uses a capped approval and maximum 1% slippage, with
+wallet confirmation and Markee-sponsored conversion gas. For Rent, incoming
+bridging and automatic rewards forwarding to a different wallet are outside this
+checkout flow. If hosted checkout is unavailable, Pay is disabled with an
+availability message; the modal does not fall back to asking for a wallet.
+
+### Reuse a Markee login
+
+Pay opens a temporary browser tab on Markee, where the existing Privy session is
+restored before showing sign-in. The SDK does not copy login tokens into the host
+app. The tab closes after the host verifies the payment. If tabs are blocked,
+checkout falls back to a same-tab redirect. To always redirect, pass
+`checkoutWindow: 'redirect'` (`checkoutWindow="redirect"` in React).
+
+Session reuse requires the same exact Markee origin and Privy app ID. A login on
+`www.markee.xyz` is not a login on a Vercel preview domain. Markee can set
+`MARKEE_CHECKOUT_ORIGIN=https://www.markee.xyz` on its API deployment **after** the
+checkout route is deployed there. Both deployments must use the same checkout KV,
+signing secret, supported configuration and Privy app. Omit this setting to keep
+checkout on the API origin. Integrators do not configure an API or checkout URL.
+Existing pending checkout sessions retain their original destination.
+
+### Pay in Markee availability
+
+The SDK checks the Markee API before offering hosted payment. Markee controls this
+feature with the server-only `FLAG_SDK_PAY_IN_MARKEE` environment variable, which
+defaults to false. Only `true`, together with the required checkout configuration,
+enables it. Integrating apps do not need to provide a flag or API key. Connected
+wallet payments remain available independently.

package/dist/checkout.d.ts

@@ -0,0 +1,7 @@
+import { type MarkeeClient } from './client.js';
+import type { Action, CheckoutSession, CheckoutStatus, Placement, TransactionResult } from './types.js';
+export declare function savedCheckout(client: MarkeeClient, placement: Placement): CheckoutSession | null;
+export declare function checkoutStatus(client: MarkeeClient, session: CheckoutSession): Promise<CheckoutStatus>;
+export declare function forgetCheckout(client: MarkeeClient, placement: Placement): void;
+/** Call directly from a click handler to preserve popup permission. */
+export declare function openHostedCheckout(client: MarkeeClient, placement: Placement, action: Action): Promise<TransactionResult>;

package/dist/client.d.ts

@@ -1,6 +1,6 @@
-import type { Action, Address, AdminOperation, AdminResult, Authorization, BridgeStatus, ClaimQuote, EIP1193Provider, Hex, Placement, PreparedAction, SDKOptions, Snapshot, TransactionResult } from './types.js';
-/** Markee-hosted API for the alpha release. */
-export declare const DEFAULT_MARKEE_API_URL = "https://markee-git-feature-markee-sdk-1hive.vercel.app/api/sdk/v1";
+import type { Action, Address, AdminOperation, AdminResult, Authorization, BridgeStatus, ClaimQuote, EIP1193Provider, Hex, Placement, PreparedAction, SDKOptions, Snapshot, SiteVerification, TransactionResult } from './types.js';
+/** Markee-hosted API used by integrations unless overridden for local development. */
+export declare const DEFAULT_MARKEE_API_URL = "https://staging.markee.xyz/api/sdk/v1";
 export declare class MarkeeError extends Error {
     code: string;
     status?: number | undefined;
@@ -38,6 +38,9 @@ export declare class MarkeeClient {
     provider(): Promise<EIP1193Provider | null>;
     account(): Promise<Address | null>;
     connect(selected?: EIP1193Provider): Promise<Address>;
+    verifySite(placement: Placement, siteUrl: string): Promise<SiteVerification>;
+    private siteRequests;
+    registerSite(placement: Placement): void;
     snapshot(placement: Placement, account?: Address | null, offset?: number, signal?: AbortSignal): Promise<Snapshot>;
     prepare(placement: Placement, action: Action): Promise<PreparedAction>;
     private ensureWallet;

package/dist/index.d.ts

@@ -4,3 +4,6 @@ export type { PendingTransaction, DiscoveredWallet } from './client.js';
 export { createMarkee, MarkeeModal } from './modal.js';
 export type { ModalOptions } from './modal.js';
 export { parseEth, formatEth } from './amount.js';
+export { openHostedCheckout, checkoutStatus, savedCheckout } from './checkout.js';
+export { createMarkeeSign, signContent } from './sign.js';
+export type { MarkeeSignOptions } from './sign.js';