outrank-cli 0.10.0 → 0.11.0

package/src/commands/improvements.js

@@ -1,6 +1,7 @@
 import { IMPROVEMENTS_CANDIDATES_MAX_LIMIT, LIST_MAX_LIMIT, LIST_MIN_LIMIT, MIN_OFFSET } from '../core/constants.js';
 import { BoolSerialize, bool, int, list, object, oneOf, string, uuid } from '../core/schema.js';
 import { BodyMode, CommandKind, Toolset, defineCommand, defineGroup } from './registry.js';
+import { subGroup } from './subGroup.js';
 
 const WEEKDAY_CODES = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
 const ENABLED_HINT = 'true starts the unattended improvement loop.';
@@ -343,17 +344,6 @@ const executionsPush = defineCommand({
     }),
 });
 
-const subGroup = ({ id, usage, actions, children }) =>
-  defineGroup({
-    id,
-    help: { usage, guidance: `Use: improvements ${id.slice(id.indexOf('.') + 1)} ${actions}.` },
-    unknown: (word) => ({
-      message: `Unknown ${id.slice(id.indexOf('.') + 1)} action: ${word}.`,
-      guidance: `Use: improvements ${id.slice(id.indexOf('.') + 1)} ${actions}.`,
-    }),
-    children,
-  });
-
 export const improvementsGroup = defineGroup({
   id: 'improvements',
   help: {

package/src/commands/index.js

@@ -1,3 +1,4 @@
+import { aiCitedListsGroup } from './aiCitedLists.js';
 import { articlesGroup } from './articles.js';
 import { authGroup } from './auth.js';
 import { billingGroup } from './billing.js';
@@ -19,4 +20,5 @@ export const registry = createRegistry([
   improvementsGroup,
   productsGroup,
   marketplaceGroup,
+  aiCitedListsGroup,
 ]);

package/src/commands/products/integrations.js

@@ -1,7 +1,15 @@
 import { usageError } from '../../core/errors.js';
 import { 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';
+import {
+  ATTEMPT_ID_PLACEHOLDERS,
+  PRODUCT_CLI,
+  attemptIdInput,
+  attemptIdQuery,
+  productInput,
+  productParams,
+  withProduct,
+} from './shared.js';
 
 const INTEGRATIONS_USAGE = `Usage:
   outrank-cli products integrations providers
@@ -92,12 +100,9 @@ const INTEGRATION_PATH = '/products/{productId}/integrations/{integrationId}';
 const CONNECT_PATH = '/products/{productId}/integrations/connect/{provider}';
 const PROVIDER_PRODUCT_CLI = { positionals: ['provider', 'productId'] };
 const INTEGRATION_CLI = withProduct(['integrationId']);
-const ATTEMPT_ID_PLACEHOLDERS = { attemptId: '<attempt-id>' };
-const ATTEMPT_ID_REQUIRED = {
-  guidance:
-    'Run `outrank-cli products integrations poll <provider> <product-id> --attempt-id <attempt-id>` after ' +
-    'connect starts.',
-};
+const ATTEMPT_ID_GUIDANCE =
+  'Run `outrank-cli products integrations poll <provider> <product-id> --attempt-id <attempt-id>` after ' +
+  'connect starts.';
 const SENSITIVE_BODY = { sensitiveBody: true };
 
 const providerInput = (providers) => ({ provider: oneOf(providers).required(), ...productInput() });
@@ -147,14 +152,14 @@ const poll = defineCommand({
   summary: 'Poll an OAuth connect attempt until the handoff completes.',
   kind: CommandKind.READ,
   toolsets: TOOLSETS,
-  input: { ...providerInput(CONNECT_PROVIDERS), attemptId: string().required(ATTEMPT_ID_REQUIRED) },
+  input: { ...providerInput(CONNECT_PROVIDERS), ...attemptIdInput(ATTEMPT_ID_GUIDANCE) },
   cli: { ...PROVIDER_PRODUCT_CLI, placeholders: ATTEMPT_ID_PLACEHOLDERS },
   run: (input, ctx) =>
     ctx.http({
       method: 'GET',
       path: CONNECT_PATH,
       pathParams: providerParams(input),
-      query: { attempt_id: input.attemptId },
+      query: attemptIdQuery(input),
     }),
 });
 

package/src/commands/products/shared.js

@@ -1,4 +1,4 @@
-import { uuid } from '../../core/schema.js';
+import { string, uuid } from '../../core/schema.js';
 
 export const PRODUCT_CLI = { positionals: ['productId'] };
 
@@ -6,3 +6,8 @@ export const productInput = () => ({ productId: uuid().required() });
 export const productParams = (input) => ({ productId: input.productId });
 
 export const withProduct = (extraPositionals) => ({ positionals: ['productId', ...extraPositionals] });
+export const productParamsWith = (input, name) => ({ productId: input.productId, [name]: input[name] });
+
+export const ATTEMPT_ID_PLACEHOLDERS = { attemptId: '<attempt-id>' };
+export const attemptIdInput = (guidance) => ({ attemptId: string().required({ guidance }) });
+export const attemptIdQuery = (input) => ({ attempt_id: input.attemptId });

package/src/commands/registry.js

@@ -23,6 +23,7 @@ export const Toolset = Object.freeze({
   MARKETPLACE_BUYER: 'marketplace-buyer',
   BILLING: 'billing',
   BLOG: 'blog',
+  AI_CITED_LISTS: 'ai-cited-lists',
 });
 
 export const BodyMode = Object.freeze({

package/src/commands/subGroup.js

@@ -0,0 +1,15 @@
+import { cliWords, defineGroup, lastSegment } from './registry.js';
+
+const WORD_SEPARATOR = ' ';
+
+export const subGroup = ({ id, usage, actions, children }) => {
+  const noun = lastSegment(id);
+  const group = cliWords(id).slice(0, -1).join(WORD_SEPARATOR);
+  const guidance = `Use: ${group} ${noun} ${actions}.`;
+  return defineGroup({
+    id,
+    help: { usage, guidance },
+    unknown: (word) => ({ message: `Unknown ${noun} action: ${word}.`, guidance }),
+    children,
+  });
+};

package/src/core/constants.js

@@ -66,6 +66,10 @@ export const BLOG_REDIRECT_GONE_STATUS_CODE = 410;
 export const BLOG_REDIRECT_STATUS_CODES = Object.freeze([301, 302, BLOG_REDIRECT_GONE_STATUS_CODE]);
 export const BLOG_WEBHOOK_EVENTS = Object.freeze(['subscriber.created']);
 
+export const AI_CITATIONS_PERIOD_WEEKS = Object.freeze([4, 12]);
+export const AI_CITED_LISTS_LIST_VIEWS = Object.freeze(['all', 'to_send', 'skipped']);
+export const AI_CITED_LISTS_ENTRY_MODES = Object.freeze(['generated', 'custom']);
+
 export const BILLING_MIN_ADDITIONAL_PRODUCTS = 1;
 export const BILLING_MAX_ADDITIONAL_PRODUCTS = 30;
 export const BILLING_MIN_CONFIRM_CHARGE_CENTS = 0;

package/src/core/execute.js

@@ -50,7 +50,8 @@ const mergeBody = (spec, input, body) => {
 };
 
 export const executeCommand = async ({ spec, raw, loadBody = async () => undefined, ctx, labels = {} }) => {
-  const validation = { ...labels, splitLists: ctx.surface !== Surface.MCP };
+  const fromText = ctx.surface !== Surface.MCP;
+  const validation = { ...labels, splitLists: fromText, coerceEnumText: fromText };
   try {
     const { bodyField, rest } = splitBodyField(spec.input);
     const input = validateInput(rest, raw, validation);

package/src/core/schema.js

@@ -83,7 +83,7 @@ const parseInteger = (value, label) => {
   return Number(value);
 };
 
-const parseScalar = (field, value, label) => {
+const parseScalar = (field, value, label, { coerceEnumText = false } = {}) => {
   if (field.kind === FieldKind.STRING) {
     if (typeof value !== 'string') throw usageError(`${label} must be a string.`);
     return value;
@@ -111,8 +111,11 @@ const parseScalar = (field, value, label) => {
     throw usageError(`${label} must be true or false.`);
   }
   if (field.kind === FieldKind.ENUM) {
-    if (!field.values.includes(value)) throw usageError(`${label} must be one of: ${field.values.join(', ')}.`);
-    return value;
+    const match = field.values.find(
+      (candidate) => candidate === value || (coerceEnumText && String(candidate) === value),
+    );
+    if (match === undefined) throw usageError(`${label} must be one of: ${field.values.join(', ')}.`);
+    return match;
   }
   if (field.kind === FieldKind.OBJECT) {
     if (!isPlainObject(value)) throw usageError(`${label} must be a JSON object.`);
@@ -139,11 +142,11 @@ const splitListValues = (field, value, splitLists) => {
   return rawItems.flatMap((item) => (typeof item === 'string' ? item.split(field.split) : [item]));
 };
 
-const parseList = (field, value, label, splitLists) => {
+const parseList = (field, value, label, splitLists, coerceEnumText) => {
   const items = splitListValues(field, value, splitLists)
     .map((item) => (typeof item === 'string' ? item.trim() : item))
     .filter((item) => item !== '');
-  return items.map((item) => parseScalar(field.item, item, label));
+  return items.map((item) => parseScalar(field.item, item, label, { coerceEnumText }));
 };
 
 const withFieldGuidance = (field, run) => {
@@ -157,11 +160,11 @@ const withFieldGuidance = (field, run) => {
   }
 };
 
-export const parseFieldValue = (field, value, label, { splitLists = true } = {}) =>
+export const parseFieldValue = (field, value, label, { splitLists = true, coerceEnumText = false } = {}) =>
   withFieldGuidance(field, () => {
     if (value === '') throw usageError(`${label} requires a value.`);
-    if (field.kind === FieldKind.LIST) return parseList(field, value, label, splitLists);
-    return parseScalar(field, value, label);
+    if (field.kind === FieldKind.LIST) return parseList(field, value, label, splitLists, coerceEnumText);
+    return parseScalar(field, value, label, { coerceEnumText });
   });
 
 const missingPropertyError = (property, label) => {
@@ -202,7 +205,11 @@ const missingFieldError = (field, name, missingMessage) => {
 
 const cloneDefault = (value) => (value !== null && typeof value === 'object' ? structuredClone(value) : value);
 
-export const validateInput = (fields, raw, { labelOf = (name) => name, missingOf, splitLists = true } = {}) => {
+export const validateInput = (
+  fields,
+  raw,
+  { labelOf = (name) => name, missingOf, splitLists = true, coerceEnumText = false } = {},
+) => {
   const missingMessage = missingOf ?? ((name) => `Missing required input: ${labelOf(name)}.`);
   const result = {};
   for (const [name, field] of Object.entries(fields)) {
@@ -212,7 +219,7 @@ export const validateInput = (fields, raw, { labelOf = (name) => name, missingOf
       if (field.defaultValue !== undefined) result[name] = cloneDefault(field.defaultValue);
       continue;
     }
-    const parsed = parseFieldValue(field, value, labelOf(name), { splitLists });
+    const parsed = parseFieldValue(field, value, labelOf(name), { splitLists, coerceEnumText });
     if (field.kind === FieldKind.LIST && field.isRequired && parsed.length === 0) {
       throw missingFieldError(field, name, missingMessage);
     }
@@ -239,6 +246,9 @@ const boundedNumber = (schema, field) => {
   return bounded;
 };
 
+const zodEnum = (z, values) =>
+  values.every((value) => typeof value === 'string') ? z.enum(values) : z.literal(values);
+
 const zodScalar = (z, field, options = {}) => {
   const { jsonAsObject = false, inBody = false } = options;
   if (field.kind === FieldKind.STRING) return inBody ? z.string() : z.string().min(1);
@@ -246,7 +256,7 @@ const zodScalar = (z, field, options = {}) => {
   if (field.kind === FieldKind.INT) return boundedNumber(z.number().int(), field);
   if (field.kind === FieldKind.NUMBER) return boundedNumber(z.number(), field);
   if (field.kind === FieldKind.BOOL) return z.boolean();
-  if (field.kind === FieldKind.ENUM) return z.enum(field.values);
+  if (field.kind === FieldKind.ENUM) return zodEnum(z, field.values);
   if (field.kind === FieldKind.OBJECT) {
     if (!field.properties) return z.object({}).passthrough();
     const propertyOptions = { ...options, inBody: true, jsonAsObject: false };

package/src/index.js

@@ -26,6 +26,7 @@ Groups:
   articles    Inspect article metadata and bodies, edit content, retry publish, precreate, and generate.
   improvements Discover, brief, schedule, run, review, and publish article improvements for existing posts.
   marketplace Seller onboarding, eligibility, placements, earnings, Stripe payouts, and buyer setup for the Outrank Marketplace.
+  ai-cited-lists AI-Cited Lists (Backlinks Enterprise): ChatGPT-cited lists, offers to their owners, won spots, outreach setup.
   subscription Inspect plan, trial, quota, and add-on status.
   usage       Inspect current usage and quota consumption.
   billing     Product-slot purchase flows.
@@ -68,6 +69,8 @@ Examples:
   outrank-cli marketplace seller status <product-id>
   outrank-cli marketplace seller onboard <product-id> --country US
   outrank-cli marketplace seller placements list <product-id> --status needs_approval
+  outrank-cli ai-cited-lists status <product-id>
+  outrank-cli ai-cited-lists lists list <product-id> --view to_send
 `;
 
 const main = async () => {