@evex-dev/linejs-cli 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-2026 Evex Developers
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,290 @@
1
- # Temporary Holding Version
1
+ # @evex-dev/linejs-cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Command-line interface and MCP server for
4
+ [LINEJS](https://linejs.evex.land). It exposes the same client, storage,
5
+ OpenChat, Album, VOOM, LIFF, Birthday Board, and raw Thrift/REST surfaces as
6
+ the library, with a `line` binary and machine-readable `--json` output.
7
+
8
+ ```sh
9
+ npm install -g @evex-dev/linejs-cli
10
+ # or run without installing:
11
+ npx -p @evex-dev/linejs-cli line --help
12
+ ```
13
+
14
+ Requires Node.js 22.18+, 24.11+, or 26+.
15
+
16
+ ## Quick start
17
+
18
+ ```sh
19
+ # Show the QR code in the terminal and save the session to ~/.linejs/default.json
20
+ line auth login
21
+
22
+ line auth status
23
+ line profile get
24
+ line contacts list
25
+ line chats list
26
+ line chats messages c... -n 20
27
+ line chats send c... "Hello from linejs"
28
+ line listen --square
29
+ ```
30
+
31
+ QR codes and PINs are printed to **stderr** so pipelines and `--json` remain
32
+ valid. With `--json`, successful results go to stdout and errors are emitted to
33
+ stderr as `{"error": {...}}`. The profile file stores the auth token plus LINEJS
34
+ internal storage (E2EE keys, refresh token, reqseq) and the last fetched
35
+ profile. It is written atomically with mode `0600`.
36
+
37
+ After login, normal commands reuse the cached profile and do **not** call
38
+ `getProfile()`. Pass `--check-session` to verify the token and refresh the cache
39
+ first. `auth *` commands still check automatically.
40
+
41
+ ## Profiles
42
+
43
+ ```sh
44
+ line auth login --profile work # ~/.linejs/work.json
45
+ line auth login --profile ./backup.json # ./backup.json
46
+ line --profile work contacts list
47
+ line auth profiles
48
+ line auth logout --yes
49
+ ```
50
+
51
+ Resolution rules:
52
+
53
+ | `--profile` value | Location |
54
+ | ---------------------- | -------------------------- |
55
+ | omitted | `~/.linejs/default.json` |
56
+ | `work` | `~/.linejs/work.json` |
57
+ | `work.json` | `~/.linejs/work.json` |
58
+ | `./profiles/work.json` | `<cwd>/profiles/work.json` |
59
+ | `/tmp/line.json` | `/tmp/line.json` |
60
+
61
+ `LINEJS_HOME` overrides `~/.linejs`, and `LINEJS_PROFILE` sets the default
62
+ profile name/path. Use `--device`, `--app-version`, and `--endpoint` to override
63
+ the emulated client without rewriting the profile.
64
+
65
+ ## Authentication
66
+
67
+ ```sh
68
+ line auth login # QR (default)
69
+ line auth login --qr-format ansi # compact|unicode|ansi|ascii|none
70
+ line auth login --email me@example.com --password-stdin
71
+ line auth login --token "$LINE_TOKEN" --force
72
+ line auth login --no-save --json # one-off; prints the token
73
+ line auth status --verify
74
+ line auth token # treat as a secret
75
+ ```
76
+
77
+ Passwords are never stored. A new profile refuses to overwrite an existing one
78
+ unless `--force` is passed. QR login is the safest first login because it
79
+ registers the E2EE key material; token-only logins may lack group E2EE keys.
80
+
81
+ ## Global options
82
+
83
+ | Option | Description |
84
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
85
+ | `--json` | Print the result as JSON; streaming commands use NDJSON. |
86
+ | `--check-session` | Verify the token with `getProfile()` and refresh the cached profile. Auth commands always do this; others use the cache unless this flag is set. |
87
+ | `--profile <name\|path>` | Select the profile file. |
88
+ | `--device <device>` | `DESKTOPWIN`, `DESKTOPMAC`, `ANDROID`, `ANDROIDSECONDARY`, `IOS`, `IOSIPAD`, `WATCHOS`, `WEAROS`. |
89
+ | `--app-version <version>` | Emulated LINE app version. |
90
+ | `--endpoint <host>` | LEGY endpoint override. |
91
+ | `--timeout <ms>` | Request timeout (default 30000). |
92
+ | `--verbose`, `-v` | Write LINEJS request logs to stderr. |
93
+ | `--no-color` | Disable ANSI colors. |
94
+ | `--help`, `-h` | Command help. |
95
+ | `--version` | CLI version. |
96
+
97
+ Run `line commands` or `line commands --json` for the full command list.
98
+ `line help <command>` prints usage, options, and examples.
99
+
100
+ ## Commands
101
+
102
+ - **auth**: `login`, `status`, `token`, `logout`, `profiles`
103
+ - **profile**: `get`, `update`, `image`, `background` (`get` uses the cached profile; add `--check-session` for a fresh `getProfile()`)
104
+ - **contacts**: `list`, `get`, `add`, `search`, `rename`, `favorite`, `mute`,
105
+ `hide`, `calendar`, `block`, `unblock`, `blocked`
106
+ - **chats**: `list`, `get`, `messages`, `send`, `send-media`, `compact`,
107
+ `create`, `invite`, `kick`, `leave`, `rename`, `bgm get`, `bgm set`
108
+ - **messages**: `react`, `cancel-reaction`, `unsend`, `read`, `reply`, `show`,
109
+ `pin`, `data`
110
+ - **square**: `list`, `get`, `chats`, `chat-get`, `chat-members`,
111
+ `chat-send`, `chat-media`, `chat-rename`, `chat-invite`, `chat-leave`,
112
+ `join`, `leave`, `create`, `rename`, `search`, `events`, `react`,
113
+ `message-reply`, `message-read`, `message-unsend`, `message-destroy`, `message-data`
114
+ - **timeline** / **note**: `post`, `list`, `get`, `update`, `delete`, `share`,
115
+ `like`, `comment`; `timeline upload`
116
+ - **moa**: `albums`, `photos`, `download`
117
+ - **media**: `upload`, `download`, `object`
118
+ - **call**: `route`, `group-route`, `group`, `url list|create|get|update|delete`,
119
+ `join`, `invite`, `kick` (control plane only; media transport is not exposed)
120
+ - **liff**: `token`, `view`, `share`, `share-text`
121
+ - **voom**: `token`, `feed`, `status`, `call`
122
+ - **birthday**: `board-id`, `board`, `cards`, `celebrations`, `likes`,
123
+ `templates`, `create`, `update`, `delete`, `delete-board`, `permission`,
124
+ `like`, `unlike`, `celebrate`, `cancel-celebration`, `report`
125
+ - **storage**: `list`, `get`, `set`, `delete`, `clear`, `export`
126
+ - **api**: `services`, `methods`, `call` — raw access to every public LINEJS
127
+ service method
128
+ - **listen**: stream talk/OpenChat events
129
+ - **mcp**: run the MCP server over stdio
130
+
131
+ Examples:
132
+
133
+ ```sh
134
+ line chats send-media u... ./photo.jpg
135
+ line messages react 123456789 NICE
136
+ line square chat-send m... "hello"
137
+ line square events m... -n 50
138
+ line timeline post c... "Hello Note"
139
+ line media upload ./file.pdf --to c... --type file
140
+ line storage get reqseq
141
+ line --json contacts list | jq '.contacts[].displayName'
142
+ ```
143
+
144
+ ### Raw API bridge
145
+
146
+ Every public method on `client`, `client.base`, and its services (`talk`,
147
+ `square`, `relation`, `call`, `liff`, `moa`, `timeline`, `obs`, `e2ee`, …) is
148
+ available. A JSON object is passed as one argument; a JSON array is spread as
149
+ multiple arguments.
150
+
151
+ ```sh
152
+ line api services
153
+ line api methods talk
154
+ line api call talk getProfile --args '{}'
155
+ line api call square getSquare --args '{"squareMid":"s..."}'
156
+ line api call call acquireGroupCallRoute --args '{"chatMid":"c...","mediaType":"AUDIO"}'
157
+ line api call obs downloadObjectForService \
158
+ --args '[{"obsPath":"talk/m/...","oid":"..."}]' --out ./file.bin
159
+ ```
160
+
161
+ Use `line api methods <service>` to discover method names. This is the escape
162
+ hatch for newer APIs that do not have a dedicated command yet.
163
+
164
+ ### Listening
165
+
166
+ ```sh
167
+ line listen # talk messages
168
+ line listen --square # OpenChat events
169
+ line listen --json --duration 60
170
+ line listen --events --count 5
171
+ ```
172
+
173
+ With `--json`, each event is one JSON line (NDJSON), followed by a summary
174
+ object. Press Ctrl+C to stop.
175
+
176
+ ## MCP server
177
+
178
+ ```sh
179
+ line mcp
180
+ ```
181
+
182
+ The stdio server exposes two tools:
183
+
184
+ - `list_linejs_cli` — lists every command with arguments, options, category,
185
+ and whether it is MCP-executable.
186
+ - `execute_linejs_cli` — receives an argv array (without the leading `line`)
187
+ and executes the CLI **in-process, without a shell**. `--json` is forced and
188
+ long-running commands (`listen`, `mcp`) are rejected.
189
+
190
+ Example client configuration:
191
+
192
+ ```json
193
+ {
194
+ "mcpServers": {
195
+ "linejs": {
196
+ "command": "line",
197
+ "args": ["mcp"]
198
+ }
199
+ }
200
+ }
201
+ ```
202
+
203
+ or with npx:
204
+
205
+ ```json
206
+ {
207
+ "mcpServers": {
208
+ "linejs": {
209
+ "command": "npx",
210
+ "args": ["-y", "-p", "@evex-dev/linejs-cli", "line", "mcp"]
211
+ }
212
+ }
213
+ }
214
+ ```
215
+
216
+ The MCP process runs with the same filesystem permissions as your user. Keep
217
+ the profile secret; `execute_linejs_cli` can call any non-long-running CLI
218
+ command, including `api call`. Log in from a terminal before exposing the
219
+ server: QR/PIN prompts produced during a tool call are only returned when that
220
+ call finishes, so interactive login is awkward over MCP.
221
+
222
+ ### MCP Events (webhooks)
223
+
224
+ The server also implements the [MCP Events](https://github.com/modelcontextprotocol/experimental-ext-triggers-events)
225
+ webhook extension that ChatGPT consumes. It advertises `events` in the
226
+ `initialize` capabilities and answers `events/list`, `events/subscribe`, and
227
+ `events/unsubscribe` on the same stdio connection.
228
+
229
+ Available events (`delivery: ["webhook"]`):
230
+
231
+ | Event | Fires when |
232
+ | -------------------------------- | --------------------------------------------- |
233
+ | `line.message.received` | a talk message arrives in a 1:1 or group chat |
234
+ | `line.message.edited` | a visible talk message is edited |
235
+ | `line.openchat.message.received` | a message arrives in an OpenChat room |
236
+
237
+ Subscription arguments are `chatId` and `from` (glob patterns) plus
238
+ `includeText` (default `true`). Payloads stay small on purpose: `messageId`,
239
+ `chatId`, `from`, `contentType`, a whitespace-collapsed text preview of at most
240
+ 400 characters, and `receivedAt`/`updatedAt`. Disable `includeText` to keep
241
+ user-authored text out of the webhook entirely.
242
+
243
+ Lifecycle and delivery:
244
+
245
+ - `events/subscribe` requires a `whsec_` signing secret (24–64 random bytes,
246
+ base64) and an `https` callback URL. The server first POSTs a signed
247
+ `{"type":"verification","challenge":"…"}` envelope and activates delivery only
248
+ when the endpoint echoes the challenge in a `2xx` response.
249
+ - Deliveries use Standard Webhooks headers (`webhook-id`, `webhook-timestamp`,
250
+ `webhook-signature`) plus `X-MCP-Subscription-Id`, signed with
251
+ HMAC-SHA256 over `id.timestamp.body`. Retries use exponential backoff, and
252
+ `410`/`413` are final.
253
+ - Subscriptions are keyed on `(profile, callback URL, event name, arguments)`,
254
+ so `events/subscribe` doubles as the refresh call. The granted TTL is 15
255
+ minutes by default (min 1 minute, max 1 hour); `ttlMs: null` is answered with
256
+ a finite grant because subscription state is in memory only. Expired or
257
+ suspended subscriptions and their `deliveryStatus` are reported on refresh.
258
+ - Callback URLs are resolved and validated on every attempt. `http`, embedded
259
+ credentials, redirects, and non-public addresses (loopback, RFC 1918, link
260
+ local, ULA, multicast, …) are rejected.
261
+ - Events are not replayable: `cursor` is always `null`. If the listener or the
262
+ MCP process restarts, events from the gap are gone.
263
+
264
+ ChatGPT talks to remote servers over Streamable HTTP, while `line mcp` speaks
265
+ stdio. Put the process behind a stdio↔HTTP bridge if you want ChatGPT to
266
+ connect directly; `line mcp --profile work` scopes the events to that profile.
267
+
268
+ ## Security
269
+
270
+ - `~/.linejs/*.json` contains an auth token and E2EE key material. Never commit
271
+ or share it. The CLI creates the directory with mode `0700` and files with
272
+ `0600`, but you should still protect backups.
273
+ - Prefer QR login for the first session and token reuse afterwards. Repeated
274
+ email/password logins can trigger LINE account restrictions.
275
+ - `line auth token` and `line storage list --values` print secrets.
276
+ - Using LINEJS may violate LINE's terms of service and can lead to account
277
+ restrictions. Use at your own risk.
278
+ - Do not run the MCP server for untrusted clients.
279
+
280
+ ## Development
281
+
282
+ ```sh
283
+ pnpm install
284
+ pnpm line --help # run the CLI from the repository root via tsx
285
+ pnpm --filter @evex-dev/linejs-cli run build
286
+ pnpm --filter @evex-dev/linejs-cli run typecheck
287
+ pnpm --filter @evex-dev/linejs-cli test
288
+ ```
289
+
290
+ The built binary is `packages/cli/dist/line.mjs` and is published as `line`.