@kolbo/mcp 1.115.0 → 1.117.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.115.0",
+  "version": "1.117.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/src/apps/widgets/plans.js

@@ -24,7 +24,11 @@ const { widgetPage } = require('../html');
  *   plans:        [{ key, name, interval, credits, price, original_price,
  *                    discount_percent, promo_text, currency, top_up_discount }],
  *   credit_packs: [{ …, subscriber_price, is_subscriber }],
- *   pricing_url
+ *   pricing_url,
+ *   // insufficient_credits only — leads the card (packs out-convert plans
+ *   // for users who just ran out); every URL carries MCP attribution tags:
+ *   recommended_pack: { …pack, covers_shortfall, url } | null,
+ *   pack_url, home_url
  * }
  */
 
@@ -52,11 +56,15 @@ var state = null;
 var interval = 'month';
 
 el('logo').innerHTML = KOLBO_LOGO + '<span>Kolbo</span>';
-el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink('https://app.kolbo.ai'); };
+function homeUrl() { return (state && state.home_url) || 'https://app.kolbo.ai'; }
+el('kolbo-link').onclick = function (e) { e.preventDefault(); window.kolbo.openLink(homeUrl()); };
+// Own handler so the shared untagged logo link (html.js) never fires here.
+el('logo').onclick = function (e) { e.stopPropagation(); window.kolbo.openLink(homeUrl()); };
 
 function pricingUrl() {
   return (state && state.pricing_url) || 'https://app.kolbo.ai/pricing';
 }
+function packUrl() { return (state && state.pack_url) || pricingUrl(); }
 function money(v, currency) {
   if (v == null || isNaN(v)) return '';
   var sym = { usd: '$', eur: '\u20ac', gbp: '\u00a3', ils: '\u20aa' }[String(currency || 'usd').toLowerCase()] || '';
@@ -76,7 +84,9 @@ function planCard(p, opts) {
   var note = p.promo_text ? '<div class="k-plan-note">' + esc(p.promo_text) + '</div>'
     : (opts.pack && p.is_subscriber && p.subscriber_price != null ? '<div class="k-plan-note">Subscriber price applied</div>' : '')
       + (!opts.pack && p.top_up_discount ? '<div class="k-plan-note">Cheaper credit packs included</div>' : '');
-  var cta = current ? '' : '<button class="k-btn ' + (opts.pack ? 'ghost' : 'primary') + '" data-open="1">' + (opts.pack ? 'Buy pack' : 'Upgrade') + ' ' + ICONS.open + '</button>';
+  if (opts.lead) note += '<div class="k-plan-note">One-time top-up, no subscription</div>';
+  var primary = opts.pack ? opts.lead : !state.recommended_pack;
+  var cta = current ? '' : '<button class="k-btn ' + (primary ? 'primary' : 'ghost') + '" data-open="' + (opts.pack ? 'pack' : 'plan') + '">' + (opts.pack ? 'Buy pack' : 'Upgrade') + ' ' + ICONS.open + '</button>';
   return '<div class="k-plan' + (current ? ' current' : '') + '">' +
     '<div class="k-plan-top"><span class="k-plan-name">' + esc(p.name || p.key || 'Plan') + '</span>' + badge + '</div>' +
     (p.credits != null ? '<div class="k-plan-credits">' + ICONS.sparkle + ' ' + esc(fmtCredits(p.credits)) + ' credits' + (opts.pack ? '' : ' / ' + (isAnnual(p) ? 'year' : 'month')) + '</div>' : '') +
@@ -85,12 +95,17 @@ function planCard(p, opts) {
 
 function renderStage() {
   var plans = (state.plans || []).filter(function (p) { return p && (p.price != null || p.credits != null); });
-  var packs = (state.credit_packs || []).filter(function (p) { return p && p.price != null; });
+  var lead = state.recommended_pack;
+  var packs = (state.credit_packs || []).filter(function (p) { return p && p.price != null && !(lead && lead.key != null && p.key === lead.key); });
   var monthly = plans.filter(function (p) { return !isAnnual(p); });
   var annual = plans.filter(isAnnual);
   var hasToggle = monthly.length && annual.length;
   var shown = hasToggle ? (interval === 'year' ? annual : monthly) : plans;
   var html = '';
+  if (lead) {
+    html += '<div class="k-pack-head">Quickest fix</div><div class="k-plan-grid">' + planCard(lead, { pack: true, lead: true }) + '</div>' +
+      '<div class="k-pack-head">Or upgrade your plan</div>';
+  }
   if (hasToggle) {
     html += '<div class="k-plan-toggle">' +
       '<button class="k-toggle-btn' + (interval === 'month' ? ' active' : '') + '" data-interval="month">Monthly</button>' +
@@ -98,7 +113,7 @@ function renderStage() {
   }
   if (shown.length) html += '<div class="k-plan-grid">' + shown.map(function (p) { return planCard(p, {}); }).join('') + '</div>';
   if (packs.length) {
-    html += '<div class="k-pack-head">Credit packs</div><div class="k-plan-grid">' +
+    html += '<div class="k-pack-head">' + (lead ? 'Other credit packs' : 'Credit packs') + '</div><div class="k-plan-grid">' +
       packs.map(function (p) { return planCard(p, { pack: true }); }).join('') + '</div>';
   }
   if (!html) html = '<div class="k-plan-note">Live plans and prices are on the Kolbo pricing page.</div>';
@@ -106,7 +121,7 @@ function renderStage() {
   var btns = el('stage').querySelectorAll('[data-interval]');
   for (var i = 0; i < btns.length; i++) btns[i].onclick = function () { interval = this.getAttribute('data-interval'); renderStage(); window.kolbo.notifySize(); };
   var opens = el('stage').querySelectorAll('[data-open]');
-  for (var j = 0; j < opens.length; j++) opens[j].onclick = function () { window.kolbo.openLink(pricingUrl()); };
+  for (var j = 0; j < opens.length; j++) opens[j].onclick = function () { window.kolbo.openLink(this.getAttribute('data-open') === 'pack' ? packUrl() : pricingUrl()); };
 }
 
 function boot(sc) {

package/src/tools/_shared.js

@@ -1163,12 +1163,44 @@ function compactList(items, { fields, cap = 50, total, extra, note, maxChars = M
   return text;
 }
 
+// Every link out of the out-of-credits card carries the same tags so MCP
+// purchases are attributable. kolbo-map's /pricing reads only `category`
+// (month | annual | one_time) — no per-pack preselect exists, so the pack link
+// lands on the credit-pack tab.
+function upgradeCardUrl(path, content, query = {}) {
+  const url = new URL(path, APP_BASE_URL);
+  const params = {
+    ...query,
+    utm_source: 'mcp',
+    utm_medium: 'upgrade_card',
+    utm_campaign: 'out_of_credits',
+    utm_content: content,
+    // kolbo-map's stable funnel-join fields (ANALYTICS_ATTRIBUTION_KEYS).
+    attribution_link_id: `mcp_upgrade_card_${content}`,
+    attribution_trigger: 'mcp_insufficient_credits',
+    upgrade_entry: 'mcp_upgrade_card',
+  };
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+  return url.toString();
+}
+
+// Smallest pack that covers the shortfall; the largest when none does; the
+// smallest when the shortfall is unknown.
+function packForShortfall(packs, shortfall) {
+  const sized = (packs || [])
+    .filter((p) => p && Number.isFinite(p.credits) && p.price != null)
+    .sort((a, b) => a.credits - b.credits);
+  if (!sized.length) return null;
+  return sized.find((p) => !(shortfall > 0) || p.credits >= shortfall) || sized[sized.length - 1];
+}
+
 /**
  * Turn a 403 INSUFFICIENT_CREDITS into the plans/upgrade card.
  *
  * Without this the user just sees the raw API sentence and has to go find the
- * pricing page themselves. The card states the shortfall, shows live
- * promo-adjusted plans, and links to app.kolbo.ai/pricing.
+ * pricing page themselves. The card states the shortfall, leads with the
+ * credit pack that covers it, shows live promo-adjusted plans below, and links
+ * to app.kolbo.ai/pricing with MCP attribution tags.
  *
  * Returns null for any other error so callers can rethrow untouched. The plan
  * fetch is best-effort: if it fails we still return a card carrying the
@@ -1209,30 +1241,56 @@ async function insufficientCreditsResult(client, err, options = {}) {
 
   const balance = err.data?.balance ?? data?.credits?.total;
   const required = err.data?.required;
+  const shortfall = (Number.isFinite(balance) && Number.isFinite(required))
+    ? Math.max(0, required - balance) : undefined;
+  const credit_packs = data?.credit_packs || [];
+  const pack = packForShortfall(credit_packs, shortfall);
+  const pack_url = upgradeCardUrl('/pricing', 'credit_pack', { category: 'one_time' });
   const structured = {
     widget: 'plans',
     reason: 'insufficient_credits',
     balance,
     required,
-    shortfall: (Number.isFinite(balance) && Number.isFinite(required))
-      ? Math.max(0, required - balance) : undefined,
+    shortfall,
     current_plan: data?.current_plan || null,
+    // Leads the card: out of credits on the web app, packs convert 56% vs
+    // plans 17.5%. Plans stay below as the alternative.
+    recommended_pack: pack ? {
+      ...pack,
+      // Only when the shortfall is known (and `required` is the API's lower
+      // bound, so this is a floor, not a promise).
+      covers_shortfall: shortfall > 0 && pack.credits >= shortfall,
+      url: pack_url,
+    } : null,
     plans: data?.plans || [],
-    credit_packs: data?.credit_packs || [],
-    pricing_url: err.data?.pricing_url || data?.pricing_url || 'https://app.kolbo.ai/pricing',
+    credit_packs,
+    // MCP-tagged, not the API's sdk-tagged link: every way out of this card
+    // must be attributable to it.
+    pricing_url: upgradeCardUrl('/pricing', 'plans'),
+    pack_url,
+    home_url: upgradeCardUrl('/', 'home'),
   };
 
   // structuredContent shadows the text on widget hosts, so the refusal reason
   // has to be inside the object too — an agent that only reads structured
   // content must still understand that nothing was generated.
   structured.error = err.message;
-  structured._hint = 'The generation did NOT run and nothing was charged. An upgrade card is shown to the user. Tell them they are out of credits and point at the card; do not retry the generation, and do not attempt to purchase anything for them.';
+  structured._hint = 'The generation did NOT run and nothing was charged. An upgrade card is shown to the user. Tell them they are out of credits and point at the card; '
+    + (pack ? 'the quickest fix is the one-time credit pack it leads with (recommended_pack), with plans as the alternative; ' : '')
+    + 'do not retry the generation, and do not attempt to purchase anything for them.';
 
   const text = JSON.stringify({
     error: err.message,
     code: 'INSUFFICIENT_CREDITS',
     balance,
     required,
+    recommended_pack: structured.recommended_pack && {
+      name: pack.name,
+      credits: pack.credits,
+      price: pack.price,
+      currency: pack.currency,
+      url: pack_url,
+    },
     pricing_url: structured.pricing_url,
     _hint: structured._hint,
   }, null, 2);

package/src/tools/models.js

@@ -115,6 +115,17 @@ const identifierRow = (m) => ({
   ...(m.new_model ? { new_model: true } : {}),
 });
 
+// upgrade_entry credits a purchase to the surface that sent the user (kolbo-map
+// markUpgradeEntryFromUrl). Set server-side so the card AND the text link carry it;
+// a tag already on the URL is kept.
+function withUpgradeEntry(raw, entry) {
+  try {
+    const u = new URL(raw);
+    if (!u.searchParams.has('upgrade_entry')) u.searchParams.set('upgrade_entry', entry);
+    return u.toString();
+  } catch { return raw; }
+}
+
 function registerModelTools(server, client, options = {}) {
   const ui = () => appsEnabled(server, options);
   // ─── list_models ───────────────────────────────────────────
@@ -516,7 +527,7 @@ function registerModelTools(server, client, options = {}) {
         current_plan: data?.current_plan || null,
         plans: data?.plans || [],
         credit_packs: data?.credit_packs || [],
-        pricing_url: data?.pricing_url || 'https://app.kolbo.ai/pricing',
+        pricing_url: withUpgradeEntry(data?.pricing_url || 'https://app.kolbo.ai/pricing', 'mcp_plans_card'),
       };
       // structuredContent SHADOWS the text on widget hosts, so everything the
       // agent needs to talk about pricing has to live in the object above.
@@ -533,4 +544,4 @@ function registerModelTools(server, client, options = {}) {
   );
 }
 
-module.exports = { registerModelTools };
+module.exports = { registerModelTools, withUpgradeEntry };