@jinshuju/cli 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,311 @@
+# @jinshuju/cli
+
+Command-line interface for the Jinshuju Open API v1.
+
+## Install
+
+```bash
+npm install -g @jinshuju/cli
+```
+
+Two equivalent entry points are installed:
+
+```bash
+jinshuju --help
+jsj --help
+```
+
+## Working on the CLI itself
+
+```bash
+npm install
+npm link          # jinshuju / jsj now resolve to your checkout
+```
+
+If `npm link` leaves you with `permission denied`, `dist/cli-bin.js` has lost
+its execute bit — `npm run build` restores it.
+
+## Authentication
+
+Three kinds of credential are supported: an access token (personal or account),
+an API key and secret pair, and an interactive browser login.
+
+Write them to the config file (`~/.jinshuju/config.json`, mode 600):
+
+```bash
+jinshuju config set access_token xxx     # access token
+jinshuju config set api_key xxx          # or API key / secret
+jinshuju config set api_secret xxx
+```
+
+Environment variables work just as well, which suits CI and scripts:
+
+```bash
+export JINSHUJU_ACCESS_TOKEN=xxx
+# or
+export JINSHUJU_API_KEY=xxx
+export JINSHUJU_API_SECRET=xxx
+```
+
+The **precedence** is access token, then API key and secret, then a stored
+browser login (`jinshuju auth login`). An explicitly configured credential
+always beats a stored session: setting a token and then acting as last week's
+login is a surprise nobody wants. `jinshuju auth status` reports which
+credential is in use and where it came from:
+
+```
+$ jinshuju auth status
+Authenticated with an access token (from env).
+```
+
+Access tokens are masked in `config get` like any other secret; pass
+`--show-secret` for the full value.
+
+## Creating forms
+
+Field types use the API v1 type names. Do not supply `api_code` when creating a
+field — the server assigns it.
+
+```bash
+jinshuju form create --json @form.json --scene registry --layout card --folder Fd2xK8
+jinshuju form create --json @exam.json --type exam        # the payload may carry exam_setting
+jinshuju form edit Kp7mQ2 --json '{"exam_setting":{"limited_time":45}}'
+
+jinshuju form create --json '{
+  "name": "Event signup",
+  "fields": [
+    { "type": "TextField", "label": "Name", "required": true },
+    { "type": "MobileField", "label": "Mobile", "required": true }
+  ]
+}'
+```
+
+`--type exam` and `--type evaluation` select both the scene and the settings
+block that belongs to it. That settings block has an endpoint of its own, so a
+payload carrying it becomes two requests — and the general form update does not
+recognise the key at all (it reads only `name`, `description`, `setting`,
+`fields` and `field_rules`), so without the dispatch `exam_setting` would be
+dropped in silence.
+
+The settings block is always sent first. It is the half that can be rejected —
+"this is not an exam form" — and sending it first is what guarantees a rejection
+leaves every other change unsent.
+
+## Reading data
+
+`entry`, `view`, `field` and `comment` are all top-level resources; the
+container is given by `--form` or `--table` (mutually exclusive, both mapping to
+the API's `form_token`).
+
+```bash
+jinshuju entry list --form Kp7mQ2
+jinshuju entry list --table Vn4xR8
+jinshuju entry get 1 --form Kp7mQ2
+jinshuju entry list --form Kp7mQ2 --view aB3dE9
+```
+
+Filtering, sorting and paging:
+
+```bash
+jinshuju entry list --form Kp7mQ2 --filter 'field_3 gte 80'
+jinshuju entry list --form Kp7mQ2 --filter 'created_at within_last 30d' --filter 'field_9 not_null'
+jinshuju entry list --form Kp7mQ2 --sort created_at:desc
+jinshuju entry list --form Kp7mQ2 --limit 10
+jinshuju entry list --form Kp7mQ2 --all
+```
+
+`--limit` can only ask for less: a listing's default page size is also its
+maximum (50 in most cases), and anything larger is capped.
+
+`--filter` is repeatable and the conditions are AND-combined. For conditions it
+cannot express, use `--filters <json|@file>`. Cursors are opaque strings — pass
+the `next` value from the previous response back verbatim.
+
+## Analysis
+
+There is no need to pull rows out and count them yourself. Counts, aggregates
+and profiles are computed server-side, and the size of the response depends only
+on how many metrics you asked for and how many groups came back.
+
+```bash
+jinshuju entry count --form Kp7mQ2 --filter 'field_3 gte 80'
+jinshuju entry count --form Kp7mQ2 --form Vn4xR8            # repeatable, up to 10 containers
+
+jinshuju entry aggregate --form Kp7mQ2 --metric avg:field_3
+jinshuju entry aggregate --form Kp7mQ2 --metric count:field_1 --by created_at:month --limit 12
+
+jinshuju entry summary --form Kp7mQ2
+jinshuju entry summary --form Kp7mQ2 --fields field_3,field_7 --no-overview
+```
+
+`--metric <func>:<field>` is repeatable, 1–20 of them; `--by <field>[:day|week|month]`
+takes at most 2, and a date dimension must name a bucket. Which functions a
+field accepts is the field's own answer — read `analytics.agg_funcs` from
+`form get`.
+
+A multi-container count takes no `--keyword`, and its `--filter` is limited to
+`created_at`, `updated_at` and `creator_id`: the same api_code names a different
+field in every container, so comparing across them would mean nothing.
+
+## Creating entries
+
+Payload keys are field `api_code`s, not field labels. `--json` accepts inline
+JSON, `@file`, and `-` for stdin.
+
+```bash
+jinshuju entry create --form Kp7mQ2 --json '{
+  "field_1": "Alice",
+  "field_2": "13800138000"
+}'
+
+jinshuju entry create --form Kp7mQ2 --json @entry.json
+cat entry.json | jinshuju entry create --form Kp7mQ2 --json -
+```
+
+## Writing
+
+Apart from the settings-block dispatch described above, every write command
+issues exactly one request, and payload keys are field `api_code`s.
+
+```bash
+jinshuju folder create Ledgers --kind table       # folders are form or table; a table cannot go in a form folder
+jinshuju form edit Kp7mQ2 --json '{"name":"2026 signups"}'
+jinshuju form copy Kp7mQ2 --name Copy
+jinshuju form move Kp7mQ2 --folder Fd2xK8         # without --folder, moves it out of its folder
+jinshuju form theme set Kp7mQ2 --primary-color "#1F6FEB"
+jinshuju table create --json @table.json --folder Nf7mDC
+jinshuju table edit Vn4xR8 --json '{"name":"2026 ledger"}'
+```
+
+Adding, changing and removing fields all land on a single PATCH of the
+container:
+
+```bash
+jinshuju field add --form Kp7mQ2 --json '{"type":"TextField","label":"Notes"}'
+jinshuju field update --form Kp7mQ2 field_3 --json '{"required":true}'
+jinshuju field update-choices --form Kp7mQ2 field_7 --json '{"add":[{"label":"Third"}]}'
+jinshuju field remove --form Kp7mQ2 field_9 --yes
+```
+
+Data and views:
+
+```bash
+jinshuju entry create --form Kp7mQ2 --batch @entries.json
+jinshuju entry update --form Kp7mQ2 12 --json '{"field_2":99}'                 # merge
+jinshuju entry update --form Kp7mQ2 12 --replace --json '{"field_1":"Bob"}'    # replace; omitted fields are cleared
+jinshuju entry update --form Kp7mQ2 --batch @rows.json                         # [{serial_number, entry}]
+jinshuju entry delete --form Kp7mQ2 12 --yes
+
+jinshuju view create --form Kp7mQ2 "High scores" --filter 'field_3 gte 80' --sort created_at:desc
+jinshuju comment create --form Kp7mQ2 --entry 12 "Contacted, awaiting reply"
+jinshuju opensearch edit Qy7nR3 --disable
+```
+
+Deletion always requires `--yes`. This CLI is non-interactive — stdin belongs to
+`--json -` — so confirmation is a flag: without it nothing is deleted, rather
+than a prompt nobody is there to answer.
+
+## Searching across containers
+
+```bash
+jinshuju entry search "Acme Corp"                     # every form and table you can read, up to 10
+jinshuju entry search 13800138000 --form Kp7mQ2 --form Vn4xR8
+jinshuju entry search repair --scope-filter 'entries_count gt 100'   # picks which forms to search, not which rows
+
+jinshuju entry stats --from 2026-09-01                # how much each form received in the period
+jinshuju entry stats --from 2026-09-01 --to 2026-09-07 --kind form --limit 10
+```
+
+A form that could not be searched stays in the result **with the reason**,
+rather than being dropped as if it had matched nothing — "not searched" and
+"nothing there" are different answers.
+
+`entry stats` and `entry count` measure different things: the former is how much
+arrived (an import counts on the day it ran, and deletions are not subtracted),
+the latter is how much is there now.
+
+## Your own submissions
+
+```bash
+jinshuju form list --mine                      # forms you filled in, not forms you own
+jinshuju entry list --form Kp7mQ2 --mine       # what you submitted to this form
+jinshuju entry search "Acme Corp" --mine        # search your own submissions
+```
+
+The scope is pinned to your own submissions: you cannot read anyone else's, and
+you need no permission on the form itself. Flags that only make sense from an
+owner's point of view (`--sort`, `--view`, `--scope-filter` and the like) are
+rejected when combined with `--mine`.
+
+## Working with files
+
+Three commands take a file. The CLI uploads with its own credential; there is no
+ticket to fetch first.
+
+```bash
+jinshuju entry import --form Kp7mQ2 ./signups.xlsx --map field_1=Name --map field_2=Mobile
+jinshuju entry import --table Vn4xR8 ./rows.csv --map field_1=1 --map field_2=2 --header-row 2 --unique field_1
+
+jinshuju entry create --form Kp7mQ2 --json '{"field_1":"Alice"}' --attach field_5=./id-card.jpg
+jinshuju form theme set Kp7mQ2 --wallpaper ./bg.png
+```
+
+```bash
+jinshuju entry import --form Kp7mQ2 ./signups.xlsx --map field_1=Name --wait   # wait for it; non-zero exit on failure
+jinshuju entry import-status --form Kp7mQ2 <job-id>                            # or look it up later
+```
+
+`--map` takes a field api_code on the left and a **column name or column
+number** on the right (a bare number is read as a position). Everything knowable
+up front is checked before the import starts — the file, the size your plan
+allows, the header row, the column mapping — so a rejected import has written
+nothing, and the error names the sheet's actual layout. Once accepted, the rows
+are written in the background: the command returning means **started**, not
+finished.
+
+That is what `--wait` is for. It waits for the job to settle, reports how many
+rows were written, skipped and rejected, and **exits non-zero on failure**.
+Without it a failed import is invisible — the command succeeds and not a single
+row is written. After the fact, `entry import-status` answers the same question
+from a job id.
+
+## Progress
+
+Long-running commands (`--all` paging, uploads, `--wait`) report progress.
+Progress is written **to stderr, and only when stderr is a terminal**, so
+`--output json | jq` receives exactly the same bytes it would without it: a pipe,
+or an agent on the other end, never sees a stray character.
+
+## Before removing a field
+
+```bash
+jinshuju field check --form Kp7mQ2 field_3 field_7:choice_1
+jinshuju field preview-convert --form Kp7mQ2 field_1 --to RadioButton
+```
+
+`field check` answers whether a field or a choice has data under it — removing
+it takes that data along, so it is worth asking first. `preview-convert` reports
+how much a type conversion would keep and how much it would clear.
+
+## Odds and ends
+
+```bash
+jinshuju form list --name signup --name survey   # several keywords match any, not one joined phrase
+jinshuju entry list --form Kp7mQ2 --labels       # carry the field label with each value, saving a form read
+jinshuju table move Vn4xR8 --folder Nf7mDC       # a table only goes into a kind=table folder
+jinshuju table create --json @t.json --with-default-entries   # seed a few blank rows, as the web UI does
+```
+
+## Token format
+
+Form, table and view tokens are **six characters of mixed-case letters and
+digits**, for example `Kp7mQ2`, `Vn4xR8`, `aB3dE9`. Examples here and in
+`--help` use that shape throughout.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+```

package/dist/auth.d.ts

@@ -0,0 +1,39 @@
+import { type LoadConfigOptions, type LoadedConfig, type OAuthConfig } from './config.js';
+export type TokenResponse = {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+    token_type?: string;
+};
+export type OAuthLoginOptions = LoadConfigOptions & {
+    host?: string;
+    authHost?: string;
+    clientId?: string;
+    scopes?: string;
+    openBrowser?: boolean;
+    timeoutMs?: number;
+    port?: number;
+};
+export type OAuthLoginResult = {
+    authorizeUrl: string;
+    callbackUrl: string;
+    token: OAuthConfig;
+};
+export type BrowserOpener = (url: string) => Promise<void>;
+export declare function createPkcePair(): {
+    verifier: string;
+    challenge: string;
+};
+export declare function buildAuthorizationUrl(params: {
+    authHost: string;
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    state: string;
+    codeChallenge: string;
+}): string;
+export declare function loginWithOAuth(options?: OAuthLoginOptions, opener?: BrowserOpener): Promise<OAuthLoginResult>;
+export declare function refreshOAuthToken(config: LoadedConfig): Promise<OAuthConfig>;
+export declare function revokeOAuthToken(config: LoadedConfig): Promise<void>;
+export declare function shouldRefresh(auth: OAuthConfig, skewMs?: number): boolean;