@adkit/cli 1.13.32 → 1.13.34

package/README.md

@@ -41,9 +41,14 @@ adkit projects current
 
 ### Ad Library
 
-Browse competitor ads and advertisers tracked by AdKit.
+Browse the shared ad library or your project’s My Watchlist. `add` finds or creates an advertiser and saves it to that project; `track` and `untrack` change membership for an existing ID. Repeating either is safe. Untracking keeps the shared advertiser and other projects intact.
 
 ```bash
+adkit library advertisers list --scope watchlist --project <project-id>
+adkit library advertisers search "notion" --scope watchlist --project <project-id>
+adkit library advertisers add --website notion.so --project <project-id>
+adkit library advertisers track <id> --project <project-id>
+adkit library advertisers untrack <id> --project <project-id>
 adkit library advertisers search "notion" --platform meta
 adkit library advertisers <id>
 adkit library advertisers similar --industry saas
@@ -51,6 +56,8 @@ adkit library ads list --advertiser <id>
 adkit library ads <id>
 ```
 
+Omit `--scope` (or use `--scope library`) for the whole library. List/search default to newest first; use `--sort name` for alphabetical order. Use `--json` for automation.
+
 ### Studio
 
 Create and manage AI-generated ads.

package/dist/cli.js

@@ -4727,7 +4727,7 @@ function readStringFlag2(flags, key) {
   const value = flags[key];
   return typeof value === "string" ? value : void 0;
 }
-var ADVERTISER_FILTER_FLAGS = ["industry", "category", "platform", "sort", "limit", "page"];
+var ADVERTISER_FILTER_FLAGS = ["industry", "category", "platform", "sort", "limit", "page", "scope"];
 async function listAdvertisers(client, _args, flags) {
   validateFlags(flags, ADVERTISER_FILTER_FLAGS, "library advertisers list");
   const qs = buildAdvertiserQueryString(flags);
@@ -4769,14 +4769,31 @@ async function addAdvertiser(client, _args, flags) {
     linkedInLibraryUrl: linkedinLibrary
   });
 }
+async function trackAdvertiser(client, args, flags) {
+  const path3 = getAdvertiserWatchlistPath(args, flags);
+  return client.post(path3);
+}
+async function untrackAdvertiser(client, args, flags) {
+  const path3 = getAdvertiserWatchlistPath(args, flags);
+  return client.delete(path3);
+}
+function getAdvertiserWatchlistPath(args, flags) {
+  validateFlags(flags, [], "library advertisers");
+  if (args.length !== 1 || !args[0]) throw new CliError("MISSING_ARGUMENT", "Expected exactly one advertiser ID", "Run: adkit library advertisers track <id> or adkit library advertisers untrack <id>");
+  if (flags.data !== void 0) throw new CliError("INVALID_VALUE", "Watchlist changes do not accept --data", "Pass the advertiser ID as a positional argument and select the project with --project");
+  const id = encodeURIComponent(args[0]);
+  return `/library/advertisers/${id}/watchlist`;
+}
 function buildAdvertiserQueryString(flags, query) {
+  const scope = flags.scope;
+  if (scope !== void 0 && scope !== "library" && scope !== "watchlist") throw new CliError("INVALID_VALUE", "--scope must be library or watchlist", "Use --scope watchlist for the selected project, or omit it to search the whole library");
   const industry = typeof flags.industry === "string" ? flags.industry : void 0;
   const category = typeof flags.category === "string" ? flags.category : void 0;
   const platform2 = typeof flags.platform === "string" ? flags.platform : void 0;
-  const sort = typeof flags.sort === "string" ? flags.sort : "name";
+  const sort = typeof flags.sort === "string" ? flags.sort : void 0;
   const limit = typeof flags.limit === "string" ? flags.limit : void 0;
   const page = typeof flags.page === "string" ? flags.page : void 0;
-  return queryString3({ industry, category, platform: platform2, query, sort, limit, page });
+  return queryString3({ industry, category, platform: platform2, query, sort, limit, page, scope });
 }
 async function listLibraryAds(client, _args, flags) {
   const platform2 = readStringFlag2(flags, "platform");
@@ -4801,6 +4818,56 @@ async function getLibraryAd(client, args, _flags) {
   if (!id) throw new CliError("MISSING_ARGUMENT", "Missing required argument: `<id>`", "Run: adkit library ads <ad-id>");
   return client.get(`/library/ads/${id}`);
 }
+var LIBRARY_BOARD_FIELDS = ["name", "description", "color"];
+async function createLibraryBoard(client, _args, flags) {
+  validateFlags(flags, LIBRARY_BOARD_FIELDS, "library boards create");
+  const name = requireFlag(flags, "name", "Run: adkit library boards create --name <name>");
+  const body = { name };
+  const description = readLibraryBoardTextFlag(flags, "description");
+  const color = readLibraryBoardTextFlag(flags, "color");
+  if (description !== void 0) body.description = description;
+  if (color !== void 0) body.color = color;
+  return client.post("/library/boards", body);
+}
+async function updateLibraryBoard(client, args, flags) {
+  validateFlags(flags, [...LIBRARY_BOARD_FIELDS, "share-enabled"], "library boards update");
+  const boardId = requireArg(args, 0, "board-id", "Run: adkit library boards update <board-id> --name <name>");
+  const body = {};
+  const name = readLibraryBoardTextFlag(flags, "name");
+  const description = readLibraryBoardTextFlag(flags, "description");
+  const color = readLibraryBoardTextFlag(flags, "color");
+  const shareEnabled = readLibraryBoardShareEnabled(flags);
+  if (name !== void 0) body.name = name;
+  if (description !== void 0) body.description = description;
+  if (color !== void 0) body.color = color;
+  if (shareEnabled !== void 0) body.shareEnabled = shareEnabled;
+  if (Object.keys(body).length === 0) throw new CliError("MISSING_FLAG", "Board update requires at least one field", "Use --name, --description, --color, or --share-enabled <true|false>");
+  const encodedBoardId = encodeURIComponent(boardId);
+  return client.patch(`/library/boards/${encodedBoardId}`, body);
+}
+async function addLibraryBoardAds(client, args, flags) {
+  validateFlags(flags, [], "library boards add-ads");
+  const boardId = requireArg(args, 0, "board-id", "Run: adkit library boards add-ads <board-id> <ad-id...>");
+  const adIds = args.slice(1);
+  if (adIds.length === 0) throw new CliError("MISSING_ARGUMENT", "Expected at least one ad ID after the board ID", "Run: adkit library boards add-ads <board-id> <ad-id...>");
+  if (adIds.length > 20) throw new CliError("INVALID_VALUE", "A board add-ads command accepts at most 20 ad IDs", "Split the ads across multiple add-ads commands");
+  const encodedBoardId = encodeURIComponent(boardId);
+  return client.post(`/library/boards/${encodedBoardId}/ads`, { adIds });
+}
+function readLibraryBoardTextFlag(flags, key) {
+  const value = flags[key];
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return void 0;
+  if (value.length === 1) return value[0];
+  throw new CliError("INVALID_VALUE", `--${key} can only be provided once for board commands`, `Use one --${key} value`);
+}
+function readLibraryBoardShareEnabled(flags) {
+  const value = flags["share-enabled"];
+  if (value === void 0) return void 0;
+  if (value === true || value === "true") return true;
+  if (value === "false") return false;
+  throw new CliError("INVALID_VALUE", "--share-enabled must be true or false", "Use --share-enabled true or --share-enabled false");
+}
 
 // src/commands/studio.ts
 import { readFile as readFile2 } from "node:fs/promises";
@@ -8105,8 +8172,27 @@ Examples:
 
   advertisers         Browse and inspect advertisers
   ads                 Browse and inspect ads
+  boards              Create, update, share, and fill inspiration boards
 
 Run \`adkit library <command> --help\` for details.`.trim(),
+  "library boards": `adkit library boards \u2014 Manage inspiration boards
+
+  create                         Create a private board
+  update <board-id>              Update board details or sharing
+  add-ads <board-id> <ad-id...>  Add 1-20 library ads without duplicates
+
+Flags (create/update):
+  --name <text>                  Board name
+  --description <text>           Board description
+  --color <value>                Board color
+  --share-enabled <true|false>   Enable or disable the public link (update only)
+  --project <id>                 Choose the project; otherwise use the active project
+
+Examples:
+  adkit library boards create --name "Offer-first banners"
+  adkit library boards update 507f1f77bcf86cd799439011 --name "Client references"
+  adkit library boards update 507f1f77bcf86cd799439011 --share-enabled true
+  adkit library boards add-ads 507f1f77bcf86cd799439011 507f1f77bcf86cd799439012 507f1f77bcf86cd799439013`.trim(),
   studio: `adkit studio \u2014 Create and manage Studio ads
 
   ads                 Manage Studio ads
@@ -8208,10 +8294,22 @@ Examples:
   <id>                   View advertiser details
   similar                Find similar to your project
   similar <id>           Find similar to an advertiser
-  add                    Add a new advertiser
+  add                    Find or add an advertiser and save it to My Watchlist
+  track <id>             Save an existing advertiser to My Watchlist
+  untrack <id>           Remove it from this project only
+
+Watchlist:
+  --scope <library|watchlist>  List/search the whole library (default) or My Watchlist
+  --project <id>              Choose the project; otherwise use the active project
+  Track/untrack return advertiserId and tracked. Repeating either is safe.
+  Untrack keeps the advertiser and other projects intact.
 
 Examples:
   adkit library advertisers list
+  adkit library advertisers list --scope watchlist --project <project-id>
+  adkit library advertisers search nike --scope watchlist --project <project-id>
+  adkit library advertisers track <advertiser-id> --project <project-id>
+  adkit library advertisers untrack <advertiser-id> --project <project-id>
   adkit library advertisers search nike
   adkit library advertisers list --platform meta --industry SaaS
   adkit library advertisers similar
@@ -8360,13 +8458,15 @@ var HELP_FULL = {
   <id>                   View advertiser details
   similar                Find similar to your project
   similar <id>           Find similar to an advertiser
-  add                    Add a new advertiser
+  add                    Find or add an advertiser and save it to My Watchlist
+  track <id>             Save an existing advertiser to My Watchlist
+  untrack <id>           Remove it from this project only
 
 Filters (list / search):
   --industry <string>       Filter by industry (e.g. "SaaS", "E-commerce")
   --category <string>       Filter by category (e.g. "Productivity Tools")
   --platform <meta|google|linkedin>  Filter by ad platform
-  --sort <name|newest|spend> Sort order (default: name)
+  --sort <name|newest|spend> Sort order (default: newest)
   --limit <n>               Results per page (default: 20, max: 100)
   --page <n>                Page number (default: 1)
 
@@ -8384,8 +8484,18 @@ Add flags:
   --google-library <url>         Google Ads Transparency URL
   --linkedin-library <url>       LinkedIn Ad Library URL
 
+Watchlist:
+  --scope <library|watchlist>  List/search the whole library (default) or My Watchlist
+  --project <id>              Choose the project; otherwise use the active project
+  Track/untrack return advertiserId and tracked. Repeating either is safe.
+  Untrack keeps the advertiser and other projects intact.
+
 Examples:
   adkit library advertisers list
+  adkit library advertisers list --scope watchlist --project <project-id>
+  adkit library advertisers search nike --scope watchlist --project <project-id>
+  adkit library advertisers track <advertiser-id> --project <project-id>
+  adkit library advertisers untrack <advertiser-id> --project <project-id>
   adkit library advertisers search nike
   adkit library advertisers search "productivity tools" --platform meta
   adkit library advertisers list --industry SaaS --limit 10
@@ -8930,11 +9040,13 @@ function printAddAdvertiserResult(data) {
   const adv = dig(data, "advertiser");
   const isNew = dig(data, "isNew");
   const jobCreated = dig(data, "jobCreated");
+  const tracked = dig(data, "tracked");
   const lines = [""];
   if (isNew) lines.push(`  \u2713 Created advertiser: ${toStr2(dig(adv, "name"))}`);
   else lines.push(`  Advertiser already exists: ${toStr2(dig(adv, "name"))}`);
   if (dig(adv, "website")) lines.push(`  Website: ${toStr2(dig(adv, "website"))}`);
   if (dig(adv, "_id")) lines.push(`  ID: ${toStr2(dig(adv, "_id"))}`);
+  if (tracked === true) lines.push("  Saved to this project\u2019s watchlist.");
   if (jobCreated) lines.push("", "  Scraping job queued \u2014 advertiser data will be populated shortly.");
   else if (!isNew && dig(adv, "hasDescription")) lines.push("", "  Advertiser already has complete data.");
   const job = dig(data, "job");
@@ -10255,6 +10367,11 @@ async function main() {
           const data = await addAdvertiser(client, args.slice(3), flags);
           if (wantsJson(flags)) printResult(data, flags);
           else printAddAdvertiserResult(data);
+        } else if (action === "track" || action === "untrack") {
+          const changeWatchlist = action === "track" ? trackAdvertiser : untrackAdvertiser;
+          const commandArgs = args.slice(3);
+          const data = await changeWatchlist(client, commandArgs, flags);
+          printResult(data, flags);
         } else if (action === "similar") {
           const advertiserId = args[3];
           if (advertiserId) flags.advertiserId = advertiserId;
@@ -10358,7 +10475,23 @@ ${pageInfo}`);
         }
         return;
       }
-      throw new CliError("UNKNOWN_COMMAND", `Unknown library command: ${libraryTarget}`, "Available: advertisers, ads");
+      if (libraryTarget === "boards") {
+        const action = args[2];
+        if (flags.help || !action) {
+          showHelp("library boards", flags.help === "full");
+          return;
+        }
+        const client = requireClient(flags);
+        const commandArgs = args.slice(3);
+        let data;
+        if (action === "create") data = await createLibraryBoard(client, commandArgs, flags);
+        else if (action === "update") data = await updateLibraryBoard(client, commandArgs, flags);
+        else if (action === "add-ads") data = await addLibraryBoardAds(client, commandArgs, flags);
+        else throw new CliError("UNKNOWN_COMMAND", `Unknown library boards action: ${action}`, "Available: create, update, add-ads");
+        printResult(data, flags);
+        return;
+      }
+      throw new CliError("UNKNOWN_COMMAND", `Unknown library command: ${libraryTarget}`, "Available: advertisers, ads, boards");
     }
     if (args[0] === "studio") {
       const studioTarget = args[1];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adkit/cli",
-  "version": "1.13.32",
+  "version": "1.13.34",
   "description": "The Ads CLI for AI agents — manage Meta & Google ad campaigns, browse the ad library, and generate creatives from your terminal.",
   "keywords": [
     "ads cli",