@simplepush/cli 0.2.1 → 0.4.0

package/dist/main.mjs

@@ -9,7 +9,7 @@ import { wordlist } from "@scure/bip39/wordlists/english.js";
 import { homedir, tmpdir } from "node:os";
 import { createServer } from "node:http";
 import { spawn } from "node:child_process";
-import { Client, Keyring, OrgClient, TypeFilter, cancelSubtask, cancelTask, cancelTaskGroup, decryptBytes, deriveKey, encrypt, fetchUserInfo, isSubtaskGroupResponse, tryDecryptEventData } from "@simplepush/sdk";
+import { Client, DownloadError, OrgClient, TypeFilter, decryptSubmission, decryptTaskPayload, decryptTaskSummary, isSubtaskGroupResponse, tryDecryptEventData } from "@simplepush/sdk";
 import { mkdir, stat, writeFile } from "node:fs/promises";
 import { connect, createConnection } from "node:net";
 import path, { basename, extname, join } from "node:path";
@@ -546,7 +546,7 @@ var VaultAccess = class extends Effect.Service()("cli/VaultAccess", {
 //#region src/global-options.ts
 const DEFAULT_BASE_URL = "https://api.simplepu.sh";
 const toHelp = (e) => HelpDoc.p(e instanceof Error ? e.message : String(e));
-const topicOption = Options.text("topic").pipe(Options.withAlias("t"), Options.withDescription("Topic to send to (`task`) or filter on (`events`, repeatable). Omit on `task` for a self-send to your own devices."), Options.repeated);
+const topicOption$1 = Options.text("topic").pipe(Options.withAlias("t"), Options.withDescription("Topic to send to (`task`) or filter on (`events`, repeatable). Omit on `task` for a self-send to your own devices."), Options.repeated);
 const apiTokenOption = Options.text("api-token").pipe(Options.withDescription("API token. Required for `get`; `collect`, `events`, and `subtask` fall back to the logged-in org session when omitted. Defaults to $SP_API_TOKEN."), Options.withFallbackConfig(Config.string("SP_API_TOKEN")), Options.optional);
 /** Personal-credential commands need the token; fail typed when absent. */
 const requireApiToken = (token) => Option.match(token, {
@@ -1525,7 +1525,7 @@ const loadOrgMasterKeys = Effect.gen(function* () {
 });
 const collectCommand = Command.make("collect", {
 	group: Options.text("group").pipe(Options.withDescription("Group id (grptsk_…) to collect over. Usually supplied via the piped `sent` line instead."), Options.optional),
-	instance: Options.text("instance").pipe(Options.withDescription("Instance id to collect: a task (tsk_…), a notification (ntf_…), or a subtask-scoped pair (tsk_…/sub_…). Repeatable. Augments/overrides the piped `sent` line's instances."), Options.repeated),
+	instance: Options.text("instance").pipe(Options.withDescription("Instance id to collect: a task (tsk_…), a notification (ntf_…), or a subtask (sub_…, or the tsk_…/sub_… pair). Repeatable. Augments/overrides the piped `sent` line's instances."), Options.repeated),
 	replies: Options.boolean("replies").pipe(Options.withDescription("Collect only replies. Default (no mode flag) is the full activity stream: inputs, replies, and completions.")),
 	inputs: Options.boolean("inputs").pipe(Options.withDescription("Collect only input events (waits for every instance to complete by default).")),
 	submissions: Options.boolean("submissions").pipe(Options.withDescription("Collect submissions (your inbox) instead of a group's events.")),
@@ -1606,14 +1606,16 @@ const collectCommand = Command.make("collect", {
 		} : null, m.subtaskId);
 		for (const spec of args.instance) {
 			const [id, subtaskId] = spec.split("/", 2);
-			if (id.startsWith("sub_")) return yield* Effect.fail(new UserError({ message: `a subtask cannot be collected by its id alone (events route under the parent task) — pass --instance <parent tsk_…>/${id}` }));
-			addMember(id, null, subtaskId);
+			if (id.startsWith("sub_")) {
+				const parent = yield* sdkCall("read subtask", () => client.getSubtask(id));
+				addMember(String(parent.parentTaskId), null, id);
+			} else addMember(id, null, subtaskId);
 		}
-		if (members.length === 0) return yield* Effect.fail(new UserError({ message: "no instances to collect: pipe a send's `sent` line (`sp task --format json | sp collect`) or pass --instance <tsk_…|ntf_…|tsk_…/sub_…> (repeatable)" }));
+		if (members.length === 0) return yield* Effect.fail(new UserError({ message: "no instances to collect: pipe a send's `sent` line (`sp task --format json | sp collect`) or pass --instance <tsk_…|ntf_…|sub_…> (repeatable)" }));
 		const notifRoster = members[0].kind === "notification";
 		if (members.some((m) => m.kind === "notification" !== notifRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix task (tsk_…) and notification (ntf_…) instances in one collect — run one per kind" }));
 		const subRoster = members[0].subtaskId !== void 0;
-		if (members.some((m) => m.subtaskId !== void 0 !== subRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix subtask-scoped instances (a piped `sp subtask --format json` line or --instance tsk_…/sub_…) with plain task/notification instances in one collect" }));
+		if (members.some((m) => m.subtaskId !== void 0 !== subRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix subtask-scoped instances (a piped `sp subtask --format json` line or --instance sub_…) with plain task/notification instances in one collect" }));
 		const streamOpts = {
 			replay: true,
 			...until.idleMs !== void 0 ? { idleMs: until.idleMs } : {}
@@ -1782,7 +1784,7 @@ const reasonOption = Options.choice("reason", [
 	"answered",
 	"superseded"
 ]).pipe(Options.withDescription("Why: plain withdrawal (default), another recipient's answer made the rest moot (`answered`), or a replacement exists (`superseded`)."), Options.withDefault("canceled"));
-const noteOption = Options.text("note").pipe(Options.withDescription("Free-text explanation shown on the recipients' canceled card. Encrypted under the org master key on the org path (default when enabled); on the personal path seal it with --password pw@topic (topic send) or a bare --password (self-send, account default key)."), Options.optional);
+const noteOption = Options.text("note").pipe(Options.withDescription("Free-text explanation shown on the recipients' canceled card. Sealed under the target's key when this CLI holds it: the org vault on an org session, or the matching -p/--password (`pw@topic`, or a bare `pw` for a self-send)."), Options.optional);
 const supersededByOption = Options.text("superseded-by").pipe(Options.withDescription("The replacement's id — a task id, a subtask id of the same chain, or (for a group cancel) the replacement group id. Requires --reason superseded."), Options.optional);
 const noEncryptOption$3 = Options.boolean("no-encrypt").pipe(Options.withDescription("For org cancels: send the note in plaintext even when the org vault is unlocked."));
 const cancelCommand = Command.make("cancel", {
@@ -1801,89 +1803,46 @@ const cancelCommand = Command.make("cancel", {
 	const note = Option.getOrUndefined(args.note);
 	const supersededBy = Option.getOrUndefined(args["superseded-by"]);
 	if (supersededBy !== void 0 && args.reason !== "superseded") return yield* Effect.fail(new UserError({ message: "--superseded-by requires --reason superseded" }));
-	const credential = yield* resolveCredential(args["api-token"], args["base-url"]);
-	let noteFields = {};
-	if (note !== void 0) if (credential.kind === "org") {
-		const vault = yield* (yield* VaultAccess).forSendOrPlaintext(args["no-encrypt"]);
-		if (vault) noteFields = {
-			note: yield* sdkCall("encrypt note", () => encrypt(vault.masterKeyCurrent.key, note)),
-			encryption: {
-				type: "org",
-				v: vault.masterKeyCurrent.version
-			}
+	const kind = args.id.startsWith("grptsk_") ? "group" : args.id.startsWith("tsk_") ? "task" : args.id.startsWith("sub_") ? "subtask" : void 0;
+	if (kind === void 0) return yield* Effect.fail(new UserError({ message: `cannot cancel \`${args.id}\`: expected a tsk_…, sub_…, or grptsk_… id` }));
+	const cred = yield* resolveCredential(args["api-token"], args["base-url"]);
+	const orgKeys = cred.kind === "org" && !args["no-encrypt"] ? yield* loadOrgMasterKeys : void 0;
+	return yield* Effect.scoped(Effect.gen(function* () {
+		const client = cred.kind === "personal" ? yield* acquireClient({
+			baseUrl: cred.baseUrl,
+			apiToken: cred.apiToken,
+			passwords: args.password
+		}) : yield* acquireOrgClient({
+			baseUrl: cred.baseUrl,
+			bearerToken: cred.bearer,
+			...orgKeys !== void 0 ? { orgMasterKeys: orgKeys } : {}
+		});
+		const opts = {
+			reason: args.reason,
+			...note !== void 0 ? { note } : {},
+			...supersededBy !== void 0 ? { supersededBy } : {}
 		};
-		else {
-			noteFields = { note };
-			yield* out.warn("note sent unencrypted (org encryption disabled or --no-encrypt)");
+		if (note !== void 0) {
+			const marker = yield* sdkCall("read cancel target", async () => kind === "task" ? (await client.getTask(args.id)).encryption : kind === "subtask" ? (await client.getSubtask(args.id)).encryption : (await client.getTaskGroup(args.id)).tasks[0]?.encryption);
+			if (marker !== void 0) {
+				if ((yield* sdkCall("keyring", async () => (await client.keyring({ includePasswordSalt: marker.type === "personal" })).keyForMarker(marker))) === void 0) yield* out.warn(marker.type === "org" ? "note sent unencrypted (org vault locked, or --no-encrypt)" : "note sent unencrypted — seal it with --password <pw>@<topic> (topic send) or a bare --password (self-send)");
+			}
 		}
-	} else {
-		const passwords = args.password;
-		if (passwords.length > 1) return yield* Effect.fail(new UserError({ message: "pass exactly one --password so the note's key is unambiguous" }));
-		const flag = passwords[0];
-		if (flag === void 0) {
-			noteFields = { note };
-			yield* out.warn("note sent unencrypted — seal it with --password <pw>@<topic> (topic send) or a bare --password (self-send)");
-		} else if (Array.isArray(flag)) {
-			const derived = yield* sdkCall("derive note key", () => deriveKey(flag[0], flag[1]));
-			noteFields = {
-				note: yield* sdkCall("encrypt note", () => encrypt(derived.symmetricKey, note)),
-				encryption: {
-					type: "personal",
-					keyFingerprint: derived.fingerprint
-				}
-			};
-		} else {
-			const info = yield* sdkCall("fetch password salt", () => fetchUserInfo({
-				baseUrl: new URL(credential.baseUrl),
-				apiToken: credential.apiToken,
-				fetch
+		if (kind === "group") {
+			const result = yield* sdkCall("cancel task group", () => client.cancelTaskGroup(args.id, opts));
+			yield* out.print(JSON.stringify({
+				type: "canceled",
+				groupId: args.id,
+				...result
 			}));
-			const derived = yield* sdkCall("derive note key", () => deriveKey(flag, info.passwordSalt));
-			noteFields = {
-				note: yield* sdkCall("encrypt note", () => encrypt(derived.symmetricKey, note)),
-				encryption: {
-					type: "personal",
-					keyFingerprint: derived.fingerprint
-				}
-			};
+		} else if (kind === "task") {
+			yield* sdkCall("cancel task", () => client.cancelTask(args.id, opts));
+			yield* out.info(`canceled ${args.id}`);
+		} else {
+			yield* sdkCall("cancel subtask", () => client.cancelSubtask(args.id, opts));
+			yield* out.info(`canceled ${args.id}`);
 		}
-	}
-	const body = {
-		reason: args.reason,
-		...noteFields,
-		...supersededBy !== void 0 ? { supersededBy } : {}
-	};
-	const baseUrl = new URL(credential.baseUrl);
-	const authHeaders = credential.kind === "personal" ? { "API-Token": credential.apiToken } : { Authorization: `Bearer ${credential.bearer}` };
-	if (args.id.startsWith("grptsk_")) {
-		const result = yield* sdkCall("cancel task group", () => cancelTaskGroup({
-			baseUrl,
-			groupId: args.id,
-			body,
-			authHeaders
-		}));
-		yield* out.print(JSON.stringify({
-			type: "canceled",
-			groupId: args.id,
-			...result
-		}));
-	} else if (args.id.startsWith("tsk_")) {
-		yield* sdkCall("cancel task", () => cancelTask({
-			baseUrl,
-			taskId: args.id,
-			body,
-			authHeaders
-		}));
-		yield* out.info(`canceled ${args.id}`);
-	} else if (args.id.startsWith("sub_")) {
-		yield* sdkCall("cancel subtask", () => cancelSubtask({
-			baseUrl,
-			subtaskId: args.id,
-			body,
-			authHeaders
-		}));
-		yield* out.info(`canceled ${args.id}`);
-	} else return yield* Effect.fail(new UserError({ message: `cannot cancel \`${args.id}\`: expected a tsk_…, sub_…, or grptsk_… id` }));
+	}));
 })).pipe(Command.withDescription("Cancel a pending task, subtask, or task group you sent (sender-side withdrawal)."));
 //#endregion
 //#region src/commands/daemon.ts
@@ -1916,6 +1875,133 @@ const daemonCommand = Command.make("daemon", {
 	});
 }));
 //#endregion
+//#region src/commands/query-support.ts
+/** Options every read command shares: credential, decryption keys, paging, output. */
+const credentialOptions = {
+	"api-token": apiTokenOption,
+	password: passwordOption,
+	"base-url": baseUrlOption,
+	quiet: quietOption
+};
+const formatOption$4 = Options.choice("format", ["json", "pretty"]).pipe(Options.withDefault("json"), Options.withDescription("json = one JSON object per line (agents, jq); pretty = human-readable lines."));
+const sinceOption$1 = mappedText("since", resolveSince).pipe(Options.optional, Options.withDescription("Only items created at or after this instant: ISO-8601, or a relative window like 7d, 12h, 30m."));
+const untilOption$1 = mappedText("until", (raw) => resolveUntil(raw).toISOString()).pipe(Options.optional, Options.withDescription("Only items created at or before this instant (same forms as --since)."));
+const memberOption$3 = Options.text("member").pipe(Options.optional, Options.withDescription("Only items involving this person: a usr_ id, or a member name on an org."));
+const limitOption$1 = Options.integer("limit").pipe(Options.optional, Options.withDescription("Page size (server default 50). With --all this is the page size, not a cap."));
+const cursorOption = Options.text("cursor").pipe(Options.optional, Options.withDescription("Continue a previous page: pass the cursor it reported."));
+const allOption = Options.boolean("all").pipe(Options.withDescription("Follow cursors until the last page instead of printing one page and a cursor."));
+const STATUSES = [
+	"pending",
+	"completed",
+	"canceled",
+	"declined",
+	"expired"
+];
+/** `--status` accepts repeats and comma lists: `--status expired --status declined` or `--status expired,declined`. */
+const statusOption = Options.text("status").pipe(Options.repeated, Options.mapTryCatch((values) => {
+	const flat = values.flatMap((v) => v.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
+	const bad = flat.filter((s) => !STATUSES.includes(s));
+	if (bad.length > 0) throw new Error(`unknown status ${bad.join(", ")} — use ${STATUSES.join(", ")}`);
+	return flat;
+}, (e) => HelpDoc.p(e instanceof Error ? e.message : String(e))), Options.withDescription("Only tasks in these states (repeatable or comma-separated)."));
+/** Resolves the credential (personal API-Token or the saved org session),
+* builds the matching client and — when keys are available — a keyring, and
+* runs `body` inside the client's scope. Mirrors what `sp events` does. */
+const withQueryClient = (args, body) => Effect.gen(function* () {
+	const out = yield* CliOutput;
+	yield* out.setQuiet(args.quiet);
+	const cred = yield* resolveCredential(args["api-token"], args["base-url"]);
+	const orgKeys = cred.kind === "org" ? yield* loadOrgMasterKeys : void 0;
+	return yield* Effect.scoped(Effect.gen(function* () {
+		const client = cred.kind === "personal" ? yield* acquireClient({
+			baseUrl: cred.baseUrl,
+			apiToken: cred.apiToken,
+			passwords: args.password
+		}) : yield* acquireOrgClient({
+			baseUrl: cred.baseUrl,
+			bearerToken: cred.bearer,
+			...orgKeys !== void 0 ? { orgMasterKeys: orgKeys } : {}
+		});
+		return yield* body({
+			client,
+			keyring: cred.kind === "org" ? orgKeys !== void 0 ? yield* sdkCall("keyring", () => client.keyring()) : void 0 : args.password.length > 0 ? yield* sdkCall("keyring", () => client.keyring({ includePasswordSalt: true })) : void 0,
+			org: cred.kind === "org",
+			out
+		});
+	}));
+});
+/** Decrypts what the keyring can and counts what it cannot, so a command can
+* report "N values left as ciphertext" once instead of per row. Each method
+* maps one wire shape onto its SDK field-schema decryptor. */
+var Decryptor = class {
+	undecryptable = 0;
+	constructor(keyring) {
+		this.keyring = keyring;
+	}
+	run(value, go) {
+		if (this.keyring === void 0) return Effect.succeed(value);
+		const keyring = this.keyring;
+		return Effect.promise(() => go(keyring)).pipe(Effect.map((r) => {
+			this.undecryptable += r.undecryptable;
+			return r.value;
+		}));
+	}
+	/** A task or subtask payload (chain reads). */
+	payload(value) {
+		return this.run(value, (kr) => decryptTaskPayload(value, kr));
+	}
+	/** A task index / roster row. */
+	summary(value) {
+		return this.run(value, (kr) => decryptTaskSummary(value, kr));
+	}
+	/** A submission under its feed entry's marker. */
+	submission(value, marker) {
+		return this.run(value, (kr) => decryptSubmission(value, kr, marker));
+	}
+	report(out) {
+		return this.undecryptable > 0 ? out.warn(`${this.undecryptable} value(s) are encrypted under a key this CLI does not hold and were left as ciphertext`) : Effect.void;
+	}
+};
+/** Runs `page` for the first cursor, then keeps following cursors when `all`
+* is set; otherwise reports the cursor of the next page so the caller can
+* continue by hand. */
+const forEachPage = (ctx, format, all, first, page, handle) => Effect.gen(function* () {
+	let cursor = first;
+	for (;;) {
+		const p = yield* page(cursor);
+		yield* handle(p);
+		if (p.nextCursor === void 0) return;
+		if (!all) {
+			yield* format === "json" ? ctx.out.print(JSON.stringify({
+				type: "more",
+				cursor: p.nextCursor
+			})) : ctx.out.info(`more available — continue with --cursor ${p.nextCursor} (or pass --all)`);
+			return;
+		}
+		cursor = p.nextCursor;
+	}
+});
+function recipientLabels(t) {
+	return t.recipients.map((r) => r.name ?? r.publicId);
+}
+/** One line per task: id, state, when, title, who, subtask counts, group. */
+function formatTaskSummary(t) {
+	const subs = Object.entries(t.subtasks).map(([k, v]) => `${k} ${v}`).join(", ");
+	return [
+		`${t.taskId}  [${t.status}]  ${t.createdAt}`,
+		t.title !== void 0 ? `  ${t.title}` : void 0,
+		`  to: ${recipientLabels(t).join(", ") || "-"}`,
+		t.topic !== void 0 ? `  topic: ${t.topic}` : void 0,
+		t.tag !== void 0 ? `  tag: ${t.tag}` : void 0,
+		t.inputs.length > 0 ? `  inputs: ${t.inputs.join(", ")}` : void 0,
+		t.attachments.length > 0 ? `  attachments: ${t.attachments.join(", ")}` : void 0,
+		t.reply !== void 0 ? `  reply: ${t.reply}` : void 0,
+		subs ? `  subtasks: ${subs}` : void 0,
+		t.expiresAt !== void 0 ? `  expires: ${t.expiresAt}` : void 0,
+		t.groupId !== void 0 ? `  group: ${t.groupId}` : void 0
+	].filter((l) => l !== void 0).join("\n");
+}
+//#endregion
 //#region src/commands/download.ts
 const ID_GLOSSARY = "(ids: tsk_ task, sub_ subtask, sbm_ submission; files: inp_ input upload, rfl_ reply file, sbf_ submission file)";
 const resolveScope = (scopeId, fileId) => {
@@ -1927,11 +2013,6 @@ const resolveScope = (scopeId, fileId) => {
 	if (wantsSubmission !== (scope === "submission")) return Effect.fail(new UserError({ message: wantsSubmission ? `${fileId} is a submission file — pass its sbm_… id, not ${scopeId} ${ID_GLOSSARY}` : `${fileId} lives on a task chain — pass the tsk_… or sub_… id it belongs to, not ${scopeId} ${ID_GLOSSARY}` }));
 	return Effect.succeed(scope);
 };
-const downloadUrlPath = (scope, scopeId, fileId) => {
-	if (scope === "submission") return `/v1/submissions/${scopeId}/files/${fileId}/download-url`;
-	const kind = fileId.startsWith("inp_") ? "inputs" : "replies";
-	return `/v1/${scope === "task" ? "tasks" : "subtasks"}/${scopeId}/${kind}/${fileId}/download-url`;
-};
 /** Resolve where to write: an explicit file path, an existing directory (the
 * server-declared filename inside it), or the current directory. */
 const resolveTarget = async (outArg, filename) => {
@@ -1953,94 +2034,31 @@ const downloadCommand = Command.make("download", {
 	"base-url": baseUrlOption,
 	quiet: quietOption
 }, (args) => Effect.gen(function* () {
-	const out = yield* CliOutput;
-	yield* out.setQuiet(args.quiet);
-	const scope = yield* resolveScope(args.scopeId, args.fileId);
-	const cred = yield* resolveCredential(args["api-token"], args["base-url"]);
-	const orgKeys = cred.kind === "org" ? yield* loadOrgMasterKeys : void 0;
-	const baseUrl = cred.baseUrl.replace(/\/+$/, "");
-	const authHeaders = cred.kind === "personal" ? { "API-Token": cred.apiToken } : { Authorization: `Bearer ${cred.bearer}` };
-	const meta = yield* Effect.tryPromise({
-		try: async () => {
-			const res = await fetch(`${baseUrl}${downloadUrlPath(scope, args.scopeId, args.fileId)}`, {
-				method: "POST",
-				headers: authHeaders
-			});
-			if (!res.ok) {
-				const body = await res.text().catch(() => "");
-				let msg = `download-url failed (${res.status})`;
-				try {
-					const parsed = JSON.parse(body);
-					if (parsed.msg) msg = `${msg}: ${parsed.msg}`;
-				} catch {
-					if (body) msg = `${msg}: ${body.slice(0, 200)}`;
-				}
-				throw new Error(msg);
-			}
-			return await res.json();
-		},
-		catch: (e) => new UserError({ message: e instanceof Error ? e.message : String(e) })
-	});
-	const stored = yield* Effect.tryPromise({
-		try: async () => {
-			const res = await fetch(meta.presignedGetUrl);
-			if (!res.ok) throw new Error(`fetching the file failed (${res.status})`);
-			return new Uint8Array(await res.arrayBuffer());
-		},
-		catch: (e) => new UserError({ message: e instanceof Error ? e.message : String(e) })
-	});
-	if (meta.checksumSha256 !== void 0) {
-		const actual = createHash("sha256").update(stored).digest("base64");
-		if (actual !== meta.checksumSha256) return yield* Effect.fail(new UserError({ message: `checksum mismatch: stored blob hashes to ${actual}, server declared ${meta.checksumSha256}` }));
-	}
-	let bytes = stored;
-	if (meta.encryption !== void 0) {
-		const passwords = [...args.password];
-		const passwordSalt = passwords.filter((p) => typeof p === "string").length > 0 && cred.kind === "personal" ? yield* Effect.tryPromise({
-			try: async () => (await fetchUserInfo({
-				baseUrl: new URL(baseUrl),
-				apiToken: cred.apiToken,
-				fetch
-			})).passwordSalt,
-			catch: (e) => new UserError({ message: `fetching the password salt failed: ${e instanceof Error ? e.message : String(e)}` })
-		}) : void 0;
-		const key = yield* Effect.tryPromise({
+	yield* resolveScope(args.scopeId, args.fileId);
+	return yield* withQueryClient(args, (ctx) => Effect.gen(function* () {
+		const file = yield* Effect.tryPromise({
+			try: () => ctx.client.downloadFile(args.scopeId, args.fileId),
+			catch: (e) => new UserError({ message: e instanceof DownloadError && e.message.includes("no matching key") ? ctx.org ? "the file is sealed under an org master key — unlock the vault (org session) to decrypt" : "the file is encrypted — pass the matching -p/--password (`pw@topic`, or a bare account password)" : e instanceof Error ? e.message : String(e) })
+		});
+		const filename = file.filename ?? args.fileId;
+		const target = yield* Effect.tryPromise({
 			try: async () => {
-				const ring = await Keyring.build({
-					passwords: [],
-					topics: [],
-					...orgKeys !== void 0 ? { orgMasterKeys: orgKeys } : {}
-				});
-				for (const p of passwords) if (typeof p !== "string") ring.add(await deriveKey(p[0], p[1]));
-				else if (passwordSalt !== void 0) ring.add(await deriveKey(p, passwordSalt));
-				return ring.keyForMarker(meta.encryption);
+				const t = await resolveTarget(Option.getOrUndefined(args.out), filename);
+				await writeFile(t, file.bytes);
+				return t;
 			},
-			catch: (e) => new UserError({ message: `building the keyring failed: ${e instanceof Error ? e.message : String(e)}` })
-		});
-		if (key === void 0) return yield* Effect.fail(new UserError({ message: meta.encryption.type === "org" ? `the file is sealed under org master_key v${meta.encryption.v} — unlock the vault (org session) to decrypt` : "the file is encrypted — pass the matching -p/--password (`pw@topic`, or a bare account password)" }));
-		bytes = yield* Effect.tryPromise({
-			try: () => decryptBytes(key, stored),
-			catch: (e) => new UserError({ message: `decryption failed: ${e instanceof Error ? e.message : String(e)}` })
+			catch: (e) => new UserError({ message: `saving failed: ${e instanceof Error ? e.message : String(e)}` })
 		});
-	}
-	const filename = meta.filename ?? args.fileId;
-	const target = yield* Effect.tryPromise({
-		try: async () => {
-			const t = await resolveTarget(Option.getOrUndefined(args.out), filename);
-			await writeFile(t, bytes);
-			return t;
-		},
-		catch: (e) => new UserError({ message: `saving failed: ${e instanceof Error ? e.message : String(e)}` })
-	});
-	if (args.format === "json") yield* out.print(JSON.stringify({
-		type: "downloaded",
-		id: args.fileId,
-		path: target,
-		filename: meta.filename ?? null,
-		contentType: meta.contentType ?? null,
-		size: meta.size ?? null
+		if (args.format === "json") yield* ctx.out.print(JSON.stringify({
+			type: "downloaded",
+			id: args.fileId,
+			path: target,
+			filename: file.filename ?? null,
+			contentType: file.contentType ?? null,
+			size: file.size ?? null
+		}));
+		else yield* ctx.out.print(target);
 	}));
-	else yield* out.print(target);
 }));
 //#endregion
 //#region src/output.ts
@@ -2103,6 +2121,7 @@ const sinceOption = mappedText("since", resolveSince).pipe(Options.withDescripti
 const untilOption = mappedText("until", resolveUntil).pipe(Options.withDescription("Stop at this timestamp. Forces a finite range, so `--follow` is ignored."), Options.optional);
 const limitOption = Options.integer("limit").pipe(Options.withDescription("Maximum number of events to print, then exit."), Options.optional);
 const followOption = Options.boolean("follow").pipe(Options.withAlias("f"), Options.withDescription("After history is drained, keep streaming live instead of exiting. Only meaningful with `--since`."));
+const memberOption$2 = Options.text("member").pipe(Options.optional, Options.withDescription("Only events by this person: a usr_ id, or the actor's name."));
 const formatOption$3 = Options.choice("format", [
 	"json",
 	"pretty",
@@ -2112,13 +2131,14 @@ const directOption = Options.boolean("direct").pipe(Options.withDescription("Ope
 const QUIET_EXIT_MS = 2e3;
 const eventsCommand = Command.make("events", {
 	type: eventTypeOption,
+	member: memberOption$2,
 	since: sinceOption,
 	until: untilOption,
 	limit: limitOption,
 	follow: followOption,
 	format: formatOption$3,
 	direct: directOption,
-	topic: topicOption,
+	topic: topicOption$1,
 	"api-token": apiTokenOption,
 	password: passwordOption,
 	"base-url": baseUrlOption,
@@ -2132,6 +2152,8 @@ const eventsCommand = Command.make("events", {
 	const untilDate = Option.getOrUndefined(args.until);
 	const limit = Option.getOrUndefined(args.limit);
 	const filter = new TypeFilter(args.type);
+	const member = Option.getOrUndefined(args.member);
+	const memberMatches = (ev) => member === void 0 || ev.actor?.publicId === member || ev.actor?.name === member;
 	yield* Effect.forEach(filter.unknown, (u) => out.warn(`ignoring unknown --type \`${u}\``));
 	const webSocketFactory = args.direct || sinceIso !== void 0 ? Option.none() : yield* sharedWebSocketFactory({
 		credential: cred.kind === "personal" ? {
@@ -2194,7 +2216,7 @@ const eventsCommand = Command.make("events", {
 		yield* sdkStream("events stream", (signal) => client.events({
 			...sinceIso !== void 0 ? { since: sinceIso } : {},
 			signal: AbortSignal.any([signal, endController.signal])
-		})).pipe(Stream.tap(() => Ref.set(lastActivity, Date.now())), Stream.interruptWhen(Deferred.await(halt)), untilDate !== void 0 ? Stream.takeUntilEffect((ev) => untilReached(ev) ? note("--until reached, exiting").pipe(Effect.zipRight(Deferred.succeed(halt, void 0)), Effect.as(true)) : Effect.succeed(false)) : (s) => s, Stream.filter((ev) => !untilReached(ev) && filter.matches(ev)), Stream.mapEffect((ev) => Effect.gen(function* () {
+		})).pipe(Stream.tap(() => Ref.set(lastActivity, Date.now())), Stream.interruptWhen(Deferred.await(halt)), untilDate !== void 0 ? Stream.takeUntilEffect((ev) => untilReached(ev) ? note("--until reached, exiting").pipe(Effect.zipRight(Deferred.succeed(halt, void 0)), Effect.as(true)) : Effect.succeed(false)) : (s) => s, Stream.filter((ev) => !untilReached(ev) && filter.matches(ev) && memberMatches(ev)), Stream.mapEffect((ev) => Effect.gen(function* () {
 			const decrypted = keyring ? yield* sdkCall("decrypt event", () => tryDecryptEventData(ev, keyring)) : void 0;
 			yield* out.print(formatEvent(ev, args.format, decrypted));
 			const n = yield* Ref.updateAndGet(printed, (x) => x + 1);
@@ -2212,6 +2234,204 @@ const eventsCommand = Command.make("events", {
 	}));
 }));
 //#endregion
+//#region src/commands/get.ts
+const topicOption = Options.text("topic").pipe(Options.optional, Options.withDescription("Only tasks sent to this topic: its value (name), or its id."));
+const groupOption = Options.text("group").pipe(Options.optional, Options.withDescription("Only the instances of this grptsk_ group."));
+/** Flags that only make sense on the paged listings. Id reads reject them by
+* name instead of silently ignoring them. */
+function rejectListFlags(args, target, allowStatus) {
+	const set = [
+		...!allowStatus && args.status.length > 0 ? ["--status"] : [],
+		...Option.isSome(args.since) ? ["--since"] : [],
+		...Option.isSome(args.until) ? ["--until"] : [],
+		...Option.isSome(args.topic) ? ["--topic"] : [],
+		...Option.isSome(args.member) ? ["--member"] : [],
+		...Option.isSome(args.group) ? ["--group"] : [],
+		...Option.isSome(args.limit) ? ["--limit"] : [],
+		...Option.isSome(args.cursor) ? ["--cursor"] : [],
+		...args.all ? ["--all"] : []
+	];
+	return set.length === 0 ? Effect.void : Effect.fail(new UserError({ message: `${set.join(", ")} does not apply when reading ${target}` }));
+}
+function getChain(args, ctx) {
+	return Effect.gen(function* () {
+		yield* rejectListFlags(args, "one task", false);
+		const chain = yield* sdkCall("read task chain", () => ctx.client.getTaskChain(args.what));
+		const dec = new Decryptor(ctx.keyring);
+		const task = yield* dec.payload(chain.task);
+		const subtasks = [];
+		for (const s of chain.subtasks) subtasks.push({
+			subtask: yield* dec.payload(s.subtask),
+			createdAt: s.createdAt
+		});
+		const view = {
+			task,
+			createdAt: chain.createdAt,
+			subtasks
+		};
+		if (args.format === "json") yield* ctx.out.print(JSON.stringify(view));
+		else {
+			yield* ctx.out.print(`${task.taskId}  [${task.status}]  ${chain.createdAt}`);
+			yield* ctx.out.print(JSON.stringify(task, null, 2));
+			for (const s of subtasks) {
+				yield* ctx.out.print(`\n${s.subtask.subtaskId}  [${s.subtask.status}]  ${s.createdAt}`);
+				yield* ctx.out.print(JSON.stringify(s.subtask, null, 2));
+			}
+		}
+		yield* dec.report(ctx.out);
+	});
+}
+function getSubtaskRead(args, ctx) {
+	return Effect.gen(function* () {
+		yield* rejectListFlags(args, "one subtask", false);
+		const subtask = yield* sdkCall("read subtask", () => ctx.client.getSubtask(args.what));
+		const dec = new Decryptor(ctx.keyring);
+		const view = yield* dec.payload(subtask);
+		if (args.format === "json") yield* ctx.out.print(JSON.stringify(view));
+		else {
+			yield* ctx.out.print(`${view.subtaskId}  [${view.status}]  parent ${String(view.parentTaskId ?? "-")}`);
+			yield* ctx.out.print(JSON.stringify(view, null, 2));
+		}
+		yield* dec.report(ctx.out);
+	});
+}
+function getRoster(args, ctx) {
+	return Effect.gen(function* () {
+		yield* rejectListFlags(args, "a task group roster", true);
+		const roster = yield* sdkCall("read task group", () => ctx.client.getTaskGroup(args.what, args.status.length > 0 ? { status: args.status } : {}));
+		const dec = new Decryptor(ctx.keyring);
+		const counts = {};
+		for (const t of roster.tasks) counts[t.status] = (counts[t.status] ?? 0) + 1;
+		if (args.format === "json") {
+			yield* ctx.out.print(JSON.stringify({
+				type: "group",
+				groupId: roster.groupId,
+				counts
+			}));
+			for (const t of roster.tasks) yield* ctx.out.print(JSON.stringify(yield* dec.summary(t)));
+		} else {
+			const summary = Object.entries(counts).map(([k, v]) => `${k} ${v}`).join(", ") || "no instances";
+			yield* ctx.out.print(`${roster.groupId}  ${summary}`);
+			for (const t of roster.tasks) yield* ctx.out.print(formatTaskSummary(yield* dec.summary(t)));
+		}
+		yield* dec.report(ctx.out);
+	});
+}
+function getTasks(args, ctx) {
+	return Effect.gen(function* () {
+		const dec = new Decryptor(ctx.keyring);
+		const opts = {
+			...args.status.length > 0 ? { status: args.status } : {},
+			...Option.match(args.since, {
+				onNone: () => ({}),
+				onSome: (since) => ({ since })
+			}),
+			...Option.match(args.until, {
+				onNone: () => ({}),
+				onSome: (until) => ({ until })
+			}),
+			...Option.match(args.topic, {
+				onNone: () => ({}),
+				onSome: (topic) => ({ topic })
+			}),
+			...Option.match(args.member, {
+				onNone: () => ({}),
+				onSome: (member) => ({ member })
+			}),
+			...Option.match(args.group, {
+				onNone: () => ({}),
+				onSome: (group) => ({ group })
+			}),
+			...Option.match(args.limit, {
+				onNone: () => ({}),
+				onSome: (limit) => ({ limit })
+			})
+		};
+		yield* forEachPage(ctx, args.format, args.all, Option.getOrUndefined(args.cursor), (cursor) => sdkCall("list tasks", () => ctx.client.listTasks({
+			...opts,
+			...cursor !== void 0 ? { cursor } : {}
+		})), (page) => Effect.forEach(page.tasks, (t) => Effect.gen(function* () {
+			const row = yield* dec.summary(t);
+			yield* ctx.out.print(args.format === "json" ? JSON.stringify(row) : formatTaskSummary(row));
+		}), { discard: true }));
+		yield* dec.report(ctx.out);
+	});
+}
+function getSubmissions(args, ctx) {
+	return Effect.gen(function* () {
+		const wrong = [
+			...args.status.length > 0 ? ["--status"] : [],
+			...Option.isSome(args.topic) ? ["--topic"] : [],
+			...Option.isSome(args.group) ? ["--group"] : []
+		];
+		if (wrong.length > 0) return yield* Effect.fail(new UserError({ message: `${wrong.join(", ")} does not apply to submissions` }));
+		const dec = new Decryptor(ctx.keyring);
+		const opts = {
+			...Option.match(args.since, {
+				onNone: () => ({}),
+				onSome: (since) => ({ since })
+			}),
+			...Option.match(args.until, {
+				onNone: () => ({}),
+				onSome: (until) => ({ until })
+			}),
+			...Option.match(args.member, {
+				onNone: () => ({}),
+				onSome: (member) => ({ member })
+			}),
+			...Option.match(args.limit, {
+				onNone: () => ({}),
+				onSome: (limit) => ({ limit })
+			})
+		};
+		yield* forEachPage(ctx, args.format, args.all, Option.getOrUndefined(args.cursor), (cursor) => sdkCall("list submissions", () => ctx.client.listSubmissions({
+			...opts,
+			...cursor !== void 0 ? { cursor } : {}
+		})), (page) => Effect.forEach(page.submissions, (entry) => Effect.gen(function* () {
+			const submission = yield* dec.submission(entry.submission, entry.encryption);
+			const by = entry.actor?.name ?? entry.actor?.publicId;
+			if (args.format === "json") yield* ctx.out.print(JSON.stringify({
+				...submission,
+				...entry.actor !== void 0 ? { actor: entry.actor } : {}
+			}));
+			else {
+				const body = submission.body;
+				const parts = [
+					body?.value !== void 0 ? body.value : void 0,
+					submission.photo !== void 0 ? "[photo]" : void 0,
+					submission.file !== void 0 ? "[file]" : void 0,
+					submission.audio !== void 0 ? "[audio]" : void 0,
+					submission.location !== void 0 ? "[location]" : void 0
+				].filter((p) => p !== void 0);
+				yield* ctx.out.print(`${submission.id}  ${submission.createdAt}  ${by ?? "-"}: ${parts.join(" ") || "(empty)"}`);
+			}
+		}), { discard: true }));
+		yield* dec.report(ctx.out);
+	});
+}
+const getCommand = Command.make("get", {
+	what: Args.text({ name: "what" }).pipe(Args.withDescription("What to read: tasks, submissions, a tsk_ id, a sub_ id, or a grptsk_ id.")),
+	status: statusOption,
+	since: sinceOption$1,
+	until: untilOption$1,
+	topic: topicOption,
+	member: memberOption$3,
+	group: groupOption,
+	limit: limitOption$1,
+	cursor: cursorOption,
+	all: allOption,
+	format: formatOption$4,
+	...credentialOptions
+}, (args) => withQueryClient(args, (ctx) => {
+	if (args.what === "tasks") return getTasks(args, ctx);
+	if (args.what === "submissions") return getSubmissions(args, ctx);
+	if (args.what.startsWith("tsk_")) return getChain(args, ctx);
+	if (args.what.startsWith("sub_")) return getSubtaskRead(args, ctx);
+	if (args.what.startsWith("grptsk_")) return getRoster(args, ctx);
+	const hint = args.what.startsWith("sbm_") ? "a single submission has no read endpoint; find it in the listing: sp get submissions --since … --format json" : "expected tasks, submissions, a tsk_ id, a sub_ id, or a grptsk_ id";
+	return Effect.fail(new UserError({ message: `cannot read '${args.what}': ${hint}` }));
+})).pipe(Command.withDescription("Read what came back: 'tasks' or 'submissions' for filtered listings, a tsk_ id for one task with its subtasks, a sub_ id for one subtask, a grptsk_ id for a group's per-recipient roster."));
+//#endregion
 //#region src/input-spec.ts
 const SETTING_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
 function looksLikeSetting(seg) {
@@ -2621,7 +2841,7 @@ const notifyCommand = Command.make("notify", {
 	shared: sharedOption$1,
 	format: formatOption$2,
 	noEncrypt: noEncryptOption$2,
-	topic: topicOption,
+	topic: topicOption$1,
 	"api-token": apiTokenOption,
 	password: passwordOption,
 	"base-url": baseUrlOption,
@@ -2812,7 +3032,7 @@ const putIntegrationWraps = (id, wraps) => Effect.gen(function* () {
 	yield* (yield* Api).put("integration wrap", `/v1/org/integrations/${encodeURIComponent(id)}/wraps`, { wraps });
 });
 const nameOption = Options.text("name").pipe(Options.withDescription("Human-readable label, shown in `sp integration list` and nowhere else."));
-const scopesOption = Options.text("scopes").pipe(Options.withDefault("send,events:read"), Options.withDescription("Comma-separated scopes (send, events:read, files:read). org:admin is refused — administration is a human act."));
+const scopesOption = Options.text("scopes").pipe(Options.withDefault("send,read"), Options.withDescription("Comma-separated scopes (send, read, files:read). org:admin is refused — administration is a human act."));
 const createCommand = Command.make("create", {
 	name: nameOption,
 	scopes: scopesOption,
@@ -3535,7 +3755,7 @@ const taskCommand = Command.make("task", {
 	shared: sharedOption,
 	expires: expiresOption,
 	format: formatOption$1,
-	topic: topicOption,
+	topic: topicOption$1,
 	"api-token": apiTokenOption,
 	password: passwordOption,
 	"base-url": baseUrlOption,
@@ -3841,7 +4061,7 @@ const subtaskCommand = Command.make("subtask", {
 	markdown: markdownOption,
 	"no-encrypt": noEncryptOption,
 	instance: instanceOption,
-	topic: topicOption,
+	topic: topicOption$1,
 	"api-token": apiTokenOption,
 	password: passwordOption,
 	"base-url": baseUrlOption,
@@ -4022,7 +4242,8 @@ const root = Command.make("simplepush").pipe(Command.withSubcommands([
 	notifyCommand,
 	taskCommand,
 	subtaskCommand,
-	cancelCommand
+	cancelCommand,
+	getCommand
 ]));
 const cli = Command.run(root, {
 	name: "Simplepush CLI",