@markee_team/sdk 0.1.0-alpha.9 → 0.1.0-beta.1

package/README.md

@@ -4,7 +4,7 @@ An ESM JavaScript SDK with a self-contained, Shadow DOM modal and an optional Re
 
 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.
 
-The package also includes a standalone **Markee sign**. It shows the board's current winner and follows Markee's moderation decisions, with an optional button to open the payment modal.
+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
 
@@ -97,9 +97,11 @@ const placement = { kind: 'board', chainId: 8453, address: '0x2768BC6e90266248BD
 <MarkeeSign placement={placement} theme={{ mode: 'dark' }} />;
 ```
 
-`MarkeeSign` shows the current on-chain winner, its message and author, and an **Open Markee** button that launches the SDK modal. It uses the same optional wallet adapter and theme as `MarkeeModal`. 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()`.
+`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 SDK snapshot API reads **board moderation flags** from Markee's database. A flagged winner is blurred with a notice; the author's name is blurred too. 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.
+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
 
@@ -119,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',
@@ -141,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
@@ -165,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
@@ -179,7 +197,13 @@ Backend configuration and API reference: [`docs/sdk/implementation.md`](https://
 
 ## API endpoint
 
-No API URL or Markee API key is required. The SDK connects to the Markee-hosted API and centralizes on-chain reads, metadata, and transaction preparation. 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`.
+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
 
@@ -212,8 +236,9 @@ Ask only the remaining unanswered requirements in one concise group:
   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, radius, and
-  light/dark/system mode?
+- 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.
@@ -236,7 +261,8 @@ Then implement the agreed scope:
    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 while preserving the built-in modal layout. Handle onEvent
+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,
@@ -291,3 +317,28 @@ 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.
+
+### Automatic message moderation
+
+When enabled by Markee, create/edit forms warn if a message matches the automatic profanity
+filter. Authors can edit or explicitly continue; publication may still be hidden. A passing
+message edit clears an automatic flag, while manual flags require moderator action.
+
+`await client.checkMessage(message)` exposes the same draft check for custom interfaces. It
+returns `enabled`, `state`, `contentHash`, `engine`, `policyVersion`, and optional `reason`.
+Treat `unavailable` as unknown, never as a pass. Names are not automatically checked.
+The standard modal handles these warnings for React and vanilla JavaScript integrations.
+No API key or moderation configuration is required in the host app.
+
+Snapshots retain `entry.moderated` (`false`, `true`, or `null`) and can additionally include
+`entry.moderation` with the state and reason. Hide unavailable and flagged content and do not
+record views for it. A moderator's false-positive exception on Markee applies only on Markee;
+it does not change SDK visibility. This optional backend feature is disabled by default.

package/dist/client.d.ts

@@ -1,6 +1,6 @@
-import type { Action, Address, AdminOperation, AdminResult, Authorization, BridgeStatus, ClaimQuote, EIP1193Provider, Hex, Placement, PreparedAction, SDKOptions, Snapshot, SiteVerification, TransactionResult } from './types.js';
+import type { MessageCheck, 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://2staging.markee.xyz/api/sdk/v1";
+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;
@@ -67,6 +67,7 @@ export declare class MarkeeClient {
         kind: 'gardens-community';
     }>): AdminResult | null;
     bridgeStatus(protocol: ClaimQuote['bridgeProtocol'], hash: Hex, fromChainId: number, toChainId: number): Promise<BridgeStatus>;
+    checkMessage(message: string): Promise<MessageCheck>;
     recordView(address: Address, message: string, url?: string): Promise<{
         counted: boolean;
         totalViews: number;