outrank-cli 0.8.0 → 0.10.0

package/src/commands/articles.js

@@ -1,6 +1,6 @@
 import { LIST_MAX_LIMIT, LIST_MIN_LIMIT, MIN_OFFSET, Surface } from '../core/constants.js';
 import { MCP_USAGE_GUIDANCE, usageError } from '../core/errors.js';
-import { image, int, object, oneOf, string, uuid } from '../core/schema.js';
+import { bool, image, int, list, object, oneOf, string, textFile, uuid } from '../core/schema.js';
 import { BodyMode, CommandKind, Toolset, defineCommand, defineGroup } from './registry.js';
 
 const ARTICLE_UPDATE_STATUSES = ['generated', 'approved', 'published'];
@@ -10,7 +10,7 @@ const ARTICLE_EXPECTED_LENGTHS = ['auto', 'short', 'medium', 'long', 'comprehens
 const ARTICLE_TITLE_HINT = 'At most 300 characters.';
 const META_DESCRIPTION_HINT = 'Trimmed to 160 characters.';
 const IMAGE_URL_HINT = 'Absolute http(s) URL.';
-const ARTICLE_STATUS_HINT = 'published publishes through the product integration for real.';
+const ARTICLE_STATUS_HINT = 'Outrank status only; publish to the CMS with articles publish.';
 const ARTICLE_INSTRUCTIONS_HINT = 'Per-article instructions of the linked scheduled keyword.';
 const ARTICLE_SUBTYPE_HINT =
   'guide: howTo | explainer | comparison | reference; listicle: roundup | resources | examples.';
@@ -24,9 +24,21 @@ const ARTICLE_UPDATE_BODY = object().shape({
   article_subtype: oneOf(ARTICLE_SUBTYPES).describe(ARTICLE_SUBTYPE_HINT),
   expected_length: oneOf(ARTICLE_EXPECTED_LENGTHS),
 });
+const ARTICLE_CREATE_BODY = object().shape({
+  product_id: uuid(),
+  title: string().describe(ARTICLE_TITLE_HINT),
+  content: string().describe('The full article body as markdown. Do not repeat the title as a # heading.'),
+  content_html: string().describe('HTML body instead of content; converted to markdown.'),
+  meta_description: string().describe('At most 160 characters.'),
+  slug: string().describe('Lowercase letters, numbers and hyphens; defaults to the title.'),
+  image_url: string().describe(IMAGE_URL_HINT),
+  tags: list(),
+  publish: bool().describe("Also publish it to the product's connected CMS now."),
+});
 
 export const ARTICLES_HELP = `Usage:
   outrank-cli articles list [--product <product-id>] [--status generated|approved|published|failed|deleted] [--title <text>] [--keyword <text>] [--content <text>] [--slug <text>] [--created-from <date>] [--created-to <date>] [--scheduled-from <date>] [--scheduled-to <date>] [--sort-by created_at|status|title] [--sort-order asc|desc] [--limit <n>] [--offset <n>]
+  outrank-cli articles create --product <product-id> --title <title> --content-file <path> [--publish] [--json <object>]
   outrank-cli articles get <article-id>
   outrank-cli articles get-content <article-id> [--format markdown|html]
   outrank-cli articles update <article-id> --json <object>
@@ -35,6 +47,8 @@ export const ARTICLES_HELP = `Usage:
   outrank-cli articles bulk-replace --json <object>
   outrank-cli articles upload-image --file <path> [--article <article-id>] [--keyword <text>]
   outrank-cli articles upload-featured-image <article-id> --file <path>
+  outrank-cli articles publish <article-id>
+  outrank-cli articles sync <article-id>
   outrank-cli articles retry-publish <article-id>
   outrank-cli articles delete <article-id>
   outrank-cli articles precreate <keyword-id>  # eligible future scheduled keyword only
@@ -45,6 +59,7 @@ JSON Input:
 
 Examples:
   outrank-cli articles list --product 00000000-0000-0000-0000-000000000000 --status published --limit 20
+  outrank-cli articles create --product 00000000-0000-0000-0000-000000000000 --title "How to choose a CRM" --content-file crm.md --publish
   outrank-cli articles get 00000000-0000-0000-0000-000000000000
   outrank-cli articles get-content 00000000-0000-0000-0000-000000000000 --format html
   outrank-cli articles update 00000000-0000-0000-0000-000000000000 --json '{"title":"New title"}'
@@ -54,6 +69,8 @@ Examples:
   outrank-cli articles bulk-replace --json-file bulk-replace.json
   outrank-cli articles upload-image --file .\\diagram.png --article 00000000-0000-0000-0000-000000000000
   outrank-cli articles upload-featured-image 00000000-0000-0000-0000-000000000000 --file .\\hero.jpg
+  outrank-cli articles publish 00000000-0000-0000-0000-000000000000
+  outrank-cli articles sync 00000000-0000-0000-0000-000000000000
   outrank-cli articles retry-publish 00000000-0000-0000-0000-000000000000
   outrank-cli articles precreate 00000000-0000-0000-0000-000000000000
   outrank-cli articles generate 00000000-0000-0000-0000-000000000000
@@ -273,6 +290,71 @@ const uploadFeaturedImageCommand = defineCommand({
     }),
 });
 
+const ARTICLE_CREATE_GUIDANCE =
+  'Pass --product <product-id>, --title and the body with --content-file article.md (markdown), or send ' +
+  '{"product_id": "...", "title": "...", "content": "..."} with --json. Add --publish to send it to the CMS.';
+
+const CREATE_REQUIRED_FIELDS = Object.freeze([
+  { field: 'product_id', option: '--product <product-id>' },
+  { field: 'title', option: '--title <title>' },
+]);
+
+const refineCreate = (input, ctx) => {
+  const body = input.body ?? {};
+  const isMcp = ctx.surface === Surface.MCP;
+  const guidance = isMcp ? MCP_USAGE_GUIDANCE : ARTICLE_CREATE_GUIDANCE;
+  const missing = CREATE_REQUIRED_FIELDS.find(({ field }) => !(typeof body[field] === 'string' && body[field].trim()));
+  if (missing) {
+    throw usageError(isMcp ? `${missing.field} is required.` : `Missing required option: ${missing.option}.`, guidance);
+  }
+  const bodies = ['content', 'content_html'].filter((name) => body[name] !== undefined);
+  if (bodies.length !== 1) {
+    throw usageError('Send exactly one of content (markdown) or content_html.', guidance);
+  }
+};
+
+const createCommand = defineCommand({
+  id: 'articles.create',
+  summary: 'Create an article from your own content and optionally publish it to the connected CMS.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: {
+    productId: uuid(),
+    title: string(),
+    contentFile: textFile().describe('Local markdown file used as the body (CLI only).'),
+    publish: bool(),
+  },
+  cli: { options: { product: 'productId' } },
+  body: BodyMode.OPTIONAL_JSON_OR_EMPTY_OBJECT,
+  bodyField: ARTICLE_CREATE_BODY,
+  bodyMerge: { product_id: 'productId', title: 'title', content: 'contentFile', publish: 'publish' },
+  longRunning: { pollTool: 'articles.list' },
+  refine: refineCreate,
+  run: (input, ctx) => ctx.http({ method: 'POST', path: '/articles', body: input.body }),
+});
+
+const publishCommand = defineCommand({
+  id: 'articles.publish',
+  summary: "Publish an article to the product's connected CMS for the first time.",
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: articleIdInput(),
+  cli: ARTICLE_ID_CLI,
+  longRunning: { pollTool: 'articles.get' },
+  run: (input, ctx) => ctx.http({ method: 'POST', path: `${ARTICLE_PATH}/publish`, pathParams: articleIdParams(input) }),
+});
+
+const syncCommand = defineCommand({
+  id: 'articles.sync',
+  summary: 'Push the edits of a published article to the post already in the connected CMS.',
+  kind: CommandKind.WRITE,
+  toolsets: TOOLSETS,
+  input: articleIdInput(),
+  cli: ARTICLE_ID_CLI,
+  longRunning: { pollTool: 'articles.get' },
+  run: (input, ctx) => ctx.http({ method: 'POST', path: `${ARTICLE_PATH}/sync`, pathParams: articleIdParams(input) }),
+});
+
 const retryPublishCommand = defineCommand({
   id: 'articles.retry-publish',
   summary: 'Retry publishing an article to its integration.',
@@ -329,8 +411,10 @@ export const articlesGroup = defineGroup({
   help: {
     usage: ARTICLES_HELP,
     guidance:
-      'Choose one of: list, get, get-content, update, update-content, replace, bulk-replace, upload-image, ' +
-      'upload-featured-image, retry-publish, delete, precreate, generate.',
+      'Choose one of: list, create, get, get-content, update, update-content, replace, bulk-replace, upload-image, ' +
+      'upload-featured-image, publish, sync, retry-publish, delete, precreate, generate. `create` stores your own ' +
+      'article (add --publish to send it to the CMS), `publish` sends an article to the CMS the first time, and ' +
+      '`sync` pushes later edits to the post already in the CMS.',
   },
   unknown: (word) => ({
     message: `Unknown articles subcommand: ${word}.`,
@@ -338,6 +422,7 @@ export const articlesGroup = defineGroup({
   }),
   children: [
     listCommand,
+    createCommand,
     getCommand,
     getContentCommand,
     updateCommand,
@@ -346,6 +431,8 @@ export const articlesGroup = defineGroup({
     bulkReplaceCommand,
     uploadImageCommand,
     uploadFeaturedImageCommand,
+    publishCommand,
+    syncCommand,
     retryPublishCommand,
     deleteCommand,
     precreateCommand,

package/src/commands/products/blog.js

@@ -7,6 +7,7 @@ import {
   BLOG_PAGE_STATUSES,
   BLOG_POSITION_MAX,
   BLOG_POST_LIST_STATUSES,
+  BLOG_POST_WRITE_STATUSES,
   BLOG_PREVIEW_DESIGN_SCOPE,
   BLOG_PREVIEW_SCOPES,
   BLOG_REDIRECT_GONE_STATUS_CODE,
@@ -19,7 +20,7 @@ import {
 } from '../../core/constants.js';
 import { Surface } from '../../core/constants.js';
 import { MCP_USAGE_GUIDANCE, usageError } from '../../core/errors.js';
-import { bool, int, json, list, object, oneOf, string, uuid } from '../../core/schema.js';
+import { bool, int, json, list, object, oneOf, string, textFile, uuid } from '../../core/schema.js';
 import { BodyMode, CommandKind, Toolset, defineCommand, defineGroup } from '../registry.js';
 import { productInput } from './shared.js';
 
@@ -35,11 +36,13 @@ const BLOG_USAGE = `Usage:
   outrank-cli products blog starter-posts <product-id>
   outrank-cli products blog preview <product-id> --scope design|post|page [--target-id <id>]
   outrank-cli products blog design get|update|publish|discard <product-id> [--json <object>]
+  outrank-cli products blog design patch <product-id> --json <object> [--publish]
   outrank-cli products blog domain get|connect|verify|remove <product-id> [--json <object>]
   outrank-cli products blog posts list <product-id> [--status all|published|scheduled|draft] [--search <text>] [--page <n>]
-  outrank-cli products blog posts create <product-id> [--title <title>]
-  outrank-cli products blog posts get|get-content|unpublish|sync <product-id> <article-id>
-  outrank-cli products blog posts update|update-content <product-id> <article-id> --json <object>
+  outrank-cli products blog posts create <product-id> [--title <title>] [--content-file <path>] [--status draft|published|scheduled] [--scheduled-for <iso-datetime>] [--json <object>]
+  outrank-cli products blog posts update <product-id> <article-id> [--title <title>] [--content-file <path>] [--status draft|published|scheduled] [--scheduled-for <iso-datetime>] [--json <object>]
+  outrank-cli products blog posts get|get-content|unpublish|sync|delete <product-id> <article-id>
+  outrank-cli products blog posts update-content <product-id> <article-id> --json <object>
   outrank-cli products blog posts publish <product-id> <article-id> [--scheduled-for <iso-datetime>]
   outrank-cli products blog pages list|create|reorder <product-id> [--json <object>]
   outrank-cli products blog pages get|update|delete <product-id> <page-id> [--json <object>]
@@ -135,6 +138,27 @@ const POST_SETTINGS_BODY = object().shape({
   showToc: bool(),
 });
 
+const POST_WRITE_FIELDS = {
+  title: string(),
+  content: string().describe('Markdown body; replaces the whole body. Do not repeat the title as a # heading.'),
+  contentHtml: string().describe('HTML body instead of content; converted to markdown.'),
+  metaDescription: string().describe('Search description, at most 320 characters.'),
+  status: oneOf(BLOG_POST_WRITE_STATUSES).describe(
+    'draft keeps or takes the post offline, published puts it live now, scheduled needs scheduledFor.',
+  ),
+  scheduledFor: string().describe('ISO 8601 date-time with offset, 1 minute to 365 days ahead.'),
+};
+
+const POST_WRITE_BODY = object().shape({ ...POST_WRITE_FIELDS, ...POST_SETTINGS_BODY.properties });
+
+const DESIGN_PATCH_BODY = object().shape({
+  config: json().describe(
+    'Only the design fields to change, for example {"theme": {"colors": {"accent": "#2563EB"}}}. Objects are ' +
+      'merged into the current draft; arrays replace the old array.',
+  ),
+  publish: bool().describe('Also make the merged design live.'),
+});
+
 const POST_CONTENT_BODY = object().shape({
   title: string(),
   content: string().describe('Markdown body; replaces the whole body.'),
@@ -267,6 +291,45 @@ const refineSnippetContent = (input, ctx) => {
 };
 
 const POST_CONTENT_GUIDANCE = 'Send {"title": "..."}, {"content": "<markdown>"} or both.';
+const POST_CREATE_GUIDANCE =
+  'Pass --title and the body with --content-file post.md (markdown), or send {"title": "...", "content": "..."} ' +
+  'with --json; add --status published to put it live now.';
+const POST_UPDATE_GUIDANCE =
+  'Pass at least one change: --title, --content-file, --status, or a --json object with the fields to change.';
+const SCHEDULE_GUIDANCE = 'Pass --status scheduled together with --scheduled-for <iso-datetime>.';
+
+const refinePostWrite = ({ requireChange }) => (input, ctx) => {
+  const body = input.body ?? {};
+  const guidance = requireChange ? POST_UPDATE_GUIDANCE : POST_CREATE_GUIDANCE;
+  if (requireChange && Object.keys(body).length === 0) {
+    throw bodyUsageError(ctx, 'Send at least one field to change.', guidance);
+  }
+  if (body.content !== undefined && body.contentHtml !== undefined) {
+    throw bodyUsageError(ctx, 'Send content (markdown) or contentHtml, not both.', guidance);
+  }
+  if ((body.status === 'scheduled') !== Boolean(body.scheduledFor)) {
+    throw bodyUsageError(ctx, 'status scheduled and scheduledFor go together.', SCHEDULE_GUIDANCE);
+  }
+};
+
+const refineDesignPatch = (input, ctx) => {
+  const config = input.body?.config;
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw bodyUsageError(
+      ctx,
+      'config must be an object with the design fields to change.',
+      'Send {"config": {"theme": {"colors": {"accent": "#2563EB"}}}}; add --publish to make it live.',
+    );
+  }
+};
+
+const POST_WRITE_MERGE = { title: 'title', content: 'contentFile', status: 'status', scheduledFor: 'scheduledFor' };
+const POST_WRITE_INPUT = {
+  title: string(),
+  contentFile: textFile().describe('Local markdown file used as the body (CLI only).'),
+  status: oneOf(BLOG_POST_WRITE_STATUSES),
+  scheduledFor: string(),
+};
 
 const refinePostContent = (input, ctx) => {
   const { title, content } = input.body ?? {};
@@ -294,6 +357,7 @@ const blogCommand = ({
   input = {},
   body,
   bodyField,
+  bodyMerge,
   bodyOf,
   query,
   mcp,
@@ -310,6 +374,7 @@ const blogCommand = ({
     cli: { positionals: [PRODUCT_ID, ...ids] },
     ...(body ? { body } : {}),
     ...(bodyField ? { bodyField } : {}),
+    ...(bodyMerge ? { bodyMerge } : {}),
     ...(mcp ? { mcp } : {}),
     ...(refine ? { refine } : {}),
     run: (values, ctx) =>
@@ -355,10 +420,12 @@ const designGroup = group({
     'design update <product-id> --json <object>',
     'design publish <product-id>',
     'design discard <product-id>',
+    'design patch <product-id> --json <object> [--publish]',
   ]),
   guidance:
-    'Edit the draft theme with `update` (send the whole config, starting from the draft returned by `get`), ' +
-    'preview it with `outrank-cli products blog preview <product-id> --scope design`, then `publish` it.',
+    'Change part of the theme with `patch` and {"config": {...}} (only the fields that change; add --publish to ' +
+    'make it live). `update` replaces the whole draft config. Preview a draft with ' +
+    '`outrank-cli products blog preview <product-id> --scope design`, then `publish` it.',
   children: [
     blogCommand({
       id: 'design.get',
@@ -389,6 +456,18 @@ const designGroup = group({
       method: 'POST',
       suffix: '/design/discard',
     }),
+    blogCommand({
+      id: 'design.patch',
+      summary: 'Change part of the blog theme (merged into the draft) and optionally publish it.',
+      kind: CommandKind.WRITE,
+      method: 'PATCH',
+      suffix: '/design',
+      input: { publish: bool() },
+      body: BodyMode.JSON,
+      bodyField: DESIGN_PATCH_BODY,
+      bodyMerge: { publish: 'publish' },
+      refine: refineDesignPatch,
+    }),
   ],
 });
 
@@ -444,9 +523,12 @@ const postsGroup = group({
   id: 'posts',
   usage: usageFor([
     'posts list <product-id> [--status all|published|scheduled|draft] [--search <text>] [--page <n>]',
-    'posts create <product-id> [--title <title>]',
+    'posts create <product-id> [--title <title>] [--content-file <path>] [--status draft|published|scheduled] ' +
+      '[--scheduled-for <iso-datetime>] [--json <object>]',
     'posts get <product-id> <article-id>',
-    'posts update <product-id> <article-id> --json <object>',
+    'posts update <product-id> <article-id> [--title <title>] [--content-file <path>] ' +
+      '[--status draft|published|scheduled] [--scheduled-for <iso-datetime>] [--json <object>]',
+    'posts delete <product-id> <article-id>',
     'posts get-content <product-id> <article-id>',
     'posts update-content <product-id> <article-id> --json <object>',
     'posts publish <product-id> <article-id> [--scheduled-for <iso-datetime>]',
@@ -454,8 +536,10 @@ const postsGroup = group({
     'posts sync <product-id> <article-id>',
   ]),
   guidance:
-    'Posts are keyed by their article id. `create` a draft, write it with `update-content`, set slug, SEO and ' +
-    'category with `update`, then `publish` (now or with --scheduled-for). After editing a live post, run `sync`.',
+    'Posts are keyed by their article id. `create` writes a whole post in one call: title, body (--content-file ' +
+    'or "content"), SEO fields and --status published or scheduled. `update` changes only the fields it is ' +
+    'given, including the body and the status, and refreshes a live post on its own. A slug that is already ' +
+    'used returns CONFLICT with error.details.existingArticleId: update that post instead of creating it again.',
   children: [
     blogCommand({
       id: 'posts.list',
@@ -468,12 +552,15 @@ const postsGroup = group({
     }),
     blogCommand({
       id: 'posts.create',
-      summary: 'Create an empty draft post on the blog.',
+      summary: 'Write a post on the blog in one call (title, body, SEO fields) as a draft, live or scheduled.',
       kind: CommandKind.WRITE,
       method: 'POST',
       suffix: '/posts',
-      input: { title: string() },
-      bodyOf: (values) => (values.title ? { title: values.title } : {}),
+      input: POST_WRITE_INPUT,
+      body: BodyMode.OPTIONAL_JSON_OR_EMPTY_OBJECT,
+      bodyField: POST_WRITE_BODY,
+      bodyMerge: POST_WRITE_MERGE,
+      refine: refinePostWrite({ requireChange: false }),
     }),
     blogCommand({
       id: 'posts.get',
@@ -485,13 +572,24 @@ const postsGroup = group({
     }),
     blogCommand({
       id: 'posts.update',
-      summary: 'Change the slug, author, category, tags, excerpt, SEO or cover of one post from a JSON body.',
+      summary: 'Change any field of one post (title, body, SEO, slug, category, cover, status); live posts refresh.',
       kind: CommandKind.WRITE,
       method: 'PATCH',
       suffix: POST_PATH,
       ids: POST_ID,
-      body: BodyMode.JSON,
-      bodyField: POST_SETTINGS_BODY,
+      input: POST_WRITE_INPUT,
+      body: BodyMode.OPTIONAL_JSON_OR_EMPTY_OBJECT,
+      bodyField: POST_WRITE_BODY,
+      bodyMerge: POST_WRITE_MERGE,
+      refine: refinePostWrite({ requireChange: true }),
+    }),
+    blogCommand({
+      id: 'posts.delete',
+      summary: 'Take one post off the blog and delete it.',
+      kind: CommandKind.DESTRUCTIVE,
+      method: 'DELETE',
+      suffix: POST_PATH,
+      ids: POST_ID,
     }),
     blogCommand({
       id: 'posts.get-content',

package/src/core/constants.js

@@ -27,6 +27,8 @@ export const MCP_STARTUP_RESOLVE_TIMEOUT_MS = 3_000;
 
 export const MAX_IMAGE_UPLOAD_MEGABYTES = 5;
 export const MAX_IMAGE_UPLOAD_BYTES = MAX_IMAGE_UPLOAD_MEGABYTES * BYTES_PER_MB;
+export const MAX_TEXT_FILE_MEGABYTES = 1;
+export const MAX_TEXT_FILE_BYTES = MAX_TEXT_FILE_MEGABYTES * BYTES_PER_MB;
 export const MAX_UPSTREAM_ERROR_BODY_CHARS = 500;
 export const MAX_RATE_LIMIT_HEADER_LENGTH = 64;
 export const MAX_TOOL_NAME_LENGTH = 46;
@@ -50,6 +52,7 @@ export const BLOG_TEMPLATES = Object.freeze(['classic', 'editorial', 'journal',
 export const BLOG_ANALYTICS_RANGES = Object.freeze(['7d', '30d', '90d']);
 export const BLOG_DOMAIN_MODES = Object.freeze(['subdomain', 'apex', 'subfolder']);
 export const BLOG_POST_LIST_STATUSES = Object.freeze(['all', 'published', 'scheduled', 'draft']);
+export const BLOG_POST_WRITE_STATUSES = Object.freeze(['draft', 'published', 'scheduled']);
 export const BLOG_SUBSCRIBER_STATUSES = Object.freeze(['subscribed', 'unsubscribed']);
 export const BLOG_PREVIEW_DESIGN_SCOPE = 'design';
 export const BLOG_PREVIEW_SCOPES = Object.freeze([BLOG_PREVIEW_DESIGN_SCOPE, 'post', 'page']);

package/src/core/files.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { MAX_IMAGE_UPLOAD_BYTES } from './constants.js';
+import { MAX_IMAGE_UPLOAD_BYTES, MAX_TEXT_FILE_BYTES } from './constants.js';
 import { usageError } from './errors.js';
 
 const ImageMime = Object.freeze({
@@ -184,3 +184,39 @@ export const readImageUpload = async ({ filePath, allowedDir }) => {
 
   return toUpload(buffer, fileName);
 };
+
+const UTF8_ENCODING = 'utf-8';
+const BYTE_ORDER_MARK = '\uFEFF';
+const LINE_BREAK_PATTERN = /\r\n?/g;
+const LINE_FEED = '\n';
+const TEXT_OVERSIZE_GUIDANCE = 'Split the content or shorten it below the limit, then retry.';
+const TEXT_ENCODING_GUIDANCE = 'Save the file as UTF-8 text, then retry.';
+
+export const readTextFile = async ({ filePath, option }) => {
+  if (typeof filePath !== 'string' || filePath === '') {
+    throw usageError(`Missing required option: ${option} <path>.`, `Pass a local file path with \`${option} <path>\`.`);
+  }
+  let buffer;
+  try {
+    const stats = await fs.stat(filePath);
+    if (!stats.isFile()) throw usageError(`Not a file: ${filePath}`, readGuidance(filePath));
+    if (stats.size > MAX_TEXT_FILE_BYTES) {
+      throw usageError(
+        `${filePath} is ${stats.size} bytes; the maximum is ${MAX_TEXT_FILE_BYTES} bytes.`,
+        TEXT_OVERSIZE_GUIDANCE,
+      );
+    }
+    buffer = await fs.readFile(filePath);
+  } catch (error) {
+    if (error?.cliCode) throw error;
+    throw usageError(`Failed to read file: ${error.message}`, readGuidance(filePath));
+  }
+  let text;
+  try {
+    text = new TextDecoder(UTF8_ENCODING, { fatal: true }).decode(buffer);
+  } catch {
+    throw usageError(`${filePath} is not valid UTF-8 text.`, TEXT_ENCODING_GUIDANCE);
+  }
+  const withoutBom = text.startsWith(BYTE_ORDER_MARK) ? text.slice(BYTE_ORDER_MARK.length) : text;
+  return withoutBom.replace(LINE_BREAK_PATTERN, LINE_FEED);
+};

package/src/core/redact.js

@@ -3,7 +3,7 @@ import { SENSITIVE_BODY_FIELDS } from './constants.js';
 export const REDACTED = '<redacted>';
 const TOO_DEEP = '<nested too deeply>';
 const DEFAULT_MAX_DEPTH = 32;
-const API_KEY_PATTERN = /outr_(?:live|test)_[A-Za-z0-9_]+/g;
+const API_KEY_PATTERN = /outr_(?:live|test|oat|ort)_[A-Za-z0-9_-]+/g;
 const BEARER_PATTERN = /Bearer\s+[A-Za-z0-9._~+/=-]+/g;
 const SENSITIVE_FIELD_SET = new Set(SENSITIVE_BODY_FIELDS.map((name) => name.toLowerCase()));
 const SENSITIVE_KEY_PATTERN = /token|secret|password|passwd|api[_-]?key|authorization|credential|private[_-]?key/i;

package/src/core/schema.js

@@ -11,6 +11,7 @@ export const FieldKind = Object.freeze({
   OBJECT: 'object',
   JSON: 'json',
   IMAGE: 'image',
+  TEXT_FILE: 'text-file',
 });
 
 export const BoolSerialize = Object.freeze({
@@ -63,6 +64,7 @@ export const list = ({ split = DEFAULT_LIST_SEPARATOR, serialize = ListSerialize
 export const object = () => createField(FieldKind.OBJECT, { properties: undefined });
 export const json = () => createField(FieldKind.JSON);
 export const image = () => createField(FieldKind.IMAGE);
+export const textFile = () => createField(FieldKind.TEXT_FILE);
 
 export const isField = (value) => Boolean(value) && Object.values(FieldKind).includes(value.kind);
 
@@ -124,6 +126,10 @@ const parseScalar = (field, value, label) => {
     if (!valid) throw usageError(`${label} must be an image upload (file_base64, file_name, file_type).`);
     return value;
   }
+  if (field.kind === FieldKind.TEXT_FILE) {
+    if (typeof value !== 'string') throw usageError(`${label} must be the path of a text file.`);
+    return value;
+  }
   throw new Error(`Unknown field kind: ${field.kind}`);
 };
 
@@ -254,6 +260,7 @@ const zodScalar = (z, field, options = {}) => {
   if (field.kind === FieldKind.IMAGE) {
     return z.object({ file_base64: z.string().min(1), file_name: z.string().min(1), file_type: z.string().min(1) });
   }
+  if (field.kind === FieldKind.TEXT_FILE) return z.string();
   throw new Error(`Unknown field kind: ${field.kind}`);
 };