listspace 0.5.0 → 0.7.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/CHANGELOG.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  One version runs through the CLI, the skill and the Claude Code plugin, so each entry covers all three.
4
4
 
5
+ ## 0.7.0
6
+
7
+ - Upload links for several files in one call: `get_upload_link` takes `files`, up to 25 entries each with `item_id`, `filename` and `size_bytes`, and the REST API has `POST /v1/upload-links` for the same. `listspace attach` uses it when it sends two or more files over 8 MB: it asks for the links of a few files at a time, right before sending them: a file joins a chunk only while the bytes queued ahead of it stay under about 500 MB, since a link for a large file holds room in storage and its upload must start within 15 minutes. A link that has run out or runs out within a minute is replaced by a fresh one before its upload. The CLI sends the files that got a link, names the ones that did not, and goes back to one link a file on a server that does not have the route yet. Publish this CLI after the server (the functions) is deployed.
8
+ - The upload limit counts files and bytes, not calls: 200 upload links or 10 GB an hour per account. A refusal says when to come back (`Try again after 14:32 UTC (in 12 minutes)`), with `retry_after_seconds` and `retry_at` in the error, and the CLI passes it on.
9
+ - The answer to an upload says in `attachment.is_cover` whether the file became the item's cover.
10
+ - The skill's file pages tell agents to send a batch in one call and to wait for the time the error names.
11
+
12
+ ## 0.6.0
13
+
14
+ - `listspace attach` takes files up to the plan's size of one file (Free 25 MB, Pro 2 GB, a team's boards 5 GB), at most 4 GB from the CLI. Up to 8 MB a file goes in the request as before; a larger one goes straight to Listspace's file storage: the CLI asks for an upload link with the file's size, sends the file from disk (it is never read into memory) and then finishes the upload. A file over the plan's size is refused before any byte is sent.
15
+ - The skill's file pages say how an agent sends a file over 8 MB with an upload link (`get_upload_link` with `size_bytes`, a PUT, then `finish_command`), that `attach_chat_file` takes files up to the plan's size, and what `virus_scan` `not_scanned_too_large` means.
16
+
5
17
  ## 0.5.0
6
18
 
7
19
  - New command `listspace call <tool> ['<json>']`: runs any tool of the Listspace MCP server by name, with its arguments as one JSON object, for example `listspace call get_item --json '{"item_id": "..."}'`. It goes to the MCP server with the same token, so the tools, the agent access level checks and the results are the same as for an MCP client, and a new tool works without a CLI update. A tool that refuses (a level, a wrong argument) exits 1 with `error.kind` `tool`. A call with an `idempotency_key` is sent once more after a network error or a 502, 503 or 504; one without is sent once.
package/README.md CHANGED
@@ -71,7 +71,7 @@ Every MCP tool (the same tools, levels and results as the MCP server)
71
71
  call <tool> ['<json>'] Run a tool with its arguments as one JSON object.
72
72
 
73
73
  Files from this computer (needs level 4, Act)
74
- attach <item> <file> [<file>...] At most 8 MB each.
74
+ attach <item> <file> [<file>...] Up to the plan's size of one file, at most 4 GB.
75
75
 
76
76
  Work on your own (needs level 4, Act)
77
77
  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
@@ -115,7 +115,7 @@ PowerShell treats quotes in JSON differently. On Windows, run these commands fro
115
115
  npx listspace attach 2b6f0c1e-... ./contract.pdf ./screenshots/footer.png
116
116
  ```
117
117
 
118
- The type comes from the extension: images (jpg, png, gif, webp, svg), PDF, Word, Excel and PowerPoint files, text, Markdown, CSV, JSON, archives (zip, rar, 7z), audio and video. Each file can be at most 8 MB. Every file is checked before the first one is sent. Attaching needs level 4 (Act) on the board: a file cannot wait in the Inbox.
118
+ The type comes from the extension: images (jpg, png, gif, webp, svg), PDF, Word, Excel and PowerPoint files, text, Markdown, CSV, JSON, archives (zip, rar, 7z), audio and video. Each file can be as large as the plan of the board's owner allows (Free 25 MB, Pro 2 GB, a team's boards 5 GB), at most 4 GB from the CLI. A file over 8 MB goes straight to Listspace's file storage, sent from disk, and is put on the item when it has arrived. Every file is checked before the first one is sent. Attaching needs level 4 (Act) on the board: a file cannot wait in the Inbox.
119
119
 
120
120
  ## Output for agents and scripts
121
121
 
@@ -216,7 +216,7 @@ var nextResult = union(
216
216
  function page(entry) {
217
217
  return object({ data: array(entry), next_cursor: nullable(string) });
218
218
  }
219
- var errorBody = object({ error: object({ code: string, message: string }) });
219
+ var errorBody = object({ error: object({ code: string, message: string, retry_after_seconds: withDefault(nullable(number), null) }) });
220
220
  var attached = object({
221
221
  outcome: literal("applied"),
222
222
  level,
@@ -229,9 +229,19 @@ var attached = object({
229
229
  url: string
230
230
  })
231
231
  });
232
+ var largeUploadLink = object({
233
+ upload_url: string,
234
+ finish_url: nullable(string),
235
+ /** When upload_url stops working to start a PUT (15 minutes after the answer); null from a server that does not say. */
236
+ expires_at: withDefault(nullable(string), null)
237
+ });
238
+ var largeUploadLinks = object({
239
+ links: array(object({ index: number, upload_url: string, finish_url: nullable(string), expires_at: withDefault(nullable(string), null) })),
240
+ refused: array(object({ index: number, filename: string, message: string }))
241
+ });
232
242
 
233
243
  // src/version.ts
234
- var VERSION = "0.5.0";
244
+ var VERSION = "0.7.0";
235
245
 
236
246
  // src/api.ts
237
247
  var DEFAULT_API_URL = "https://api.listspace.app/v1";
@@ -272,6 +282,31 @@ var ApiClient = class {
272
282
  const json = await this.send(method, path2, init);
273
283
  return { value: decodeOrFail(decoder, json, "body"), raw: json };
274
284
  }
285
+ /**
286
+ * PUTs a file to a signed storage link (get_upload_link for a large file).
287
+ * The link is the credential: no token is sent with it. The Blob's size
288
+ * is the Content-Length, which the link signed.
289
+ */
290
+ async putToStorage(url, file) {
291
+ let response;
292
+ try {
293
+ response = await this.options.fetch(url, { method: "PUT", body: file, headers: { "User-Agent": `listspace-cli/${VERSION}` } });
294
+ } catch (cause) {
295
+ const reason = cause instanceof Error ? cause.message : String(cause);
296
+ return fail({ kind: "network", message: `Could not send the file to Listspace's file storage: ${reason}` });
297
+ }
298
+ await response.body?.cancel();
299
+ if (!response.ok) {
300
+ return fail({ kind: "api", status: response.status, code: "upload_failed", message: `Listspace's file storage refused the file (HTTP ${response.status}). Run the command again for a new link.` });
301
+ }
302
+ }
303
+ /** POSTs to an upload link's finish address (no body; the link is the credential) and decodes `data`. */
304
+ async finishUpload(url, decoder) {
305
+ const { response, json } = await this.exchange(new URL(url), { method: "POST", headers: { Accept: "application/json", "User-Agent": `listspace-cli/${VERSION}` } }, false);
306
+ if (!response.ok) return fail(errorFor(response, json));
307
+ if (!isRecord(json) || !("data" in json)) return fail({ kind: "unexpected", message: "Unexpected response from Listspace: no data." });
308
+ return { value: decodeOrFail(decoder, json.data, "data"), raw: json.data };
309
+ }
275
310
  /** A new idempotency key: a random UUID, or the tests' own. */
276
311
  newKey() {
277
312
  return (this.options.newKey ?? (() => crypto.randomUUID()))();
@@ -413,16 +448,19 @@ function decodeOrFail(decoder, value, path2) {
413
448
  function errorFor(response, json) {
414
449
  let code2 = "unknown";
415
450
  let message = `Listspace answered ${response.status}.`;
451
+ let retryAfter = null;
416
452
  try {
417
453
  const parsed = errorBody(json, "body");
418
454
  code2 = parsed.error.code;
419
455
  message = parsed.error.message;
456
+ retryAfter = parsed.error.retry_after_seconds;
420
457
  } catch {
421
458
  }
422
459
  if (response.status === 401) return { kind: "auth", message: `${message} ${LOGIN_HINT}` };
423
460
  if (response.status === 429) {
424
461
  const header = response.headers.get("Retry-After");
425
- const seconds = header !== null && /^\d+$/.test(header) ? Number(header) : null;
462
+ const seconds = retryAfter ?? (header !== null && /^\d+$/.test(header) ? Number(header) : null);
463
+ if (/try again after/i.test(message)) return { kind: "rate_limited", message, retryAfterSeconds: seconds };
426
464
  const wait = seconds === null ? "Wait a minute" : `Wait ${seconds} seconds`;
427
465
  return { kind: "rate_limited", message: `${message} ${wait} before trying again.`, retryAfterSeconds: seconds };
428
466
  }
@@ -433,8 +471,10 @@ function errorFor(response, json) {
433
471
  }
434
472
 
435
473
  // src/files.ts
474
+ import { openAsBlob } from "node:fs";
436
475
  import { readFile, stat } from "node:fs/promises";
437
476
  var MAX_FILE_BYTES = 8 * 1024 * 1024;
477
+ var MAX_LARGE_FILE_BYTES = 4 * 1024 * 1024 * 1024;
438
478
  var TYPES = {
439
479
  jpg: "image/jpeg",
440
480
  jpeg: "image/jpeg",
@@ -478,7 +518,7 @@ function mimeTypeFor(fileName) {
478
518
  if (dot <= 0 || dot === fileName.length - 1) return null;
479
519
  return TYPES[fileName.slice(dot + 1).toLowerCase()] ?? null;
480
520
  }
481
- async function readLocalFile(path2, maxBytes) {
521
+ async function readLocalFile(path2, maxBytes, largeMaxBytes = maxBytes) {
482
522
  let size;
483
523
  try {
484
524
  const info = await stat(path2);
@@ -488,7 +528,14 @@ async function readLocalFile(path2, maxBytes) {
488
528
  if (isErrnoCode(error, "ENOENT")) return { kind: "missing" };
489
529
  return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
490
530
  }
491
- if (size > maxBytes) return { kind: "too_large", sizeBytes: size };
531
+ if (size > largeMaxBytes) return { kind: "too_large", sizeBytes: size };
532
+ if (size > maxBytes) {
533
+ try {
534
+ return { kind: "large", blob: await openAsBlob(path2), sizeBytes: size };
535
+ } catch (error) {
536
+ return { kind: "unreadable", reason: error instanceof Error ? error.message : String(error) };
537
+ }
538
+ }
492
539
  try {
493
540
  const bytes = await readFile(path2);
494
541
  if (bytes.length > maxBytes) return { kind: "too_large", sizeBytes: bytes.length };
@@ -503,7 +550,8 @@ function isErrnoCode(error, code2) {
503
550
  function formatSize(bytes) {
504
551
  if (bytes < 1024) return `${bytes} bytes`;
505
552
  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
506
- return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
553
+ if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
554
+ return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
507
555
  }
508
556
 
509
557
  // src/format.ts
@@ -837,18 +885,21 @@ async function prepareFiles(paths, read) {
837
885
  if (mimeType === null) {
838
886
  return fail({ kind: "usage", message: `${fileName}: this type of file cannot be attached. Allowed: ${ATTACHABLE_EXTENSIONS.join(", ")}.` });
839
887
  }
840
- const file = await read(filePath, MAX_FILE_BYTES);
888
+ const file = await read(filePath, MAX_FILE_BYTES, MAX_LARGE_FILE_BYTES);
841
889
  switch (file.kind) {
842
890
  case "ok":
843
891
  if (file.bytes.length === 0) return fail({ kind: "usage", message: `${filePath} is empty.` });
844
- out.push({ path: filePath, fileName, mimeType, bytes: file.bytes });
892
+ out.push({ path: filePath, fileName, mimeType, content: { kind: "bytes", bytes: file.bytes } });
893
+ break;
894
+ case "large":
895
+ out.push({ path: filePath, fileName, mimeType, content: { kind: "blob", blob: file.blob, sizeBytes: file.sizeBytes } });
845
896
  break;
846
897
  case "missing":
847
898
  return fail({ kind: "usage", message: `${filePath}: no such file.` });
848
899
  case "not_a_file":
849
900
  return fail({ kind: "usage", message: `${filePath} is a folder, not a file.` });
850
901
  case "too_large":
851
- return fail({ kind: "usage", message: `${filePath} is ${formatSize(file.sizeBytes)}; a file can be at most ${formatSize(MAX_FILE_BYTES)}. Share a link with attach_url instead, or make it smaller.` });
902
+ return fail({ kind: "usage", message: `${filePath} is ${formatSize(file.sizeBytes)}; a file can be at most ${formatSize(MAX_LARGE_FILE_BYTES)} from here. Add it in the Listspace app instead, or make it smaller.` });
852
903
  case "unreadable":
853
904
  return fail({ kind: "unexpected", message: `Could not read ${filePath}: ${file.reason}` });
854
905
  default: {
@@ -859,24 +910,95 @@ async function prepareFiles(paths, read) {
859
910
  }
860
911
  return out;
861
912
  }
913
+ var CHUNK_BYTES = 500 * 1024 * 1024;
914
+ var CHUNK_FILES = 10;
915
+ var STALE_MS = 6e4;
862
916
  async function attachCommand(client, input) {
863
917
  if (!UUID.test(input.item)) return fail({ kind: "usage", message: `"${input.item}" is not an item id. Item ids come from \`listspace board <board>\`.` });
864
918
  const results = [];
865
919
  const raw = [];
866
- for (const file of input.files) {
867
- const body = { filename: file.fileName, mime_type: file.mimeType, content_base64: Buffer.from(file.bytes).toString("base64") };
920
+ const skipped = [];
921
+ const links = /* @__PURE__ */ new Map();
922
+ let batches = true;
923
+ for (const [position, file] of input.files.entries()) {
868
924
  try {
869
- const answer = await client.data("POST", `/items/${path(input.item)}/attachments`, attached, { body });
925
+ let made;
926
+ if (file.content.kind === "blob") {
927
+ if (batches && !links.has(file)) batches = await askForLinks(client, input.item, input.files.slice(position), links);
928
+ const got = links.get(file);
929
+ if (got !== void 0 && "refused" in got) {
930
+ skipped.push({ name: file.fileName, reason: got.refused });
931
+ continue;
932
+ }
933
+ made = got;
934
+ }
935
+ const answer = await attachOne(client, input.item, file, made);
870
936
  results.push(answer.value);
871
937
  raw.push(answer.raw);
872
938
  } catch (error) {
873
- if (!(error instanceof CliFailure) || results.length === 0) throw error;
939
+ if (!(error instanceof CliFailure) || results.length === 0 && skipped.length === 0) throw error;
874
940
  const done = results.map((result) => result.attachment.filename).join(", ");
875
- throw new CliFailure({ ...error.error, message: `Attached ${done}; ${file.fileName} and the rest were not: ${error.error.message}` });
941
+ throw new CliFailure({ ...error.error, message: `Attached ${done === "" ? "nothing" : done}; ${file.fileName} and the rest were not: ${error.error.message}` });
876
942
  }
877
943
  }
944
+ if (skipped.length > 0) {
945
+ const done = results.map((result) => result.attachment.filename).join(", ");
946
+ return fail({
947
+ kind: "api",
948
+ status: 400,
949
+ code: "invalid_request",
950
+ message: `Attached ${done === "" ? "nothing" : done}; not attached: ${skipped.map((s) => `${s.name} (${s.reason})`).join("; ")}`
951
+ });
952
+ }
878
953
  return { raw: { data: raw }, text: formatAttached(results) };
879
954
  }
955
+ async function askForLinks(client, item2, rest, links) {
956
+ const next = rest.filter((file) => file.content.kind === "blob" && !links.has(file));
957
+ if (next.length < 2) return true;
958
+ const chunk = [];
959
+ let queued = 0;
960
+ for (const file of next) {
961
+ if (chunk.length >= CHUNK_FILES || chunk.length > 0 && queued >= CHUNK_BYTES) break;
962
+ chunk.push(file);
963
+ queued += file.content.kind === "blob" ? file.content.sizeBytes : 0;
964
+ }
965
+ const body = { files: chunk.map((file) => ({ item_id: item2, filename: file.fileName, size_bytes: file.content.kind === "blob" ? file.content.sizeBytes : 0 })) };
966
+ let answer;
967
+ try {
968
+ answer = (await client.data("POST", "/upload-links", largeUploadLinks, { body })).value;
969
+ } catch (error) {
970
+ if (error instanceof CliFailure && error.error.kind === "api" && error.error.status === 404 && error.error.code === "not_found" && error.error.message.startsWith("No such endpoint")) return false;
971
+ throw error;
972
+ }
973
+ for (const link of answer.links) {
974
+ const file = chunk[link.index];
975
+ if (file !== void 0) links.set(file, link);
976
+ }
977
+ for (const entry of answer.refused) {
978
+ const file = chunk[entry.index];
979
+ if (file !== void 0) links.set(file, { refused: entry.message });
980
+ }
981
+ return true;
982
+ }
983
+ async function attachOne(client, item2, file, made) {
984
+ switch (file.content.kind) {
985
+ case "bytes": {
986
+ const body = { filename: file.fileName, mime_type: file.mimeType, content_base64: Buffer.from(file.content.bytes).toString("base64") };
987
+ return client.data("POST", `/items/${path(item2)}/attachments`, attached, { body });
988
+ }
989
+ case "blob": {
990
+ const stale = made !== void 0 && made.expires_at !== null && Date.parse(made.expires_at) - Date.now() < STALE_MS;
991
+ const link = made === void 0 || stale ? (await client.data("POST", `/items/${path(item2)}/upload-links`, largeUploadLink, { body: { filename: file.fileName, size_bytes: file.content.sizeBytes } })).value : made;
992
+ if (link.finish_url === null) return fail({ kind: "unexpected", message: "Listspace answered without a link to finish a large upload. Update the CLI, or the server is older than it." });
993
+ await client.putToStorage(link.upload_url, file.content.blob);
994
+ return client.finishUpload(link.finish_url, attached);
995
+ }
996
+ default: {
997
+ const exhaustive = file.content;
998
+ return exhaustive;
999
+ }
1000
+ }
1001
+ }
880
1002
 
881
1003
  // src/tools.ts
882
1004
  var UUID2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -1089,9 +1211,12 @@ Every MCP tool (the same tools, levels and results as the MCP server)
1089
1211
 
1090
1212
  Files from this computer (needs level 4, Act; a file cannot wait in the Inbox)
1091
1213
  attach <item> <file> [<file>...]
1092
- Upload files to an item, at most 8 MB each:
1093
- images, PDF, Office files, text, Markdown, CSV,
1094
- JSON, archives, audio and video.
1214
+ Upload files to an item: images, PDF, Office
1215
+ files, text, Markdown, CSV, JSON, archives, audio
1216
+ and video. Up to the plan's size of one file
1217
+ (Free 25 MB, Pro 2 GB, a team's boards 5 GB), at
1218
+ most 4 GB from here; over 8 MB the file goes
1219
+ straight to file storage.
1095
1220
 
1096
1221
  Work on your own (needs level 4, Act; other agents leave a claimed item alone)
1097
1222
  next <board> [--kinds todo,backlog] [--label <id>] [--no-move] [--ttl <minutes>]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "listspace",
3
- "version": "0.5.0",
3
+ "version": "0.7.0",
4
4
  "description": "Listspace from the command line: the agentic project memory, for people and coding agents.",
5
5
  "keywords": [
6
6
  "listspace",