@jinshuju/cli 0.1.1

package/dist/options.js

@@ -0,0 +1,232 @@
+import { readFileSync } from 'node:fs';
+export const OUTPUT_FORMATS = ['text', 'json'];
+/** Accepted by every command. */
+export const GLOBAL_OPTIONS = [
+    { name: '--output', type: 'string', choices: OUTPUT_FORMATS, placeholder: '<format>', description: 'Output format: text, json' },
+    { name: '--config', type: 'string', placeholder: '<path>', description: 'Config file path' },
+    { name: '--help', short: '-h', type: 'boolean', description: 'Show help' },
+    // -V rather than -v: nearly every CLI reads -v as verbose, and a flag that
+    // prints a version where the reader expected more output is a small betrayal.
+    // -v is left unclaimed, so it is free for --verbose if that ever exists.
+    { name: '--version', short: '-V', type: 'boolean', description: 'Show version' }
+];
+/**
+ * What the local commands — auth and config, the ones that never reach the API —
+ * accept on top of the global options. They live here so the command table can
+ * describe them: help is rendered from that table, and a flag nobody can find
+ * in it is a flag nobody knows about.
+ */
+export const LOCAL_OPTIONS = [
+    { name: '--api-key', type: 'string', placeholder: '<key>', description: 'Override API key' },
+    { name: '--api-secret', type: 'string', placeholder: '<secret>', description: 'Override API secret' },
+    { name: '--host', type: 'string', placeholder: '<url>', description: 'API host' },
+    { name: '--auth-host', type: 'string', placeholder: '<url>', description: 'OAuth host' },
+    { name: '--client-id', type: 'string', placeholder: '<id>', description: 'OAuth public client id' },
+    { name: '--scopes', type: 'string', placeholder: '<scopes>', description: 'Space-separated OAuth scopes' },
+    { name: '--no-open', type: 'boolean', description: 'Print the login URL instead of opening a browser' },
+    { name: '--verify', type: 'boolean', description: 'Verify the credentials with a lightweight call' },
+    { name: '--show-secret', type: 'boolean', description: 'Show secrets unmasked' }
+];
+/** The data container a command acts on. Mutually exclusive; both map to form_token. */
+export const CONTAINER_OPTIONS = [
+    { name: '--form', type: 'string', placeholder: '<token>', description: 'Form token, six letters and digits, e.g. Kp7mQ2' },
+    { name: '--table', type: 'string', placeholder: '<token>', description: 'Table token, six letters and digits, e.g. Vn4xR8' }
+];
+/**
+ * The same container, repeatable, for the reads that answer about several at
+ * once. Still one kind per call: `--form` and `--table` stay mutually exclusive.
+ */
+export const CONTAINER_LIST_OPTIONS = [
+    { name: '--form', type: 'string', repeatable: true, placeholder: '<token>', description: 'Form token, repeatable, e.g. Kp7mQ2' },
+    { name: '--table', type: 'string', repeatable: true, placeholder: '<token>', description: 'Table token, repeatable, e.g. Vn4xR8' }
+];
+export const FILTER_OPTION = {
+    name: '--filter',
+    type: 'string',
+    repeatable: true,
+    placeholder: "'<field> <op> [value]'",
+    description: "Filter condition, repeatable, AND-combined. e.g. 'field_3 gte 80', 'created_at within_last 30d', 'field_4 between 1,10'"
+};
+export const FILTERS_OPTION = {
+    name: '--filters',
+    type: 'json',
+    placeholder: '<json|@file>',
+    description: 'Filter conditions as raw JSON, for conditions --filter cannot express'
+};
+export const SORT_OPTION = {
+    name: '--sort',
+    type: 'string',
+    repeatable: true,
+    placeholder: '<field>:asc|desc',
+    description: 'Sort rule, repeatable'
+};
+/** Asks for a smaller page; a listing's default is also its cap. */
+export const LIMIT_OPTION = {
+    name: '--limit', type: 'integer', placeholder: '<n>', description: 'Rows per page, up to the listing default'
+};
+export const PAGINATION_OPTIONS = [
+    LIMIT_OPTION,
+    { name: '--next', type: 'string', placeholder: '<cursor>', description: 'Cursor from the previous response, passed back verbatim' },
+    { name: '--all', type: 'boolean', description: 'Follow the cursor and return every page' }
+];
+export const JSON_OPTION = {
+    name: '--json',
+    type: 'json',
+    placeholder: '<json|@file|->',
+    description: 'JSON payload: inline, @file, or - to read stdin'
+};
+export const MINE_OPTION = {
+    name: '--mine',
+    type: 'boolean',
+    description: 'Switch to what the current user submitted'
+};
+export class UsageError extends Error {
+}
+/** `--api-key` reads back as `api_key`. */
+export function optionKey(spec) {
+    return spec.name.replace(/^--/, '').replace(/-/g, '_');
+}
+const NO_VALUE_OPERATORS = new Set(['null', 'not_null']);
+const PAIR_OPERATORS = new Set(['between', 'not_between']);
+const LIST_OPERATORS = new Set(['any_in', 'none_in']);
+const RELATIVE_UNITS = { d: 'day', w: 'week', m: 'month' };
+/**
+ * `field_3 gte 80` into `{field, operator, value}`.
+ *
+ * Values stay strings. The server converts a condition value by the field's own
+ * type — a number field runs it through to_f — so a phone number keeps its
+ * digits instead of being guessed into a number here. Only the operators whose
+ * value has a shape get one built: a pair, a list, or a relative window.
+ */
+export function parseFilter(input) {
+    const match = /^\s*(\S+)\s+(\S+)\s*(.*)$/.exec(input);
+    if (!match) {
+        throw new UsageError(`--filter must be '<field> <op> [value]', got ${JSON.stringify(input)}`);
+    }
+    const [, field, operator, rest] = match;
+    const raw = rest.trim();
+    if (NO_VALUE_OPERATORS.has(operator)) {
+        if (raw)
+            throw new UsageError(`--filter operator '${operator}' takes no value, got ${JSON.stringify(raw)}`);
+        return { field, operator };
+    }
+    if (!raw)
+        throw new UsageError(`--filter operator '${operator}' needs a value`);
+    if (PAIR_OPERATORS.has(operator)) {
+        const parts = splitList(raw);
+        if (parts.length !== 2) {
+            throw new UsageError(`--filter operator '${operator}' needs two values separated by a comma, got ${JSON.stringify(raw)}`);
+        }
+        return { field, operator, value: parts };
+    }
+    if (LIST_OPERATORS.has(operator))
+        return { field, operator, value: splitList(raw) };
+    if (operator === 'within_last')
+        return { field, operator, value: parseRelativeWindow(raw) };
+    return { field, operator, value: raw };
+}
+/** `30d` into `{unit: 'day', n: 30}`. */
+function parseRelativeWindow(raw) {
+    const match = /^(\d+)\s*([dwm])$/i.exec(raw);
+    if (!match) {
+        throw new UsageError(`--filter within_last needs a window like 30d, 4w or 6m, got ${JSON.stringify(raw)}`);
+    }
+    const n = Number.parseInt(match[1], 10);
+    if (n <= 0)
+        throw new UsageError(`--filter within_last needs a positive window, got ${JSON.stringify(raw)}`);
+    return { unit: RELATIVE_UNITS[match[2].toLowerCase()], n };
+}
+/** A comma-separated list, with backslash-escaped commas kept as text. */
+function splitList(raw) {
+    return raw
+        .split(/(?<!\\),/)
+        .map((part) => part.replace(/\\,/g, ',').trim())
+        .filter((part) => part.length > 0);
+}
+/** `created_at:desc`; the order defaults to asc, as a bare field reads. */
+export function parseSort(input) {
+    const [field, order = 'asc'] = input.split(':');
+    if (!field)
+        throw new UsageError(`--sort must be '<field>:asc|desc', got ${JSON.stringify(input)}`);
+    if (order !== 'asc' && order !== 'desc') {
+        throw new UsageError(`--sort order must be asc or desc, got ${JSON.stringify(order)}`);
+    }
+    return { field, order };
+}
+export const TIME_BUCKETS = ['day', 'week', 'month'];
+/**
+ * `avg:field_3`. Which functions a field takes is the field's own answer — read
+ * `analytics.agg_funcs` off `form get --include-analytics` — so the function is
+ * passed through rather than checked against a list kept here, the same way an
+ * operator is.
+ */
+export function parseMetric(input) {
+    const [func, field] = input.split(':');
+    if (!func || !field)
+        throw new UsageError(`--metric must be '<func>:<field>', got ${JSON.stringify(input)}`);
+    return { func, field };
+}
+/** `field_7`, or `created_at:month` for a date. */
+export function parseDimension(input) {
+    const [field, bucket] = input.split(':');
+    if (!field)
+        throw new UsageError(`--by must be '<field>[:${TIME_BUCKETS.join('|')}]', got ${JSON.stringify(input)}`);
+    if (bucket === undefined)
+        return { field };
+    if (!TIME_BUCKETS.includes(bucket)) {
+        throw new UsageError(`--by bucket must be ${TIME_BUCKETS.join(', ')}, got ${JSON.stringify(bucket)}`);
+    }
+    return { field, bucket };
+}
+// --- json input ------------------------------------------------------------
+/** Inline JSON, `@path`, or `-` for stdin. */
+export function readJsonInput(raw, stdin) {
+    let source = raw;
+    if (raw === '-') {
+        source = stdin();
+    }
+    else if (raw.startsWith('@')) {
+        const path = raw.slice(1);
+        try {
+            source = readFileSync(path, 'utf8');
+        }
+        catch (error) {
+            throw new UsageError(`could not read ${path}: ${error.message}`);
+        }
+    }
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new UsageError(`invalid JSON: ${error.message}`);
+    }
+}
+/**
+ * Both `--form` and `--table` address the same API parameter, so exactly one has
+ * to be given: a command that guessed would read the wrong object silently.
+ */
+export function resolveContainer(options) {
+    const form = options.form;
+    const table = options.table;
+    if (form && table)
+        throw new UsageError('--form and --table are mutually exclusive');
+    if (form)
+        return { token: form, kind: 'form' };
+    if (table)
+        return { token: table, kind: 'table' };
+    throw new UsageError('one of --form <token> or --table <token> is required');
+}
+/** The repeatable form of the above, for a read that answers about several. */
+export function resolveContainers(options, max) {
+    const forms = options.form ?? [];
+    const tables = options.table ?? [];
+    if (forms.length > 0 && tables.length > 0)
+        throw new UsageError('--form and --table are mutually exclusive');
+    const tokens = forms.length > 0 ? forms : tables;
+    if (tokens.length === 0)
+        throw new UsageError('one of --form <token> or --table <token> is required');
+    if (tokens.length > max) {
+        throw new UsageError(`at most ${max} containers can be asked about in one call, got ${tokens.length}`);
+    }
+    return { tokens, kind: forms.length > 0 ? 'form' : 'table' };
+}

package/dist/payload.d.ts

@@ -0,0 +1,12 @@
+export type FormCreatePayload = {
+    name: string;
+    description?: string;
+    fields: Array<Record<string, unknown> & {
+        type: string;
+        label?: string;
+    }>;
+    setting?: Record<string, unknown>;
+    folder_token?: string;
+};
+export declare function parseJsonPayload(value: string): unknown;
+export declare function validateCreateFormPayload(payload: unknown): FormCreatePayload;

package/dist/payload.js

@@ -0,0 +1,59 @@
+const API_V1_FIELD_TYPES = new Set([
+    'TextField', 'TextArea', 'NumberField', 'EmailField', 'MobileField', 'TelephoneField', 'IdCardField',
+    'NameField', 'AddressField', 'LinkField', 'GeoField', 'AttachmentField', 'DateTimeField', 'TimeField',
+    'RatingField', 'NpsField', 'RadioButton', 'CheckBox', 'DropDown', 'TableField', 'CascadeDropDown',
+    'SortField', 'LikertField', 'MatrixField', 'MatrixScaleField', 'ImageRadioButton', 'ImageCheckBox',
+    'GoodsField', 'FormulaField', 'ReservationField', 'FormAssociation', 'ESignatureField', 'AudioField',
+    'PageBreak', 'SectionBreak', 'WidgetButton', 'WidgetContact', 'WidgetMap', 'WidgetMarquee'
+]);
+/**
+ * The question types only a scorable scene has. They are not Fields::* classes
+ * of their own — each persists as a base field plus a customized_type and the
+ * correct answers — which is why they are absent from the list above and were
+ * being refused here: `--type exam` could create an exam-scene form and then
+ * not one question that scores, the only thing the scene is for.
+ *
+ * Which scene accepts which is the server's answer, and it names them in the
+ * refusal; there is nothing to duplicate here beyond letting them through.
+ */
+const SCENE_FIELD_TYPES = new Set([
+    'SingleSelect', 'MultiSelect', 'ImageSingleSelect', 'ImageMultiSelect', 'TrueOrFalse', 'DropDownSelect',
+    'FillInBlank', 'ShortAnswer', 'FillInNumber', 'Rating', 'Nps',
+    'Department', 'Grade'
+]);
+export function parseJsonPayload(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON payload: ${error.message}`);
+    }
+}
+export function validateCreateFormPayload(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new Error('Form payload must be a JSON object');
+    }
+    const form = payload;
+    if (typeof form.name !== 'string' || form.name.trim() === '') {
+        throw new Error('Form payload requires non-empty name');
+    }
+    if (!Array.isArray(form.fields) || form.fields.length === 0) {
+        throw new Error('Form payload requires at least one field');
+    }
+    for (const field of form.fields) {
+        if (!field || typeof field !== 'object' || Array.isArray(field)) {
+            throw new Error('Each field must be an object');
+        }
+        const fieldObject = field;
+        if ('api_code' in fieldObject) {
+            throw new Error('Do not pass api_code when creating fields; backend generates it');
+        }
+        if (typeof fieldObject.type !== 'string' || !(API_V1_FIELD_TYPES.has(fieldObject.type) || SCENE_FIELD_TYPES.has(fieldObject.type))) {
+            throw new Error(`Field type must be an API v1 field type, got ${String(fieldObject.type)}`);
+        }
+        if (typeof fieldObject.label !== 'string' && fieldObject.type !== 'PageBreak') {
+            throw new Error('Each field requires label');
+        }
+    }
+    return form;
+}

package/dist/progress.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Progress for the person watching, and nothing for anyone else.
+ *
+ * It writes to stderr and only when stderr is a terminal. That is what lets a
+ * command say "uploading…" to someone waiting at a prompt while `--output json
+ * | jq` stays byte-for-byte what it was, and while an agent reading the pipe
+ * sees no decoration it would have to strip.
+ *
+ * A step overwrites the line before it, so a long run stays one line rather
+ * than a scroll of near-identical ones. done() clears whatever is left.
+ */
+export interface Progress {
+    step(message: string): void;
+    done(): void;
+}
+export declare function progress(stream?: NodeJS.WriteStream): Progress;

package/dist/progress.js

@@ -0,0 +1,17 @@
+const SILENT = { step: () => { }, done: () => { } };
+export function progress(stream = process.stderr) {
+    if (!stream.isTTY)
+        return SILENT;
+    let width = 0;
+    return {
+        step(message) {
+            stream.write(`\r${' '.repeat(width)}\r${message}`);
+            width = message.length;
+        },
+        done() {
+            if (width > 0)
+                stream.write(`\r${' '.repeat(width)}\r`);
+            width = 0;
+        }
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@jinshuju/cli",
+  "version": "0.1.1",
+  "description": "Command line interface for Jinshuju Open API v1",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jinshuju/cli.git"
+  },
+  "homepage": "https://github.com/jinshuju/cli#readme",
+  "bugs": {
+    "url": "https://github.com/jinshuju/cli/issues"
+  },
+  "type": "module",
+  "bin": {
+    "jinshuju": "dist/cli-bin.js",
+    "jsj": "dist/cli-bin.js"
+  },
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json && chmod +x dist/cli-bin.js",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test dist/*.test.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}