ckweb-cli 0.6.0 → 0.8.0

package/README.md

@@ -72,15 +72,19 @@ ckweb seo traffic "example.com"
 | `referrals dashboard` | View referral stats |
 | `referrals request-payout` | Request payout |
 | `referrals payout-history` | View payout history |
+| `referrals leaderboard\|tiers\|resolve\|track\|referees` | Referral discovery, tracking, and referee lookup |
 | `payout profile` | View payout profiles |
 | `payout create-profile` | Create payout profile |
 | `payout delete-profile` | Delete payout profile |
 
+Payout profile note: current `claudekit-web` payout profile endpoints are browser-session routes. Full API-key automation for payout profile and VNeID conversion flows requires a backend API-key contract first.
+
 ### Content
 | Command | Description |
 |---------|-------------|
 | `blog list` | List blog articles |
 | `blog get <id>` | Get article details |
+| `blog regenerate-html --article <id>\|--all` | Regenerate article HTML (admin key) |
 | `releases list [--tab]` | List product releases |
 
 ### Proxy Services (YouTube, Web, SEO)
@@ -97,12 +101,13 @@ ckweb seo traffic "example.com"
 | `pricing exchange-rate` | Get USD/VND rate |
 | `pricing early-access` | Early access status |
 | `loyalty eligibility` | Check loyalty eligibility |
+| `premium validate` | Validate premium access for current API key |
 | `stats users` | Platform user count |
 
 ### Other
 | Command | Description |
 |---------|-------------|
-| `github invite\|revoke` | GitHub repo access |
+| `github validate\|invite\|revoke` | GitHub username validation and repo access |
 | `newsletter subscribe\|unsubscribe` | Newsletter management |
 | `waitlist join` | Join product waitlist |
 | `health` | Check API health |
@@ -122,9 +127,13 @@ ckweb seo traffic "example.com"
 | `admin invites` | list, create, get, delete, resend, accept, validate |
 | `admin admins` | list, get, promote, demote, permissions |
 | `admin discounts` | list, create, update, delete, sync-status, export |
-| `admin discount-groups` | list, get, create, update, delete |
+| `admin discount-groups` | list, get, create (--generate), generate, update, delete |
 | `admin tiers` | list |
 
+Admin payout note: backend payout PII/actions such as `/api/admin/payouts`, `/api/admin/payout-requests`, and `/api/admin/payout-vneid-requests` intentionally require an interactive browser admin session. The CLI documents those as unsupported by API-key auth instead of pretending they are safe automation commands.
+
+Browser-session note: several dashboard endpoints in `claudekit-web` still use cookie session auth (`getCurrentUser()`), including user API-key management, teams, loyalty checkout, GDPR account actions, and referral payout requests. The coverage test tracks these as explicit backend-contract gaps, not working API-key CLI coverage.
+
 ## Authentication
 
 Two types of API keys:

package/dist/index.js

@@ -211,7 +211,7 @@ function buildUrl(path2, params) {
 }
 function buildHeaders(apiKey, hasBody) {
   const headers = {
-    "User-Agent": `ckweb-cli/${"0.6.0"}`
+    "User-Agent": `ckweb-cli/${"0.8.0"}`
   };
   if (hasBody) {
     headers["Content-Type"] = "application/json";
@@ -823,6 +823,22 @@ var PAYOUT_COLUMNS = [
   { key: "status", header: "Status", width: 12 },
   { key: "createdAt", header: "Created", width: 22 }
 ];
+var REFEREE_STATUSES = ["all", "pending", "approved", "paid", "cancelled"];
+var REFEREE_SORTS = ["createdAt", "amount", "status"];
+var REFEREE_ORDERS = ["asc", "desc"];
+function parseBoundedInteger(value, label, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new CliError(`${label} must be an integer between ${min} and ${max}`);
+  }
+  return parsed;
+}
+function assertOneOf(value, allowed, label) {
+  if (!allowed.includes(value)) {
+    throw new CliError(`${label} must be one of: ${allowed.join(", ")}`);
+  }
+  return value;
+}
 function registerReferralsCommand(program2) {
   const referrals = program2.command("referrals").description("Referral program management");
   referrals.command("dashboard").description("View your referral dashboard").action(async function() {
@@ -853,6 +869,69 @@ function registerReferralsCommand(program2) {
       handleError(err);
     }
   });
+  referrals.command("leaderboard").description("View public referral leaderboard").action(async function() {
+    try {
+      const data = await fetchApi("GET", "/referrals/leaderboard", { noAuth: true });
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  referrals.command("tiers").description("List public referral tiers").action(async function() {
+    try {
+      const data = await fetchApi("GET", "/referrals/tiers", { noAuth: true });
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  referrals.command("resolve <code>").description("Resolve a referral code").action(async function(code) {
+    try {
+      const data = await fetchApi("GET", "/referrals/resolve", {
+        noAuth: true,
+        params: { code }
+      });
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  referrals.command("track <code>").description("Track a referral click").action(async function(code) {
+    try {
+      const data = await fetchApi("GET", "/referrals/track", {
+        noAuth: true,
+        params: { code }
+      });
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  referrals.command("referees").description("List referees attributed to your referral account").option("--status <status>", "Filter by commission status", "all").option("--sort <field>", "Sort by createdAt, amount, or status", "createdAt").option("--order <direction>", "Sort direction: asc or desc", "desc").option("--order-ref <id>", "Filter by 8-character order display ID").option("--limit <n>", "Page size", "50").option("--offset <n>", "Offset for pagination", "0").action(async function() {
+    try {
+      ensureAuth();
+      const opts = this.opts();
+      const limit = parseBoundedInteger(opts.limit, "--limit", 1, 100);
+      const offset = parseBoundedInteger(opts.offset, "--offset", 0, 5e3);
+      const params = {
+        status: assertOneOf(opts.status, REFEREE_STATUSES, "--status"),
+        sort: assertOneOf(opts.sort, REFEREE_SORTS, "--sort"),
+        order: assertOneOf(opts.order, REFEREE_ORDERS, "--order"),
+        limit: String(limit),
+        offset: String(offset)
+      };
+      if (opts.orderRef) {
+        if (!/^[0-9a-fA-F]{8}$/.test(opts.orderRef)) {
+          throw new CliError("--order-ref must be an 8-character order display ID");
+        }
+        params["orderRef"] = opts.orderRef.toLowerCase();
+      }
+      const data = await fetchApi("GET", "/referrals/referees", { params });
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
 }
 
 // src/commands/blog.ts
@@ -881,6 +960,26 @@ function registerBlogCommand(program2) {
       handleError(err);
     }
   });
+  blog.command("regenerate-html").description("Regenerate stored HTML for missing article content").option("--article <id>", "Regenerate one article by ID").option("--all", "Regenerate all articles missing HTML").action(async function() {
+    try {
+      ensureAdminAuth();
+      const opts = this.opts();
+      if (!opts.article && !opts.all) {
+        throw new CliError("Provide --article <id> or explicit --all.");
+      }
+      if (opts.article && opts.all) {
+        throw new CliError("Use either --article <id> or --all, not both.");
+      }
+      const body = opts.article ? { articleId: opts.article } : {};
+      const data = await fetchApi("POST", "/blog/regenerate-html", {
+        adminAuth: true,
+        body
+      });
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
 }
 
 // src/commands/health.ts
@@ -987,6 +1086,17 @@ function registerCheckoutCommand(program2) {
 import * as readline3 from "readline/promises";
 function registerGithubCommand(program2) {
   const github = program2.command("github").description("GitHub repository access");
+  github.command("validate <username>").description("Validate a GitHub username").action(async function(username) {
+    try {
+      const data = await fetchApi("GET", "/github/validate", {
+        noAuth: true,
+        params: { username }
+      });
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
   github.command("invite").description("Grant GitHub repository access via license").requiredOption("--license <id>", "License ID").action(async function() {
     try {
       ensureAuth();
@@ -1154,6 +1264,20 @@ function registerPricingCommand(program2) {
   });
 }
 
+// src/commands/premium.ts
+function registerPremiumCommand(program2) {
+  const premium = program2.command("premium").description("Premium license utilities");
+  premium.command("validate").description("Validate whether the current API key has premium access").action(async function() {
+    try {
+      ensureAuth();
+      const data = await fetchApi("GET", "/premium/validate");
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
+}
+
 // src/commands/refunds.ts
 import * as readline5 from "readline/promises";
 function registerRefundsCommand(program2) {
@@ -2971,6 +3095,14 @@ var GROUP_COLUMNS = [
   { key: "codesUsed", header: "Used", width: 8 },
   { key: "createdAt", header: "Created", width: 22 }
 ];
+function parseGenerateCount(value, optionName = "--count") {
+  if (value === void 0) return void 0;
+  const count = Number(value);
+  if (!Number.isInteger(count) || count < 1 || count > 100) {
+    throw new CliError(`${optionName} must be an integer from 1 to 100`);
+  }
+  return count;
+}
 function buildGroupBody(opts) {
   const body = {};
   if (opts.name !== void 0) body["name"] = opts.name;
@@ -3011,6 +3143,12 @@ function buildGroupBody(opts) {
   if (opts.ends !== void 0) body["endsAt"] = opts.ends;
   return body;
 }
+async function generateDiscountGroupCodes(id, count) {
+  return fetchApi("POST", `/admin/discount-groups/${id}/codes`, {
+    adminAuth: true,
+    body: { count }
+  });
+}
 function registerAdminDiscountGroupsCommand(admin) {
   const groups = admin.command("discount-groups").description("Discount group management");
   groups.command("list").description("List discount groups").option("--query <text>", "Search by name or prefix").option("--page <n>", "Page number", "1").option("--limit <n>", "Page size", "50").action(async function() {
@@ -3038,15 +3176,37 @@ function registerAdminDiscountGroupsCommand(admin) {
       handleError(err);
     }
   });
-  groups.command("create").description("Create a discount group template").requiredOption("--name <name>", "Group name").requiredOption("--prefix <prefix>", "Code prefix (3-20 chars, uppercased)").requiredOption("--type <percentage|fixed>", "Discount type").option("--amount <n>", "Amount in cents (fixed type)").option("--basis-points <n>", "Basis points (percentage type, 0..10000)").option("--duration <once|repeating|forever>", "Discount duration").option("--duration-in-months <n>", "Months for repeating duration (1..24)").option("--max-redemptions-per-code <n>", "Per-code redemption cap").option("--starts <date>", "Start date (ISO 8601)").option("--ends <date>", "End date (ISO 8601)").action(async function() {
+  groups.command("create").description("Create a discount group template").requiredOption("--name <name>", "Group name").requiredOption("--prefix <prefix>", "Code prefix (3-20 chars, uppercased)").requiredOption("--type <percentage|fixed>", "Discount type").option("--amount <n>", "Amount in cents (fixed type)").option("--basis-points <n>", "Basis points (percentage type, 0..10000)").option("--duration <once|repeating|forever>", "Discount duration").option("--duration-in-months <n>", "Months for repeating duration (1..24)").option("--max-redemptions-per-code <n>", "Per-code redemption cap").option("--starts <date>", "Start date (ISO 8601)").option("--ends <date>", "End date (ISO 8601)").option("--generate <n>", "Generate N discount codes after creating the group (1..100)").action(async function() {
     try {
       ensureAdminAuth();
-      const body = buildGroupBody(this.opts());
+      const opts = this.opts();
+      const generateCount = parseGenerateCount(opts.generate, "--generate");
+      const body = buildGroupBody(opts);
       const data = await fetchApi("POST", "/admin/discount-groups", {
         adminAuth: true,
         body
       });
       printSuccess(`Discount group created: ${data?.group?.id ?? ""}`);
+      if (generateCount !== void 0) {
+        const id = data?.group?.id;
+        if (!id) throw new CliError("Backend did not return a discount group ID for code generation.");
+        const generated = await generateDiscountGroupCodes(id, generateCount);
+        printSuccess(`Generated ${generated.generated} discount code(s).`);
+        formatOutput({ ...data, ...generated }, getOutputOpts(this));
+        return;
+      }
+      formatOutput(data, getOutputOpts(this));
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  groups.command("generate <id>").description("Generate discount codes for a group").requiredOption("--count <n>", "Number of codes to generate (1..100)").action(async function(id) {
+    try {
+      ensureAdminAuth();
+      validateId(id, "discount group ID");
+      const count = parseGenerateCount(this.opts().count);
+      const data = await generateDiscountGroupCodes(id, count);
+      printSuccess(`Generated ${data.generated} discount code(s).`);
       formatOutput(data, getOutputOpts(this));
     } catch (err) {
       handleError(err);
@@ -3133,7 +3293,7 @@ function registerAdminCommand(program2) {
 // src/index.ts
 loadDotenvFiles();
 var program = new Command();
-program.name("ckweb").description("CLI for interacting with ClaudeKit.cc API").version("0.6.0");
+program.name("ckweb").description("CLI for interacting with ClaudeKit.cc API").version("0.8.0");
 program.option("--json", "Output as JSON").option("--table", "Output as table").option("--quiet", "Minimal output");
 registerAuthCommand(program);
 registerHealthCommand(program);
@@ -3147,6 +3307,7 @@ registerLoyaltyCommand(program);
 registerNewsletterCommand(program);
 registerPayoutCommand(program);
 registerPricingCommand(program);
+registerPremiumCommand(program);
 registerRefundsCommand(program);
 registerReleasesCommand(program);
 registerStatsCommand(program);