outrank-cli 0.5.0 → 0.6.0

package/src/commands/products/backlinks.js

@@ -0,0 +1,181 @@
+import { LIST_MAX_LIMIT, LIST_MIN_LIMIT } from '../../core/constants.js';
+import { bool, int, oneOf, string, uuid } from '../../core/schema.js';
+import { BodyMode, CommandKind, Toolset, defineCommand, defineGroup } from '../registry.js';
+import { PRODUCT_CLI, productInput, productParams, withProduct } from './shared.js';
+
+const BACKLINKS_USAGE = `Usage:
+  outrank-cli products backlinks get <product-id>
+  outrank-cli products backlinks update <product-id> --json <object>
+  outrank-cli products backlinks credits <product-id>
+  outrank-cli products backlinks earned <product-id> [--limit <n>] [--cursor <iso>] [--status <status>] [--sort-by created_at|status|credits_applied] [--sort-order desc] [--include-article] [--include-summary]
+  outrank-cli products backlinks unverified <product-id> [--limit <n>] [--cursor <iso>] [--status <status>] [--sort-by created_at|verification_error_reason] [--sort-order desc]
+  outrank-cli products backlinks check-removal <product-id> <backlink-id>
+  outrank-cli products backlinks reverify <product-id> <backlink-id>
+  outrank-cli products backlinks subscription <product-id>
+  outrank-cli products backlinks subscribe-quote <product-id> --plan premium|enterprise`;
+
+const TOOLSETS = [Toolset.BACKLINKS];
+const BACKLINKS_PATH = '/products/{productId}/backlinks';
+const BACKLINK_PATH = `${BACKLINKS_PATH}/{backlinkId}`;
+const BACKLINK_CLI = withProduct(['backlinkId']);
+const BACKLINK_PLANS = Object.freeze(['premium', 'enterprise']);
+const PLAN_PLACEHOLDERS = { plan: BACKLINK_PLANS.join('|') };
+const PLAN_REQUIRED = {
+  guidance:
+    'Run `outrank-cli products backlinks subscribe-quote <product-id> --plan premium|enterprise` to inspect the ' +
+    'dashboard-equivalent quote.',
+};
+
+const backlinkInput = () => ({ ...productInput(), backlinkId: uuid().required() });
+const backlinkParams = (input) => ({ productId: input.productId, backlinkId: input.backlinkId });
+
+const listInput = () => ({
+  ...productInput(),
+  limit: int({ min: LIST_MIN_LIMIT, max: LIST_MAX_LIMIT }),
+  cursor: string(),
+  status: string(),
+  sortBy: string(),
+  sortOrder: string(),
+});
+const listQuery = (input) => ({
+  limit: input.limit,
+  cursor: input.cursor,
+  status: input.status,
+  sort_by: input.sortBy,
+  sort_order: input.sortOrder,
+});
+
+const get = defineCommand({
+  id: 'products.backlinks.get',
+  summary: 'Get the backlink exchange settings of a product.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  run: (input, ctx) => ctx.http({ method: 'GET', path: BACKLINKS_PATH, pathParams: productParams(input) }),
+});
+
+const update = defineCommand({
+  id: 'products.backlinks.update',
+  summary: 'Update the backlink exchange settings of a product from a JSON body.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  body: BodyMode.JSON,
+  run: (input, ctx) =>
+    ctx.http({ method: 'PATCH', path: BACKLINKS_PATH, pathParams: productParams(input), body: input.body }),
+});
+
+const credits = defineCommand({
+  id: 'products.backlinks.credits',
+  summary: 'Show the backlink credit balance of a product.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  run: (input, ctx) => ctx.http({ method: 'GET', path: `${BACKLINKS_PATH}/credits`, pathParams: productParams(input) }),
+});
+
+const earned = defineCommand({
+  id: 'products.backlinks.earned',
+  summary: 'List earned backlinks with optional article and summary details.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { ...listInput(), includeArticle: bool(), includeSummary: bool() },
+  cli: PRODUCT_CLI,
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: `${BACKLINKS_PATH}/earned`,
+      pathParams: productParams(input),
+      query: {
+        ...listQuery(input),
+        include_article: input.includeArticle ? true : undefined,
+        include_summary: input.includeSummary ? true : undefined,
+      },
+    }),
+});
+
+const unverified = defineCommand({
+  id: 'products.backlinks.unverified',
+  summary: 'List backlinks that failed verification.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: listInput(),
+  cli: PRODUCT_CLI,
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: `${BACKLINKS_PATH}/unverified`,
+      pathParams: productParams(input),
+      query: listQuery(input),
+    }),
+});
+
+const backlinkAction = ({ id, summary, suffix }) =>
+  defineCommand({
+    id: `products.backlinks.${id}`,
+    summary,
+    kind: CommandKind.WRITE,
+    toolsets: TOOLSETS,
+    input: backlinkInput(),
+    cli: BACKLINK_CLI,
+    run: (input, ctx) =>
+      ctx.http({ method: 'POST', path: `${BACKLINK_PATH}/${suffix}`, pathParams: backlinkParams(input) }),
+  });
+
+const checkRemoval = backlinkAction({
+  id: 'check-removal',
+  summary: 'Check whether an earned backlink was removed.',
+  suffix: 'check-removal',
+});
+const reverify = backlinkAction({
+  id: 'reverify',
+  summary: 'Re-run verification for one backlink.',
+  suffix: 'reverify',
+});
+
+const subscription = defineCommand({
+  id: 'products.backlinks.subscription',
+  summary: 'Show the backlink plan subscription of a product.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  entryPoint: true,
+  run: (input, ctx) =>
+    ctx.http({ method: 'GET', path: `${BACKLINKS_PATH}/subscription`, pathParams: productParams(input) }),
+});
+
+const subscribeQuote = defineCommand({
+  id: 'products.backlinks.subscribe-quote',
+  summary: 'Quote a backlink plan subscription for a product.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { ...productInput(), plan: oneOf(BACKLINK_PLANS).required(PLAN_REQUIRED) },
+  cli: { ...PRODUCT_CLI, placeholders: PLAN_PLACEHOLDERS },
+  entryPoint: true,
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: `${BACKLINKS_PATH}/subscribe-quote`,
+      pathParams: productParams(input),
+      query: { plan: input.plan },
+    }),
+});
+
+export const backlinksGroup = defineGroup({
+  id: 'products.backlinks',
+  help: {
+    usage: BACKLINKS_USAGE,
+    guidance:
+      'Use `get` and `update` for product backlink settings, `credits` and `subscription` for status, `earned` and ' +
+      '`unverified` for review queues, and the action commands for verification follow-up.',
+  },
+  unknown: (word) => ({
+    message: `Unknown products backlinks subcommand: ${word}.`,
+    guidance: 'Run `outrank-cli products backlinks --help` to see the available backlink commands.',
+  }),
+  children: [get, update, credits, earned, unverified, checkRemoval, reverify, subscription, subscribeQuote],
+});

package/src/commands/products/core.js

@@ -0,0 +1,149 @@
+import { LIST_MAX_LIMIT, LIST_MIN_LIMIT } from '../../core/constants.js';
+import { int, string } from '../../core/schema.js';
+import { BodyMode, CommandKind, Toolset, defineCommand, defineGroup } from '../registry.js';
+import { PRODUCT_CLI, productInput, productParams } from './shared.js';
+
+const TOOLSETS = [Toolset.CORE];
+const PRODUCT_PATH = '/products/{productId}';
+
+export const productsList = defineCommand({
+  id: 'products.list',
+  summary: 'List products with optional status filter and cursor pagination.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { status: string(), limit: int({ min: LIST_MIN_LIMIT, max: LIST_MAX_LIMIT }), cursor: string() },
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: '/products',
+      query: { status: input.status, limit: input.limit, cursor: input.cursor },
+    }),
+});
+
+export const productsGet = defineCommand({
+  id: 'products.get',
+  summary: 'Get one product.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  run: (input, ctx) => ctx.http({ method: 'GET', path: PRODUCT_PATH, pathParams: productParams(input) }),
+});
+
+export const productsCreate = defineCommand({
+  id: 'products.create',
+  summary: 'Create a product from a JSON body. The server queues an initial keyword plan.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  body: BodyMode.JSON,
+  run: (input, ctx) => ctx.http({ method: 'POST', path: '/products', body: input.body }),
+});
+
+export const productsUpdate = defineCommand({
+  id: 'products.update',
+  summary: 'Update a product from a JSON body.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  body: BodyMode.JSON,
+  run: (input, ctx) =>
+    ctx.http({ method: 'PATCH', path: PRODUCT_PATH, pathParams: productParams(input), body: input.body }),
+});
+
+export const productsPause = defineCommand({
+  id: 'products.pause',
+  summary: 'Pause a product and free its slot.',
+  kind: CommandKind.DESTRUCTIVE,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  run: (input, ctx) => ctx.http({ method: 'POST', path: `${PRODUCT_PATH}/pause`, pathParams: productParams(input) }),
+});
+
+export const productsResume = defineCommand({
+  id: 'products.resume',
+  summary: 'Resume a paused product.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: productInput(),
+  cli: PRODUCT_CLI,
+  run: (input, ctx) =>
+    ctx.http({ method: 'POST', path: `${PRODUCT_PATH}/resume`, pathParams: productParams(input) }),
+});
+
+const settingsPair = ({ id, noun, resource, getSummary, replaceSummary, replaceMethod, replaceKind, guidance }) =>
+  defineGroup({
+    id: `products.${id}`,
+    help: {
+      usage: `Usage:\n  outrank-cli products ${id} ${noun} <product-id>\n  outrank-cli products ${id} ${
+        replaceMethod === 'PATCH' ? 'update' : 'replace'
+      } <product-id> --json <object>`,
+      guidance,
+    },
+    unknown: (word) => ({
+      message: `Unknown products ${id} subcommand: ${word}.`,
+      guidance: `Run \`outrank-cli products ${id} --help\` to see the available ${resource} commands.`,
+    }),
+    children: [
+      defineCommand({
+        id: `products.${id}.${noun}`,
+        summary: getSummary,
+        kind: CommandKind.READ,
+        toolsets: TOOLSETS,
+        input: productInput(),
+        cli: PRODUCT_CLI,
+        run: (input, ctx) =>
+          ctx.http({ method: 'GET', path: `${PRODUCT_PATH}/${id}`, pathParams: productParams(input) }),
+      }),
+      defineCommand({
+        id: `products.${id}.${replaceMethod === 'PATCH' ? 'update' : 'replace'}`,
+        summary: replaceSummary,
+        kind: replaceKind,
+        toolsets: TOOLSETS,
+        input: productInput(),
+        cli: PRODUCT_CLI,
+        body: BodyMode.JSON,
+        run: (input, ctx) =>
+          ctx.http({
+            method: replaceMethod,
+            path: `${PRODUCT_PATH}/${id}`,
+            pathParams: productParams(input),
+            body: input.body,
+          }),
+      }),
+    ],
+  });
+
+export const outputSettingsGroup = settingsPair({
+  id: 'output-settings',
+  noun: 'get',
+  resource: 'output-settings',
+  getSummary: 'Get the article output settings of a product.',
+  replaceSummary: 'Patch the article output settings of a product from a JSON body.',
+  replaceMethod: 'PATCH',
+  replaceKind: CommandKind.WRITE,
+  guidance: 'Use `get` to inspect current article settings and `update` to patch them.',
+});
+
+export const targetAudiencesGroup = settingsPair({
+  id: 'target-audiences',
+  noun: 'list',
+  resource: 'target-audience',
+  getSummary: 'List the target audiences of a product.',
+  replaceSummary: 'Replace the full target-audience list of a product from a JSON body.',
+  replaceMethod: 'PUT',
+  replaceKind: CommandKind.DESTRUCTIVE,
+  guidance: 'Use `list` to inspect the target-audience list and `replace` to submit the full replacement set.',
+});
+
+export const competitorsGroup = settingsPair({
+  id: 'competitors',
+  noun: 'list',
+  resource: 'competitor',
+  getSummary: 'List the competitors of a product.',
+  replaceSummary: 'Replace the full competitor list of a product from a JSON body (3-7 entries, server-enforced).',
+  replaceMethod: 'PUT',
+  replaceKind: CommandKind.DESTRUCTIVE,
+  guidance: 'Use `list` to inspect the competitor list and `replace` to submit the full replacement set.',
+});

package/src/commands/products/gsc.js

@@ -0,0 +1,250 @@
+import {
+  GSC_MAX_MONTHS,
+  GSC_MIN_MONTHS,
+  GSC_SEARCH_ANALYTICS_MAX_LIMIT,
+  LIST_MIN_LIMIT,
+} from '../../core/constants.js';
+import { Surface } from '../../core/constants.js';
+import { MCP_USAGE_GUIDANCE, usageError } from '../../core/errors.js';
+import { int, string } from '../../core/schema.js';
+import { CommandKind, Toolset, defineCommand, defineGroup } from '../registry.js';
+import { PRODUCT_CLI, productInput, productParams } from './shared.js';
+
+const GSC_USAGE = `Usage:
+  outrank-cli products gsc status <product-id>
+  outrank-cli products gsc connect <product-id>
+  outrank-cli products gsc poll <product-id> --attempt-id <attempt-id>
+  outrank-cli products gsc reconnect <product-id>
+  outrank-cli products gsc disconnect <product-id>
+  outrank-cli products gsc accounts <product-id>
+  outrank-cli products gsc properties <product-id> --email <email>
+  outrank-cli products gsc set-property <product-id> --email <email> --site-url <url>
+  outrank-cli products gsc performance <product-id> [--months <n>]
+  outrank-cli products gsc search-analytics <product-id> [--dimensions <csv>] [--limit <n>] [--months <n>] [--start-date <yyyy-mm-dd>] [--end-date <yyyy-mm-dd>] [--page <text>] [--query <text>] [--country <cc>] [--device <device>]
+  outrank-cli products gsc inspect-url <product-id> --url <url> [--language-code <code>]
+  outrank-cli products gsc cannibalization <product-id>`;
+
+const TOOLSETS = [Toolset.GSC];
+const GSC_PATH = '/products/{productId}/gsc';
+const ATTEMPT_ID_REQUIRED = {
+  guidance: 'Run `outrank-cli products gsc poll <product-id> --attempt-id <attempt-id>` after connect starts.',
+};
+const EMAIL_REQUIRED = {
+  guidance:
+    'Run `outrank-cli products gsc properties <product-id> --email <email>` to list properties for a connected ' +
+    'Google account.',
+};
+const SET_PROPERTY_GUIDANCE =
+  'Run `outrank-cli products gsc set-property <product-id> --email <email> --site-url <url>` to save the ' +
+  'verified property.';
+const URL_REQUIRED = {
+  guidance:
+    'Run `outrank-cli products gsc inspect-url <product-id> --url <url>` to inspect indexing details for one page.',
+};
+const ATTEMPT_ID_PLACEHOLDERS = { attemptId: '<attempt-id>' };
+const EMAIL_PLACEHOLDERS = { email: '<email>' };
+const URL_PLACEHOLDERS = { url: '<url>' };
+
+const simple = ({ id, summary, kind, method, suffix = '' }) =>
+  defineCommand({
+    id: `products.gsc.${id}`,
+    summary,
+    kind,
+    toolsets: TOOLSETS,
+    input: productInput(),
+    cli: PRODUCT_CLI,
+    run: (input, ctx) => ctx.http({ method, path: `${GSC_PATH}${suffix}`, pathParams: productParams(input) }),
+  });
+
+const status = simple({
+  id: 'status',
+  summary: 'Show the Google Search Console connection status of a product.',
+  kind: CommandKind.READ,
+  method: 'GET',
+});
+const connect = simple({
+  id: 'connect',
+  summary: 'Start the Google Search Console OAuth handoff and return the connect URL.',
+  kind: CommandKind.WRITE,
+  method: 'POST',
+  suffix: '/connect',
+});
+const reconnect = simple({
+  id: 'reconnect',
+  summary: 'Restart the Google Search Console OAuth handoff for a product.',
+  kind: CommandKind.WRITE,
+  method: 'POST',
+  suffix: '/reconnect',
+});
+const disconnect = simple({
+  id: 'disconnect',
+  summary: 'Disconnect Google Search Console from a product.',
+  kind: CommandKind.DESTRUCTIVE,
+  method: 'DELETE',
+});
+const accounts = simple({
+  id: 'accounts',
+  summary: 'List the connected Google accounts of a product.',
+  kind: CommandKind.READ,
+  method: 'GET',
+  suffix: '/accounts',
+});
+const cannibalization = simple({
+  id: 'cannibalization',
+  summary: 'Report keyword cannibalization across the product pages.',
+  kind: CommandKind.READ,
+  method: 'GET',
+  suffix: '/cannibalization',
+});
+
+const poll = defineCommand({
+  id: 'products.gsc.poll',
+  summary: 'Poll a Google Search Console connect attempt.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { ...productInput(), attemptId: string().required(ATTEMPT_ID_REQUIRED) },
+  cli: { ...PRODUCT_CLI, placeholders: ATTEMPT_ID_PLACEHOLDERS },
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: `${GSC_PATH}/connect`,
+      pathParams: productParams(input),
+      query: { attempt_id: input.attemptId },
+    }),
+});
+
+const properties = defineCommand({
+  id: 'products.gsc.properties',
+  summary: 'List the Search Console properties of a connected Google account.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { ...productInput(), email: string().required(EMAIL_REQUIRED) },
+  cli: { ...PRODUCT_CLI, placeholders: EMAIL_PLACEHOLDERS },
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: `${GSC_PATH}/properties`,
+      pathParams: productParams(input),
+      query: { email: input.email },
+    }),
+});
+
+const setProperty = defineCommand({
+  id: 'products.gsc.set-property',
+  summary: 'Save the verified Search Console property for a product.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: { ...productInput(), email: string(), siteUrl: string() },
+  cli: PRODUCT_CLI,
+  refine: (input, ctx) => {
+    if (input.email && input.siteUrl) return;
+    if (ctx.surface === Surface.MCP) {
+      throw usageError('Missing required arguments: email and site_url.', MCP_USAGE_GUIDANCE);
+    }
+    throw usageError('Missing required options: --email <email> and --site-url <url>.', SET_PROPERTY_GUIDANCE);
+  },
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'PUT',
+      path: `${GSC_PATH}/property`,
+      pathParams: productParams(input),
+      body: { email: input.email, site_url: input.siteUrl },
+    }),
+});
+
+const performance = defineCommand({
+  id: 'products.gsc.performance',
+  summary: 'Show Search Console performance for the last months.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { ...productInput(), months: int({ min: GSC_MIN_MONTHS, max: GSC_MAX_MONTHS }) },
+  cli: PRODUCT_CLI,
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: `${GSC_PATH}/performance`,
+      pathParams: productParams(input),
+      query: { months: input.months },
+    }),
+});
+
+const searchAnalytics = defineCommand({
+  id: 'products.gsc.search-analytics',
+  summary: 'Query Search Console search analytics with dimensions and filters.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: {
+    ...productInput(),
+    dimensions: string(),
+    limit: int({ min: LIST_MIN_LIMIT, max: GSC_SEARCH_ANALYTICS_MAX_LIMIT }),
+    months: int({ min: GSC_MIN_MONTHS, max: GSC_MAX_MONTHS }),
+    startDate: string(),
+    endDate: string(),
+    page: string(),
+    query: string(),
+    country: string(),
+    device: string(),
+  },
+  cli: PRODUCT_CLI,
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'GET',
+      path: `${GSC_PATH}/search-analytics`,
+      pathParams: productParams(input),
+      query: {
+        dimensions: input.dimensions,
+        limit: input.limit,
+        months: input.months,
+        start_date: input.startDate,
+        end_date: input.endDate,
+        page: input.page,
+        query: input.query,
+        country: input.country,
+        device: input.device,
+      },
+    }),
+});
+
+const inspectUrl = defineCommand({
+  id: 'products.gsc.inspect-url',
+  summary: 'Inspect the indexing status of one URL.',
+  kind: CommandKind.READ,
+  toolsets: TOOLSETS,
+  input: { ...productInput(), url: string().required(URL_REQUIRED), languageCode: string() },
+  cli: { ...PRODUCT_CLI, placeholders: URL_PLACEHOLDERS },
+  run: (input, ctx) =>
+    ctx.http({
+      method: 'POST',
+      path: `${GSC_PATH}/url-inspection`,
+      pathParams: productParams(input),
+      body: { inspection_url: input.url, ...(input.languageCode ? { language_code: input.languageCode } : {}) },
+    }),
+});
+
+export const gscGroup = defineGroup({
+  id: 'products.gsc',
+  help: {
+    usage: GSC_USAGE,
+    guidance:
+      'Use connect plus poll for the OAuth handoff, then inspect accounts, properties, performance, indexing, ' +
+      'and keyword data from the same subtree.',
+  },
+  unknown: (word) => ({
+    message: `Unknown products gsc subcommand: ${word}.`,
+    guidance: 'Run `outrank-cli products gsc --help` to see the available Google Search Console commands.',
+  }),
+  children: [
+    status,
+    connect,
+    poll,
+    reconnect,
+    disconnect,
+    accounts,
+    properties,
+    setProperty,
+    performance,
+    searchAnalytics,
+    inspectUrl,
+    cannibalization,
+  ],
+});