@crediball/elements 0.4.1 → 0.6.0

package/dist/{chunk-WUPVPARI.js → chunk-MWB56UEW.js}

@@ -185,7 +185,7 @@ var CrediballLowCreditWarningElement = class extends CrediballElement {
 };
 
 // src/paywall.ts
-import { formatMoney } from "@crediball/core";
+import { formatMoney, fetchReferral } from "@crediball/core";
 var CURRENCY_SYMBOLS = { EUR: "\u20AC", USD: "$", GBP: "\xA3" };
 function currencySymbolFor(currency) {
   return CURRENCY_SYMBOLS[currency.toUpperCase()] ?? currency;
@@ -283,15 +283,59 @@ var STYLE = `
     padding: 11px 22px;
     border-radius: var(--crediball-radius, 9999px);
   }
+  .referral { margin-top: 20px; padding-top: 16px; border-top: 1px solid var(--crediball-hairline, #e0e0e0); }
+  .referral .eyebrow { margin-bottom: 8px; }
+  .referral-row { display: flex; gap: 8px; align-items: center; }
+  .referral-row .link {
+    flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    font-size: 13px; color: var(--crediball-ink, #1d1d1f);
+    border: 1px solid var(--crediball-hairline, #e0e0e0);
+    border-radius: var(--crediball-radius, 9999px); padding: 8px 14px;
+  }
+  button.referral-copy {
+    flex: none; appearance: none; cursor: pointer; background: transparent;
+    color: var(--crediball-ink, #1d1d1f); border: 1px solid var(--crediball-hairline, #e0e0e0);
+    font: inherit; font-size: 14px; padding: 8px 16px; border-radius: var(--crediball-radius, 9999px);
+    white-space: nowrap;
+  }
 `;
 var CrediballPaywallElement = class extends CrediballElement {
-  static get observedAttributes() {
-    return [...CrediballElement.observedAttributes, "open", "title", "description", "amounts"];
-  }
   constructor() {
     super();
+    this.referral = null;
+    this.referralCopied = false;
     this.shadow = this.attachShadow({ mode: "open" });
   }
+  static get observedAttributes() {
+    return [...CrediballElement.observedAttributes, "open", "title", "description", "amounts"];
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    void this.loadReferral();
+  }
+  attributeChangedCallback(name) {
+    super.attributeChangedCallback(name);
+    if (this.isConnected && (name === "publishable-key" || name === "user-id" || name === "api-url")) {
+      void this.loadReferral();
+    }
+  }
+  /** Fetch the user's invite link for the "Refer a friend" row (best-effort). */
+  async loadReferral() {
+    const publishableKey = this.getAttribute("publishable-key");
+    const userId = this.getAttribute("user-id");
+    const apiUrl = this.getAttribute("api-url") ?? void 0;
+    if (!publishableKey || !userId) {
+      this.referral = null;
+      return;
+    }
+    try {
+      const data = await fetchReferral({ publishableKey, userId, apiUrl });
+      this.referral = data.enabled ? data : null;
+    } catch {
+      this.referral = null;
+    }
+    if (this.hasAttribute("open")) this.render();
+  }
   open() {
     this.setAttribute("open", "");
   }
@@ -357,6 +401,13 @@ var CrediballPaywallElement = class extends CrediballElement {
                    <button class="custom-add" type="button">${escapeHtml(addButtonText)}</button>
                  </div>` : ""}
           <p class="error" hidden></p>
+          ${this.referral?.link ? `<div class="referral">
+                   <div class="eyebrow">${this.referral.rewardCredits && this.referral.rewardCredits > 0 ? `Refer a friend \xB7 earn ${formatCredits(this.referral.rewardCredits)} credits` : "Refer a friend"}</div>
+                   <div class="referral-row">
+                     <div class="link" title="${escapeHtml(this.referral.link)}">${escapeHtml(this.referral.link)}</div>
+                     <button class="referral-copy" type="button">${this.referralCopied ? "Copied!" : "Copy"}</button>
+                   </div>
+                 </div>` : ""}
           <button class="close" part="close" type="button">Not now</button>
         </div>
       </div>
@@ -365,6 +416,7 @@ var CrediballPaywallElement = class extends CrediballElement {
       if (e.target === e.currentTarget) this.close();
     });
     this.shadow.querySelector(".close")?.addEventListener("click", () => this.close());
+    this.shadow.querySelector(".referral-copy")?.addEventListener("click", () => void this.copyReferral());
     this.shadow.querySelectorAll("button.option").forEach((el) => {
       const btn = el;
       btn.addEventListener("click", () => {
@@ -414,6 +466,18 @@ var CrediballPaywallElement = class extends CrediballElement {
       });
     }
   }
+  /** Copy the invite link to the clipboard, with a 2s "Copied!" confirmation. */
+  async copyReferral() {
+    const link = this.referral?.link;
+    if (!link || typeof navigator === "undefined" || !navigator.clipboard) return;
+    await navigator.clipboard.writeText(link);
+    this.referralCopied = true;
+    this.render();
+    setTimeout(() => {
+      this.referralCopied = false;
+      if (this.hasAttribute("open")) this.render();
+    }, 2e3);
+  }
   /** Dispatch a cancelable option event; returns true when the host did NOT preventDefault. */
   emit(name, detail) {
     const ev = new CustomEvent(name, { detail, bubbles: true, composed: true, cancelable: true });
@@ -456,11 +520,191 @@ function showError(el, message) {
   }
 }
 
+// src/referral-card.ts
+import {
+  fetchReferral as fetchReferral2,
+  captureReferral,
+  completeStoredReferral
+} from "@crediball/core";
+var HTML_ESCAPES2 = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+function escapeHtml2(s) {
+  return s.replace(/[&<>"']/g, (c) => HTML_ESCAPES2[c] ?? c);
+}
+var STYLE2 = `
+  :host { font: var(--crediball-font, system-ui, -apple-system, sans-serif); color: var(--crediball-ink, #1d1d1f); }
+  .card {
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+    padding: 24px;
+    border: 1px solid var(--crediball-hairline, #e0e0e0);
+    border-radius: var(--crediball-radius-card, 18px);
+    background: var(--crediball-canvas, #ffffff);
+  }
+  .title { font-size: 16px; font-weight: 600; }
+  .desc { font-size: 13px; color: var(--crediball-ink-muted, #7a7a7a); margin-top: 2px; }
+  .row { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+  .link {
+    flex: 1 1 180px;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: 14px;
+    border: 1px solid var(--crediball-hairline, #e0e0e0);
+    border-radius: var(--crediball-radius, 9999px);
+    padding: 8px 14px;
+  }
+  button {
+    appearance: none;
+    cursor: pointer;
+    font: inherit;
+    font-size: 14px;
+    padding: 8px 16px;
+    border-radius: var(--crediball-radius, 9999px);
+    white-space: nowrap;
+  }
+  button.copy { border: 1px solid var(--crediball-hairline, #e0e0e0); background: transparent; color: var(--crediball-ink, #1d1d1f); }
+  button.share { border: none; background: var(--crediball-accent, #0066cc); color: var(--crediball-on-accent, #ffffff); }
+  .stats { display: flex; gap: 16px; font-size: 13px; color: var(--crediball-ink-muted, #7a7a7a); }
+  .stats strong { color: var(--crediball-ink, #1d1d1f); font-weight: 600; }
+`;
+var CrediballReferralCardElement = class extends CrediballElement {
+  constructor() {
+    super();
+    this.data = null;
+    this.copied = false;
+    this.copiedTimer = null;
+    this.shadow = this.attachShadow({ mode: "open" });
+  }
+  static get observedAttributes() {
+    return [
+      ...CrediballElement.observedAttributes,
+      "title",
+      "description",
+      "copy-label",
+      "share-label",
+      "hide-stats"
+    ];
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    void this.loadReferral();
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    if (this.copiedTimer) clearTimeout(this.copiedTimer);
+  }
+  attributeChangedCallback(name) {
+    super.attributeChangedCallback(name);
+    if (!this.isConnected) return;
+    if (name === "publishable-key" || name === "user-id" || name === "api-url") {
+      void this.loadReferral();
+    }
+  }
+  /** Auto-capture ?ref=, auto-complete once a user is known, then fetch the card data. */
+  async loadReferral() {
+    const publishableKey = this.getAttribute("publishable-key");
+    const userId = this.getAttribute("user-id");
+    const apiUrl = this.getAttribute("api-url") ?? void 0;
+    if (!publishableKey) return;
+    if (this.getAttribute("capture-referrals") !== "false") {
+      captureReferral({ publishableKey, apiUrl });
+      if (userId) {
+        void completeStoredReferral({ publishableKey, userId, apiUrl }).catch(() => {
+        });
+      }
+    }
+    if (!userId) {
+      this.data = null;
+      this.render();
+      return;
+    }
+    try {
+      this.data = await fetchReferral2({ publishableKey, userId, apiUrl });
+    } catch {
+      this.data = null;
+    }
+    this.render();
+  }
+  render() {
+    const d = this.data;
+    if (!d || !d.enabled || !d.code) {
+      this.shadow.innerHTML = "";
+      return;
+    }
+    const title = this.getAttribute("title") ?? "Invite friends";
+    const copyLabel = this.getAttribute("copy-label") ?? "Copy";
+    const shareLabel = this.getAttribute("share-label") ?? "Share";
+    const hideStats = this.getAttribute("hide-stats") != null;
+    const reward = d.rewardCredits ?? 0;
+    const referredReward = d.referredRewardCredits ?? 0;
+    const description = this.getAttribute("description") ?? (reward > 0 ? referredReward > 0 ? `Earn ${formatCredits(reward)} credits for every friend who joins \u2014 they get ${formatCredits(referredReward)} credits too.` : `Earn ${formatCredits(reward)} credits for every friend who joins.` : null);
+    const shown = d.link ?? d.code;
+    const rewards = d.rewards ?? { pending: 0, converted: 0, creditsEarned: 0 };
+    const canShare = typeof navigator !== "undefined" && typeof navigator.share === "function";
+    this.shadow.innerHTML = `
+      <style>${STYLE2}</style>
+      <div class="card" part="card">
+        <div>
+          <div class="title">${escapeHtml2(title)}</div>
+          ${description ? `<div class="desc">${escapeHtml2(description)}</div>` : ""}
+        </div>
+        <div class="row">
+          <div class="link" part="link" title="${escapeHtml2(shown)}">${escapeHtml2(shown)}</div>
+          <button class="copy" part="copy-button" type="button">${escapeHtml2(this.copied ? "Copied!" : copyLabel)}</button>
+          ${canShare ? `<button class="share" part="share-button" type="button">${escapeHtml2(shareLabel)}</button>` : ""}
+        </div>
+        ${hideStats ? "" : `<div class="stats">
+                 <span><strong>${d.clicks ?? 0}</strong> clicks</span>
+                 <span><strong>${rewards.converted}</strong> joined</span>
+                 ${rewards.creditsEarned > 0 ? `<span><strong>${formatCredits(rewards.creditsEarned)}</strong> credits earned</span>` : ""}
+               </div>`}
+      </div>
+    `;
+    this.shadow.querySelector("button.copy")?.addEventListener("click", () => void this.copy());
+    this.shadow.querySelector("button.share")?.addEventListener("click", () => void this.share());
+  }
+  linkOrCode() {
+    return this.data?.link ?? this.data?.code ?? null;
+  }
+  async copy() {
+    const text = this.linkOrCode();
+    if (!text || typeof navigator === "undefined" || !navigator.clipboard) return;
+    await navigator.clipboard.writeText(text);
+    this.copied = true;
+    this.render();
+    if (this.copiedTimer) clearTimeout(this.copiedTimer);
+    this.copiedTimer = setTimeout(() => {
+      this.copied = false;
+      this.render();
+    }, 2e3);
+  }
+  async share() {
+    const url = this.data?.link ?? void 0;
+    if (url && typeof navigator !== "undefined" && typeof navigator.share === "function") {
+      try {
+        await navigator.share({ url });
+        return;
+      } catch {
+      }
+    }
+    await this.copy();
+  }
+};
+
 export {
   CrediballElement,
   CrediballBalanceElement,
   CrediballUsageElement,
   CrediballTopUpButtonElement,
   CrediballLowCreditWarningElement,
-  CrediballPaywallElement
+  CrediballPaywallElement,
+  CrediballReferralCardElement
 };

package/dist/crediball-elements.iife.js

@@ -25,6 +25,7 @@ var Crediball = (() => {
     CrediballElement: () => CrediballElement,
     CrediballLowCreditWarningElement: () => CrediballLowCreditWarningElement,
     CrediballPaywallElement: () => CrediballPaywallElement,
+    CrediballReferralCardElement: () => CrediballReferralCardElement,
     CrediballTopUpButtonElement: () => CrediballTopUpButtonElement,
     CrediballUsageElement: () => CrediballUsageElement
   });
@@ -301,6 +302,69 @@ var Crediball = (() => {
     return client;
   }
 
+  // ../core/dist/referral.js
+  var storageKey = (publishableKey) => `crediball_ref_${publishableKey}`;
+  function apiBase(config) {
+    return (config.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+  }
+  function authHeaders(config) {
+    return { Authorization: `Bearer ${config.publishableKey}` };
+  }
+  function getStoredReferralCode(publishableKey) {
+    try {
+      return window.localStorage.getItem(storageKey(publishableKey));
+    } catch {
+      return null;
+    }
+  }
+  function clearStoredReferralCode(publishableKey) {
+    try {
+      window.localStorage.removeItem(storageKey(publishableKey));
+    } catch {
+    }
+  }
+  function captureReferral(config, code) {
+    let captured = code?.trim();
+    if (!captured && typeof window !== "undefined") {
+      captured = new URLSearchParams(window.location.search).get("ref")?.trim() ?? void 0;
+    }
+    if (!captured)
+      return;
+    captured = captured.toUpperCase();
+    const already = getStoredReferralCode(config.publishableKey);
+    try {
+      window.localStorage.setItem(storageKey(config.publishableKey), captured);
+    } catch {
+      return;
+    }
+    if (already === captured)
+      return;
+    void fetchJson(`${apiBase(config)}/public/referral/click`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...authHeaders(config) },
+      body: JSON.stringify({ code: captured })
+    }, "Referral click").catch(() => {
+    });
+  }
+  async function completeStoredReferral(config) {
+    const code = getStoredReferralCode(config.publishableKey);
+    if (!code || !config.userId)
+      return;
+    await fetchJson(`${apiBase(config)}/public/referral/complete`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...authHeaders(config) },
+      body: JSON.stringify({ code, userId: config.userId })
+    }, "Referral completion");
+    clearStoredReferralCode(config.publishableKey);
+  }
+  async function fetchReferral(config) {
+    const data = await fetchJson(`${apiBase(config)}/public/referral?userId=${encodeURIComponent(config.userId)}`, { headers: authHeaders(config) }, "Referral fetch");
+    if (data.enabled && data.code && !data.link && typeof window !== "undefined") {
+      data.link = `${window.location.origin}/?ref=${data.code}`;
+    }
+    return data;
+  }
+
   // ../core/dist/format.js
   function formatCredits(credits) {
     return new Intl.NumberFormat(void 0).format(Math.round(credits));
@@ -630,15 +694,59 @@ var Crediball = (() => {
     padding: 11px 22px;
     border-radius: var(--crediball-radius, 9999px);
   }
+  .referral { margin-top: 20px; padding-top: 16px; border-top: 1px solid var(--crediball-hairline, #e0e0e0); }
+  .referral .eyebrow { margin-bottom: 8px; }
+  .referral-row { display: flex; gap: 8px; align-items: center; }
+  .referral-row .link {
+    flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    font-size: 13px; color: var(--crediball-ink, #1d1d1f);
+    border: 1px solid var(--crediball-hairline, #e0e0e0);
+    border-radius: var(--crediball-radius, 9999px); padding: 8px 14px;
+  }
+  button.referral-copy {
+    flex: none; appearance: none; cursor: pointer; background: transparent;
+    color: var(--crediball-ink, #1d1d1f); border: 1px solid var(--crediball-hairline, #e0e0e0);
+    font: inherit; font-size: 14px; padding: 8px 16px; border-radius: var(--crediball-radius, 9999px);
+    white-space: nowrap;
+  }
 `;
   var CrediballPaywallElement = class extends CrediballElement {
-    static get observedAttributes() {
-      return [...CrediballElement.observedAttributes, "open", "title", "description", "amounts"];
-    }
     constructor() {
       super();
+      this.referral = null;
+      this.referralCopied = false;
       this.shadow = this.attachShadow({ mode: "open" });
     }
+    static get observedAttributes() {
+      return [...CrediballElement.observedAttributes, "open", "title", "description", "amounts"];
+    }
+    connectedCallback() {
+      super.connectedCallback();
+      void this.loadReferral();
+    }
+    attributeChangedCallback(name) {
+      super.attributeChangedCallback(name);
+      if (this.isConnected && (name === "publishable-key" || name === "user-id" || name === "api-url")) {
+        void this.loadReferral();
+      }
+    }
+    /** Fetch the user's invite link for the "Refer a friend" row (best-effort). */
+    async loadReferral() {
+      const publishableKey = this.getAttribute("publishable-key");
+      const userId = this.getAttribute("user-id");
+      const apiUrl = this.getAttribute("api-url") ?? void 0;
+      if (!publishableKey || !userId) {
+        this.referral = null;
+        return;
+      }
+      try {
+        const data = await fetchReferral({ publishableKey, userId, apiUrl });
+        this.referral = data.enabled ? data : null;
+      } catch {
+        this.referral = null;
+      }
+      if (this.hasAttribute("open")) this.render();
+    }
     open() {
       this.setAttribute("open", "");
     }
@@ -704,6 +812,13 @@ var Crediball = (() => {
                    <button class="custom-add" type="button">${escapeHtml(addButtonText)}</button>
                  </div>` : ""}
           <p class="error" hidden></p>
+          ${this.referral?.link ? `<div class="referral">
+                   <div class="eyebrow">${this.referral.rewardCredits && this.referral.rewardCredits > 0 ? `Refer a friend \xB7 earn ${formatCredits(this.referral.rewardCredits)} credits` : "Refer a friend"}</div>
+                   <div class="referral-row">
+                     <div class="link" title="${escapeHtml(this.referral.link)}">${escapeHtml(this.referral.link)}</div>
+                     <button class="referral-copy" type="button">${this.referralCopied ? "Copied!" : "Copy"}</button>
+                   </div>
+                 </div>` : ""}
           <button class="close" part="close" type="button">Not now</button>
         </div>
       </div>
@@ -712,6 +827,7 @@ var Crediball = (() => {
         if (e.target === e.currentTarget) this.close();
       });
       this.shadow.querySelector(".close")?.addEventListener("click", () => this.close());
+      this.shadow.querySelector(".referral-copy")?.addEventListener("click", () => void this.copyReferral());
       this.shadow.querySelectorAll("button.option").forEach((el) => {
         const btn = el;
         btn.addEventListener("click", () => {
@@ -761,6 +877,18 @@ var Crediball = (() => {
         });
       }
     }
+    /** Copy the invite link to the clipboard, with a 2s "Copied!" confirmation. */
+    async copyReferral() {
+      const link = this.referral?.link;
+      if (!link || typeof navigator === "undefined" || !navigator.clipboard) return;
+      await navigator.clipboard.writeText(link);
+      this.referralCopied = true;
+      this.render();
+      setTimeout(() => {
+        this.referralCopied = false;
+        if (this.hasAttribute("open")) this.render();
+      }, 2e3);
+    }
     /** Dispatch a cancelable option event; returns true when the host did NOT preventDefault. */
     emit(name, detail) {
       const ev = new CustomEvent(name, { detail, bubbles: true, composed: true, cancelable: true });
@@ -803,6 +931,180 @@ var Crediball = (() => {
     }
   }
 
+  // src/referral-card.ts
+  var HTML_ESCAPES2 = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;"
+  };
+  function escapeHtml2(s) {
+    return s.replace(/[&<>"']/g, (c) => HTML_ESCAPES2[c] ?? c);
+  }
+  var STYLE2 = `
+  :host { font: var(--crediball-font, system-ui, -apple-system, sans-serif); color: var(--crediball-ink, #1d1d1f); }
+  .card {
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+    padding: 24px;
+    border: 1px solid var(--crediball-hairline, #e0e0e0);
+    border-radius: var(--crediball-radius-card, 18px);
+    background: var(--crediball-canvas, #ffffff);
+  }
+  .title { font-size: 16px; font-weight: 600; }
+  .desc { font-size: 13px; color: var(--crediball-ink-muted, #7a7a7a); margin-top: 2px; }
+  .row { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+  .link {
+    flex: 1 1 180px;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: 14px;
+    border: 1px solid var(--crediball-hairline, #e0e0e0);
+    border-radius: var(--crediball-radius, 9999px);
+    padding: 8px 14px;
+  }
+  button {
+    appearance: none;
+    cursor: pointer;
+    font: inherit;
+    font-size: 14px;
+    padding: 8px 16px;
+    border-radius: var(--crediball-radius, 9999px);
+    white-space: nowrap;
+  }
+  button.copy { border: 1px solid var(--crediball-hairline, #e0e0e0); background: transparent; color: var(--crediball-ink, #1d1d1f); }
+  button.share { border: none; background: var(--crediball-accent, #0066cc); color: var(--crediball-on-accent, #ffffff); }
+  .stats { display: flex; gap: 16px; font-size: 13px; color: var(--crediball-ink-muted, #7a7a7a); }
+  .stats strong { color: var(--crediball-ink, #1d1d1f); font-weight: 600; }
+`;
+  var CrediballReferralCardElement = class extends CrediballElement {
+    constructor() {
+      super();
+      this.data = null;
+      this.copied = false;
+      this.copiedTimer = null;
+      this.shadow = this.attachShadow({ mode: "open" });
+    }
+    static get observedAttributes() {
+      return [
+        ...CrediballElement.observedAttributes,
+        "title",
+        "description",
+        "copy-label",
+        "share-label",
+        "hide-stats"
+      ];
+    }
+    connectedCallback() {
+      super.connectedCallback();
+      void this.loadReferral();
+    }
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      if (this.copiedTimer) clearTimeout(this.copiedTimer);
+    }
+    attributeChangedCallback(name) {
+      super.attributeChangedCallback(name);
+      if (!this.isConnected) return;
+      if (name === "publishable-key" || name === "user-id" || name === "api-url") {
+        void this.loadReferral();
+      }
+    }
+    /** Auto-capture ?ref=, auto-complete once a user is known, then fetch the card data. */
+    async loadReferral() {
+      const publishableKey = this.getAttribute("publishable-key");
+      const userId = this.getAttribute("user-id");
+      const apiUrl = this.getAttribute("api-url") ?? void 0;
+      if (!publishableKey) return;
+      if (this.getAttribute("capture-referrals") !== "false") {
+        captureReferral({ publishableKey, apiUrl });
+        if (userId) {
+          void completeStoredReferral({ publishableKey, userId, apiUrl }).catch(() => {
+          });
+        }
+      }
+      if (!userId) {
+        this.data = null;
+        this.render();
+        return;
+      }
+      try {
+        this.data = await fetchReferral({ publishableKey, userId, apiUrl });
+      } catch {
+        this.data = null;
+      }
+      this.render();
+    }
+    render() {
+      const d = this.data;
+      if (!d || !d.enabled || !d.code) {
+        this.shadow.innerHTML = "";
+        return;
+      }
+      const title = this.getAttribute("title") ?? "Invite friends";
+      const copyLabel = this.getAttribute("copy-label") ?? "Copy";
+      const shareLabel = this.getAttribute("share-label") ?? "Share";
+      const hideStats = this.getAttribute("hide-stats") != null;
+      const reward = d.rewardCredits ?? 0;
+      const referredReward = d.referredRewardCredits ?? 0;
+      const description = this.getAttribute("description") ?? (reward > 0 ? referredReward > 0 ? `Earn ${formatCredits(reward)} credits for every friend who joins \u2014 they get ${formatCredits(referredReward)} credits too.` : `Earn ${formatCredits(reward)} credits for every friend who joins.` : null);
+      const shown = d.link ?? d.code;
+      const rewards = d.rewards ?? { pending: 0, converted: 0, creditsEarned: 0 };
+      const canShare = typeof navigator !== "undefined" && typeof navigator.share === "function";
+      this.shadow.innerHTML = `
+      <style>${STYLE2}</style>
+      <div class="card" part="card">
+        <div>
+          <div class="title">${escapeHtml2(title)}</div>
+          ${description ? `<div class="desc">${escapeHtml2(description)}</div>` : ""}
+        </div>
+        <div class="row">
+          <div class="link" part="link" title="${escapeHtml2(shown)}">${escapeHtml2(shown)}</div>
+          <button class="copy" part="copy-button" type="button">${escapeHtml2(this.copied ? "Copied!" : copyLabel)}</button>
+          ${canShare ? `<button class="share" part="share-button" type="button">${escapeHtml2(shareLabel)}</button>` : ""}
+        </div>
+        ${hideStats ? "" : `<div class="stats">
+                 <span><strong>${d.clicks ?? 0}</strong> clicks</span>
+                 <span><strong>${rewards.converted}</strong> joined</span>
+                 ${rewards.creditsEarned > 0 ? `<span><strong>${formatCredits(rewards.creditsEarned)}</strong> credits earned</span>` : ""}
+               </div>`}
+      </div>
+    `;
+      this.shadow.querySelector("button.copy")?.addEventListener("click", () => void this.copy());
+      this.shadow.querySelector("button.share")?.addEventListener("click", () => void this.share());
+    }
+    linkOrCode() {
+      return this.data?.link ?? this.data?.code ?? null;
+    }
+    async copy() {
+      const text = this.linkOrCode();
+      if (!text || typeof navigator === "undefined" || !navigator.clipboard) return;
+      await navigator.clipboard.writeText(text);
+      this.copied = true;
+      this.render();
+      if (this.copiedTimer) clearTimeout(this.copiedTimer);
+      this.copiedTimer = setTimeout(() => {
+        this.copied = false;
+        this.render();
+      }, 2e3);
+    }
+    async share() {
+      const url = this.data?.link ?? void 0;
+      if (url && typeof navigator !== "undefined" && typeof navigator.share === "function") {
+        try {
+          await navigator.share({ url });
+          return;
+        } catch {
+        }
+      }
+      await this.copy();
+    }
+  };
+
   // src/register.ts
   function define(name, ctor) {
     if (!customElements.get(name)) customElements.define(name, ctor);
@@ -812,5 +1114,6 @@ var Crediball = (() => {
   define("crediball-topup-button", CrediballTopUpButtonElement);
   define("crediball-low-credit-warning", CrediballLowCreditWarningElement);
   define("crediball-paywall", CrediballPaywallElement);
+  define("crediball-referral-card", CrediballReferralCardElement);
   return __toCommonJS(iife_exports);
 })();

package/dist/index.d.ts

@@ -110,11 +110,19 @@ declare class CrediballLowCreditWarningElement extends CrediballElement {
  */
 declare class CrediballPaywallElement extends CrediballElement {
     private shadow;
+    private referral;
+    private referralCopied;
     static get observedAttributes(): string[];
     constructor();
+    connectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    /** Fetch the user's invite link for the "Refer a friend" row (best-effort). */
+    private loadReferral;
     open(): void;
     close(): void;
     protected render(): void;
+    /** Copy the invite link to the clipboard, with a 2s "Copied!" confirmation. */
+    private copyReferral;
     /** Dispatch a cancelable option event; returns true when the host did NOT preventDefault. */
     private emit;
     private returnPath;
@@ -125,4 +133,39 @@ declare class CrediballPaywallElement extends CrediballElement {
     private redirect;
 }
 
-export { CrediballBalanceElement, CrediballElement, CrediballLowCreditWarningElement, CrediballPaywallElement, CrediballTopUpButtonElement, CrediballUsageElement };
+/**
+ * <crediball-referral-card publishable-key="cb_pub_..." user-id="u123"></crediball-referral-card>
+ *
+ * Drop-in invite card — the web-component sibling of @crediball/react's
+ * <ReferralCard/>, wrapping the same @crediball/core referral functions:
+ *  - lazily creates + fetches the user's referral code/link/stats,
+ *  - AUTO-CAPTURES a `?ref=CODE` visit into localStorage and, once a user-id is
+ *    present, attaches it as a pending referral (set `capture-referrals="false"`
+ *    to opt out and drive capture/completion yourself),
+ *  - renders nothing while loading or when the referral program is disabled in
+ *    the dashboard.
+ *
+ * Rewards are only ever granted server-side, when the dashboard-configured
+ * conversion condition is observed on a secret-key call — a browser can't
+ * trigger a payout. Optional attributes: title, description, copy-label,
+ * share-label, hide-stats.
+ */
+declare class CrediballReferralCardElement extends CrediballElement {
+    private shadow;
+    private data;
+    private copied;
+    private copiedTimer;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    /** Auto-capture ?ref=, auto-complete once a user is known, then fetch the card data. */
+    private loadReferral;
+    protected render(): void;
+    private linkOrCode;
+    private copy;
+    private share;
+}
+
+export { CrediballBalanceElement, CrediballElement, CrediballLowCreditWarningElement, CrediballPaywallElement, CrediballReferralCardElement, CrediballTopUpButtonElement, CrediballUsageElement };

package/dist/index.js

@@ -3,14 +3,16 @@ import {
   CrediballElement,
   CrediballLowCreditWarningElement,
   CrediballPaywallElement,
+  CrediballReferralCardElement,
   CrediballTopUpButtonElement,
   CrediballUsageElement
-} from "./chunk-WUPVPARI.js";
+} from "./chunk-MWB56UEW.js";
 export {
   CrediballBalanceElement,
   CrediballElement,
   CrediballLowCreditWarningElement,
   CrediballPaywallElement,
+  CrediballReferralCardElement,
   CrediballTopUpButtonElement,
   CrediballUsageElement
 };

package/dist/register.js

@@ -2,9 +2,10 @@ import {
   CrediballBalanceElement,
   CrediballLowCreditWarningElement,
   CrediballPaywallElement,
+  CrediballReferralCardElement,
   CrediballTopUpButtonElement,
   CrediballUsageElement
-} from "./chunk-WUPVPARI.js";
+} from "./chunk-MWB56UEW.js";
 
 // src/register.ts
 function define(name, ctor) {
@@ -15,3 +16,4 @@ define("crediball-usage", CrediballUsageElement);
 define("crediball-topup-button", CrediballTopUpButtonElement);
 define("crediball-low-credit-warning", CrediballLowCreditWarningElement);
 define("crediball-paywall", CrediballPaywallElement);
+define("crediball-referral-card", CrediballReferralCardElement);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/elements",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Framework-agnostic web components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",