@nickchristensen/ppls 1.0.1

package/dist/list-command.js

@@ -0,0 +1,98 @@
+import { Flags } from '@oclif/core';
+import { createValueFormatter } from './helpers/table.js';
+import { PaginatedCommand } from './paginated-command.js';
+export class ListCommand extends PaginatedCommand {
+    static baseFlags = {
+        ...PaginatedCommand.baseFlags,
+        'id-in': Flags.string({
+            description: 'Filter by id list (comma-separated)',
+            exclusive: ['name-contains'],
+        }),
+        'name-contains': Flags.string({
+            description: 'Filter by name substring',
+            exclusive: ['id-in'],
+        }),
+        sort: Flags.string({ description: 'Sort results by the provided field' }),
+    };
+    async fetchListResults(options) {
+        const { flags, params = {}, path } = options;
+        const url = this.buildPaginatedUrlFromFlags({
+            flags,
+            params: {
+                ordering: flags.sort,
+                ...params,
+            },
+            path,
+        });
+        return this.fetchPaginatedResultsFromFlags({
+            autoPaginate: this.shouldAutoPaginate(flags),
+            flags,
+            url,
+        });
+    }
+    listParams(flags) {
+        return {
+            'id__in': flags['id-in'],
+            'name__icontains': flags['name-contains'],
+        };
+    }
+    renderListOutput(options) {
+        if (this.jsonEnabled()) {
+            return;
+        }
+        const { flags, results } = options;
+        const dateFormat = flags['date-format'];
+        if (flags.plain) {
+            for (const item of results) {
+                const line = this.plainTemplate(item);
+                if (line) {
+                    this.log(line);
+                }
+            }
+            return;
+        }
+        const valueFormatter = createValueFormatter(dateFormat);
+        const columns = this.tableAttrs.map((value) => typeof value === 'string' ? { formatter: valueFormatter, value } : { formatter: valueFormatter, ...value });
+        this.logTable(columns, results);
+    }
+    async run() {
+        const { flags, metadata } = await this.parse();
+        const { dateFormat, ...apiFlags } = await this.resolveGlobalFlags(flags, metadata);
+        const listFlags = {
+            headers: apiFlags.headers,
+            hostname: apiFlags.hostname,
+            'id-in': flags['id-in'],
+            'name-contains': flags['name-contains'],
+            page: flags.page,
+            'page-size': flags['page-size'],
+            sort: flags.sort,
+            token: apiFlags.token,
+        };
+        const outputFlags = {
+            ...listFlags,
+            'date-format': dateFormat,
+            plain: flags.plain,
+            table: flags.table,
+        };
+        const rawResults = await this.fetchListResults({
+            flags: listFlags,
+            params: this.listParams(listFlags),
+            path: this.listPath,
+        });
+        const results = this.transformResults(rawResults);
+        this.renderListOutput({
+            flags: outputFlags,
+            results,
+        });
+        return results;
+    }
+    shouldAutoPaginate(flags) {
+        return flags.page === undefined && flags['page-size'] === undefined;
+    }
+    transformResult(result) {
+        return result;
+    }
+    transformResults(results) {
+        return results.map((result) => this.transformResult(result));
+    }
+}

package/dist/paginated-command.d.ts

@@ -0,0 +1,48 @@
+import type { ApiFlags } from './base-command.js';
+import { BaseCommand } from './base-command.js';
+type PaginatedFlags = ApiFlags & {
+    page?: number;
+    'page-size'?: number;
+};
+export declare abstract class PaginatedCommand extends BaseCommand {
+    static baseFlags: {
+        page: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'page-size': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        '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>;
+    };
+    protected buildPaginatedUrl(options: {
+        hostname: string;
+        page?: number;
+        pageSize?: number;
+        params?: Record<string, number | string | undefined>;
+        path: string;
+    }): URL;
+    protected buildPaginatedUrlFromFlags(options: {
+        flags: PaginatedFlags;
+        params?: Record<string, number | string | undefined>;
+        path: string;
+    }): URL;
+    protected fetchPaginatedResults<T>(options: {
+        autoPaginate: boolean;
+        headers: Record<string, string>;
+        spinnerText?: string;
+        token: string;
+        url: URL;
+    }): Promise<T[]>;
+    protected fetchPaginatedResultsFromFlags<T>(options: {
+        autoPaginate: boolean;
+        flags: {
+            headers: Record<string, string>;
+            token: string;
+        };
+        spinnerText?: string;
+        url: URL;
+    }): Promise<T[]>;
+    protected paginate<T>(url: URL, tokenValue: string, headers: Record<string, string>, autoPaginate: boolean): AsyncGenerator<T>;
+}
+export {};

package/dist/paginated-command.js

@@ -0,0 +1,89 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from './base-command.js';
+export class PaginatedCommand extends BaseCommand {
+    static baseFlags = {
+        ...BaseCommand.baseFlags,
+        page: Flags.integer({ description: 'Page number to fetch' }),
+        'page-size': Flags.integer({ description: 'Number of results per page' }),
+    };
+    buildPaginatedUrl(options) {
+        const { hostname, page, pageSize, params = {}, path } = options;
+        if (page !== undefined && page < 1) {
+            this.error('Invalid page value. Page must be 1 or greater.');
+        }
+        if (pageSize !== undefined && pageSize < 1) {
+            this.error('Invalid page size. Page size must be 1 or greater.');
+        }
+        return this.buildApiUrl(hostname, path, {
+            ...params,
+            page,
+            'page_size': pageSize,
+        });
+    }
+    buildPaginatedUrlFromFlags(options) {
+        const { flags, params, path } = options;
+        return this.buildPaginatedUrl({
+            hostname: flags.hostname,
+            page: flags.page,
+            pageSize: flags['page-size'],
+            params,
+            path,
+        });
+    }
+    async fetchPaginatedResults(options) {
+        const { autoPaginate, headers, spinnerText, token, url } = options;
+        const spinner = this.startSpinner(spinnerText ?? `Fetching ${url.pathname}`);
+        const results = [];
+        try {
+            let nextUrl = url;
+            while (nextUrl) {
+                // eslint-disable-next-line no-await-in-loop -- pagination is sequential and depends on the next page URL.
+                const payload = await this.fetchJson(nextUrl, token, headers);
+                results.push(...(payload.results ?? []));
+                if (!autoPaginate || !payload.next) {
+                    break;
+                }
+                try {
+                    nextUrl = new URL(payload.next, nextUrl);
+                }
+                catch {
+                    this.error('API returned an invalid next URL for pagination.');
+                }
+            }
+        }
+        finally {
+            spinner?.stop();
+        }
+        return results;
+    }
+    async fetchPaginatedResultsFromFlags(options) {
+        const { autoPaginate, flags, spinnerText, url } = options;
+        return this.fetchPaginatedResults({
+            autoPaginate,
+            headers: flags.headers,
+            spinnerText,
+            token: flags.token,
+            url,
+        });
+    }
+    async *paginate(url, tokenValue, headers, autoPaginate) {
+        let nextUrl = url;
+        while (nextUrl) {
+            // eslint-disable-next-line no-await-in-loop -- pagination is sequential and depends on the next page URL.
+            const payload = await this.fetchJson(nextUrl, tokenValue, headers);
+            const results = payload.results ?? [];
+            for (const result of results) {
+                yield result;
+            }
+            if (!autoPaginate || !payload.next) {
+                break;
+            }
+            try {
+                nextUrl = new URL(payload.next, nextUrl);
+            }
+            catch {
+                this.error('API returned an invalid next URL for pagination.');
+            }
+        }
+    }
+}

package/dist/show-command.d.ts

@@ -0,0 +1,27 @@
+import type { ApiFlags } from './base-command.js';
+import { BaseCommand } from './base-command.js';
+type ShowCommandArgs = {
+    id: number | string;
+};
+type ShowCommandFlags = ApiFlags & {
+    'date-format': string;
+    plain?: boolean;
+    table?: boolean;
+};
+type ShowTableRow = {
+    field: string;
+    value: unknown;
+};
+export declare abstract class ShowCommand<TRaw extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = TRaw> extends BaseCommand {
+    protected abstract plainTemplate(item: TOutput): null | string | undefined;
+    protected renderShowOutput(options: {
+        flags: ShowCommandFlags;
+        result: TOutput;
+    }): void;
+    run(): Promise<TOutput>;
+    protected showId(args: ShowCommandArgs): number | string;
+    protected abstract showPath(id: number | string): string;
+    protected showRows(result: TOutput): ShowTableRow[];
+    protected transformResult(result: TRaw): TOutput;
+}
+export {};

package/dist/show-command.js

@@ -0,0 +1,50 @@
+import { BaseCommand } from './base-command.js';
+import { createValueFormatter, formatField } from './helpers/table.js';
+export class ShowCommand extends BaseCommand {
+    renderShowOutput(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.showRows(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 id = this.showId(args);
+        const rawResult = await this.fetchApiJson(apiFlags, this.showPath(id));
+        const result = this.transformResult(rawResult);
+        this.renderShowOutput({ flags: outputFlags, result });
+        return result;
+    }
+    showId(args) {
+        return args.id;
+    }
+    showRows(result) {
+        return Object.entries(result).map(([field, value]) => ({
+            field,
+            value,
+        }));
+    }
+    transformResult(result) {
+        return result;
+    }
+}

package/dist/types/correspondents.d.ts

@@ -0,0 +1,28 @@
+import type { MatchingAlgorithm } from './shared.js';
+export type Correspondent = {
+    document_count: number;
+    id: number;
+    is_insensitive?: boolean;
+    last_correspondence: string;
+    match?: string;
+    matching_algorithm?: MatchingAlgorithm;
+    name: string;
+    owner?: null | number;
+    permissions: {
+        change: {
+            groups: number[];
+            users: number[];
+        };
+        view: {
+            groups: number[];
+            users: number[];
+        };
+    };
+    slug: string;
+    user_can_change: boolean;
+};
+export type CorrespondentCreate = {
+    matching_algorithm?: MatchingAlgorithm;
+    name: string;
+};
+export type CorrespondentUpdate = Partial<CorrespondentCreate>;

package/dist/types/correspondents.js

@@ -0,0 +1 @@
+export {};

package/dist/types/custom-fields.d.ts

@@ -0,0 +1,18 @@
+import type { DataTypeEnum } from './shared.js';
+export type CustomField = {
+    data_type: DataTypeEnum;
+    document_count: number;
+    extra_data?: null | Record<string, unknown>;
+    id: number;
+    name: string;
+};
+export type CustomFieldCreate = {
+    data_type: DataTypeEnum;
+    extra_data?: {
+        select_options: Array<{
+            label: string;
+        }>;
+    };
+    name: string;
+};
+export type CustomFieldUpdate = Partial<CustomFieldCreate>;

package/dist/types/custom-fields.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,27 @@
+import type { MatchingAlgorithm } from './shared.js';
+export type DocumentType = {
+    document_count: number;
+    id: number;
+    is_insensitive?: boolean;
+    match?: string;
+    matching_algorithm?: MatchingAlgorithm;
+    name: string;
+    owner?: null | number;
+    permissions: {
+        change: {
+            groups: number[];
+            users: number[];
+        };
+        view: {
+            groups: number[];
+            users: number[];
+        };
+    };
+    slug: string;
+    user_can_change: boolean;
+};
+export type DocumentTypeCreate = {
+    matching_algorithm?: MatchingAlgorithm;
+    name: string;
+};
+export type DocumentTypeUpdate = Partial<DocumentTypeCreate>;

package/dist/types/document-types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/documents.d.ts

@@ -0,0 +1,70 @@
+import type { DateString, DateTimeString } from './shared.js';
+export type DocumentNote = {
+    created?: DateTimeString;
+    id: number;
+    note?: string;
+    user?: {
+        email?: string;
+        first_name?: string;
+        id?: number;
+        last_name?: string;
+        username?: string;
+    };
+};
+export type CustomFieldInstance = {
+    field: number;
+    value: null | number | object | string;
+};
+export type DocumentCreate = {
+    archive_serial_number?: number;
+    correspondent?: null | number;
+    created?: DateTimeString;
+    document_type?: null | number;
+    storage_path?: null | number;
+    tags?: number[];
+    title?: string;
+};
+export type DocumentUpdate = {
+    archive_serial_number?: null | number;
+    content?: string;
+    correspondent?: null | number;
+    created?: DateString;
+    document_type?: null | number;
+    storage_path?: null | number;
+    tags?: number[];
+    title?: string;
+};
+export type Document = {
+    added: DateTimeString;
+    archive_serial_number?: null | number;
+    archived_file_name?: null | string;
+    content?: string;
+    correspondent: null | number;
+    created: DateString;
+    created_date?: DateString;
+    custom_fields?: CustomFieldInstance[];
+    deleted_at?: DateTimeString | null;
+    document_type: null | number;
+    id: number;
+    is_shared_by_requester?: boolean;
+    mime_type?: string;
+    modified?: DateTimeString;
+    notes?: DocumentNote[];
+    original_file_name?: null | string;
+    owner?: null | number;
+    page_count?: null | number;
+    permissions?: {
+        change?: {
+            groups?: number[];
+            users?: number[];
+        };
+        view?: {
+            groups?: number[];
+            users?: number[];
+        };
+    };
+    storage_path: null | number;
+    tags: number[];
+    title?: string;
+    user_can_change?: boolean;
+};

package/dist/types/documents.js

@@ -0,0 +1 @@
+export {};

package/dist/types/profile.d.ts

@@ -0,0 +1,15 @@
+export type SocialAccount = {
+    id: number;
+    name: string;
+    provider: string;
+};
+export type Profile = {
+    auth_token: string;
+    email?: string;
+    first_name?: string;
+    has_usable_password: boolean;
+    is_mfa_enabled: boolean;
+    last_name?: string;
+    password?: string;
+    social_accounts: SocialAccount[];
+};

package/dist/types/profile.js

@@ -0,0 +1 @@
+export {};

package/dist/types/shared.d.ts

@@ -0,0 +1,4 @@
+export type MatchingAlgorithm = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export type DataTypeEnum = 'boolean' | 'date' | 'documentlink' | 'float' | 'integer' | 'longtext' | 'monetary' | 'select' | 'string' | 'url';
+export type DateString = `${number}-${number}-${number}`;
+export type DateTimeString = `${number}-${number}-${number}T${number}:${number}:${number}${string}`;

package/dist/types/shared.js

@@ -0,0 +1 @@
+export {};

package/dist/types/tags.d.ts

@@ -0,0 +1,31 @@
+import type { MatchingAlgorithm } from './shared.js';
+type TagBase = {
+    color?: string;
+    document_count: number;
+    id: number;
+    is_inbox_tag?: boolean;
+    is_insensitive?: boolean;
+    match?: string;
+    matching_algorithm?: MatchingAlgorithm;
+    name: string;
+    owner?: null | number;
+    parent?: null | number;
+    slug: string;
+    text_color: string;
+    user_can_change: boolean;
+};
+export type TagCreate = {
+    color?: string;
+    is_inbox_tag?: boolean;
+    matching_algorithm?: MatchingAlgorithm;
+    name: string;
+    parent?: number;
+};
+export type TagUpdate = Partial<TagCreate>;
+export type Tag = TagBase & {
+    children: number[];
+};
+export type TagApi = TagBase & {
+    children: TagApi[];
+};
+export {};

package/dist/types/tags.js

@@ -0,0 +1 @@
+export {};

package/dist/update-command.d.ts

@@ -0,0 +1,28 @@
+import type { ApiFlags } from './base-command.js';
+import { BaseCommand } from './base-command.js';
+type UpdateCommandArgs = {
+    id: number | string;
+};
+type UpdateCommandFlags = ApiFlags & {
+    'date-format': string;
+    plain?: boolean;
+    table?: boolean;
+};
+type UpdateTableRow = {
+    field: string;
+    value: unknown;
+};
+export declare abstract class UpdateCommand<TUpdate = Record<string, unknown>, TRaw extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = TRaw> extends BaseCommand {
+    protected abstract buildPayload(args: unknown, flags: Record<string, unknown>): TUpdate;
+    protected abstract plainTemplate(item: TOutput): null | string | undefined;
+    protected renderUpdateOutput(options: {
+        flags: UpdateCommandFlags;
+        result: TOutput;
+    }): void;
+    run(): Promise<TOutput>;
+    protected transformResult(result: TRaw): TOutput;
+    protected updateId(args: UpdateCommandArgs): number | string;
+    protected abstract updatePath(id: number | string): string;
+    protected updateRows(result: TOutput): UpdateTableRow[];
+}
+export {};

package/dist/update-command.js

@@ -0,0 +1,51 @@
+import { BaseCommand } from './base-command.js';
+import { createValueFormatter, formatField } from './helpers/table.js';
+export class UpdateCommand extends BaseCommand {
+    renderUpdateOutput(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.updateRows(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 id = this.updateId(args);
+        const rawResult = await this.patchApiJson(apiFlags, this.updatePath(id), payload);
+        const result = this.transformResult(rawResult);
+        this.renderUpdateOutput({ flags: outputFlags, result });
+        return result;
+    }
+    transformResult(result) {
+        return result;
+    }
+    updateId(args) {
+        return args.id;
+    }
+    updateRows(result) {
+        return Object.entries(result).map(([field, value]) => ({
+            field,
+            value,
+        }));
+    }
+}