@pitcher/cli-scripts 2.6.0 → 2.7.0

package/README.md

@@ -394,3 +394,23 @@ p roles list --scope instance --api-key myapikey
 ```
 
 `list` returns a `{ items: [...] }` object; each item's `role_key` is **prefixed** (`org:admin`, `instance:editor`). Pass the **short** name (e.g. `editor`) to `set-role`, not the prefixed key. Like `set-role`, `roles list` currently needs an **org-admin** key: while the granular-permissions rollout is off (the production default), the endpoint 403s non-org-admin callers.
+
+## To run the `metadata-template` command:
+
+Read and additively build an instance's metadata-field schema. `list` and `upsert` require `--instance-id` (`get` only needs `--id`; `scaffold` makes no request).
+
+```bash
+# Read the schema for an instance (0 or 1 template — one per instance)
+p metadata-template list --instance-id 01... --api-key myapikey
+
+# Get one template by id (ids are ULIDs)
+p metadata-template get --id 01TEMPLATEID... --api-key myapikey
+
+# Print a starter schema to fill in (optionally to a file)
+p metadata-template scaffold --out ./schema.json
+
+# Additively upsert the schema (merges by section label)
+p metadata-template upsert --instance-id 01... --sections-file ./schema.json --api-key myapikey
+```
+
+`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`).

package/dist/index.js

@@ -23,6 +23,7 @@ import { createInvitationsCommand } from './src/commands/invitations.js';
 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';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -51,6 +52,7 @@ program.addCommand(createInvitationsCommand());
 program.addCommand(createMembershipsCommand());
 program.addCommand(createGroupsCommand());
 program.addCommand(createRolesCommand());
+program.addCommand(createMetadataTemplateCommand());
 program.addCommand(createOrgCommand());
 program.addCommand(createAnalyticsCommand());
 program.parseAsync(process.argv);

package/dist/src/commands/groups.js

@@ -67,14 +67,15 @@ export async function runGroupsAddUser(opts, deps = {}) {
 }
 export async function runGroupsListUsers(opts, deps = {}) {
     try {
+        if (!opts.groupId)
+            throw createCliError('VALIDATION', '--group-id is required for groups list-users');
         assertIntFlags(opts);
         const client = clientFor(opts, deps);
         const params = { ...listPageParams(opts) };
         // The list filterset is content_distribution_group_id (NOT the bare relation
         // name) — an unknown param is silently ignored by DjangoFilterBackend and the
         // endpoint returns every visible membership in the org.
-        if (opts.groupId)
-            params.content_distribution_group_id = opts.groupId;
+        params.content_distribution_group_id = opts.groupId;
         const res = await client.get(GROUP_MEMBERS, { params });
         return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
     }
@@ -114,7 +115,7 @@ export function createGroupsCommand() {
         emitEnvelope(await runGroupsAddUser({ ...options, quiet: globals.quiet }), globals);
     });
     withAuthFlags(cmd.command('list-users'))
-        .option('--group-id <id>', 'Group whose members to list')
+        .option('--group-id <id>', 'Group whose members to list (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) => {

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

@@ -0,0 +1,27 @@
+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 MetadataTemplateDeps {
+    client?: AxiosInstance;
+}
+export declare function runMetadataTemplateScaffold(opts: CommonOpts & {
+    out?: string;
+}, _deps?: MetadataTemplateDeps): Promise<Envelope<unknown>>;
+export declare function runMetadataTemplateList(opts: CommonOpts & {
+    instanceId?: string;
+    page?: number;
+    pageSize?: number;
+}, deps?: MetadataTemplateDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function runMetadataTemplateGet(opts: CommonOpts & {
+    id?: string;
+}, deps?: MetadataTemplateDeps): Promise<Envelope<unknown>>;
+export declare function runMetadataTemplateUpsert(opts: CommonOpts & {
+    instanceId?: string;
+    sections?: string;
+    sectionsFile?: string;
+}, deps?: MetadataTemplateDeps): Promise<Envelope<unknown>>;
+export declare function createMetadataTemplateCommand(): Command;

package/dist/src/commands/metadataTemplate.js

@@ -0,0 +1,112 @@
+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, parseJsonArray } from '../schema/content.js';
+import { readTextFile } from '../core/readInput.js';
+import { withAuthFlags } from './withAuth.js';
+import { emitScaffold, METADATA_TEMPLATE_SCAFFOLD_JSON } from './scaffolds.js';
+const ENDPOINT = '/api/v1/metadata-templates/';
+export async function runMetadataTemplateScaffold(opts, _deps = {}) {
+    return emitScaffold(METADATA_TEMPLATE_SCAFFOLD_JSON, opts.out);
+}
+export async function runMetadataTemplateList(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for metadata-template list');
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { instance_id: opts.instanceId, ...listPageParams(opts) };
+        const res = await client.get(ENDPOINT, {
+            params,
+        });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runMetadataTemplateGet(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for metadata-template get');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`${ENDPOINT}${encodeURIComponent(opts.id)}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runMetadataTemplateUpsert(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for metadata-template upsert');
+        // Presence-based (not truthiness) so an explicit empty --sections '' is still
+        // counted as a source and can't silently coexist with --sections-file.
+        if (opts.sections !== undefined && opts.sectionsFile !== undefined)
+            throw createCliError('VALIDATION', 'pass exactly one of --sections or --sections-file');
+        // readTextFile → parseJsonArray (NOT readJsonFile, which would bypass the
+        // array-shape VALIDATION check). Both throw a VALIDATION CliError.
+        const raw = opts.sections !== undefined
+            ? opts.sections
+            : opts.sectionsFile !== undefined
+                ? readTextFile(opts.sectionsFile)
+                : undefined;
+        if (raw === undefined)
+            throw createCliError('VALIDATION', 'pass exactly one of --sections or --sections-file');
+        const sections = parseJsonArray(raw, 'sections');
+        const client = clientFor(opts, deps);
+        const res = await client.post(ENDPOINT, { instance_id: opts.instanceId, sections });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+const UPSERT_HELP = `
+Upserts the instance's metadata-field schema. POST is an upsert keyed by
+instance that 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 (a full-replace / UI operation).
+  --instance-id    the instance whose schema to upsert (required)
+  --sections       inline JSON array of sections, OR
+  --sections-file  path to a JSON file with the sections array (exactly one)
+Run 'p metadata-template scaffold' for a starter. Requires an instance- or
+org-admin key; a non-admin member key is rejected (400 -> VALIDATION).`;
+export function createMetadataTemplateCommand() {
+    const cmd = new Command('metadata-template').description('read and additively build an instance metadata-field schema');
+    withAuthFlags(cmd.command('list'))
+        .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) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runMetadataTemplateList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('get'))
+        .option('--id <id>', 'Metadata template ID (ULID)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runMetadataTemplateGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('upsert'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--sections <json>', 'Sections JSON array (inline)')
+        .option('--sections-file <path>', 'Path to a JSON file with the sections array')
+        .addHelpText('after', UPSERT_HELP)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runMetadataTemplateUpsert({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('scaffold'))
+        .description('print a starter metadata-field schema (sections array) to fill in and upsert')
+        .option('--out <path>', 'Write the scaffold to a file instead of stdout')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runMetadataTemplateScaffold({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -17,3 +17,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;

package/dist/src/commands/scaffolds.js

@@ -174,3 +174,98 @@ const ANNOUNCEMENT_SCAFFOLD_DATA = {
     popup_link_label: null,
 };
 export const ANNOUNCEMENT_SCAFFOLD_JSON = JSON.stringify(ANNOUNCEMENT_SCAFFOLD_DATA, null, 2);
+/**
+ * Starter metadata-field schema for `p metadata-template scaffold`. A working
+ * example, not a blank template: one section demonstrating every field `type`
+ * (text/number/date/select/multi-select/checkbox/html) and every attribute the
+ * serializer accepts. NOTE: `options` (select/multi-select) MUST be
+ * { label, value } objects — bare strings are rejected 400. `multi-select`
+ * cannot be `is_sortable`. A select/multi-select `default` is an option `value`.
+ * Section-level `are_fields_dependent` and field-level `help_text` are optional.
+ */
+const METADATA_TEMPLATE_SCAFFOLD_DATA = [
+    {
+        label: 'Product Info',
+        are_fields_dependent: false,
+        fields: [
+            {
+                name: 'product_name',
+                label: 'Product Name',
+                type: 'text',
+                is_required: true,
+                is_filterable: true,
+                is_sortable: true,
+                is_pitch_master: false,
+                help_text: 'Marketed product name',
+                default: '',
+            },
+            {
+                name: 'launch_date',
+                label: 'Launch Date',
+                type: 'date',
+                is_required: false,
+                is_filterable: true,
+                is_sortable: true,
+                is_pitch_master: false,
+            },
+            {
+                name: 'therapeutic_area',
+                label: 'Therapeutic Area',
+                type: 'select',
+                is_required: false,
+                is_filterable: true,
+                is_sortable: false,
+                is_pitch_master: false,
+                options: [
+                    { label: 'Cardiology', value: 'cardiology' },
+                    { label: 'Oncology', value: 'oncology' },
+                ],
+                default: 'cardiology',
+            },
+            {
+                name: 'audiences',
+                label: 'Audiences',
+                type: 'multi-select',
+                is_required: false,
+                is_filterable: true,
+                is_sortable: false,
+                is_pitch_master: false,
+                options: [
+                    { label: 'HCP', value: 'hcp' },
+                    { label: 'Payer', value: 'payer' },
+                    { label: 'Patient', value: 'patient' },
+                ],
+            },
+            {
+                name: 'priority',
+                label: 'Priority',
+                type: 'number',
+                is_required: false,
+                is_filterable: false,
+                is_sortable: true,
+                is_pitch_master: false,
+                default: 0,
+            },
+            {
+                name: 'is_approved',
+                label: 'Approved',
+                type: 'checkbox',
+                is_required: false,
+                is_filterable: true,
+                is_sortable: false,
+                is_pitch_master: false,
+                default: false,
+            },
+            {
+                name: 'notes',
+                label: 'Notes',
+                type: 'html',
+                is_required: false,
+                is_filterable: false,
+                is_sortable: false,
+                is_pitch_master: false,
+            },
+        ],
+    },
+];
+export const METADATA_TEMPLATE_SCAFFOLD_JSON = JSON.stringify(METADATA_TEMPLATE_SCAFFOLD_DATA, null, 2);

package/package.json

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