@pitcher/cli-scripts 2.3.0 → 2.4.0

package/dist/src/commands/scaffolds.js

@@ -0,0 +1,176 @@
+import fs from 'fs';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+// Annotated starter-content constants for the `scaffold` subcommands. Each
+// constant is a working example, never a blank template — see design §5.
+// Task 1 adds EMAIL_SCAFFOLD_HTML; Tasks 2/3 add DSR + announcement consts.
+export function emitScaffold(content, out) {
+    if (!out)
+        return ok(content);
+    try {
+        fs.writeFileSync(out, content);
+        return ok({ path: out });
+    }
+    catch {
+        // A bad --out path is user input, so classify it VALIDATION (not UNKNOWN).
+        return fail(createCliError('VALIDATION', `could not write file: ${out}`));
+    }
+}
+/**
+ * Starter HTML email (inline CSS, table layout) for `p email-template scaffold`.
+ * Contains the common {{recipient.*}} tokens in context, each documented with
+ * an HTML comment. The emails app resolves tokens at send time; unknown
+ * tokens render blank (no server-side validation).
+ */
+export const EMAIL_SCAFFOLD_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Sample Email Template</title>
+  </head>
+  <body style="margin:0;padding:0;background-color:#f4f4f4;font-family:Arial,Helvetica,sans-serif;">
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background-color:#f4f4f4;padding:24px 0;">
+      <tr>
+        <td align="center">
+          <table role="presentation" width="600" cellpadding="0" cellspacing="0" style="background-color:#ffffff;border-radius:8px;overflow:hidden;">
+            <tr>
+              <td style="background-color:#29335C;padding:24px;text-align:center;">
+                <span style="color:#ffffff;font-size:20px;font-weight:bold;">Pitcher</span>
+              </td>
+            </tr>
+            <tr>
+              <td style="padding:32px 24px;color:#212121;font-size:15px;line-height:1.5;">
+                <!-- token: recipient.firstName -> the recipient's first name -->
+                <!-- token: recipient.lastName -> the recipient's last name -->
+                <p style="margin:0 0 16px 0;">Dear {{recipient.firstName}} {{recipient.lastName}},</p>
+                <p style="margin:0 0 16px 0;">
+                  Thanks for your time today. As promised, here is the material we discussed.
+                  Reach out any time if you have questions.
+                </p>
+                <table role="presentation" cellpadding="0" cellspacing="0" style="margin:24px 0;">
+                  <tr>
+                    <td style="background-color:#29335C;border-radius:4px;">
+                      <a href="https://example.com" style="display:inline-block;padding:12px 24px;color:#ffffff;text-decoration:none;font-size:14px;font-weight:bold;">
+                        View content
+                      </a>
+                    </td>
+                  </tr>
+                </table>
+                <!-- token: recipient.email -> the recipient's email address, e.g. for a footer mailto: link -->
+                <p style="margin:0;color:#757575;font-size:12px;">
+                  Sent to {{recipient.email}}. If you'd rather not receive these, let your rep know.
+                </p>
+              </td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
+`;
+/**
+ * Starter DSR (Digital Sales Room) landing page HTML for `p dsr-landing scaffold`.
+ * Contains the required `data-pitcher-email-gate` marker, an editable-region
+ * example via `data-field-*` attributes, a themeable accent color via the
+ * `--p-primary` CSS variable, and the Handlebars tokens the platform resolves
+ * at render time, each documented with an HTML comment. No `<script>` or
+ * external `<link>` tags — the server strips both via DOMPurify.
+ */
+export const DSR_SCAFFOLD_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Sample DSR Landing Page</title>
+  </head>
+  <body style="margin:0;padding:0;background-color:#f4f4f4;font-family:Arial,Helvetica,sans-serif;color:#212121;">
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="padding:32px 0;">
+      <tr>
+        <td align="center">
+          <table role="presentation" width="640" cellpadding="0" cellspacing="0" style="background-color:#ffffff;border-radius:8px;overflow:hidden;">
+            <tr>
+              <td style="background-color:var(--p-primary, #29335C);padding:28px;text-align:center;">
+                <!-- token: organization.name -> the sharing org's display name -->
+                <span style="color:#ffffff;font-size:20px;font-weight:bold;">{{organization.name}}</span>
+              </td>
+            </tr>
+            <tr>
+              <td style="padding:32px;">
+                <!-- token: recipient.firstName -> the recipient's first name -->
+                <!-- token: customer.name -> the recipient's company name -->
+                <h1 style="margin:0 0 8px 0;font-size:22px;">Welcome, {{recipient.firstName}}</h1>
+                <p style="margin:0 0 24px 0;color:#757575;font-size:14px;">Prepared for {{customer.name}}</p>
+
+                <!--
+                  Editable region: admins can edit this block's text in the DSR
+                  landing editor without touching markup. data-field-char-limit
+                  enforces a max length in that editor.
+                -->
+                <div
+                  data-field-id="welcome-message"
+                  data-field-editable="true"
+                  data-field-char-limit="120"
+                  style="padding:16px;margin:0 0 24px 0;border-left:3px solid var(--p-primary, #29335C);background-color:#f7f8fb;font-size:15px;line-height:1.5;"
+                >
+                  Thanks for stopping by. Everything you need for this conversation is right here.
+                </div>
+
+                <!-- token: rep.name -> the sharing rep's display name -->
+                <p style="margin:0 0 24px 0;font-size:14px;color:#757575;">Shared by {{rep.name}}</p>
+
+                <!--
+                  Required marker: the platform injects the email-gate form
+                  into this div at render time. It MUST be present verbatim
+                  (a literal data-pitcher-email-gate attribute) or the
+                  server rejects the template on create/update.
+                -->
+                <div data-pitcher-email-gate></div>
+              </td>
+            </tr>
+            <tr>
+              <td style="padding:16px 32px;border-top:1px solid #e0e2ed;text-align:center;color:#757575;font-size:12px;">
+                <!-- token: sharedLink.valid_until -> when this share expires, if the share sets an expiry -->
+                This link is valid until {{sharedLink.valid_until}}.
+              </td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
+`;
+/**
+ * Starter announcement `data` object for `p announcements scaffold`, used by
+ * the wa-announcements app. Every field the app understands is present with
+ * a sensible default so users edit a working example rather than a blank
+ * file. JSON cannot hold comments, so the per-field legend and the
+ * naive-local-date note live in `create --help` instead (see announcements.ts).
+ *
+ * `start_at`/`expires_at` are naive local date(-time) strings compared as
+ * wall-clock time by the app, NOT ISO/UTC — see the note in `create --help`.
+ */
+const ANNOUNCEMENT_SCAFFOLD_DATA = {
+    title: 'New feature: Q3 product launch',
+    body: '<p>Check out what is new this quarter and how it helps your customers.</p>',
+    media_type: 'none',
+    media_url: '',
+    link_type: 'url',
+    link_url: '',
+    link_label: '',
+    link_file_id: '',
+    link_target_name: '',
+    priority: 'normal',
+    author_name: 'Sales Enablement Team',
+    published_at: '',
+    start_at: '',
+    expires_at: '',
+    target_groups: [],
+    display_mode: ['inline'],
+    popup_title: null,
+    popup_body: null,
+    popup_link_label: null,
+};
+export const ANNOUNCEMENT_SCAFFOLD_JSON = JSON.stringify(ANNOUNCEMENT_SCAFFOLD_DATA, null, 2);

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

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface SearchDeps {
+    client?: AxiosInstance;
+}
+export declare function runSearch(opts: CommonOpts & {
+    instanceId?: string;
+    query?: string;
+    includeExpired?: boolean;
+}, deps?: SearchDeps): Promise<Envelope<unknown>>;
+export declare function createSearchCommand(): Command;

package/dist/src/commands/search.js

@@ -0,0 +1,35 @@
+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';
+export async function runSearch(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for search');
+        if (!opts.query)
+            throw createCliError('VALIDATION', '--query is required for search');
+        const client = clientFor(opts, deps);
+        // Flat limit/offset-paginated result set; each item carries a `type`
+        // (file/canvas/user/app). Pass res.data through raw — no listPaginationEcho.
+        const params = { instance_id: opts.instanceId, query: opts.query };
+        if (opts.includeExpired)
+            params.include_expired = true;
+        const res = await client.get('/api/v1/search/', { params });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createSearchCommand() {
+    return withAuthFlags(new Command('search').description('search content across an instance (files, canvases, users, apps)'))
+        .requiredOption('--instance-id <id>', 'Instance ID')
+        .requiredOption('--query <text>', 'Search query')
+        .option('--include-expired', 'Include expired content')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runSearch({ ...options, quiet: globals.quiet }), globals);
+    });
+}

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

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface SharedLinksDeps {
+    client?: AxiosInstance;
+}
+export declare function runSharedLinksCreate(opts: CommonOpts & {
+    canvasId?: string;
+    fileId?: string;
+}, deps?: SharedLinksDeps): Promise<Envelope<unknown>>;
+export declare function runSharedLinksGet(opts: CommonOpts & {
+    canvasId?: string;
+    fileId?: string;
+}, deps?: SharedLinksDeps): Promise<Envelope<unknown>>;
+export declare function createSharedLinksCommand(): Command;

package/dist/src/commands/sharedLinks.js

@@ -0,0 +1,61 @@
+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';
+/** Enforce exactly one of --canvas-id / --file-id. Scope is derived from the target. */
+function requireOneTarget(opts) {
+    if (opts.canvasId && opts.fileId)
+        throw createCliError('VALIDATION', 'pass exactly one of --canvas-id or --file-id');
+    if (opts.canvasId)
+        return 'canvas';
+    if (opts.fileId)
+        return 'file';
+    throw createCliError('VALIDATION', 'pass exactly one of --canvas-id or --file-id');
+}
+export async function runSharedLinksCreate(opts, deps = {}) {
+    try {
+        const target = requireOneTarget(opts);
+        const client = clientFor(opts, deps);
+        const body = target === 'canvas' ? { canvas_id: opts.canvasId } : { file_id: opts.fileId };
+        const res = await client.post('/api/v1/shared-links/', body);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runSharedLinksGet(opts, deps = {}) {
+    try {
+        const target = requireOneTarget(opts);
+        const client = clientFor(opts, deps);
+        // encodeURIComponent so an id containing `/` or `..` can't retarget the request path
+        const path = target === 'canvas'
+            ? `/api/v1/shared-links/canvas/${encodeURIComponent(opts.canvasId)}`
+            : `/api/v1/shared-links/file/${encodeURIComponent(opts.fileId)}`;
+        const res = await client.get(path);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createSharedLinksCommand() {
+    const cmd = new Command('shared-links').description('create and read share links for canvases and files');
+    withAuthFlags(cmd.command('create'))
+        .option('--canvas-id <id>', 'Canvas to share')
+        .option('--file-id <id>', 'File to share')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runSharedLinksCreate({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('get'))
+        .option('--canvas-id <id>', 'Canvas whose link to fetch')
+        .option('--file-id <id>', 'File whose link to fetch')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runSharedLinksGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,20 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface TagsDeps {
+    client?: AxiosInstance;
+}
+export declare function runTagsList(opts: CommonOpts & {
+    instanceId?: string;
+    search?: string;
+    type?: string;
+    canvasType?: string;
+    includeHidden?: boolean;
+    page?: number;
+    pageSize?: number;
+}, deps?: TagsDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function createTagsCommand(): Command;

package/dist/src/commands/tags.js

@@ -0,0 +1,52 @@
+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 { listPageParams, listPaginationEcho } from '../core/pagination.js';
+import { assertIntFlags } from '../schema/content.js';
+import { withAuthFlags } from './withAuth.js';
+export async function runTagsList(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for tags list');
+        if (!opts.search)
+            throw createCliError('VALIDATION', '--search is required for tags list');
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        // Server enforces search min_length=3; we pass it through and let the
+        // server 400 rather than re-implementing field validation client-side.
+        const params = {
+            instance_id: opts.instanceId,
+            search: opts.search,
+            ...listPageParams(opts),
+        };
+        if (opts.type)
+            params.type = opts.type;
+        if (opts.canvasType)
+            params.canvas_type = opts.canvasType;
+        if (opts.includeHidden)
+            params.include_hidden = true;
+        const res = await client.get('/api/v1/tags/', { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createTagsCommand() {
+    const cmd = new Command('tags').description('list tags in an instance (search term of >=3 chars required)');
+    withAuthFlags(cmd.command('list'))
+        .requiredOption('--instance-id <id>', 'Instance ID')
+        .requiredOption('--search <text>', 'Search term (server requires at least 3 characters)')
+        .option('--type <type>', 'files | canvases')
+        .option('--canvas-type <type>', 'Canvas type filter')
+        .option('--include-hidden', 'Include hidden tags')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--page-size <n>', 'Page size (max 500)', (v) => parseInt(v, 10))
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runTagsList({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+/** Attach the shared auth flags (--api-key/--org/--url) to a (sub)command. */
+export declare function withAuthFlags(c: Command): Command;

package/dist/src/commands/withAuth.js

@@ -0,0 +1,7 @@
+/** Attach the shared auth flags (--api-key/--org/--url) to a (sub)command. */
+export function withAuthFlags(c) {
+    return c
+        .option('--api-key <apiKey>', 'API Key for authentication')
+        .option('--org <organization>', 'Organization subdomain', 'dev')
+        .option('--url <url>', 'Explicit base URL override');
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+/** Attach the shared --instance-id flag to a (sub)command. */
+export declare function withInstanceFlag(c: Command): Command;

package/dist/src/commands/withInstance.js

@@ -0,0 +1,4 @@
+/** Attach the shared --instance-id flag to a (sub)command. */
+export function withInstanceFlag(c) {
+    return c.requiredOption('--instance-id <id>', 'Instance ID');
+}

package/dist/src/core/pagination.d.ts

@@ -5,6 +5,17 @@ export interface PageOpts {
 }
 /** Page query params to merge into a list request (clamped so sent === echoed). */
 export declare function listPageParams(opts: PageOpts): Record<string, number>;
+export interface LimitOffsetOpts {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Limit/offset query params to merge into a list request. Some next-core routes
+ * (email-template, announcements) paginate with limit/offset rather than the
+ * Django page/page_size scheme, so this lives beside `listPageParams` and stays
+ * the single place those two flags are serialized.
+ */
+export declare function listLimitOffsetParams(opts: LimitOffsetOpts): Record<string, number>;
 /**
  * Pagination block echoed in the envelope. `count`/`next`/`previous` are
  * server-truth. `page_size` is echoed ONLY when the caller set it (the clamped

package/dist/src/core/pagination.js

@@ -14,6 +14,20 @@ export function listPageParams(opts) {
         params.page_size = pageSize;
     return params;
 }
+/**
+ * Limit/offset query params to merge into a list request. Some next-core routes
+ * (email-template, announcements) paginate with limit/offset rather than the
+ * Django page/page_size scheme, so this lives beside `listPageParams` and stays
+ * the single place those two flags are serialized.
+ */
+export function listLimitOffsetParams(opts) {
+    const params = {};
+    if (opts.limit !== undefined)
+        params.limit = opts.limit;
+    if (opts.offset !== undefined)
+        params.offset = opts.offset;
+    return params;
+}
 /**
  * Pagination block echoed in the envelope. `count`/`next`/`previous` are
  * server-truth. `page_size` is echoed ONLY when the caller set it (the clamped

package/dist/src/core/readInput.d.ts

@@ -0,0 +1,2 @@
+export declare function readTextFile(filePath: string): string;
+export declare function readJsonFile(filePath: string): unknown;

package/dist/src/core/readInput.js

@@ -0,0 +1,23 @@
+import fs from 'fs';
+import { createCliError } from './errors.js';
+export function readTextFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        // Covers missing AND unreadable (permissions, directory, etc.) paths — fs
+        // throws the same way for both, so don't claim "not found" specifically.
+        throw createCliError('VALIDATION', `could not read file: ${filePath}`);
+    }
+}
+export function readJsonFile(filePath) {
+    const text = readTextFile(filePath);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Keep the message generic: the JSON.parse error echoes a snippet of the
+        // file, which may contain customer PII.
+        throw createCliError('VALIDATION', `invalid JSON in ${filePath}`);
+    }
+}

package/dist/src/schema/content.d.ts

@@ -1,3 +1,4 @@
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
 export declare function parseJsonObject(raw: string, flagName: string): Record<string, unknown>;
 export declare function parseJsonArray(raw: string, flagName: string): unknown[];
 export declare function parseTags(raw: string): string[];
@@ -5,5 +6,7 @@ export declare function validateAccessType(v: string | undefined): string | unde
 export declare function assertIntFlags(opts: {
     page?: number;
     pageSize?: number;
+    limit?: number;
+    offset?: number;
 }): void;
 export declare function deepMerge(base: unknown, patch: Record<string, unknown>): Record<string, unknown>;

package/dist/src/schema/content.js

@@ -1,6 +1,6 @@
 import { createCliError } from '../core/errors.js';
 const ACCESS_TYPES = ['public', 'restricted', 'personal'];
-function isPlainObject(v) {
+export function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 function parseJson(raw, flagName) {
@@ -24,7 +24,10 @@ export function parseJsonArray(raw, flagName) {
     return parsed;
 }
 export function parseTags(raw) {
-    return raw.split(',').map((t) => t.trim()).filter(Boolean);
+    return raw
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
 }
 export function validateAccessType(v) {
     if (v === undefined)
@@ -37,13 +40,16 @@ export function validateAccessType(v) {
 // Guards against NaN reaching the request (commander's parseInt yields NaN on
 // non-numeric input, e.g. `--page abc`).
 export function assertIntFlags(opts) {
+    // page/page-size are 1-indexed (min 1); limit/offset are counts/skips (min 0).
     const checks = [
-        ['page', opts.page],
-        ['page-size', opts.pageSize],
+        ['page', opts.page, 1],
+        ['page-size', opts.pageSize, 1],
+        ['limit', opts.limit, 0],
+        ['offset', opts.offset, 0],
     ];
-    for (const [flag, val] of checks) {
-        if (val !== undefined && (!Number.isInteger(val) || val < 1)) {
-            throw createCliError('VALIDATION', `--${flag} must be a positive integer`);
+    for (const [flag, val, min] of checks) {
+        if (val !== undefined && (!Number.isInteger(val) || val < min)) {
+            throw createCliError('VALIDATION', `--${flag} must be a${min === 0 ? ' non-negative' : ' positive'} integer`);
         }
     }
 }

package/package.json

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