@pitcher/cli-scripts 2.2.2 → 2.4.0

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/baseUrl.js

@@ -6,10 +6,10 @@ export function resolveBaseUrl(opts) {
             parsed = new URL(opts.url);
         }
         catch {
-            throw createCliError('VALIDATION', `Invalid --publish-url: ${opts.url}`);
+            throw createCliError('VALIDATION', `Invalid base URL: ${opts.url}`);
         }
         if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-            throw createCliError('VALIDATION', `--publish-url must be an http(s) URL: ${opts.url}`);
+            throw createCliError('VALIDATION', `Base URL must be an http(s) URL: ${opts.url}`);
         }
         return parsed.origin;
     }

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

@@ -1,6 +1,16 @@
 import { type AxiosInstance } from 'axios';
 import { type CliError } from './errors.js';
 export declare function makeClient(baseUrl: string, apiKey: string): AxiosInstance;
+export interface CommonOpts {
+    apiKey?: string;
+    org?: string;
+    url?: string;
+    quiet?: boolean;
+}
+/** Resolve auth + base URL into a client, or use an injected one (tests). */
+export declare function clientFor(opts: CommonOpts, deps?: {
+    client?: AxiosInstance;
+}): AxiosInstance;
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays

package/dist/src/core/http.js

@@ -1,4 +1,6 @@
 import axios from 'axios';
+import { resolveApiKey } from './auth.js';
+import { resolveBaseUrl } from './baseUrl.js';
 import { createCliError, isCliError } from './errors.js';
 export function makeClient(baseUrl, apiKey) {
     return axios.create({
@@ -9,6 +11,10 @@ export function makeClient(baseUrl, apiKey) {
         },
     });
 }
+/** Resolve auth + base URL into a client, or use an injected one (tests). */
+export function clientFor(opts, deps = {}) {
+    return deps.client ?? makeClient(resolveBaseUrl({ org: opts.org, url: opts.url }), resolveApiKey(opts));
+}
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays

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

@@ -0,0 +1,30 @@
+export declare const MAX_PAGE_SIZE = 500;
+export interface PageOpts {
+    page?: number;
+    pageSize?: number;
+}
+/** 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
+ * value we sent) — we don't fabricate a default, because the server can apply a
+ * different window than requested (e.g. Django ignores page_size when `id__in`
+ * is present), so a guessed value would misreport what actually happened.
+ */
+export declare function listPaginationEcho(opts: PageOpts, res: {
+    count?: unknown;
+    next?: unknown;
+    previous?: unknown;
+}): Record<string, unknown>;

package/dist/src/core/pagination.js

@@ -0,0 +1,47 @@
+// Shared list-pagination helpers so the page-size cap and default live in ONE
+// place (files.ts and folders.ts both consume these — see PR #4956 review).
+export const MAX_PAGE_SIZE = 500;
+function clampPageSize(pageSize) {
+    return pageSize ? Math.min(pageSize, MAX_PAGE_SIZE) : undefined;
+}
+/** Page query params to merge into a list request (clamped so sent === echoed). */
+export function listPageParams(opts) {
+    const params = {};
+    if (opts.page !== undefined)
+        params.page = opts.page;
+    const pageSize = clampPageSize(opts.pageSize);
+    if (pageSize !== undefined)
+        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
+ * value we sent) — we don't fabricate a default, because the server can apply a
+ * different window than requested (e.g. Django ignores page_size when `id__in`
+ * is present), so a guessed value would misreport what actually happened.
+ */
+export function listPaginationEcho(opts, res) {
+    const pageSize = clampPageSize(opts.pageSize);
+    return {
+        count: res.count,
+        next: res.next,
+        previous: res.previous,
+        page: opts.page ?? 1,
+        ...(pageSize !== undefined ? { page_size: pageSize } : {}),
+    };
+}

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/core/upload.d.ts

@@ -0,0 +1,15 @@
+import axios, { type AxiosInstance } from 'axios';
+export interface UploadDeps {
+    put?: typeof axios.put;
+    readFile?: (p: string) => Buffer;
+}
+/**
+ * Upload a local file via the presigned-URL flow and return its content_upload_id.
+ * The S3 PUT uses a BARE axios call (not the Pitcher client) so it carries no
+ * x-api-key, and sends Content-Type equal to the server-signed `type` — omitting
+ * or mismatching it yields a 403 SignatureDoesNotMatch.
+ */
+export declare function uploadFile(client: AxiosInstance, opts: {
+    instanceId: string;
+    filePath: string;
+}, deps?: UploadDeps): Promise<string>;

package/dist/src/core/upload.js

@@ -0,0 +1,30 @@
+import fs from 'fs';
+import path from 'path';
+import axios from 'axios';
+import { createCliError } from './errors.js';
+/**
+ * Upload a local file via the presigned-URL flow and return its content_upload_id.
+ * The S3 PUT uses a BARE axios call (not the Pitcher client) so it carries no
+ * x-api-key, and sends Content-Type equal to the server-signed `type` — omitting
+ * or mismatching it yields a 403 SignatureDoesNotMatch.
+ */
+export async function uploadFile(client, opts, deps = {}) {
+    const readFile = deps.readFile ?? fs.readFileSync;
+    const put = deps.put ?? axios.put;
+    const resolved = path.resolve(opts.filePath);
+    const buffer = readFile(resolved);
+    const name = path.basename(resolved);
+    const createRes = await client.post('/api/v1/uploads/', {
+        name,
+        size: buffer.length,
+        instance_id: opts.instanceId,
+    });
+    const { id, presigned_url, type } = createRes.data;
+    // `type` is required: it's the server-signed Content-Type; sending undefined
+    // yields an opaque S3 403 SignatureDoesNotMatch instead of a clear error.
+    if (!id || !presigned_url || !type) {
+        throw createCliError('NETWORK', 'Upload init failed: /uploads response missing id, presigned_url, or type');
+    }
+    await put(presigned_url, buffer, { headers: { 'Content-Type': type } });
+    return id;
+}

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

@@ -0,0 +1,12 @@
+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[];
+export declare function validateAccessType(v: string | undefined): string | undefined;
+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

@@ -0,0 +1,63 @@
+import { createCliError } from '../core/errors.js';
+const ACCESS_TYPES = ['public', 'restricted', 'personal'];
+export function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function parseJson(raw, flagName) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw createCliError('VALIDATION', `--${flagName} must be valid JSON`);
+    }
+}
+export function parseJsonObject(raw, flagName) {
+    const parsed = parseJson(raw, flagName);
+    if (!isPlainObject(parsed))
+        throw createCliError('VALIDATION', `--${flagName} must be a JSON object`);
+    return parsed;
+}
+export function parseJsonArray(raw, flagName) {
+    const parsed = parseJson(raw, flagName);
+    if (!Array.isArray(parsed))
+        throw createCliError('VALIDATION', `--${flagName} must be a JSON array`);
+    return parsed;
+}
+export function parseTags(raw) {
+    return raw
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+}
+export function validateAccessType(v) {
+    if (v === undefined)
+        return undefined;
+    if (!ACCESS_TYPES.includes(v)) {
+        throw createCliError('VALIDATION', `--access-type must be one of: ${ACCESS_TYPES.join(', ')}`);
+    }
+    return 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, 1],
+        ['page-size', opts.pageSize, 1],
+        ['limit', opts.limit, 0],
+        ['offset', opts.offset, 0],
+    ];
+    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`);
+        }
+    }
+}
+export function deepMerge(base, patch) {
+    const out = isPlainObject(base) ? { ...base } : {};
+    for (const [k, v] of Object.entries(patch)) {
+        const cur = out[k];
+        out[k] = isPlainObject(v) && isPlainObject(cur) ? deepMerge(cur, v) : v;
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
@@ -26,13 +26,13 @@
   ],
   "devDependencies": {
     "@types/archiver": "^7.0.0",
-    "@types/node": "^24.10.9",
+    "@types/node": "^24.13.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },
   "dependencies": {
     "archiver": "^7.0.1",
-    "axios": "^1.16.0",
+    "axios": "^1.18.1",
     "chokidar": "^5.0.0",
     "commander": "^14.0.3",
     "form-data": "^4.0.6"