@pitcher/cli-scripts 2.4.0 → 2.5.0

package/README.md

@@ -270,6 +270,23 @@ p announcements scaffold --out ./announcement.json --api-key myapikey
 
 `scaffold` returns the starter JSON in the envelope `data`; pass `--out <path>` to write it to a file instead.
 
+## To run the `themes` command:
+
+Read canvas/branding themes (colors via `settings`, fonts via `typography`, plus `assets`/`logo`) to reference when authoring email/DSR/canvas content. Read-only.
+
+```bash
+# List all themes in the org (returns full theme objects)
+p themes list --api-key myapikey
+
+# Narrow to one instance; add per-theme canvas usage and canvas ids
+p themes list --instance-id 01... --with-usage --with-canvas-ids --api-key myapikey
+
+# Get one theme by id
+p themes get --id 01THEMEID... --api-key myapikey
+```
+
+`list` is server-capped (newest-first) with no `--limit`/`--page`; when the cap is hit the envelope carries a truncation warning. `--instance-id` narrows to themes bound to that instance and **excludes** org-level (default) themes, so omit it to see everything usable in the org.
+
 ## To run the `org` command:
 
 Read the organization the API key belongs to.

package/dist/index.js

@@ -17,6 +17,7 @@ import { createAnalyticsCommand } from './src/commands/analytics.js';
 import { createAnnouncementsCommand } from './src/commands/announcements.js';
 import { createDsrLandingCommand } from './src/commands/dsrLanding.js';
 import { createEmailTemplateCommand } from './src/commands/emailTemplate.js';
+import { createThemesCommand } from './src/commands/themes.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -39,6 +40,7 @@ program.addCommand(createTagsCommand());
 program.addCommand(createAnnouncementsCommand());
 program.addCommand(createDsrLandingCommand());
 program.addCommand(createEmailTemplateCommand());
+program.addCommand(createThemesCommand());
 program.addCommand(createOrgCommand());
 program.addCommand(createAnalyticsCommand());
 program.parseAsync(process.argv);

package/dist/src/commands/themes.d.ts

@@ -0,0 +1,17 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export declare const THEME_RETRIEVE_LIMIT = 1000;
+export interface ThemesDeps {
+    client?: AxiosInstance;
+}
+export declare function runThemesList(opts: CommonOpts & {
+    instanceId?: string;
+    withUsage?: boolean;
+    withCanvasIds?: boolean;
+}, deps?: ThemesDeps): Promise<Envelope<unknown>>;
+export declare function runThemesGet(opts: CommonOpts & {
+    id?: string;
+}, deps?: ThemesDeps): Promise<Envelope<unknown>>;
+export declare function createThemesCommand(): Command;

package/dist/src/commands/themes.js

@@ -0,0 +1,82 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { withAuthFlags } from './withAuth.js';
+const THEMES_ENDPOINT = '/core/api/protected/themes';
+// Mirror of next-core THEME_RETRIEVE_LIMIT (themes/limits.ts). The list route
+// caps at this many rows (newest-first) with no total/hasMore, so a full page
+// may be silently truncated — we warn when the count equals the cap. Keep this
+// in sync with the server constant: if the server cap changes and this does not,
+// the truncation warning stops firing.
+export const THEME_RETRIEVE_LIMIT = 1000;
+export async function runThemesList(opts, deps = {}) {
+    try {
+        const client = clientFor(opts, deps);
+        const params = {};
+        if (opts.instanceId)
+            params.instance_id = opts.instanceId;
+        // The route compares === 'true' (string); send the literal only when set.
+        if (opts.withUsage)
+            params.used_in_canvases_count = 'true';
+        if (opts.withCanvasIds)
+            params.include_canvas_ids = 'true';
+        const res = await client.get(THEMES_ENDPOINT, { params });
+        const data = res.data;
+        if (Array.isArray(data) && data.length === THEME_RETRIEVE_LIMIT) {
+            const base = `results may be truncated at the server cap of ${THEME_RETRIEVE_LIMIT}`;
+            // Only advise --instance-id when it isn't already narrowing the scope.
+            return ok(data, [opts.instanceId ? base : `${base}; narrow with --instance-id`]);
+        }
+        return ok(data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runThemesGet(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for themes get');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`${THEMES_ENDPOINT}/${encodeURIComponent(opts.id)}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+const LIST_HELP = `
+Themes carry the instance branding you reference when authoring:
+  settings     colors
+  typography   fonts
+  assets, logo branding assets
+
+Notes:
+  - Results are server-capped (newest-first); there is no --limit/--page.
+  - --instance-id narrows to themes bound to that instance and EXCLUDES
+    org-level (default) themes; omit it to see all themes in the org.`;
+export function createThemesCommand() {
+    const cmd = new Command('themes').description('read canvas/branding themes (colors, fonts, assets) for authoring');
+    withAuthFlags(cmd.command('list'))
+        .option('--instance-id <id>', 'Filter to themes bound to this instance (excludes org-level themes)')
+        .option('--with-usage', 'Include a per-theme count of canvases using it')
+        .option('--with-canvas-ids', 'Include the canvas ids using each theme')
+        .addHelpText('after', LIST_HELP)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runThemesList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('get'))
+        // --id via .option (not .requiredOption) so a missing id flows through the
+        // in-run guard in runThemesGet and returns a VALIDATION envelope (the agent
+        // contract: envelope + exit code on stdout), rather than commander's plain
+        // parse error + exit 1.
+        .option('--id <id>', 'Theme ID')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runThemesGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",