@pitcher/cli-scripts 2.2.2 → 2.4.0

package/dist/src/commands/folders.js

@@ -0,0 +1,120 @@
+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 { parseJsonArray, validateAccessType, assertIntFlags } from '../schema/content.js';
+import { withAuthFlags } from './withAuth.js';
+export async function runFoldersList(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for folders list');
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { instance_id: opts.instanceId, ...listPageParams(opts) };
+        const res = await client.get('/api/v1/folders/', { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFoldersGet(opts, deps = {}) {
+    try {
+        if (opts.root && opts.id)
+            throw createCliError('VALIDATION', 'pass either a folder id or --root, not both');
+        if (!opts.root && !opts.id)
+            throw createCliError('VALIDATION', 'a folder id or --root is required');
+        const client = clientFor(opts, deps);
+        if (opts.root) {
+            if (!opts.instanceId)
+                throw createCliError('VALIDATION', '--instance-id is required with --root');
+            const res = await client.get(`/api/v1/folders/root/${opts.instanceId}`);
+            return ok(res.data);
+        }
+        const res = await client.get(`/api/v1/folders/${opts.id}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFoldersCreate(opts, deps = {}) {
+    try {
+        if (!opts.name)
+            throw createCliError('VALIDATION', '--name is required for folders create');
+        if (!opts.parentFolderId)
+            throw createCliError('VALIDATION', '--parent-folder-id is required for folders create');
+        const client = clientFor(opts, deps);
+        const body = { name: opts.name, parent_folder_id: opts.parentFolderId };
+        const accessType = validateAccessType(opts.accessType);
+        if (accessType)
+            body.access_type = accessType;
+        if (opts.rules)
+            body.rules = parseJsonArray(opts.rules, 'rules');
+        const res = await client.post('/api/v1/folders/', body);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFoldersUpdate(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', 'folder id is required');
+        const client = clientFor(opts, deps);
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        const accessType = validateAccessType(opts.accessType);
+        if (accessType)
+            body.access_type = accessType;
+        if (opts.rules)
+            body.rules = parseJsonArray(opts.rules, 'rules');
+        const res = await client.patch(`/api/v1/folders/${opts.id}`, body);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createFoldersCommand() {
+    const cmd = new Command('folders').description('manage Pitcher content folders');
+    withAuthFlags(cmd.command('list'))
+        .requiredOption('--instance-id <id>', 'Instance ID')
+        .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 runFoldersList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('get'))
+        .argument('[id]', 'Folder ID (omit and use --root for the instance root)')
+        .option('--root', 'Fetch the instance root folder')
+        .option('--instance-id <id>', 'Instance ID (required with --root)')
+        .action(async (id, options, command) => {
+        const globals = command.optsWithGlobals();
+        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('--access-type <type>', 'public | restricted | personal')
+        .option('--rules <json>', 'Smart-folder rules JSON array')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFoldersCreate({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('update'))
+        .argument('<id>', 'Folder ID')
+        .option('--name <name>', 'Folder name')
+        .option('--access-type <type>', 'public | restricted | personal')
+        .option('--rules <json>', 'Smart-folder rules JSON array (replaces existing)')
+        .action(async (id, options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFoldersUpdate({ ...options, id, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,21 @@
+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 InstancesDeps {
+    client?: AxiosInstance;
+}
+export declare function runInstancesList(opts: CommonOpts & {
+    region?: string;
+    storageRegion?: string;
+    environment?: string;
+    page?: number;
+    pageSize?: number;
+}, deps?: InstancesDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function runInstancesInfo(opts: CommonOpts & {
+    id?: string;
+}, deps?: InstancesDeps): Promise<Envelope<unknown>>;
+export declare function createInstancesCommand(): Command;

package/dist/src/commands/instances.js

@@ -0,0 +1,58 @@
+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 runInstancesList(opts, deps = {}) {
+    try {
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { ...listPageParams(opts) };
+        if (opts.region)
+            params.region = opts.region;
+        if (opts.storageRegion)
+            params.storage_region = opts.storageRegion;
+        if (opts.environment)
+            params.environment = opts.environment;
+        const res = await client.get('/api/v1/instances/', { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runInstancesInfo(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', 'instance id is required');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`/api/v1/instances/${encodeURIComponent(opts.id)}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createInstancesCommand() {
+    const cmd = new Command('instances').description('discover Pitcher instances (resolve names to instance IDs)');
+    withAuthFlags(cmd.command('list'))
+        .option('--region <r>', 'Filter by region')
+        .option('--storage-region <r>', 'Filter by storage region')
+        .option('--environment <e>', 'Filter by environment')
+        .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 runInstancesList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('info'))
+        .argument('<id>', 'Instance ID')
+        .action(async (id, options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runInstancesInfo({ ...options, id, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,9 @@
+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 OrgDeps {
+    client?: AxiosInstance;
+}
+export declare function runOrgGet(opts: CommonOpts, deps?: OrgDeps): Promise<Envelope<unknown>>;
+export declare function createOrgCommand(): Command;

package/dist/src/commands/org.js

@@ -0,0 +1,26 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { emitEnvelope } from '../core/output.js';
+import { withAuthFlags } from './withAuth.js';
+export async function runOrgGet(opts, deps = {}) {
+    try {
+        const client = clientFor(opts, deps);
+        // Returns raw settings/metadata (no server allow-list) — may include
+        // integration credentials; treat JSON output as sensitive.
+        const res = await client.get('/api/v1/organization/');
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createOrgCommand() {
+    const cmd = new Command('org').description('read the organization this API key belongs to');
+    withAuthFlags(cmd.command('get'))
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runOrgGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,19 @@
+import { type Envelope } from '../core/envelope.js';
+export declare function emitScaffold(content: string, out?: string): Envelope<unknown>;
+/**
+ * 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 declare const EMAIL_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 Email Template</title>\n  </head>\n  <body style=\"margin:0;padding:0;background-color:#f4f4f4;font-family:Arial,Helvetica,sans-serif;\">\n    <table role=\"presentation\" width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" style=\"background-color:#f4f4f4;padding:24px 0;\">\n      <tr>\n        <td align=\"center\">\n          <table role=\"presentation\" width=\"600\" cellpadding=\"0\" cellspacing=\"0\" style=\"background-color:#ffffff;border-radius:8px;overflow:hidden;\">\n            <tr>\n              <td style=\"background-color:#29335C;padding:24px;text-align:center;\">\n                <span style=\"color:#ffffff;font-size:20px;font-weight:bold;\">Pitcher</span>\n              </td>\n            </tr>\n            <tr>\n              <td style=\"padding:32px 24px;color:#212121;font-size:15px;line-height:1.5;\">\n                <!-- token: recipient.firstName -> the recipient's first name -->\n                <!-- token: recipient.lastName -> the recipient's last name -->\n                <p style=\"margin:0 0 16px 0;\">Dear {{recipient.firstName}} {{recipient.lastName}},</p>\n                <p style=\"margin:0 0 16px 0;\">\n                  Thanks for your time today. As promised, here is the material we discussed.\n                  Reach out any time if you have questions.\n                </p>\n                <table role=\"presentation\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin:24px 0;\">\n                  <tr>\n                    <td style=\"background-color:#29335C;border-radius:4px;\">\n                      <a href=\"https://example.com\" style=\"display:inline-block;padding:12px 24px;color:#ffffff;text-decoration:none;font-size:14px;font-weight:bold;\">\n                        View content\n                      </a>\n                    </td>\n                  </tr>\n                </table>\n                <!-- token: recipient.email -> the recipient's email address, e.g. for a footer mailto: link -->\n                <p style=\"margin:0;color:#757575;font-size:12px;\">\n                  Sent to {{recipient.email}}. If you'd rather not receive these, let your rep know.\n                </p>\n              </td>\n            </tr>\n          </table>\n        </td>\n      </tr>\n    </table>\n  </body>\n</html>\n";
+/**
+ * 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 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;

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;