@jinshuju/cli 0.1.1

package/dist/config.d.ts

@@ -0,0 +1,64 @@
+export type ConfigKey = 'access_token' | 'api_key' | 'api_secret' | 'host' | 'auth_host' | 'client_id';
+export type ConfigSource = 'cli' | 'env' | 'file' | 'missing';
+export type OAuthConfig = {
+    type: 'oauth';
+    auth_host: string;
+    client_id: string;
+    access_token: string;
+    refresh_token?: string;
+    expires_at?: string;
+    scope?: string;
+};
+export type LoadedConfig = {
+    /**
+     * A personal or account access token, sent as a bearer. Goldendata accepts it
+     * on API v1 alongside the API key pair and an OAuth session.
+     */
+    accessToken?: string;
+    apiKey?: string;
+    apiSecret?: string;
+    host: string;
+    authHost: string;
+    clientId?: string;
+    auth?: OAuthConfig;
+    configPath: string;
+    sources: {
+        accessToken: ConfigSource;
+        apiKey: ConfigSource;
+        apiSecret: ConfigSource;
+        host: ConfigSource;
+        authHost: ConfigSource;
+        clientId: ConfigSource;
+        auth: ConfigSource;
+    };
+};
+export type LoadConfigOptions = {
+    configPath?: string;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+    cli?: {
+        accessToken?: string;
+        apiKey?: string;
+        apiSecret?: string;
+        host?: string;
+        authHost?: string;
+        clientId?: string;
+    };
+};
+export declare const defaultConfigPath: string;
+export declare const defaultHost = "https://jinshuju.net";
+export declare const defaultAuthHost = "https://account.jinshuju.net";
+export declare const defaultOAuthClientId = "jinshuju_cli_public";
+export declare const defaultScopes = "public forms read_entries write_entries form_setting read_contacts users";
+export type RawConfig = Partial<Record<ConfigKey, string>> & {
+    auth?: OAuthConfig;
+};
+export declare function loadConfig(options?: LoadConfigOptions): LoadedConfig;
+export declare function setConfigValue(configPath: string, key: ConfigKey, value: string): void;
+export declare function unsetConfigValue(configPath: string, key: ConfigKey): void;
+export declare function saveOAuthConfig(configPath: string, auth: OAuthConfig): void;
+export declare function clearOAuthConfig(configPath: string): void;
+export declare function getConfig(configPath: string): RawConfig;
+export declare function maskSecret(value: string | undefined): string | undefined;
+/** Every key the config file holds, in the order help should list them. */
+export declare const CONFIG_KEYS: readonly ConfigKey[];
+export declare function assertConfigKey(value: string): asserts value is ConfigKey;

package/dist/config.js

@@ -0,0 +1,99 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export const defaultConfigPath = join(homedir(), '.jinshuju', 'config.json');
+export const defaultHost = 'https://jinshuju.net';
+export const defaultAuthHost = 'https://account.jinshuju.net';
+export const defaultOAuthClientId = 'jinshuju_cli_public';
+export const defaultScopes = 'public forms read_entries write_entries form_setting read_contacts users';
+function readConfigFile(configPath) {
+    if (!existsSync(configPath))
+        return {};
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+}
+function writeConfigFile(configPath, config) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+function pickValue(cliValue, envValue, fileValue, fallback) {
+    if (cliValue)
+        return { value: cliValue, source: 'cli' };
+    if (envValue)
+        return { value: envValue, source: 'env' };
+    if (fileValue)
+        return { value: fileValue, source: 'file' };
+    if (fallback)
+        return { value: fallback, source: 'missing' };
+    return { source: 'missing' };
+}
+export function loadConfig(options = {}) {
+    const configPath = options.configPath ?? defaultConfigPath;
+    const env = options.env ?? process.env;
+    const file = readConfigFile(configPath);
+    const accessToken = pickValue(options.cli?.accessToken, env.JINSHUJU_ACCESS_TOKEN, file.access_token);
+    const apiKey = pickValue(options.cli?.apiKey, env.JINSHUJU_API_KEY, file.api_key);
+    const apiSecret = pickValue(options.cli?.apiSecret, env.JINSHUJU_API_SECRET, file.api_secret);
+    const host = pickValue(options.cli?.host, env.JINSHUJU_HOST, file.host, defaultHost);
+    const authHost = pickValue(options.cli?.authHost, env.JINSHUJU_AUTH_HOST, file.auth_host ?? file.auth?.auth_host, defaultAuthHost);
+    const defaultClientId = authHost.value === defaultAuthHost ? defaultOAuthClientId : undefined;
+    const clientId = pickValue(options.cli?.clientId, env.JINSHUJU_OAUTH_CLIENT_ID, file.client_id ?? file.auth?.client_id, defaultClientId);
+    const auth = file.auth?.type === 'oauth' ? file.auth : undefined;
+    return {
+        accessToken: accessToken.value,
+        apiKey: apiKey.value,
+        apiSecret: apiSecret.value,
+        host: host.value,
+        authHost: authHost.value,
+        clientId: clientId.value,
+        auth,
+        configPath,
+        sources: {
+            accessToken: accessToken.source,
+            apiKey: apiKey.source,
+            apiSecret: apiSecret.source,
+            host: host.source,
+            authHost: authHost.source,
+            clientId: clientId.source,
+            auth: auth ? 'file' : 'missing'
+        }
+    };
+}
+export function setConfigValue(configPath, key, value) {
+    const config = readConfigFile(configPath);
+    config[key] = value;
+    writeConfigFile(configPath, config);
+}
+export function unsetConfigValue(configPath, key) {
+    const config = readConfigFile(configPath);
+    delete config[key];
+    writeConfigFile(configPath, config);
+}
+export function saveOAuthConfig(configPath, auth) {
+    const config = readConfigFile(configPath);
+    config.auth = auth;
+    config.auth_host = auth.auth_host;
+    config.client_id = auth.client_id;
+    writeConfigFile(configPath, config);
+}
+export function clearOAuthConfig(configPath) {
+    const config = readConfigFile(configPath);
+    delete config.auth;
+    writeConfigFile(configPath, config);
+}
+export function getConfig(configPath) {
+    return readConfigFile(configPath);
+}
+export function maskSecret(value) {
+    if (!value)
+        return undefined;
+    if (value.length <= 8)
+        return '••••';
+    return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+/** Every key the config file holds, in the order help should list them. */
+export const CONFIG_KEYS = ['access_token', 'api_key', 'api_secret', 'host', 'auth_host', 'client_id'];
+export function assertConfigKey(value) {
+    if (!CONFIG_KEYS.includes(value)) {
+        throw new Error(`Config key must be one of ${CONFIG_KEYS.join(', ')}`);
+    }
+}

package/dist/help.d.ts

@@ -0,0 +1,15 @@
+import { type Command } from './commands.js';
+/**
+ * Help is rendered from the command table, so a command cannot be reachable
+ * without appearing here, and a flag cannot be accepted without being
+ * described. The root help lists one line per resource, then the global
+ * options.
+ */
+export declare function rootHelp(commands?: readonly Command[]): string;
+/** Every verb of one resource, for `jinshuju form --help`. */
+export declare function resourceHelp(resource: string, commands?: readonly Command[]): string;
+export declare function commandHelp(command: Command): string;
+/** What the caller typed that matched nothing, and the nearest things that do. */
+export declare function unknownCommandHelp(words: readonly string[], commands?: readonly Command[]): string;
+/** Help for whatever the words point at: a command, a resource, or the root. */
+export declare function helpFor(words: readonly string[], commands?: readonly Command[]): string;

package/dist/help.js

@@ -0,0 +1,98 @@
+import { COMMANDS, RESOURCES, findCommand } from './commands.js';
+import { GLOBAL_OPTIONS, optionKey } from './options.js';
+/**
+ * Help is rendered from the command table, so a command cannot be reachable
+ * without appearing here, and a flag cannot be accepted without being
+ * described. The root help lists one line per resource, then the global
+ * options.
+ */
+export function rootHelp(commands = COMMANDS) {
+    const present = new Set(commands.map((command) => command.path[0]));
+    const resources = RESOURCES.filter((resource) => present.has(resource.name) || resource.name === 'auth' || resource.name === 'config');
+    const width = Math.max(...resources.map((resource) => resource.name.length)) + 4;
+    return [
+        'Usage: jinshuju <resource> <verb> [args] [flags]',
+        '',
+        'Commands:',
+        ...resources.map((resource) => `  ${resource.name.padEnd(width)}${resource.summary}`),
+        '',
+        'Global Options:',
+        ...GLOBAL_OPTIONS.map((option) => `  ${flagLabel(option).padEnd(width + 12)}${option.description}`),
+        '',
+        'Run `jinshuju <resource> --help` to see its verbs.',
+        ''
+    ].join('\n');
+}
+/** Every verb of one resource, for `jinshuju form --help`. */
+export function resourceHelp(resource, commands = COMMANDS) {
+    const owned = commands.filter((command) => command.path[0] === resource);
+    if (owned.length === 0)
+        return rootHelp(commands);
+    const width = Math.max(...owned.map((command) => command.path.join(' ').length)) + 4;
+    return [
+        `Usage: jinshuju ${resource} <verb> [args] [flags]`,
+        '',
+        'Commands:',
+        ...owned.map((command) => `  ${command.path.join(' ').padEnd(width)}${command.summary}`),
+        '',
+        `Run \`jinshuju ${resource} <verb> --help\` for one of them.`,
+        ''
+    ].join('\n');
+}
+export function commandHelp(command) {
+    const usage = [
+        'Usage: jinshuju',
+        ...command.path,
+        ...(command.args ?? []).map((arg) => {
+            const name = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+            return arg.variadic ? `${name}...` : name;
+        }),
+        '[flags]'
+    ].join(' ');
+    const parts = [usage, '', command.description ?? command.summary];
+    if (command.args?.length) {
+        const width = Math.max(...command.args.map((arg) => arg.name.length)) + 4;
+        parts.push('', 'Arguments:', ...command.args.map((arg) => `  ${arg.name.padEnd(width)}${arg.description}`));
+    }
+    const options = [...(command.options ?? []), ...GLOBAL_OPTIONS];
+    const width = Math.max(...options.map((option) => flagLabel(option).length)) + 4;
+    parts.push('', 'Flags:', ...options.map((option) => `  ${flagLabel(option).padEnd(width)}${option.description}`));
+    if (command.payload?.length)
+        parts.push('', 'Payload:', ...command.payload.map((line) => `  ${line}`));
+    if (command.examples?.length)
+        parts.push('', 'Examples:', ...command.examples.map((example) => `  ${example}`));
+    return `${parts.join('\n')}\n`;
+}
+/** What the caller typed that matched nothing, and the nearest things that do. */
+export function unknownCommandHelp(words, commands = COMMANDS) {
+    const typed = words.join(' ');
+    const resource = words[0];
+    const siblings = commands.filter((command) => command.path[0] === resource).slice(0, 10);
+    return [
+        `Unknown command: jinshuju ${typed}`,
+        ...(siblings.length > 0
+            ? ['', 'Did you mean:', ...siblings.map((command) => `  jinshuju ${command.path.join(' ')}`)]
+            : []),
+        '',
+        'Run `jinshuju --help` for the full list.',
+        ''
+    ].join('\n');
+}
+/** Help for whatever the words point at: a command, a resource, or the root. */
+export function helpFor(words, commands = COMMANDS) {
+    if (words.length === 0)
+        return rootHelp(commands);
+    const command = findCommand(words, commands);
+    if (command)
+        return commandHelp(command);
+    const resource = words[0];
+    if (commands.some((candidate) => candidate.path[0] === resource))
+        return resourceHelp(resource, commands);
+    return rootHelp(commands);
+}
+function flagLabel(option) {
+    const flags = option.short ? `${option.short}, ${option.name}` : option.name;
+    if (option.type === 'boolean')
+        return flags;
+    return `${flags} ${option.placeholder ?? `<${optionKey(option)}>`}`;
+}

package/dist/http.d.ts

@@ -0,0 +1,29 @@
+import { type LoadedConfig } from './config.js';
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+export type HttpRequest = {
+    method: HttpMethod | string;
+    path: string;
+    body?: unknown;
+    /**
+     * A multipart body, for the three endpoints that take a file. fetch sets its
+     * own Content-Type here, boundary included, so the JSON one must not be sent.
+     */
+    form?: FormData;
+};
+export interface HttpClient {
+    request<T>(request: HttpRequest): Promise<T>;
+}
+export declare class JinshujuHttpClient implements HttpClient {
+    private config;
+    private readonly baseUrl;
+    constructor(config?: LoadedConfig, baseUrl?: string);
+    request<T>(request: HttpRequest): Promise<T>;
+    private requestWithAuth;
+    /**
+     * An explicitly configured credential outranks a stored session: someone who
+     * set a token in the environment meant this request to use it, and finding a
+     * login from last week used instead would be a surprise with no signal.
+     * `auth status` says which one is in play and where it came from.
+     */
+    private authorizationHeader;
+}

package/dist/http.js

@@ -0,0 +1,127 @@
+import { loadConfig } from './config.js';
+import { refreshOAuthToken, shouldRefresh } from './auth.js';
+/** How much of an unexpected body is worth putting in front of a reader. */
+const MAX_SNIPPET = 200;
+function parseBody(text) {
+    if (!text)
+        return { json: true, value: undefined };
+    try {
+        return { json: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { json: false };
+    }
+}
+function snippet(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length <= MAX_SNIPPET ? flat : `${flat.slice(0, MAX_SNIPPET)}…`;
+}
+/**
+ * What to say about a request the server refused.
+ *
+ * A server that stated a reason has it repeated verbatim, which is the whole of
+ * the message and reads as it always did. Everything else falls back through
+ * what the body does carry rather than to the HTTP status text: answering
+ * "Unprocessable Entity" to a batch whose response named the offending row and
+ * field is throwing away the only useful part of the answer.
+ */
+function describeFailure(response, text, parsed) {
+    const status = `${response.status} ${response.statusText}`.trim();
+    if (!parsed.json) {
+        return text.trim() ? `${status}, and the body is not JSON: ${snippet(text)}` : status;
+    }
+    if (parsed.value === undefined || parsed.value === null)
+        return status;
+    const body = parsed.value;
+    const stated = body.message ?? body.error_description;
+    if (typeof stated === 'string' && stated.trim())
+        return stated;
+    return rowErrors(body) ?? `${status}: ${snippet(JSON.stringify(parsed.value))}`;
+}
+/**
+ * A batch write answers per row: `{errors: [{index, reason}]}`. The index is the
+ * caller's own array position, and is left as the server gave it so it lines up
+ * with both the payload that was sent and what `--output json` shows.
+ */
+function rowErrors(body) {
+    const errors = body.errors;
+    if (!Array.isArray(errors) || errors.length === 0)
+        return undefined;
+    const lines = errors.map((item) => {
+        if (typeof item === 'string')
+            return item;
+        if (item === null || typeof item !== 'object')
+            return String(item);
+        const { index, reason, message } = item;
+        const said = [reason, message].find((value) => typeof value === 'string' && value.trim());
+        const text = said ?? JSON.stringify(item);
+        return typeof index === 'number' ? `row ${index}: ${text}` : text;
+    });
+    return `${lines.length} row${lines.length === 1 ? '' : 's'} rejected — ${lines.join('; ')}`;
+}
+export class JinshujuHttpClient {
+    config;
+    baseUrl;
+    constructor(config = loadConfig(), baseUrl = config.host) {
+        this.config = config;
+        this.baseUrl = baseUrl;
+    }
+    async request(request) {
+        return this.requestWithAuth(request, true);
+    }
+    async requestWithAuth(request, allowRefresh) {
+        const headers = {
+            Authorization: await this.authorizationHeader(),
+            Accept: 'application/json'
+        };
+        if (!request.form)
+            headers['Content-Type'] = 'application/json';
+        const response = await fetch(`${this.baseUrl}${request.path}`, {
+            method: request.method,
+            headers,
+            body: request.form ?? (request.body === undefined ? undefined : JSON.stringify(request.body))
+        });
+        // Only an OAuth session can be refreshed; an access token that stopped
+        // working has to be replaced by whoever issued it.
+        if (response.status === 401 && allowRefresh && !this.config.accessToken && this.config.auth?.refresh_token) {
+            this.config.auth = await refreshOAuthToken(this.config);
+            return this.requestWithAuth(request, false);
+        }
+        const text = await response.text();
+        const parsed = parseBody(text);
+        // Parsing is not allowed to decide whether the request failed. A 500 answers
+        // with an HTML error page and a gateway with its own, and parsing first
+        // turned both into "Unexpected token '<'", throwing away the status that was
+        // the only thing that said what had happened.
+        if (!response.ok) {
+            const error = new Error(describeFailure(response, text, parsed));
+            Object.assign(error, { status: response.status, body: parsed.json ? parsed.value : text });
+            throw error;
+        }
+        if (!parsed.json) {
+            throw new Error(`${response.status} ${response.statusText}, but the body is not JSON: ${snippet(text)}`);
+        }
+        return parsed.value;
+    }
+    /**
+     * An explicitly configured credential outranks a stored session: someone who
+     * set a token in the environment meant this request to use it, and finding a
+     * login from last week used instead would be a surprise with no signal.
+     * `auth status` says which one is in play and where it came from.
+     */
+    async authorizationHeader() {
+        if (this.config.accessToken)
+            return `Bearer ${this.config.accessToken}`;
+        if (this.config.apiKey && this.config.apiSecret) {
+            const credentials = Buffer.from(`${this.config.apiKey}:${this.config.apiSecret}`).toString('base64');
+            return `Basic ${credentials}`;
+        }
+        if (this.config.auth?.access_token) {
+            if (shouldRefresh(this.config.auth) && this.config.auth.refresh_token) {
+                this.config.auth = await refreshOAuthToken(this.config);
+            }
+            return `Bearer ${this.config.auth.access_token}`;
+        }
+        throw new Error('Missing authentication. Run `jinshuju auth login`, or configure JINSHUJU_ACCESS_TOKEN, or JINSHUJU_API_KEY with JINSHUJU_API_SECRET.');
+    }
+}

package/dist/options.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The shared option grammar, written once here because every resource uses it:
+ * container, filter, sort, pagination, JSON input and output format.
+ */
+export type OptionType = 'string' | 'integer' | 'boolean' | 'json' | 'list';
+export interface OptionSpec {
+    /** Long flag with dashes, e.g. `--filter`. */
+    readonly name: string;
+    readonly short?: string;
+    readonly type: OptionType;
+    /** May be given more than once; values collect into a list. */
+    readonly repeatable?: boolean;
+    /** Placeholder shown in help, e.g. `<field> <op> [value]`. */
+    readonly placeholder?: string;
+    readonly choices?: readonly string[];
+    readonly description: string;
+}
+export declare const OUTPUT_FORMATS: readonly ["text", "json"];
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+/** Accepted by every command. */
+export declare const GLOBAL_OPTIONS: readonly OptionSpec[];
+/**
+ * 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 declare const LOCAL_OPTIONS: readonly OptionSpec[];
+/** The data container a command acts on. Mutually exclusive; both map to form_token. */
+export declare const CONTAINER_OPTIONS: readonly OptionSpec[];
+/**
+ * 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 declare const CONTAINER_LIST_OPTIONS: readonly OptionSpec[];
+export declare const FILTER_OPTION: OptionSpec;
+export declare const FILTERS_OPTION: OptionSpec;
+export declare const SORT_OPTION: OptionSpec;
+/** Asks for a smaller page; a listing's default is also its cap. */
+export declare const LIMIT_OPTION: OptionSpec;
+export declare const PAGINATION_OPTIONS: readonly OptionSpec[];
+export declare const JSON_OPTION: OptionSpec;
+export declare const MINE_OPTION: OptionSpec;
+export declare class UsageError extends Error {
+}
+/** `--api-key` reads back as `api_key`. */
+export declare function optionKey(spec: OptionSpec): string;
+export interface FilterCondition {
+    readonly field: string;
+    readonly operator: string;
+    readonly value?: unknown;
+}
+/**
+ * `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 declare function parseFilter(input: string): FilterCondition;
+export interface SortRule {
+    readonly field: string;
+    readonly order: 'asc' | 'desc';
+}
+/** `created_at:desc`; the order defaults to asc, as a bare field reads. */
+export declare function parseSort(input: string): SortRule;
+export interface Metric {
+    readonly func: string;
+    readonly field: string;
+}
+export interface Dimension {
+    readonly field: string;
+    readonly bucket?: string;
+}
+export declare const TIME_BUCKETS: readonly ["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 declare function parseMetric(input: string): Metric;
+/** `field_7`, or `created_at:month` for a date. */
+export declare function parseDimension(input: string): Dimension;
+/** Inline JSON, `@path`, or `-` for stdin. */
+export declare function readJsonInput(raw: string, stdin: () => string): unknown;
+export interface Container {
+    readonly token: string;
+    readonly kind: 'form' | 'table';
+}
+/**
+ * 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 declare function resolveContainer(options: Record<string, unknown>): Container;
+export interface Containers {
+    readonly tokens: readonly string[];
+    readonly kind: 'form' | 'table';
+}
+/** The repeatable form of the above, for a read that answers about several. */
+export declare function resolveContainers(options: Record<string, unknown>, max: number): Containers;