@nickchristensen/ppls 1.0.1

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+
+import {execute} from '@oclif/core'
+
+await execute({development: true, dir: import.meta.url})

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

package/dist/add-command.d.ts

@@ -0,0 +1,24 @@
+import type { ApiFlags } from './base-command.js';
+import { BaseCommand } from './base-command.js';
+type AddCommandFlags = ApiFlags & {
+    'date-format': string;
+    plain?: boolean;
+    table?: boolean;
+};
+type AddTableRow = {
+    field: string;
+    value: unknown;
+};
+export declare abstract class AddCommand<TCreate = Record<string, unknown>, TRaw extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = TRaw> extends BaseCommand {
+    protected abstract createPath: string;
+    protected addRows(result: TOutput): AddTableRow[];
+    protected abstract buildPayload(args: unknown, flags: Record<string, unknown>): TCreate;
+    protected abstract plainTemplate(item: TOutput): null | string | undefined;
+    protected renderAddOutput(options: {
+        flags: AddCommandFlags;
+        result: TOutput;
+    }): void;
+    run(): Promise<TOutput>;
+    protected transformResult(result: TRaw): TOutput;
+}
+export {};

package/dist/add-command.js

@@ -0,0 +1,47 @@
+import { BaseCommand } from './base-command.js';
+import { createValueFormatter, formatField } from './helpers/table.js';
+export class AddCommand extends BaseCommand {
+    addRows(result) {
+        return Object.entries(result).map(([field, value]) => ({
+            field,
+            value,
+        }));
+    }
+    renderAddOutput(options) {
+        if (this.jsonEnabled()) {
+            return;
+        }
+        const { flags, result } = options;
+        const dateFormat = flags['date-format'];
+        if (flags.plain) {
+            const line = this.plainTemplate(result);
+            if (line) {
+                this.log(line);
+            }
+            return;
+        }
+        const valueFormatter = createValueFormatter(dateFormat);
+        this.logTable([
+            { align: 'right', formatter: formatField, value: 'field' },
+            { formatter: valueFormatter, value: 'value' },
+        ], this.addRows(result), { showHeader: false });
+    }
+    async run() {
+        const { args, flags, metadata } = await this.parse();
+        const { dateFormat, ...apiFlags } = await this.resolveGlobalFlags(flags, metadata);
+        const outputFlags = {
+            ...apiFlags,
+            'date-format': dateFormat,
+            plain: flags.plain,
+            table: flags.table,
+        };
+        const payload = this.buildPayload(args, flags);
+        const rawResult = await this.postApiJson(apiFlags, this.createPath, payload);
+        const result = this.transformResult(rawResult);
+        this.renderAddOutput({ flags: outputFlags, result });
+        return result;
+    }
+    transformResult(result) {
+        return result;
+    }
+}

package/dist/base-command.d.ts

@@ -0,0 +1,63 @@
+import { Command } from '@oclif/core';
+import yoctoSpinner from 'yocto-spinner';
+import { type TableColumn, type TableOptions, type TableRow } from './helpers/table.js';
+export type ApiFlags = {
+    headers: Record<string, string>;
+    hostname: string;
+    token: string;
+};
+type ResolvedGlobalFlags = ApiFlags & {
+    dateFormat: string;
+};
+type UserConfig = Partial<ApiFlags> & {
+    dateFormat?: string;
+    headers?: Record<string, unknown>;
+};
+type CommandMetadata = {
+    flags?: Record<string, {
+        setFromDefault?: boolean;
+    }>;
+};
+export declare abstract class BaseCommand extends Command {
+    static baseFlags: {
+        'date-format': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        header: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        hostname: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        plain: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        table: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static enableJsonFlag: boolean;
+    private userConfigPromise?;
+    protected buildApiUrl(hostnameValue: string, path: string, params?: Record<string, number | string | undefined>): URL;
+    protected buildApiUrlFromFlags(flags: ApiFlags, path: string, params?: Record<string, number | string | undefined>): URL;
+    protected deleteApiJson<T>(flags: ApiFlags, path: string): Promise<null | T>;
+    protected fetchApiBinary(flags: ApiFlags, path: string, params?: Record<string, number | string | undefined>): Promise<{
+        data: Uint8Array;
+        headers: Headers;
+    }>;
+    protected fetchApiJson<T>(flags: ApiFlags, path: string, params?: Record<string, number | string | undefined>): Promise<T>;
+    protected fetchJson<T>(url: URL, tokenValue: string, headers?: Record<string, string>): Promise<T>;
+    protected formatErrorMessage(response: Response): Promise<string>;
+    protected loadUserConfig(): Promise<UserConfig>;
+    protected logTable(headers: TableColumn[], rows: TableRow[], options?: TableOptions): void;
+    protected parseHeaderEntries(entries: string[], source: string): Record<string, string>;
+    protected parseHeadersConfig(input: unknown, source: string): Record<string, string>;
+    protected parseHeadersInput(input: unknown, source: string): Record<string, string>;
+    protected patchApiJson<T>(flags: ApiFlags, path: string, body: unknown): Promise<T>;
+    protected postApiFormData<T>(flags: ApiFlags, path: string, body: FormData): Promise<T>;
+    protected postApiJson<T>(flags: ApiFlags, path: string, body: unknown): Promise<T>;
+    protected requestJson<T>(options: {
+        body?: unknown;
+        headers: Record<string, string>;
+        method: string;
+        token: string;
+        url: URL;
+    }): Promise<T>;
+    protected resolveDateFormat(flags: Record<string, unknown>, metadata: CommandMetadata | undefined, userConfig: UserConfig): string;
+    protected resolveGlobalFlags(flags: Record<string, unknown>, metadata?: CommandMetadata): Promise<ResolvedGlobalFlags>;
+    protected resolveHeaders(flags: Record<string, unknown>, userConfig: UserConfig): Record<string, string>;
+    protected shouldShowSpinner(): boolean;
+    protected startSpinner(text: string): null | ReturnType<typeof yoctoSpinner>;
+}
+export {};

package/dist/base-command.js

@@ -0,0 +1,306 @@
+import { Command, Flags } from '@oclif/core';
+import yoctoSpinner from 'yocto-spinner';
+import { readConfig } from './helpers/config-store.js';
+import { renderTable } from './helpers/table.js';
+export class BaseCommand extends Command {
+    static baseFlags = {
+        'date-format': Flags.string({
+            default: 'yyyy-MM-dd',
+            description: 'Format output dates using a template.',
+            env: 'PPLS_DATE_FORMAT',
+            helpGroup: 'GLOBAL',
+        }),
+        header: Flags.string({
+            description: 'Add a custom request header (repeatable, format: Key=Value)',
+            env: 'PPLS_HEADERS',
+            helpGroup: 'ENVIRONMENT',
+            multiple: true,
+        }),
+        hostname: Flags.string({
+            description: 'Paperless-ngx base URL',
+            env: 'PPLS_HOSTNAME',
+            helpGroup: 'ENVIRONMENT',
+        }),
+        plain: Flags.boolean({
+            description: 'Format output as plain text.',
+            exclusive: ['json', 'table'],
+            helpGroup: 'GLOBAL',
+        }),
+        table: Flags.boolean({
+            description: 'Format output as table.',
+            exclusive: ['json', 'plain'],
+            helpGroup: 'GLOBAL',
+        }),
+        token: Flags.string({
+            description: 'Paperless-ngx API token',
+            env: 'PPLS_TOKEN',
+            helpGroup: 'ENVIRONMENT',
+        }),
+    };
+    static enableJsonFlag = true;
+    userConfigPromise;
+    buildApiUrl(hostnameValue, path, params = {}) {
+        let url;
+        try {
+            url = new URL(path, new URL(hostnameValue));
+        }
+        catch {
+            this.error('Invalid hostname. Expected a full URL like https://paperless.example.com');
+        }
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        return url;
+    }
+    buildApiUrlFromFlags(flags, path, params = {}) {
+        return this.buildApiUrl(flags.hostname, path, params);
+    }
+    async deleteApiJson(flags, path) {
+        const url = this.buildApiUrlFromFlags(flags, path);
+        const requestHeaders = {
+            Accept: 'application/json',
+            Authorization: `Token ${flags.token}`,
+            ...flags.headers,
+        };
+        const response = await fetch(url, {
+            headers: requestHeaders,
+            method: 'DELETE',
+        });
+        if (!response.ok) {
+            this.error(await this.formatErrorMessage(response));
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        const payloadText = await response.text();
+        if (!payloadText.trim()) {
+            return null;
+        }
+        if (contentType.includes('application/json')) {
+            return JSON.parse(payloadText);
+        }
+        return payloadText;
+    }
+    async fetchApiBinary(flags, path, params = {}) {
+        const url = this.buildApiUrlFromFlags(flags, path, params);
+        const requestHeaders = {
+            Accept: '*/*',
+            Authorization: `Token ${flags.token}`,
+            ...flags.headers,
+        };
+        const response = await fetch(url, {
+            headers: requestHeaders,
+        });
+        if (!response.ok) {
+            this.error(await this.formatErrorMessage(response));
+        }
+        return {
+            data: new Uint8Array(await response.arrayBuffer()),
+            headers: response.headers,
+        };
+    }
+    async fetchApiJson(flags, path, params = {}) {
+        const url = this.buildApiUrlFromFlags(flags, path, params);
+        return this.fetchJson(url, flags.token, flags.headers);
+    }
+    async fetchJson(url, tokenValue, headers = {}) {
+        return this.requestJson({
+            headers,
+            method: 'GET',
+            token: tokenValue,
+            url,
+        });
+    }
+    async formatErrorMessage(response) {
+        const baseMessage = `Request failed with ${response.status} ${response.statusText}`.trim();
+        if (response.status >= 400 && response.status < 600) {
+            try {
+                const payloadText = await response.clone().text();
+                if (payloadText) {
+                    const payload = JSON.parse(payloadText);
+                    if (typeof payload?.error === 'string' && payload.error.trim()) {
+                        return `${payload.error}`;
+                    }
+                }
+            }
+            catch {
+                // Fall back to generic error when response isn't JSON.
+            }
+        }
+        return baseMessage;
+    }
+    async loadUserConfig() {
+        if (this.userConfigPromise) {
+            return this.userConfigPromise;
+        }
+        this.userConfigPromise = (async () => {
+            try {
+                return (await readConfig(this.config.configDir));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.error(message);
+            }
+        })();
+        return this.userConfigPromise;
+    }
+    logTable(headers, rows, options) {
+        this.log(renderTable(headers, rows, options));
+    }
+    parseHeaderEntries(entries, source) {
+        const headers = {};
+        for (const entry of entries) {
+            const trimmed = entry.trim();
+            if (!trimmed) {
+                continue;
+            }
+            const equalsIndex = trimmed.indexOf('=');
+            const separatorIndex = equalsIndex;
+            if (separatorIndex === -1) {
+                this.error(`Invalid header "${entry}" from ${source}. Use "Key=Value".`);
+            }
+            const key = trimmed.slice(0, separatorIndex).trim();
+            const value = trimmed.slice(separatorIndex + 1).trim();
+            if (!key) {
+                this.error(`Invalid header "${entry}" from ${source}. Header name cannot be empty.`);
+            }
+            headers[key] = value;
+        }
+        return headers;
+    }
+    parseHeadersConfig(input, source) {
+        if (input === undefined || input === null) {
+            return {};
+        }
+        if (typeof input !== 'object' || Array.isArray(input)) {
+            this.error(`Invalid headers from ${source}. Expected an object of header key/value pairs.`);
+        }
+        const headers = {};
+        for (const [key, value] of Object.entries(input)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            headers[key] = String(value);
+        }
+        return headers;
+    }
+    parseHeadersInput(input, source) {
+        if (input === undefined || input === null) {
+            return {};
+        }
+        if (typeof input === 'string') {
+            const trimmed = input.trim();
+            if (!trimmed) {
+                return {};
+            }
+            return this.parseHeaderEntries([trimmed], source);
+        }
+        if (Array.isArray(input)) {
+            const headers = {};
+            for (const [index, entry] of input.entries()) {
+                Object.assign(headers, this.parseHeadersInput(entry, `${source}[${index}]`));
+            }
+            return headers;
+        }
+        this.error(`Invalid headers from ${source}. Expected a string or array of strings.`);
+    }
+    async patchApiJson(flags, path, body) {
+        const url = this.buildApiUrlFromFlags(flags, path);
+        return this.requestJson({
+            body,
+            headers: flags.headers,
+            method: 'PATCH',
+            token: flags.token,
+            url,
+        });
+    }
+    async postApiFormData(flags, path, body) {
+        const url = this.buildApiUrlFromFlags(flags, path);
+        const requestHeaders = {
+            Accept: 'application/json',
+            Authorization: `Token ${flags.token}`,
+            ...flags.headers,
+        };
+        const response = await fetch(url, {
+            body,
+            headers: requestHeaders,
+            method: 'POST',
+        });
+        if (!response.ok) {
+            this.error(await this.formatErrorMessage(response));
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (contentType.includes('application/json')) {
+            return (await response.json());
+        }
+        return (await response.text());
+    }
+    async postApiJson(flags, path, body) {
+        const url = this.buildApiUrlFromFlags(flags, path);
+        return this.requestJson({
+            body,
+            headers: flags.headers,
+            method: 'POST',
+            token: flags.token,
+            url,
+        });
+    }
+    async requestJson(options) {
+        const { body, headers, method, token, url } = options;
+        const requestHeaders = {
+            Accept: 'application/json',
+            Authorization: `Token ${token}`,
+            ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            ...headers,
+        };
+        const response = await fetch(url, {
+            body: body === undefined ? undefined : JSON.stringify(body),
+            headers: requestHeaders,
+            method,
+        });
+        if (!response.ok) {
+            this.error(await this.formatErrorMessage(response));
+        }
+        return (await response.json());
+    }
+    resolveDateFormat(flags, metadata, userConfig) {
+        const configDateFormat = userConfig.dateFormat;
+        const flagValue = flags['date-format'];
+        const usedDefault = metadata?.flags?.['date-format']?.setFromDefault;
+        if (usedDefault && configDateFormat) {
+            return configDateFormat;
+        }
+        return flagValue ?? configDateFormat ?? 'yyyy-MM-dd';
+    }
+    async resolveGlobalFlags(flags, metadata) {
+        const userConfig = await this.loadUserConfig();
+        const inputFlags = flags;
+        const hostname = inputFlags.hostname ?? userConfig.hostname;
+        const token = inputFlags.token ?? userConfig.token;
+        const dateFormat = this.resolveDateFormat(flags, metadata, userConfig);
+        const headers = this.resolveHeaders(flags, userConfig);
+        if (!hostname) {
+            this.error('hostname required. Use --hostname, set PPLS_HOSTNAME, or use `ppls config set hostname <value>`');
+        }
+        if (!token) {
+            this.error('token required. Use --token, set PPLS_TOKEN, or use `ppls config set token <value>`');
+        }
+        return { dateFormat, headers, hostname, token };
+    }
+    resolveHeaders(flags, userConfig) {
+        const configHeaders = this.parseHeadersConfig(userConfig.headers, 'config.json headers');
+        const envHeaders = this.parseHeadersInput(process.env.PPLS_HEADERS, 'PPLS_HEADERS');
+        const flagHeaders = this.parseHeadersInput(flags.header, '--header');
+        return {
+            ...configHeaders,
+            ...envHeaders,
+            ...flagHeaders,
+        };
+    }
+    shouldShowSpinner() {
+        return Boolean(process.stderr.isTTY);
+    }
+    startSpinner(text) {
+        return this.shouldShowSpinner() ? yoctoSpinner({ text }).start() : null;
+    }
+}

package/dist/commands/config/get.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+import { type ConfigData } from '../../helpers/config-store.js';
+export default class ConfigGet extends Command {
+    static args: {
+        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    run(): Promise<ConfigData>;
+}

package/dist/commands/config/get.js

@@ -0,0 +1,34 @@
+import { Args, Command } from '@oclif/core';
+import { readConfig } from '../../helpers/config-store.js';
+export default class ConfigGet extends Command {
+    static args = {
+        key: Args.string({ description: 'Config key', required: true }),
+    };
+    static description = 'Get a config value';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %> hostname'];
+    async run() {
+        const { args } = await this.parse();
+        const typedArgs = args;
+        const config = await readConfig(this.config.configDir);
+        if (!Object.hasOwn(config, typedArgs.key)) {
+            if (!this.jsonEnabled()) {
+                this.log(`Config key ${typedArgs.key} not set.`);
+            }
+            return {};
+        }
+        const value = config[typedArgs.key];
+        if (!this.jsonEnabled()) {
+            if (value === null || value === undefined) {
+                this.log('');
+            }
+            else if (typeof value === 'string') {
+                this.log(value);
+            }
+            else {
+                this.log(JSON.stringify(value));
+            }
+        }
+        return { [typedArgs.key]: value };
+    }
+}

package/dist/commands/config/init.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+type ConfigInitResult = {
+    overwritten: boolean;
+    path: string;
+};
+export default class ConfigInit extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<ConfigInitResult>;
+}
+export {};

package/dist/commands/config/init.js

@@ -0,0 +1,43 @@
+import { Command, Flags } from '@oclif/core';
+import { stat } from 'node:fs/promises';
+import { configPath, writeConfig } from '../../helpers/config-store.js';
+export default class ConfigInit extends Command {
+    static description = 'Initialize a config file';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %>'];
+    static flags = {
+        force: Flags.boolean({ char: 'f', description: 'Overwrite existing config file' }),
+    };
+    async run() {
+        const { flags } = await this.parse();
+        const typedFlags = flags;
+        const configFile = configPath(this.config.configDir);
+        let exists = false;
+        try {
+            await stat(configFile);
+            exists = true;
+        }
+        catch (error) {
+            const typedError = error;
+            if (typedError.code !== 'ENOENT') {
+                this.error(`Failed to access config at ${configFile}: ${typedError.message ?? String(error)}`);
+            }
+        }
+        if (exists && !typedFlags.force) {
+            this.error(`Config already exists at ${configFile}. Use --force to overwrite.`);
+        }
+        await writeConfig(this.config.configDir, {
+            dateFormat: 'YYYY-MM-DD',
+            headers: {
+                'Custom-Header': 'value',
+            },
+            hostname: 'http://example.com',
+            token: 'your-api-token-here',
+        });
+        const result = { overwritten: exists, path: configFile };
+        if (!this.jsonEnabled()) {
+            this.log(`Created config at ${configFile}`);
+        }
+        return result;
+    }
+}

package/dist/commands/config/list.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+import { type ConfigData } from '../../helpers/config-store.js';
+export default class ConfigList extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        plain: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        table: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<ConfigData>;
+    private buildRows;
+}

package/dist/commands/config/list.js

@@ -0,0 +1,64 @@
+import { Command, Flags } from '@oclif/core';
+import { readConfig } from '../../helpers/config-store.js';
+import { renderTable } from '../../helpers/table.js';
+const formatConfigValue = (value) => {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return JSON.stringify(value);
+};
+export default class ConfigList extends Command {
+    static description = 'List config values';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %>'];
+    static flags = {
+        plain: Flags.boolean({
+            description: 'Format output as plain text.',
+            exclusive: ['json', 'table'],
+        }),
+        table: Flags.boolean({
+            description: 'Format output as table.',
+            exclusive: ['json', 'plain'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse();
+        const typedFlags = flags;
+        const config = await readConfig(this.config.configDir);
+        if (this.jsonEnabled()) {
+            return config;
+        }
+        const entries = Object.entries(config);
+        if (entries.length === 0) {
+            this.log('No config values set.');
+            return config;
+        }
+        if (typedFlags.plain) {
+            for (const [key, value] of entries) {
+                this.log(`${key}=${formatConfigValue(value)}`);
+            }
+            return config;
+        }
+        const rows = this.buildRows(config);
+        const output = renderTable([
+            { align: 'right', formatter: String, value: 'key' },
+            { value: 'value' },
+        ], rows, { showHeader: false });
+        this.log(output);
+        return config;
+    }
+    buildRows(config) {
+        return Object.entries(config)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, value]) => ({
+            key,
+            value: formatConfigValue(value),
+        }));
+    }
+}

package/dist/commands/config/remove.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+import { type ConfigData } from '../../helpers/config-store.js';
+export default class ConfigRemove extends Command {
+    static args: {
+        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    run(): Promise<ConfigData>;
+}