@billing-io/designs 1.0.0

package/src/brand.ts

@@ -0,0 +1,62 @@
+// @billing-io/designs — Brand assets
+// Canonical SVG badge and brand constants for billing.io
+
+/**
+ * Full SVG logo badge (the "b." glyph) used in billing.js overlay headers.
+ * This is the production brand mark — use this in all customer-facing contexts.
+ */
+export const BRAND_SVG_VIEWBOX = "0 0 1024 1024";
+
+export const BRAND_SVG_PATHS = {
+  background: { fill: "#000", d: "" },
+  letterB: {
+    fill: "#fff",
+    d: "M648.077,530.65c0,46.2-18.34,81.95-55,107.25-25.3,17.239-51.7,25.851-79.2,25.851-10.27,0-25.119-3.301-44.55-9.9-10.27-3.661-18.149-5.5-23.649-5.5-9.9,0-19.989,3.67-30.25,11-2.2,1.461-3.851,2.2-4.95,2.2-2.569,0-4.039-1.101-4.4-3.3-.369-2.2-.55-8.801-.55-19.801v-322.85c0-9.53-1.719-15.761-5.156-18.7-3.438-2.931-10.948-4.4-22.533-4.4-9.771,0-14.66-1.28-14.66-3.85s2.234-3.85,6.694-3.85c41.653,0,77.919-4.581,108.797-13.75l.559,8.8v162.25c14.618-20.161,34.899-30.25,60.853-30.25,31.427,0,57.285,11.095,77.567,33.274,20.281,22.189,30.43,50.695,30.43,85.525ZM566.127,532.851c0-71.131-14.85-106.7-44.55-106.7-16.5,0-28.6,7.7-36.3,23.1-2.939,5.87-4.675,12.745-5.225,20.625-.551,7.89-.825,30.345-.825,67.375v33.551c0,34.469,2.286,57.294,6.875,68.475,4.58,11.189,13.836,16.775,27.774,16.775,19.062,0,32.536-9.351,40.426-28.051,7.88-18.699,11.824-50.41,11.824-95.149Z",
+  },
+  dot: {
+    fill: "#fff",
+    d: "M692.003,642.041c0,7.235-2.336,13.186-7,17.851-4.671,4.665-10.621,7-17.851,7s-13.3-2.396-18.2-7.175c-4.899-4.78-7.35-10.676-7.35-17.676,0-7.229,2.45-13.3,7.35-18.199s10.965-7.351,18.2-7.351c6.765,0,12.601,2.45,17.5,7.351,4.9,4.899,7.351,10.97,7.351,18.199Z",
+  },
+};
+
+/**
+ * Build an inline-HTML brand badge at the given size.
+ * This is the full SVG version used in the canonical billing.js.
+ */
+export type BadgeSize = "sm" | "md" | "lg";
+
+export interface BadgeDimensions {
+  size: number;
+  borderRadius: number;
+}
+
+export const BADGE_DIMENSIONS: Record<BadgeSize, BadgeDimensions> = {
+  sm: { size: 18, borderRadius: 4 },
+  md: { size: 20, borderRadius: 5 },
+  lg: { size: 24, borderRadius: 6 },
+};
+
+export function buildBrandBadgeHTML(size: BadgeSize = "md"): string {
+  const { size: dim, borderRadius: br } = BADGE_DIMENSIONS[size];
+  return (
+    `<div style="width:${dim}px;height:${dim}px;background:#000;border-radius:${br}px;display:flex;align-items:center;justify-content:center;overflow:hidden;">` +
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${BRAND_SVG_VIEWBOX}" width="${dim}" height="${dim}">` +
+    `<rect width="1024" height="1024" fill="#000"/>` +
+    `<path fill="${BRAND_SVG_PATHS.letterB.fill}" d="${BRAND_SVG_PATHS.letterB.d}"/>` +
+    `<path fill="${BRAND_SVG_PATHS.dot.fill}" d="${BRAND_SVG_PATHS.dot.d}"/>` +
+    `</svg></div>`
+  );
+}
+
+/**
+ * Get the full SVG markup for the brand logo (no container div).
+ */
+export function getBrandSVG(width: number = 24, height: number = 24): string {
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${BRAND_SVG_VIEWBOX}" width="${width}" height="${height}">` +
+    `<rect width="1024" height="1024" fill="#000"/>` +
+    `<path fill="${BRAND_SVG_PATHS.letterB.fill}" d="${BRAND_SVG_PATHS.letterB.d}"/>` +
+    `<path fill="${BRAND_SVG_PATHS.dot.fill}" d="${BRAND_SVG_PATHS.dot.d}"/>` +
+    `</svg>`
+  );
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+// @billing-io/designs — Centralized design definitions for billing.io
+//
+// This package is the single source of truth for:
+//   - Plan/pricing definitions and types
+//   - Brand assets (SVG badge, logo)
+//   - Checkout overlay design constants (variations, animations, dimensions)
+//   - Billing system constants (thresholds, event types)
+//
+// All billing.io projects should import from this package instead of
+// duplicating these values.
+
+// Plans, pricing, and billing constants
+export {
+  PLANS,
+  MARKETING_PLANS,
+  MARKETING_SANDBOX,
+  COMPARISON_PLANS,
+  COMPARISON_DATA,
+  PRICING_FAQS,
+  MID_CYCLE_THRESHOLD_USD,
+  PAST_DUE_RESTRICT_HOURS,
+  RESTRICT_SUSPEND_HOURS,
+  USAGE_WARNING_THRESHOLD,
+  BILLING_EMAIL_EVENTS,
+  BILLING_EVENT_TYPES,
+} from "./plans.js";
+
+export type {
+  PlanId,
+  BillingStatus,
+  PlanConfig,
+  MarketingPlan,
+  MarketingSandboxPlan,
+  ComparisonValue,
+  ComparisonFeature,
+  ComparisonSection,
+  FaqEntry,
+} from "./plans.js";
+
+// Brand assets
+export {
+  BRAND_SVG_VIEWBOX,
+  BRAND_SVG_PATHS,
+  BADGE_DIMENSIONS,
+  buildBrandBadgeHTML,
+  getBrandSVG,
+} from "./brand.js";
+
+export type { BadgeSize, BadgeDimensions } from "./brand.js";
+
+// Overlay design constants
+export {
+  OVERLAY_Z_INDEX,
+  EASING,
+  MSG_PREFIX,
+  VARIATION_ALIASES,
+  VARIATIONS,
+  CLOSE_BUTTON,
+  BACKDROP,
+  CARD,
+  PANEL,
+  BOTTOM_SHEET,
+  POPUP,
+  FULLSCREEN,
+  SUCCESS_AUTO_CLOSE_MS,
+} from "./overlay/index.js";
+
+export type { VariationName, VariationMeta } from "./overlay/index.js";

package/src/overlay/constants.ts

@@ -0,0 +1,99 @@
+// @billing-io/designs — Checkout overlay design constants
+// Shared values used across all 5 overlay variations in billing.js
+
+export const OVERLAY_Z_INDEX = 2147483647;
+
+// Spring-like easing curves for overlay animations
+export const EASING = {
+  OUT_EXPO: "cubic-bezier(0.16, 1, 0.3, 1)",
+  OUT_QUINT: "cubic-bezier(0.22, 1, 0.36, 1)",
+  IN_EXPO: "cubic-bezier(0.7, 0, 0.84, 0)",
+} as const;
+
+// PostMessage protocol
+export const MSG_PREFIX = "billing:";
+
+// Variation name -> number mapping
+export const VARIATION_ALIASES: Record<string, number> = {
+  centered: 1, card: 1,
+  panel: 2, side: 2, sidepanel: 2,
+  bottom: 3, sheet: 3, bottomsheet: 3,
+  fullscreen: 4, full: 4, takeover: 4,
+  popup: 5, floating: 5, pill: 5,
+};
+
+export type VariationName = "centered" | "panel" | "bottom" | "fullscreen" | "popup";
+
+export interface VariationMeta {
+  id: number;
+  name: string;
+  description: string;
+  /** Primary alias for this variation */
+  alias: VariationName;
+}
+
+export const VARIATIONS: VariationMeta[] = [
+  { id: 1, name: "Centered Card", description: "Classic centered modal, backdrop blur", alias: "centered" },
+  { id: 2, name: "Side Panel", description: "Right-anchored slide-in sheet", alias: "panel" },
+  { id: 3, name: "Bottom Sheet", description: "Mobile-friendly bottom sheet", alias: "bottom" },
+  { id: 4, name: "Fullscreen", description: "Immersive full-screen overlay", alias: "fullscreen" },
+  { id: 5, name: "Floating Popup", description: "Compact bottom-right popup", alias: "popup" },
+];
+
+// Close button dimensions
+export const CLOSE_BUTTON = {
+  size: 32,
+  borderRadius: 10,
+  background: "#f3f4f6",
+  hoverBackground: "#e5e7eb",
+  color: "#6b7280",
+  iconSize: 14,
+} as const;
+
+// Backdrop defaults
+export const BACKDROP = {
+  color: "rgba(0,0,0,0.4)",
+  blur: "12px",
+  lightColor: "rgba(0,0,0,0.3)",
+  lightBlur: "6px",
+  scrimColor: "rgba(0,0,0,0.08)",
+} as const;
+
+// Card dimensions shared across variations
+export const CARD = {
+  maxWidth: 460,
+  maxHeight: 680,
+  borderRadius: 20,
+  minIframeHeight: 600,
+} as const;
+
+// Side panel dimensions
+export const PANEL = {
+  width: 460,
+} as const;
+
+// Bottom sheet dimensions
+export const BOTTOM_SHEET = {
+  maxWidth: 500,
+  maxHeight: "92vh",
+  minIframeHeight: 580,
+  handleWidth: 36,
+  handleHeight: 4,
+} as const;
+
+// Floating popup dimensions
+export const POPUP = {
+  width: 420,
+  height: 640,
+  offset: 24,
+  borderRadius: 16,
+} as const;
+
+// Fullscreen background
+export const FULLSCREEN = {
+  background: "rgba(247,248,250,1)",
+  backgroundTransparent: "rgba(247,248,250,0)",
+} as const;
+
+// Auto-close delay after successful payment (ms)
+export const SUCCESS_AUTO_CLOSE_MS = 2500;

package/src/overlay/index.ts

@@ -0,0 +1,17 @@
+export {
+  OVERLAY_Z_INDEX,
+  EASING,
+  MSG_PREFIX,
+  VARIATION_ALIASES,
+  VARIATIONS,
+  CLOSE_BUTTON,
+  BACKDROP,
+  CARD,
+  PANEL,
+  BOTTOM_SHEET,
+  POPUP,
+  FULLSCREEN,
+  SUCCESS_AUTO_CLOSE_MS,
+} from "./constants.js";
+
+export type { VariationName, VariationMeta } from "./constants.js";

package/src/plans.ts

@@ -0,0 +1,359 @@
+// @billing-io/designs — Canonical plan definitions
+// All billing.io projects should import plan data from this package.
+
+export type PlanId = "free" | "starter" | "growth" | "enterprise";
+
+export type BillingStatus = "active" | "past_due" | "restricted" | "suspended";
+
+export interface PlanConfig {
+  id: PlanId;
+  name: string;
+  description: string;
+  monthlyMinimum: number; // USD
+  volumeBps: number; // basis points (30 = 0.30%)
+  perPaymentFee: number; // USD per successful payment
+  includedVolumeUsd: number; // free volume threshold
+  features: string[];
+  requiresCard: boolean;
+}
+
+export const PLANS: Record<PlanId, PlanConfig> = {
+  free: {
+    id: "free",
+    name: "Free",
+    description: "For development and testing",
+    monthlyMinimum: 0,
+    volumeBps: 0,
+    perPaymentFee: 0,
+    includedVolumeUsd: 2_000,
+    features: [
+      "Up to $2,000/month processed",
+      "Limited API rate",
+      "No production SLA",
+      "No webhook retries",
+    ],
+    requiresCard: false,
+  },
+  starter: {
+    id: "starter",
+    name: "Starter",
+    description: "For production applications",
+    monthlyMinimum: 49,
+    volumeBps: 30, // 0.30%
+    perPaymentFee: 0.02,
+    includedVolumeUsd: 5_000,
+    features: [
+      "0.30% of settled volume",
+      "$0.02 per successful payment",
+      "First $5,000/month included",
+      "Standard webhooks",
+      "Email support",
+    ],
+    requiresCard: true,
+  },
+  growth: {
+    id: "growth",
+    name: "Growth",
+    description: "For scaling businesses",
+    monthlyMinimum: 199,
+    volumeBps: 20, // 0.20%
+    perPaymentFee: 0.02,
+    includedVolumeUsd: 50_000,
+    features: [
+      "0.20% of settled volume",
+      "$0.02 per successful payment",
+      "First $50,000/month included",
+      "Webhook retries + logs",
+      "Team access",
+      "Priority email support",
+    ],
+    requiresCard: true,
+  },
+  enterprise: {
+    id: "enterprise",
+    name: "Enterprise",
+    description: "Custom pricing and SLA",
+    monthlyMinimum: 2_000,
+    volumeBps: 10, // 0.10-0.15%, configurable
+    perPaymentFee: 0.02,
+    includedVolumeUsd: 500_000,
+    features: [
+      "0.10-0.15% volume rate",
+      "Custom minimums",
+      "SLA guarantee",
+      "Dedicated infrastructure",
+      "Custom confirmations",
+    ],
+    requiresCard: true,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Marketing-facing plan display data
+// These are the customer-facing descriptions used on the pricing page.
+// They reference the canonical PLANS above but add marketing copy.
+// ---------------------------------------------------------------------------
+
+export interface MarketingPlan {
+  id: PlanId;
+  name: string;
+  price: string; // display string, e.g. "$49"
+  period: string; // e.g. "/month"
+  badge?: string;
+  subheadline: string;
+  features: string[];
+  ctaLabel: string;
+  ctaHref: string;
+  ctaExternal?: boolean;
+}
+
+export const MARKETING_PLANS: MarketingPlan[] = [
+  {
+    id: "starter",
+    name: "Starter",
+    price: `$${PLANS.starter.monthlyMinimum}`,
+    period: "/month",
+    badge: "Most common",
+    subheadline: `${(PLANS.starter.volumeBps / 100).toFixed(2)}% of volume + $${PLANS.starter.perPaymentFee.toFixed(2)} per payment.`,
+    features: [
+      "Branded checkout on your domain",
+      "Embeddable checkout",
+      "SDK access",
+      "Signed webhooks",
+      "Dashboard and analytics",
+      "Email support",
+    ],
+    ctaLabel: "Go live",
+    ctaHref: "https://app.billing.io/signup",
+  },
+  {
+    id: "growth",
+    name: "Growth",
+    price: `$${PLANS.growth.monthlyMinimum}`,
+    period: "/month",
+    subheadline: `${(PLANS.growth.volumeBps / 100).toFixed(2)}% of volume + $${PLANS.growth.perPaymentFee.toFixed(2)} per payment.`,
+    features: [
+      "Everything in Starter",
+      "Webhook retries and logs",
+      "Team access (up to 5)",
+      "Priority support",
+    ],
+    ctaLabel: "Upgrade to Growth",
+    ctaHref: "https://app.billing.io/signup",
+  },
+  {
+    id: "enterprise",
+    name: "Scale",
+    price: `$${PLANS.enterprise.monthlyMinimum}`,
+    period: "/month",
+    subheadline: `${(PLANS.enterprise.volumeBps / 100).toFixed(2)}% of volume + $${PLANS.enterprise.perPaymentFee.toFixed(2)} per payment.`,
+    features: [
+      "Everything in Growth",
+      "Higher throughput and billing caps",
+      "Unlimited team members",
+      "Direct support channel",
+    ],
+    ctaLabel: "Contact sales",
+    ctaHref: "https://wa.me/message/ZTXL4WR3SWZQP1",
+    ctaExternal: true,
+  },
+];
+
+export interface MarketingSandboxPlan {
+  name: string;
+  price: string;
+  period: string;
+  features: string[];
+  ctaLabel: string;
+  ctaHref: string;
+  footnote: string;
+}
+
+export const MARKETING_SANDBOX: MarketingSandboxPlan = {
+  name: "Sandbox (development only)",
+  price: "$0",
+  period: "/month",
+  features: [
+    "Testnet access only",
+    "Full SDK access",
+    "Simulated webhooks",
+    "Dashboard preview",
+    "No card required",
+    "No time limit",
+  ],
+  ctaLabel: "Start in sandbox",
+  ctaHref: "https://app.billing.io/signup",
+  footnote: "Production usage requires a paid plan.",
+};
+
+// ---------------------------------------------------------------------------
+// Plan comparison table data
+// ---------------------------------------------------------------------------
+
+export type ComparisonValue = boolean | string | Record<string, boolean | string>;
+
+export interface ComparisonFeature {
+  name: string;
+  value: ComparisonValue;
+}
+
+export interface ComparisonSection {
+  title: string;
+  features: ComparisonFeature[];
+}
+
+export const COMPARISON_PLANS = ["Sandbox", "Starter", "Growth", "Scale"] as const;
+
+export const COMPARISON_DATA: ComparisonSection[] = [
+  {
+    title: "Payments",
+    features: [
+      { name: "Testnet access", value: true },
+      {
+        name: "Mainnet payments",
+        value: { Sandbox: false, Starter: true, Growth: true, Scale: true },
+      },
+      {
+        name: "Hosted checkout",
+        value: { Sandbox: false, Starter: true, Growth: true, Scale: true },
+      },
+      {
+        name: "Embeddable checkout",
+        value: { Sandbox: false, Starter: true, Growth: true, Scale: true },
+      },
+    ],
+  },
+  {
+    title: "Developer tools",
+    features: [
+      { name: "SDK access", value: true },
+      {
+        name: "Webhooks",
+        value: { Sandbox: "Simulated", Starter: "Signed", Growth: "Signed", Scale: "Signed" },
+      },
+      {
+        name: "Webhook retries",
+        value: { Sandbox: false, Starter: false, Growth: true, Scale: true },
+      },
+      {
+        name: "Dashboard",
+        value: { Sandbox: "Preview", Starter: true, Growth: true, Scale: true },
+      },
+    ],
+  },
+  {
+    title: "Team and support",
+    features: [
+      {
+        name: "Team members",
+        value: { Sandbox: "1", Starter: "1", Growth: "Up to 5", Scale: "Unlimited" },
+      },
+      {
+        name: "Support level",
+        value: { Sandbox: "Docs only", Starter: "Email", Growth: "Priority", Scale: "Direct channel" },
+      },
+    ],
+  },
+  {
+    title: "Billing and limits",
+    features: [
+      {
+        name: "Billing cap",
+        value: { Sandbox: "N/A", Starter: "$200", Growth: "$500", Scale: "$1,500" },
+      },
+      {
+        name: "Fiat access eligibility",
+        value: { Sandbox: false, Starter: "After volume", Growth: "After volume", Scale: "After volume" },
+      },
+    ],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// FAQ data
+// ---------------------------------------------------------------------------
+
+export interface FaqEntry {
+  id: string;
+  question: string;
+  answer: string;
+}
+
+export const PRICING_FAQS: FaqEntry[] = [
+  {
+    id: "faq-1",
+    question: "Do I need a credit card to start?",
+    answer: "Not for sandbox. You can build and test without a card. A payment method is required when you move to production.",
+  },
+  {
+    id: "faq-2",
+    question: "When do I start paying?",
+    answer: "You can build and test for free in sandbox. Production usage is billed according to your plan when you process real payments.",
+  },
+  {
+    id: "faq-3",
+    question: "When do you charge me?",
+    answer: "Your plan fee is charged at the start of each billing cycle. Usage fees are charged when they hit a cap or at month-end.",
+  },
+  {
+    id: "faq-4",
+    question: "What happens if my card fails?",
+    answer: "We notify you and retry. If payment stays unresolved, production features may be paused until it is sorted out.",
+  },
+  {
+    id: "faq-5",
+    question: "Do you hold my funds?",
+    answer: "No. Payments settle directly to your wallet. billing.io is non-custodial.",
+  },
+  {
+    id: "faq-6",
+    question: "Can I upgrade or downgrade plans?",
+    answer: "Yes. We recommend upgrades automatically when they save you money at your current volume.",
+  },
+  {
+    id: "faq-7",
+    question: "When can I access fiat payments?",
+    answer: "Fiat access becomes available after you process meaningful volume. It is not included by default.",
+  },
+  {
+    id: "faq-8",
+    question: "Is billing.io right for low-volume projects?",
+    answer: "If you are still building, use the sandbox. Production plans are designed for businesses processing real payments.",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Billing system constants (thresholds, events)
+// ---------------------------------------------------------------------------
+
+export const MID_CYCLE_THRESHOLD_USD = 100;
+
+export const PAST_DUE_RESTRICT_HOURS = 48;
+export const RESTRICT_SUSPEND_HOURS = 168; // 7 days
+
+export const USAGE_WARNING_THRESHOLD = 0.8; // 80%
+
+export const BILLING_EMAIL_EVENTS = {
+  CARD_REQUIRED: "card_required",
+  USAGE_APPROACHING_LIMIT: "usage_approaching_limit",
+  MID_CYCLE_CHARGE: "mid_cycle_charge",
+  PAYMENT_FAILED: "payment_failed",
+  SERVICE_RESTRICTED: "service_restricted",
+  SERVICE_SUSPENDED: "service_suspended",
+  PAYMENT_RECOVERED: "payment_recovered",
+} as const;
+
+export const BILLING_EVENT_TYPES = {
+  PLAN_CHANGED: "plan_changed",
+  SUBSCRIPTION_CREATED: "subscription_created",
+  USAGE_RECORDED: "usage_recorded",
+  INVOICE_CREATED: "invoice_created",
+  INVOICE_PAID: "invoice_paid",
+  INVOICE_FAILED: "invoice_failed",
+  MID_CYCLE_INVOICE: "mid_cycle_invoice",
+  STATUS_CHANGED: "status_changed",
+  PAYMENT_METHOD_UPDATED: "payment_method_updated",
+  ACCOUNT_RESTRICTED: "account_restricted",
+  ACCOUNT_SUSPENDED: "account_suspended",
+  ACCOUNT_RECOVERED: "account_recovered",
+} as const;