@nickchristensen/ppls 1.0.1

package/dist/commands/document-types/delete.js

@@ -0,0 +1,18 @@
+import { Args, Flags } from '@oclif/core';
+import { DeleteCommand } from '../../delete-command.js';
+export default class DocumentTypesDelete extends DeleteCommand {
+    static args = {
+        id: Args.integer({ description: 'Document type id', required: true }),
+    };
+    static description = 'Delete a document type';
+    static examples = ['<%= config.bin %> <%= command.id %> 123'];
+    static flags = {
+        yes: Flags.boolean({ char: 'y', description: 'Skip confirmation prompt' }),
+    };
+    deleteLabel(id) {
+        return `document type ${id}`;
+    }
+    deletePath(id) {
+        return `/api/document_types/${id}/`;
+    }
+}

package/dist/commands/document-types/list.d.ts

@@ -0,0 +1,9 @@
+import type { DocumentType } from '../../types/document-types.js';
+import { ListCommand } from '../../list-command.js';
+export default class DocumentTypesList extends ListCommand<DocumentType> {
+    static description: string;
+    static examples: string[];
+    protected listPath: string;
+    protected tableAttrs: string[];
+    protected plainTemplate(documentType: DocumentType): string | undefined;
+}

package/dist/commands/document-types/list.js

@@ -0,0 +1,12 @@
+import { ListCommand } from '../../list-command.js';
+export default class DocumentTypesList extends ListCommand {
+    static description = 'List document types';
+    static examples = ['<%= config.bin %> <%= command.id %>'];
+    listPath = '/api/document_types/';
+    tableAttrs = ['id', 'name', 'slug', 'document_count'];
+    plainTemplate(documentType) {
+        const count = documentType.document_count;
+        const suffix = count === undefined ? '' : ` (${count} ${count === 1 ? 'document' : 'documents'})`;
+        return `[${documentType.id}] ${documentType.name}${suffix}`;
+    }
+}

package/dist/commands/document-types/show.d.ts

@@ -0,0 +1,14 @@
+import type { DocumentType } from '../../types/document-types.js';
+import { ShowCommand } from '../../show-command.js';
+export default class DocumentTypesShow extends ShowCommand<DocumentType> {
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<number, {
+            max?: number;
+            min?: number;
+        }>;
+    };
+    static description: string;
+    static examples: string[];
+    protected plainTemplate(documentType: DocumentType): string | undefined;
+    protected showPath(id: number | string): string;
+}

package/dist/commands/document-types/show.js

@@ -0,0 +1,17 @@
+import { Args } from '@oclif/core';
+import { ShowCommand } from '../../show-command.js';
+export default class DocumentTypesShow extends ShowCommand {
+    static args = {
+        id: Args.integer({ description: 'Document type id', required: true }),
+    };
+    static description = 'Show document type details';
+    static examples = ['<%= config.bin %> <%= command.id %> 123'];
+    plainTemplate(documentType) {
+        const count = documentType.document_count;
+        const suffix = count === undefined ? '' : ` (${count} ${count === 1 ? 'document' : 'documents'})`;
+        return `[${documentType.id}] ${documentType.name}${suffix}`;
+    }
+    showPath(id) {
+        return `/api/document_types/${id}/`;
+    }
+}

package/dist/commands/document-types/update.d.ts

@@ -0,0 +1,18 @@
+import type { DocumentType, DocumentTypeUpdate } from '../../types/document-types.js';
+import { UpdateCommand } from '../../update-command.js';
+export default class DocumentTypesUpdate extends UpdateCommand<DocumentTypeUpdate, DocumentType> {
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<number, {
+            max?: number;
+            min?: number;
+        }>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    protected buildPayload(_args: unknown, flags: Record<string, unknown>): DocumentTypeUpdate;
+    protected plainTemplate(documentType: DocumentType): string | undefined;
+    protected updatePath(id: number | string): string;
+}

package/dist/commands/document-types/update.js

@@ -0,0 +1,26 @@
+import { Args, Flags } from '@oclif/core';
+import { UpdateCommand } from '../../update-command.js';
+export default class DocumentTypesUpdate extends UpdateCommand {
+    static args = {
+        id: Args.integer({ description: 'Document type id', required: true }),
+    };
+    static description = 'Update a document type';
+    static examples = ['<%= config.bin %> <%= command.id %> 123 --name "Invoice"'];
+    static flags = {
+        name: Flags.string({ description: 'Document type name' }),
+    };
+    buildPayload(_args, flags) {
+        const typedFlags = flags;
+        return {
+            name: typedFlags.name,
+        };
+    }
+    plainTemplate(documentType) {
+        const count = documentType.document_count;
+        const suffix = count === undefined ? '' : ` (${count} ${count === 1 ? 'document' : 'documents'})`;
+        return `[${documentType.id}] ${documentType.name}${suffix}`;
+    }
+    updatePath(id) {
+        return `/api/document_types/${id}/`;
+    }
+}

package/dist/commands/documents/add.d.ts

@@ -0,0 +1,70 @@
+import type { DocumentCreate } from '../../types/documents.js';
+import { BaseCommand } from '../../base-command.js';
+type DocumentsAddArgs = {
+    path?: string;
+};
+type DocumentsAddFlags = {
+    'archive-serial-number'?: number;
+    correspondent?: number;
+    created?: DocumentCreate['created'];
+    'document-type'?: number;
+    'storage-path'?: number;
+    tag?: number[];
+    title?: string;
+};
+type UploadOutputFlags = {
+    'date-format': string;
+    plain?: boolean;
+    table?: boolean;
+};
+type UploadResult = Record<string, unknown>;
+type UploadFileOptions = {
+    apiFlags: {
+        headers: Record<string, string>;
+        hostname: string;
+        token: string;
+    };
+    filePath: string;
+    payload: DocumentCreate;
+};
+export default class DocumentsAdd extends BaseCommand {
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string | undefined, {
+            exists?: boolean;
+        }>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'archive-serial-number': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        correspondent: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        created: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'document-type': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'storage-path': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<number[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        title: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static strict: boolean;
+    protected buildPayload(flags: DocumentsAddFlags): DocumentCreate;
+    protected buildUploadFormData(payload: DocumentCreate, filename: string, fileContents: Buffer): FormData;
+    protected normalizeResult(result: unknown): UploadResult;
+    protected plainTemplate(result: UploadResult): string | undefined;
+    protected renderUploadOutput(options: {
+        flags: UploadOutputFlags;
+        result: UploadResult;
+    }): void;
+    protected resolveUploadPaths(args: DocumentsAddArgs, argv: unknown[]): string[];
+    run(): Promise<UploadResult | UploadResult[]>;
+    protected toOptionalString(value: null | number | undefined): string | undefined;
+    protected uploadFile(options: UploadFileOptions): Promise<UploadResult>;
+    protected uploadFiles(options: {
+        apiFlags: {
+            headers: Record<string, string>;
+            hostname: string;
+            token: string;
+        };
+        paths: string[];
+        payload: DocumentCreate;
+    }): Promise<UploadResult[]>;
+}
+export {};

package/dist/commands/documents/add.js

@@ -0,0 +1,166 @@
+import { Args, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { BaseCommand } from '../../base-command.js';
+import { createValueFormatter, formatField } from '../../helpers/table.js';
+export default class DocumentsAdd extends BaseCommand {
+    static args = {
+        path: Args.file({ description: 'Document file path(s)' }),
+    };
+    static description = 'Upload one or more documents. Supports multiple arguments or a glob.';
+    static examples = ['<%= config.bin %> <%= command.id %> ./receipt.pdf --title "Receipt"'];
+    static flags = {
+        'archive-serial-number': Flags.integer({ description: 'Archive serial number' }),
+        correspondent: Flags.integer({ description: 'Correspondent id' }),
+        created: Flags.string({ description: 'Document created date-time' }),
+        'document-type': Flags.integer({ description: 'Document type id' }),
+        'storage-path': Flags.integer({ description: 'Storage path id' }),
+        tag: Flags.integer({ description: 'Tag id (repeatable)', multiple: true }),
+        title: Flags.string({ description: 'Document title' }),
+    };
+    static strict = false;
+    buildPayload(flags) {
+        return {
+            'archive_serial_number': flags['archive-serial-number'],
+            correspondent: flags.correspondent,
+            created: flags.created,
+            'document_type': flags['document-type'],
+            'storage_path': flags['storage-path'],
+            tags: flags.tag,
+            title: flags.title,
+        };
+    }
+    buildUploadFormData(payload, filename, fileContents) {
+        const formData = new FormData();
+        const arrayBuffer = fileContents.buffer.slice(fileContents.byteOffset, fileContents.byteOffset + fileContents.byteLength);
+        formData.set('document', new Blob([arrayBuffer]), filename);
+        const fields = [
+            ['title', payload.title],
+            ['correspondent', this.toOptionalString(payload.correspondent)],
+            ['document_type', this.toOptionalString(payload.document_type)],
+            ['storage_path', this.toOptionalString(payload.storage_path)],
+            ['created', payload.created],
+            ['archive_serial_number', this.toOptionalString(payload.archive_serial_number)],
+        ];
+        for (const [field, value] of fields) {
+            if (value === undefined) {
+                continue;
+            }
+            formData.set(field, value);
+        }
+        if (payload.tags && payload.tags.length > 0) {
+            for (const tag of payload.tags) {
+                formData.append('tags', String(tag));
+            }
+        }
+        return formData;
+    }
+    normalizeResult(result) {
+        if (result === null || result === undefined) {
+            return { result: null };
+        }
+        if (typeof result === 'object') {
+            return result;
+        }
+        return { result };
+    }
+    plainTemplate(result) {
+        if (typeof result.result === 'string' && result.result.trim()) {
+            return result.result;
+        }
+        if (typeof result.id === 'number' || typeof result.id === 'string') {
+            return String(result.id);
+        }
+        return JSON.stringify(result);
+    }
+    renderUploadOutput(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);
+        const rows = Object.entries(result).map(([field, value]) => ({ field, value }));
+        this.logTable([
+            { align: 'right', formatter: formatField, value: 'field' },
+            { formatter: valueFormatter, value: 'value' },
+        ], rows, { showHeader: false });
+    }
+    resolveUploadPaths(args, argv) {
+        const rawPaths = argv.length > 0 ? argv : args.path ? [args.path] : [];
+        if (rawPaths.length === 0) {
+            this.error('Provide at least one file path to upload.');
+        }
+        return rawPaths.map(String);
+    }
+    async run() {
+        const { args, argv, flags, metadata } = await this.parse();
+        const { dateFormat, ...apiFlags } = await this.resolveGlobalFlags(flags, metadata);
+        const outputFlags = {
+            'date-format': dateFormat,
+            plain: flags.plain,
+            table: flags.table,
+        };
+        const typedArgs = args;
+        const typedFlags = flags;
+        const paths = this.resolveUploadPaths(typedArgs, argv);
+        const payload = this.buildPayload(typedFlags);
+        const results = await this.uploadFiles({ apiFlags, paths, payload });
+        if (!this.jsonEnabled()) {
+            for (const result of results) {
+                this.renderUploadOutput({ flags: outputFlags, result });
+            }
+        }
+        return results.length === 1 ? results[0] : results;
+    }
+    toOptionalString(value) {
+        if (value === null || value === undefined) {
+            return;
+        }
+        return String(value);
+    }
+    async uploadFile(options) {
+        const { apiFlags, filePath, payload } = options;
+        let fileContents;
+        try {
+            fileContents = await readFile(filePath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.error(`Failed to read file at ${filePath}: ${message}`);
+        }
+        const filename = path.basename(filePath);
+        const formData = this.buildUploadFormData(payload, filename, fileContents);
+        const rawResult = await this.postApiFormData(apiFlags, '/api/documents/post_document/', formData);
+        return this.normalizeResult(rawResult);
+    }
+    async uploadFiles(options) {
+        const { apiFlags, paths, payload } = options;
+        const results = [];
+        const spinner = this.startSpinner('');
+        try {
+            for (let index = 0; index < paths.length; index += 1) {
+                const filePath = paths[index];
+                const filename = path.basename(filePath);
+                const prefix = paths.length > 1 ? `[${index + 1}/${paths.length}] ` : '';
+                if (spinner) {
+                    spinner.text = `${prefix}Uploading ${filename}`;
+                }
+                // eslint-disable-next-line no-await-in-loop -- uploads are sequential to keep spinner output in order.
+                const result = await this.uploadFile({ apiFlags, filePath, payload });
+                results.push(result);
+            }
+        }
+        finally {
+            spinner?.stop();
+        }
+        return results;
+    }
+}

package/dist/commands/documents/delete.d.ts

@@ -0,0 +1,16 @@
+import { DeleteCommand } from '../../delete-command.js';
+export default class DocumentsDelete extends DeleteCommand {
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<number, {
+            max?: number;
+            min?: number;
+        }>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    protected deleteLabel(id: number | string): string;
+    protected deletePath(id: number | string): string;
+}

package/dist/commands/documents/delete.js

@@ -0,0 +1,18 @@
+import { Args, Flags } from '@oclif/core';
+import { DeleteCommand } from '../../delete-command.js';
+export default class DocumentsDelete extends DeleteCommand {
+    static args = {
+        id: Args.integer({ description: 'Document id', required: true }),
+    };
+    static description = 'Delete a document';
+    static examples = ['<%= config.bin %> <%= command.id %> 123'];
+    static flags = {
+        yes: Flags.boolean({ char: 'y', description: 'Skip confirmation prompt' }),
+    };
+    deleteLabel(id) {
+        return `document ${id}`;
+    }
+    deletePath(id) {
+        return `/api/documents/${id}/`;
+    }
+}

package/dist/commands/documents/download.d.ts

@@ -0,0 +1,48 @@
+import { BaseCommand } from '../../base-command.js';
+type DownloadResult = {
+    bytes: number;
+    contentType?: string;
+    filename: string;
+    id: number;
+    original: boolean;
+    output: string;
+};
+type DownloadDocumentOptions = {
+    apiFlags: {
+        headers: Record<string, string>;
+        hostname: string;
+        token: string;
+    };
+    id: number;
+    original?: boolean;
+    output?: string;
+    outputDir?: string;
+};
+type DownloadDocumentsOptions = {
+    apiFlags: {
+        headers: Record<string, string>;
+        hostname: string;
+        token: string;
+    };
+    ids: number[];
+    original?: boolean;
+    output?: string;
+    outputDir?: string;
+};
+export default class DocumentsDownload extends BaseCommand {
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        original: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'output-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    protected downloadDocument(options: DownloadDocumentOptions): Promise<DownloadResult>;
+    protected downloadDocuments(options: DownloadDocumentsOptions): Promise<DownloadResult[]>;
+    protected parseIds(raw: string): number[];
+    run(): Promise<DownloadResult | DownloadResult[]>;
+}
+export {};

package/dist/commands/documents/download.js

@@ -0,0 +1,152 @@
+import { Args, Flags } from '@oclif/core';
+import { stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { BaseCommand } from '../../base-command.js';
+const parseContentDispositionFilename = (header) => {
+    if (!header) {
+        return;
+    }
+    const starMatch = /filename\*=([^']*)''([^;]+)/i.exec(header);
+    if (starMatch?.[2]) {
+        try {
+            return decodeURIComponent(starMatch[2]);
+        }
+        catch {
+            return starMatch[2];
+        }
+    }
+    const match = /filename="?([^";]+)"?/i.exec(header);
+    return match?.[1];
+};
+const resolveFallbackFilename = (id, contentType) => {
+    if (contentType?.includes('pdf')) {
+        return `document-${id}.pdf`;
+    }
+    return `document-${id}`;
+};
+const resolveOutputPath = async (output, filename) => {
+    if (!output) {
+        return path.resolve(process.cwd(), filename);
+    }
+    const resolved = path.resolve(output);
+    try {
+        const stats = await stat(resolved);
+        if (stats.isDirectory()) {
+            return path.join(resolved, filename);
+        }
+    }
+    catch {
+        // Assume output is a file path if it doesn't exist yet.
+    }
+    return resolved;
+};
+export default class DocumentsDownload extends BaseCommand {
+    static args = {
+        id: Args.string({ description: 'Document id or comma-separated list of ids', required: true }),
+    };
+    static description = 'Download one or more documents';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> 123 --output document.pdf',
+        '<%= config.bin %> <%= command.id %> 123,124 --output-dir ./downloads',
+    ];
+    static flags = {
+        original: Flags.boolean({ description: 'Download original file' }),
+        output: Flags.string({
+            char: 'o',
+            description: 'Output file path (single document)',
+            exclusive: ['output-dir'],
+        }),
+        'output-dir': Flags.directory({
+            description: 'Output directory (multiple documents)',
+            exclusive: ['output'],
+            exists: true,
+        }),
+    };
+    async downloadDocument(options) {
+        const { apiFlags, id, original, output, outputDir } = options;
+        const { data, headers: responseHeaders } = await this.fetchApiBinary(apiFlags, `/api/documents/${id}/download/`, {
+            original: original ? 'true' : undefined,
+        });
+        const contentDisposition = responseHeaders.get('content-disposition');
+        const contentType = responseHeaders.get('content-type') ?? undefined;
+        const headerFilename = parseContentDispositionFilename(contentDisposition);
+        const safeFilename = path.basename(headerFilename ?? resolveFallbackFilename(id, contentType));
+        const outputPath = outputDir ? path.join(outputDir, safeFilename) : await resolveOutputPath(output, safeFilename);
+        await writeFile(outputPath, data);
+        return {
+            bytes: data.length,
+            contentType,
+            filename: path.basename(outputPath),
+            id,
+            original: Boolean(original),
+            output: outputPath,
+        };
+    }
+    async downloadDocuments(options) {
+        const { apiFlags, ids, original, output, outputDir } = options;
+        const results = [];
+        const spinner = this.startSpinner('');
+        try {
+            for (let index = 0; index < ids.length; index += 1) {
+                const id = ids[index];
+                const prefix = ids.length > 1 ? `[${index + 1}/${ids.length}] ` : '';
+                if (spinner) {
+                    spinner.text = `${prefix}Downloading document ${id}`;
+                }
+                // eslint-disable-next-line no-await-in-loop -- downloads are sequential to keep spinner output in order.
+                const result = await this.downloadDocument({ apiFlags, id, original, output, outputDir });
+                results.push(result);
+            }
+        }
+        finally {
+            spinner?.stop();
+        }
+        return results;
+    }
+    parseIds(raw) {
+        const values = raw
+            .split(',')
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0);
+        if (values.length === 0) {
+            this.error('Provide at least one document id.');
+        }
+        return values.map((value) => {
+            if (!/^-?\d+$/.test(value)) {
+                this.error(`Invalid document id: ${value}`);
+            }
+            return Number.parseInt(value, 10);
+        });
+    }
+    async run() {
+        const { args, flags, metadata } = await this.parse();
+        const { headers: apiHeaders, hostname, token } = await this.resolveGlobalFlags(flags, metadata);
+        const apiFlags = { headers: apiHeaders, hostname, token };
+        const typedArgs = args;
+        const typedFlags = flags;
+        const ids = this.parseIds(typedArgs.id);
+        let outputDir = typedFlags['output-dir'];
+        if (ids.length > 1) {
+            if (typedFlags.output) {
+                this.error('Use --output-dir when downloading multiple documents.');
+            }
+            outputDir = path.resolve(outputDir ?? process.cwd());
+        }
+        else if (outputDir) {
+            this.error('Use --output for a single document download.');
+        }
+        const results = await this.downloadDocuments({
+            apiFlags,
+            ids,
+            original: typedFlags.original,
+            output: typedFlags.output,
+            outputDir,
+        });
+        if (!this.jsonEnabled()) {
+            for (const result of results) {
+                this.log(`Saved ${result.output}`);
+            }
+        }
+        return results.length === 1 ? results[0] : results;
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { Document } from '../../types/documents.js';
+import { ListCommand } from '../../list-command.js';
+export default class DocumentsList extends ListCommand<Document> {
+    static description: string;
+    static examples: string[];
+    protected listPath: string;
+    protected tableAttrs: string[];
+    protected plainTemplate(document: Document): string | undefined;
+}

package/dist/commands/documents/list.js

@@ -0,0 +1,14 @@
+import { ListCommand } from '../../list-command.js';
+export default class DocumentsList extends ListCommand {
+    static description = 'List documents';
+    static examples = ['<%= config.bin %> <%= command.id %>'];
+    listPath = '/api/documents/';
+    tableAttrs = ['id', 'title', 'created', 'added', 'correspondent', 'document_type', 'tags'];
+    plainTemplate(document) {
+        const title = document.title?.trim();
+        if (!title) {
+            return;
+        }
+        return `[${document.id}] ${title}`;
+    }
+}

package/dist/commands/documents/show.d.ts

@@ -0,0 +1,14 @@
+import type { Document } from '../../types/documents.js';
+import { ShowCommand } from '../../show-command.js';
+export default class DocumentsShow extends ShowCommand<Document> {
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<number, {
+            max?: number;
+            min?: number;
+        }>;
+    };
+    static description: string;
+    static examples: string[];
+    protected plainTemplate(document: Document): string | undefined;
+    protected showPath(id: number | string): string;
+}

package/dist/commands/documents/show.js

@@ -0,0 +1,19 @@
+import { Args } from '@oclif/core';
+import { ShowCommand } from '../../show-command.js';
+export default class DocumentsShow extends ShowCommand {
+    static args = {
+        id: Args.integer({ description: 'Document id', required: true }),
+    };
+    static description = 'Show document details';
+    static examples = ['<%= config.bin %> <%= command.id %> 123'];
+    plainTemplate(document) {
+        const title = document.title?.trim();
+        if (!title) {
+            return;
+        }
+        return `[${document.id}] ${title}`;
+    }
+    showPath(id) {
+        return `/api/documents/${id}/`;
+    }
+}