@pitcher/cli-scripts 2.7.0 → 2.8.0

package/README.md

@@ -414,3 +414,25 @@ p metadata-template upsert --instance-id 01... --sections-file ./schema.json --a
 ```
 
 `upsert` merges the incoming sections by section `label` — a section whose label matches an existing one is replaced, other sections are preserved. It **cannot remove** a section or field (that's a UI operation). `options` for `select`/`multi-select` fields are `{ label, value }` objects (bare strings are rejected). `upsert` requires an instance- or org-admin key; a non-admin member key is rejected (400 → `VALIDATION`).
+
+## To run the `dsr` command:
+
+Create and share a Digital Sales Room (a canvas share link) and get a link back in one command. Three subcommands: `create` (build + share, with optional landing-page binding), `bind-landing` (bind/unbind a landing template on an existing share), and `scaffold` (print a starter `{source,security,landing}` spec for `--config-file`).
+
+```bash
+# simplest — email-gated link (server default auth_strategy=any_email)
+p dsr create --instance-id 01... --canvas-id 01... --api-key myapikey
+# open link
+p dsr create --instance-id 01... --canvas-id 01... --auth-strategy none
+# ShareBox + security + branded landing
+p dsr create --instance-id 01... --sharebox-file-ids 01A,01B --account-id 01... \
+  --auth-strategy specified_domains --allowed-domains acme.com --valid-until 2026-09-01T00:00:00Z \
+  --landing-template-id 01... --landing-context '{"rep":"Sam"}'
+# bind/unbind a landing template on an existing share
+p dsr bind-landing --id 01... --landing-template-id 01...
+p dsr bind-landing --id 01... --landing-template-id none
+# scaffold a spec for --config-file
+p dsr scaffold --out share.json
+```
+
+Creating needs a share-capable key; **binding a landing page currently needs an editor key** (PIT-7525 will open it to reps for their own DSRs) — a denied bind returns the link with a warning. Discover landing template IDs via `p dsr-landing list`.

package/dist/index.js

@@ -24,6 +24,7 @@ import { createMembershipsCommand } from './src/commands/memberships.js';
 import { createGroupsCommand } from './src/commands/groups.js';
 import { createRolesCommand } from './src/commands/roles.js';
 import { createMetadataTemplateCommand } from './src/commands/metadataTemplate.js';
+import { createDsrCommand } from './src/commands/dsr.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -53,6 +54,7 @@ program.addCommand(createMembershipsCommand());
 program.addCommand(createGroupsCommand());
 program.addCommand(createRolesCommand());
 program.addCommand(createMetadataTemplateCommand());
+program.addCommand(createDsrCommand());
 program.addCommand(createOrgCommand());
 program.addCommand(createAnalyticsCommand());
 program.parseAsync(process.argv);

package/dist/src/commands/analytics.js

@@ -35,7 +35,7 @@ export function createAnalyticsCommand() {
         emitEnvelope(await runAnalyticsOrg({ ...options, quiet: globals.quiet }), globals);
     });
     withAuthFlags(cmd.command('instance'))
-        .requiredOption('--instance-id <id>', 'Instance ID')
+        .option('--instance-id <id>', 'Instance ID (required)')
         .description('instance rollups (instance-admin or org-admin key required)')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();

package/dist/src/commands/canvases.js

@@ -50,7 +50,7 @@ export async function runCanvasesGet(opts, deps = {}) {
 export function createCanvasesCommand() {
     const cmd = new Command('canvases').description('read Pitcher canvases (presentations, sections, blocks)');
     withAuthFlags(cmd.command('list'))
-        .requiredOption('--instance-id <id>', 'Instance ID')
+        .option('--instance-id <id>', 'Instance ID (required)')
         .option('--is-template', 'Only templates')
         .option('--is-section', 'Only sections')
         .option('--is-block', 'Only blocks (blocks are hidden unless this flag is set)')

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

@@ -0,0 +1,36 @@
+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 DsrDeps {
+    client?: AxiosInstance;
+}
+export declare function runDsrScaffold(opts: CommonOpts & {
+    out?: string;
+}, _deps?: DsrDeps): Promise<Envelope<unknown>>;
+export declare function runDsrBindLanding(opts: CommonOpts & {
+    id?: string;
+    landingTemplateId?: string;
+    landingContext?: string;
+    instanceId?: string;
+}, deps?: DsrDeps): Promise<Envelope<unknown>>;
+export interface DsrCreateOpts extends CommonOpts {
+    instanceId?: string;
+    canvasId?: string;
+    shareboxFileIds?: string[];
+    canvasName?: string;
+    accountId?: string;
+    templateId?: string;
+    authStrategy?: string;
+    allowedEmails?: string[];
+    allowedDomains?: string[];
+    validUntil?: string;
+    allowForward?: boolean;
+    allowDownload?: boolean;
+    tags?: string[];
+    landingTemplateId?: string;
+    landingContext?: string;
+    configFile?: string;
+}
+export declare function runDsrCreate(opts: DsrCreateOpts, deps?: DsrDeps): Promise<Envelope<unknown>>;
+export declare function createDsrCommand(): Command;

package/dist/src/commands/dsr.js

@@ -0,0 +1,229 @@
+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 { parseJsonObject, parseTags, isPlainObject } from '../schema/content.js';
+import { readTextFile } from '../core/readInput.js';
+import { withAuthFlags } from './withAuth.js';
+import { emitScaffold, DSR_SHARE_SCAFFOLD_JSON } from './scaffolds.js';
+const ENDPOINT = '/core/api/protected/shared-links';
+export async function runDsrScaffold(opts, _deps = {}) {
+    return emitScaffold(DSR_SHARE_SCAFFOLD_JSON, opts.out);
+}
+// resolve --landing-template-id text into the PUT value: undefined = not given; '' / 'none' = unbind (null); else the id
+function resolveTemplateId(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === '' || raw.toLowerCase() === 'none')
+        return null;
+    return raw;
+}
+async function bindLandingRequest(client, id, body, instanceId) {
+    const url = `${ENDPOINT}/${encodeURIComponent(id)}/landing-page`;
+    const res = await client.put(url, body, instanceId ? { params: { instance_id: instanceId } } : undefined);
+    return res.data;
+}
+export async function runDsrBindLanding(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for dsr bind-landing');
+        const templateId = resolveTemplateId(opts.landingTemplateId);
+        if (templateId === undefined)
+            throw createCliError('VALIDATION', '--landing-template-id is required (use "none" to unbind)');
+        const body = { landing_page_template_id: templateId };
+        if (opts.landingContext !== undefined)
+            body.landing_page_context = parseJsonObject(opts.landingContext, 'landing-context');
+        const client = clientFor(opts, deps);
+        const data = await bindLandingRequest(client, opts.id, body, opts.instanceId);
+        return ok(data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+const AUTH_STRATEGIES = [
+    'none', 'any_email', 'specified_emails', 'specified_domains', 'verified_emails', 'verified_domains',
+];
+const SPEC_FLAG_KEYS = [
+    'canvasId', 'shareboxFileIds', 'canvasName', 'accountId', 'templateId', 'authStrategy', 'allowedEmails',
+    'allowedDomains', 'validUntil', 'allowForward', 'allowDownload', 'tags', 'landingTemplateId', 'landingContext',
+];
+// config-file blocks must be JSON objects — a bare cast would silently spread a string/array into the request body
+function requirePlainObjectField(v, field) {
+    if (v === undefined)
+        return {};
+    if (!isPlainObject(v))
+        throw createCliError('VALIDATION', `config "${field}" must be a JSON object`);
+    return v;
+}
+function assembleSpec(opts) {
+    if (opts.configFile !== undefined) {
+        if (SPEC_FLAG_KEYS.some((k) => opts[k] !== undefined))
+            throw createCliError('VALIDATION', 'pass individual flags or --config-file, not both');
+        const cfg = parseJsonObject(readTextFile(opts.configFile), 'config');
+        const source = requirePlainObjectField(cfg.source, 'source');
+        const security = requirePlainObjectField(cfg.security, 'security');
+        // JSON null is a valid "no landing" opt-out, same as omitting the block
+        const landing = cfg.landing == null ? null : requirePlainObjectField(cfg.landing, 'landing');
+        const body = { ...source, ...security };
+        if (opts.instanceId !== undefined)
+            body.instance_id = opts.instanceId;
+        return { body, landing };
+    }
+    const body = {};
+    if (opts.instanceId !== undefined)
+        body.instance_id = opts.instanceId;
+    if (opts.canvasId !== undefined)
+        body.canvas_id = opts.canvasId;
+    if (opts.shareboxFileIds !== undefined)
+        body.sharebox_items = opts.shareboxFileIds.map((file_id) => ({ file_id }));
+    if (opts.canvasName !== undefined)
+        body.canvas_name = opts.canvasName;
+    if (opts.accountId !== undefined)
+        body.account_id = opts.accountId;
+    if (opts.templateId !== undefined)
+        body.template_id = opts.templateId;
+    if (opts.authStrategy !== undefined)
+        body.auth_strategy = opts.authStrategy;
+    if (opts.allowedEmails !== undefined)
+        body.allowed_emails = opts.allowedEmails;
+    if (opts.allowedDomains !== undefined)
+        body.allowed_domains = opts.allowedDomains;
+    if (opts.validUntil !== undefined)
+        body.valid_until = opts.validUntil;
+    if (opts.allowForward !== undefined)
+        body.allow_forward = opts.allowForward;
+    if (opts.allowDownload !== undefined)
+        body.allow_download = opts.allowDownload;
+    if (opts.tags !== undefined)
+        body.tags = opts.tags;
+    return { body, landing: null };
+}
+function assertCreateBody(body, instanceId) {
+    const hasCanvas = body.canvas_id !== undefined && body.canvas_id !== '';
+    const items = body.sharebox_items;
+    const hasSharebox = Array.isArray(items) && items.length > 0;
+    if (hasCanvas === hasSharebox)
+        throw createCliError('VALIDATION', 'pass exactly one source: --canvas-id or --sharebox-file-ids');
+    if (hasSharebox && !instanceId && body.instance_id === undefined)
+        throw createCliError('VALIDATION', '--instance-id is required for --sharebox-file-ids');
+    const strat = body.auth_strategy;
+    if (strat !== undefined) {
+        if (!AUTH_STRATEGIES.includes(strat))
+            throw createCliError('VALIDATION', `--auth-strategy must be one of: ${AUTH_STRATEGIES.join(', ')}`);
+        const emails = body.allowed_emails;
+        const domains = body.allowed_domains;
+        if ((strat === 'specified_emails' || strat === 'verified_emails') && !(emails && emails.length))
+            throw createCliError('VALIDATION', `--allowed-emails is required for --auth-strategy ${strat}`);
+        if ((strat === 'specified_domains' || strat === 'verified_domains') && !(domains && domains.length))
+            throw createCliError('VALIDATION', `--allowed-domains is required for --auth-strategy ${strat}`);
+    }
+}
+// binding a landing page on create needs a real template id — unlike bind-landing, there is nothing to unbind on a
+// brand-new share, so 'none'/''/null/missing (and a non-string config value) are all rejected as VALIDATION
+function requireCreateTemplateId(tid) {
+    const resolved = typeof tid === 'string' ? resolveTemplateId(tid) : tid;
+    if (typeof resolved !== 'string')
+        throw createCliError('VALIDATION', 'a landing template id is required to bind a landing page on create (use `dsr bind-landing` to unbind an existing share)');
+    return resolved;
+}
+// derive the landing PUT body from flags or from the config-file landing block; null if none requested
+function resolveLandingBody(opts, cfgLanding) {
+    if (opts.configFile !== undefined) {
+        if (!cfgLanding)
+            return null;
+        const tid = cfgLanding.landing_page_template_id;
+        const ctx = cfgLanding.landing_page_context;
+        // a blank/null template id with no (or empty) context = the untouched `dsr scaffold` default → no landing bind
+        const templateBlank = tid === undefined || tid === null || tid === '' || (typeof tid === 'string' && tid.toLowerCase() === 'none');
+        const contextEmpty = ctx === undefined || (isPlainObject(ctx) && Object.keys(ctx).length === 0);
+        if (templateBlank && contextEmpty)
+            return null;
+        const b = { landing_page_template_id: requireCreateTemplateId(tid) };
+        if (ctx !== undefined) {
+            if (!isPlainObject(ctx))
+                throw createCliError('VALIDATION', 'landing.landing_page_context must be a JSON object');
+            if (Object.keys(ctx).length > 0)
+                b.landing_page_context = ctx;
+        }
+        return b;
+    }
+    if (opts.landingTemplateId === undefined && opts.landingContext === undefined)
+        return null;
+    const b = { landing_page_template_id: requireCreateTemplateId(opts.landingTemplateId) };
+    if (opts.landingContext !== undefined)
+        b.landing_page_context = parseJsonObject(opts.landingContext, 'landing-context');
+    return b;
+}
+export async function runDsrCreate(opts, deps = {}) {
+    try {
+        const { body, landing: cfgLanding } = assembleSpec(opts);
+        assertCreateBody(body, opts.instanceId);
+        const landingBody = resolveLandingBody(opts, cfgLanding); // parse/validate context BEFORE the network call
+        // bind against the same instance the share was created in — a config-file source.instance_id must reach the PUT too
+        const effectiveInstanceId = body.instance_id ?? opts.instanceId;
+        const client = clientFor(opts, deps);
+        const res = await client.post(ENDPOINT, body);
+        const share = res.data;
+        if (!landingBody)
+            return ok(share);
+        const shareId = share?.id;
+        if (!shareId)
+            return ok({ ...share, landing: null }, ['landing not attached: no share id in create response']);
+        try {
+            const landing = await bindLandingRequest(client, shareId, landingBody, effectiveInstanceId);
+            return ok({ ...share, landing });
+        }
+        catch (e) {
+            return ok({ ...share, landing: null }, [`landing not attached: ${toCliError(e).message}`]);
+        }
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createDsrCommand() {
+    const cmd = new Command('dsr').description('create and share a Digital Sales Room (a canvas share link)');
+    withAuthFlags(cmd.command('scaffold'))
+        .description('print a {source,security,landing} share spec to fill in and pass to `dsr create --config-file`')
+        .option('--out <path>', 'Write the scaffold to a file instead of stdout')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrScaffold({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('create'))
+        .description('create + share a DSR (canvas share link) and return the link')
+        .option('--instance-id <id>', 'Instance ID (required for --sharebox-file-ids)')
+        .option('--canvas-id <id>', 'Existing canvas to share (one source required)')
+        .option('--sharebox-file-ids <csv>', 'Build a canvas from these file IDs (one source required)', parseTags)
+        .option('--canvas-name <name>', 'Name for the ShareBox-built canvas')
+        .option('--account-id <id>', 'Account for the ShareBox-built canvas')
+        .option('--template-id <id>', 'Canvas template for the ShareBox-built canvas')
+        .option('--auth-strategy <v>', 'none|any_email|specified_emails|specified_domains|verified_emails|verified_domains')
+        .option('--allowed-emails <csv>', 'Allowed emails (required for specified/verified_emails)', parseTags)
+        .option('--allowed-domains <csv>', 'Allowed domains (required for specified/verified_domains)', parseTags)
+        .option('--valid-until <iso>', 'Expiry (ISO datetime)')
+        .option('--allow-forward', 'Allow recipients to forward')
+        .option('--no-allow-forward', 'Disallow forwarding')
+        .option('--allow-download', 'Allow download')
+        .option('--tags <csv>', 'Tags', parseTags)
+        .option('--landing-template-id <id>', 'Landing template to bind (optional)')
+        .option('--landing-context <json>', 'Landing personalization merge fields (JSON object)')
+        .option('--config-file <path>', 'Full {source,security,landing} spec JSON (mutually exclusive with the flags above)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrCreate({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('bind-landing'))
+        .description("bind (or unbind with 'none') a landing-page template on an existing share")
+        .option('--id <id>', 'Shared link ID (required)')
+        .option('--landing-template-id <id>', "Landing template ID, or 'none' to unbind (required)")
+        .option('--landing-context <json>', 'Personalization merge fields (JSON object)')
+        .option('--instance-id <id>', 'Instance ID (optional)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrBindLanding({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

package/dist/src/commands/dsrLanding.js

@@ -116,8 +116,8 @@ export async function runDsrLandingScaffold(opts, _deps = {}) {
 export function createDsrLandingCommand() {
     const cmd = new Command('dsr-landing').description('create/list DSR (Digital Sales Room) landing-page templates, and set one as default');
     withInstanceFlag(withAuthFlags(cmd.command('create')))
-        .requiredOption('--name <name>', 'Template name')
-        .requiredOption('--html-file <path>', `Path to the landing HTML (must contain ${REQUIRED_MARKER})`)
+        .option('--name <name>', 'Template name (required)')
+        .option('--html-file <path>', `Path to the landing HTML (required; must contain ${REQUIRED_MARKER})`)
         .option('--css-file <path>', 'Path to a CSS file for the template')
         .option('--merge-schema <json>', 'Merge schema array as inline JSON')
         .option('--language <lang>', 'Language code (max 10 chars)')
@@ -129,7 +129,7 @@ export function createDsrLandingCommand() {
         emitEnvelope(await runDsrLandingCreate({ ...options, quiet: globals.quiet }), globals);
     });
     withInstanceFlag(withAuthFlags(cmd.command('set-default')))
-        .requiredOption('--id <id>', 'Template ID')
+        .option('--id <id>', 'Template ID (required)')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runDsrLandingSetDefault({ ...options, quiet: globals.quiet }), globals);

package/dist/src/commands/emailTemplate.js

@@ -85,7 +85,7 @@ export async function runEmailTemplateScaffold(opts, _deps = {}) {
 export function createEmailTemplateCommand() {
     const cmd = new Command('email-template').description('create/list/get HTML email templates for the emails app');
     withInstanceFlag(withAuthFlags(cmd.command('create')))
-        .requiredOption('--name <name>', 'Template name')
+        .option('--name <name>', 'Template name (required)')
         .option('--body-file <path>', 'Path to an HTML file (inline CSS) used as the template body')
         .option('--subject <text>', 'Email subject (supports {{tokens}})')
         .option('--tags <json>', 'Tags object as inline JSON')
@@ -107,7 +107,7 @@ export function createEmailTemplateCommand() {
         emitEnvelope(await runEmailTemplateList({ ...options, quiet: globals.quiet }), globals);
     });
     withInstanceFlag(withAuthFlags(cmd.command('get')))
-        .requiredOption('--id <id>', 'Template ID')
+        .option('--id <id>', 'Template ID (required)')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runEmailTemplateGet({ ...options, quiet: globals.quiet }), globals);

package/dist/src/commands/files.js

@@ -119,7 +119,7 @@ export async function runFilesUpdate(opts, deps = {}) {
 export function createFilesCommand() {
     const cmd = new Command('files').description('manage Pitcher content files');
     withAuthFlags(cmd.command('list'))
-        .requiredOption('--instance-id <id>', 'Instance ID')
+        .option('--instance-id <id>', 'Instance ID (required)')
         .option('--id-in <ids>', 'Comma-separated file IDs')
         .option('--tags <tags>', 'Comma-separated tags (filters via tags__in)')
         .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
@@ -135,7 +135,7 @@ export function createFilesCommand() {
         emitEnvelope(await runFilesGet({ ...options, id, quiet: globals.quiet }), globals);
     });
     withAuthFlags(cmd.command('create'))
-        .requiredOption('--instance-id <id>', 'Instance ID')
+        .option('--instance-id <id>', 'Instance ID (required)')
         .option('--name <name>', 'File name')
         .option('--folder-id <id>', 'Destination folder')
         .option('--file <path>', 'Local file to upload')

package/dist/src/commands/folders.js

@@ -83,7 +83,7 @@ export async function runFoldersUpdate(opts, deps = {}) {
 export function createFoldersCommand() {
     const cmd = new Command('folders').description('manage Pitcher content folders');
     withAuthFlags(cmd.command('list'))
-        .requiredOption('--instance-id <id>', 'Instance ID')
+        .option('--instance-id <id>', 'Instance ID (required)')
         .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) => {
@@ -99,8 +99,8 @@ export function createFoldersCommand() {
         emitEnvelope(await runFoldersGet({ ...options, id, quiet: globals.quiet }), globals);
     });
     withAuthFlags(cmd.command('create'))
-        .requiredOption('--name <name>', 'Folder name')
-        .requiredOption('--parent-folder-id <id>', 'Parent folder ID')
+        .option('--name <name>', 'Folder name (required)')
+        .option('--parent-folder-id <id>', 'Parent folder ID (required)')
         .option('--access-type <type>', 'public | restricted | personal')
         .option('--rules <json>', 'Smart-folder rules JSON array')
         .action(async (options, command) => {

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

@@ -18,3 +18,4 @@ export declare const EMAIL_SCAFFOLD_HTML = "<!doctype html>\n<html lang=\"en\">\
 export declare const DSR_SCAFFOLD_HTML = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <title>Sample DSR Landing Page</title>\n  </head>\n  <body style=\"margin:0;padding:0;background-color:#f4f4f4;font-family:Arial,Helvetica,sans-serif;color:#212121;\">\n    <table role=\"presentation\" width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" style=\"padding:32px 0;\">\n      <tr>\n        <td align=\"center\">\n          <table role=\"presentation\" width=\"640\" cellpadding=\"0\" cellspacing=\"0\" style=\"background-color:#ffffff;border-radius:8px;overflow:hidden;\">\n            <tr>\n              <td style=\"background-color:var(--p-primary, #29335C);padding:28px;text-align:center;\">\n                <!-- token: organization.name -> the sharing org's display name -->\n                <span style=\"color:#ffffff;font-size:20px;font-weight:bold;\">{{organization.name}}</span>\n              </td>\n            </tr>\n            <tr>\n              <td style=\"padding:32px;\">\n                <!-- token: recipient.firstName -> the recipient's first name -->\n                <!-- token: customer.name -> the recipient's company name -->\n                <h1 style=\"margin:0 0 8px 0;font-size:22px;\">Welcome, {{recipient.firstName}}</h1>\n                <p style=\"margin:0 0 24px 0;color:#757575;font-size:14px;\">Prepared for {{customer.name}}</p>\n\n                <!--\n                  Editable region: admins can edit this block's text in the DSR\n                  landing editor without touching markup. data-field-char-limit\n                  enforces a max length in that editor.\n                -->\n                <div\n                  data-field-id=\"welcome-message\"\n                  data-field-editable=\"true\"\n                  data-field-char-limit=\"120\"\n                  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;\"\n                >\n                  Thanks for stopping by. Everything you need for this conversation is right here.\n                </div>\n\n                <!-- token: rep.name -> the sharing rep's display name -->\n                <p style=\"margin:0 0 24px 0;font-size:14px;color:#757575;\">Shared by {{rep.name}}</p>\n\n                <!--\n                  Required marker: the platform injects the email-gate form\n                  into this div at render time. It MUST be present verbatim\n                  (a literal data-pitcher-email-gate attribute) or the\n                  server rejects the template on create/update.\n                -->\n                <div data-pitcher-email-gate></div>\n              </td>\n            </tr>\n            <tr>\n              <td style=\"padding:16px 32px;border-top:1px solid #e0e2ed;text-align:center;color:#757575;font-size:12px;\">\n                <!-- token: sharedLink.valid_until -> when this share expires, if the share sets an expiry -->\n                This link is valid until {{sharedLink.valid_until}}.\n              </td>\n            </tr>\n          </table>\n        </td>\n      </tr>\n    </table>\n  </body>\n</html>\n";
 export declare const ANNOUNCEMENT_SCAFFOLD_JSON: string;
 export declare const METADATA_TEMPLATE_SCAFFOLD_JSON: string;
+export declare const DSR_SHARE_SCAFFOLD_JSON: string;

package/dist/src/commands/scaffolds.js

@@ -269,3 +269,27 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
     },
 ];
 export const METADATA_TEMPLATE_SCAFFOLD_JSON = JSON.stringify(METADATA_TEMPLATE_SCAFFOLD_DATA, null, 2);
+const DSR_SHARE_SCAFFOLD_DATA = {
+    source: {
+        // provide ONE of the following:
+        canvas_id: '01EXAMPLECANVASID000000000',
+        // sharebox_items: [{ file_id: '01EXAMPLEFILEID0000000000', page_index: 0 }],
+        // canvas_name: 'Acme QBR',
+        // account_id: '01EXAMPLEACCOUNTID00000000',
+        // template_id: '01EXAMPLECANVASTEMPLATE0000',
+    },
+    security: {
+        auth_strategy: 'any_email', // none|any_email|specified_emails|specified_domains|verified_emails|verified_domains
+        allowed_emails: [],
+        allowed_domains: [],
+        valid_until: null,
+        allow_forward: true,
+        allow_download: false,
+        tags: [],
+    },
+    landing: {
+        landing_page_template_id: null, // discover ids via `p dsr-landing list --instance-id <id>`
+        landing_page_context: {},
+    },
+};
+export const DSR_SHARE_SCAFFOLD_JSON = JSON.stringify(DSR_SHARE_SCAFFOLD_DATA, null, 2);

package/dist/src/commands/search.js

@@ -25,8 +25,8 @@ export async function runSearch(opts, deps = {}) {
 }
 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('--instance-id <id>', 'Instance ID (required)')
+        .option('--query <text>', 'Search query (required)')
         .option('--include-expired', 'Include expired content')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();

package/dist/src/commands/tags.js

@@ -37,8 +37,8 @@ export async function runTagsList(opts, deps = {}) {
 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('--instance-id <id>', 'Instance ID (required)')
+        .option('--search <text>', 'Search term (required; at least 3 characters)')
         .option('--type <type>', 'files | canvases')
         .option('--canvas-type <type>', 'Canvas type filter')
         .option('--include-hidden', 'Include hidden tags')

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

@@ -1,3 +1,8 @@
 import { Command } from 'commander';
-/** Attach the shared --instance-id flag to a (sub)command. */
+/**
+ * Attach the shared --instance-id flag to a (sub)command.
+ * Uses .option (not .requiredOption) so a missing flag flows through the
+ * command's in-run VALIDATION guard and yields the JSON envelope (exit 3),
+ * instead of commander aborting with plain text on stderr (exit 1).
+ */
 export declare function withInstanceFlag(c: Command): Command;

package/dist/src/commands/withInstance.js

@@ -1,4 +1,9 @@
-/** Attach the shared --instance-id flag to a (sub)command. */
+/**
+ * Attach the shared --instance-id flag to a (sub)command.
+ * Uses .option (not .requiredOption) so a missing flag flows through the
+ * command's in-run VALIDATION guard and yields the JSON envelope (exit 3),
+ * instead of commander aborting with plain text on stderr (exit 1).
+ */
 export function withInstanceFlag(c) {
-    return c.requiredOption('--instance-id <id>', 'Instance ID');
+    return c.option('--instance-id <id>', 'Instance ID (required)');
 }

package/package.json

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