@hive3/cli 0.4.0 → 0.5.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.
@@ -0,0 +1,11 @@
1
+ // @ts-check
2
+
3
+ export function createTeamClient(client) {
4
+ return {
5
+ operations: () => client.request("GET", "/team/operations"),
6
+ execute: (operation, payload, options = {}) => client.request("POST", `/team/operations/${encodeURIComponent(operation)}`, {
7
+ body: { payload, ...(options.confirmed ? { confirmed: true } : {}), ...(options.confirmation !== undefined ? { confirmation: options.confirmation } : {}), ...(options.requestId ? { requestId: options.requestId } : {}) },
8
+ idempotencyKey: options.requestId,
9
+ }),
10
+ };
11
+ }
@@ -0,0 +1,84 @@
1
+ // @ts-check
2
+
3
+ import { randomUUID } from "node:crypto";
4
+ import path from "node:path";
5
+ import { authenticatedClient, readJsonObject, requiredFlagValue, writeJson, writeLine } from "./shared.js";
6
+ import { createTeamClient } from "./team-client.js";
7
+ import { runFeedbackCommand } from "./feedback-commands.js";
8
+
9
+ // Client preflight only; authoritative operation names, validators and permissions live on the server.
10
+ const READ_OPERATIONS = new Set([
11
+ "accounts.search", "accounts.get", "events.search", "accounts.suggest-handle", "accounts.check-handle", "accounts.list-processing", "accounts.handover-target",
12
+ "featured.list", "onboarding.list", "credentials.list", "credentials.summary", "credentials.platform-wallets", "invites.list", "invites.email-account-hint", "billing.list",
13
+ "worlds.list", "worlds.get", "worlds.calendar", "worlds.sharedBans", "worlds.capacity", "reports.summary", "reports.rows",
14
+ "referrals.summary", "referrals.listReferrals", "referrals.referrerDetail", "referrals.referrerAttributions", "referrals.referrerConversions", "referrals.conversionPayments", "referrals.conversionAdjustments",
15
+ "migration.summary", "migration.accounts", "migration.unowned", "migration.clusters", "migration.resolutions",
16
+ ]);
17
+ const EXACT_OPERATIONS = new Set(["featured.remove", "featured.remove-highlight", "onboarding.remove", "invites.remove", "billing.cancel", "credentials.withdraw-fees"]);
18
+
19
+ export function teamUsage() {
20
+ return `Usage:
21
+ hive3 team operations [domain]
22
+ hive3 team <domain> <action> [--file payload.json] [--yes] [--confirm <exact-text>] [--idempotency-key <key>]
23
+ hive3 team feedback <list|get|messages|reply|status> [options]
24
+
25
+ Team Tools require current staff access and team:read/team:write scopes.
26
+ Staff: run hive3 login again (Team Tools are added automatically for staff accounts).
27
+ Operations are a fixed server allowlist, never arbitrary Convex function names.
28
+ team operations returns each operation's argument schema, description and confirmation rule.
29
+ Read payloads default to {}; use --file for operation arguments, including sensitive data.
30
+ Changes require --yes; resource removal and fee collection also require exact --confirm text.
31
+ Ownership transfers and legacy login invitations stay in browser Team Tools.
32
+ A fresh request ID is generated for each confirmed command; pass --idempotency-key to replay safely.
33
+ No automatic retry repeats an external email, entry issuance or withdrawal attempt.
34
+ Account deletion, destructive merges and resolution retries are not available through the CLI or API.
35
+
36
+ Examples:
37
+ hive3 team operations accounts
38
+ hive3 team accounts get --file account.json
39
+ hive3 team accounts set-tier --file tier.json --yes
40
+ hive3 team accounts grant-time --file time.json --yes
41
+ hive3 team credentials platform-wallets
42
+ hive3 team feedback list --status open`;
43
+ }
44
+
45
+ function parseOptions(args) {
46
+ const parsed = { yes: false };
47
+ for (let index = 0; index < args.length; index++) {
48
+ const flag = args[index];
49
+ if (flag === "--yes") { parsed.yes = true; continue; }
50
+ if (!["--file", "--confirm", "--idempotency-key"].includes(flag)) throw new Error(`Unknown team option: ${flag}`);
51
+ const key = flag.slice(2);
52
+ if (parsed[key] !== undefined) throw new Error(`${flag} may only be given once`);
53
+ parsed[key] = requiredFlagValue(flag, args[++index]);
54
+ }
55
+ if (parsed.confirm !== undefined && !parsed.yes) throw new Error("--confirm also requires --yes");
56
+ if (parsed["idempotency-key"] !== undefined && (!parsed["idempotency-key"].trim() || parsed["idempotency-key"].length > 128)) throw new Error("--idempotency-key must contain 1–128 characters");
57
+ return parsed;
58
+ }
59
+
60
+ export async function runTeamCommand(args, deps) {
61
+ if (args.length === 0 || args.some(arg => arg === "--help" || arg === "-h")) {
62
+ writeLine(deps.stdout, teamUsage());
63
+ return 0;
64
+ }
65
+ if (args[0] === "feedback") return await runFeedbackCommand(["team", ...args.slice(1)], deps);
66
+ if (args[0] === "operations") {
67
+ if (args.length > 2 || args[1]?.startsWith("-")) throw new Error("Usage: hive3 team operations [domain]");
68
+ const client = createTeamClient(await authenticatedClient(deps));
69
+ const result = await client.operations();
70
+ writeJson(deps.stdout, args[1] ? { ...result, data: result.data.filter(operation => operation.name.startsWith(`${args[1]}.`)) } : result);
71
+ return 0;
72
+ }
73
+ const [domain, action, ...rest] = args;
74
+ if (!domain || !action || !/^[a-z][a-zA-Z0-9-]*$/.test(domain) || !/^[a-z][a-zA-Z0-9-]*$/.test(action)) throw new Error("Usage: hive3 team <domain> <action> [--file payload.json] [--yes]");
75
+ const options = parseOptions(rest);
76
+ const operation = `${domain}.${action}`;
77
+ if (!READ_OPERATIONS.has(operation) && !options.yes) throw new Error("Team changes require --yes. Use team operations to discover argument and confirmation requirements.");
78
+ if (EXACT_OPERATIONS.has(operation) && options.confirm === undefined) throw new Error("This Team operation requires --confirm <exact-text>. Read team operations for its confirmation rule.");
79
+ const payload = options.file ? await readJsonObject(path.resolve(deps.cwd, options.file)) : {};
80
+ const client = createTeamClient(await authenticatedClient(deps));
81
+ const result = await client.execute(operation, payload, { confirmed: options.yes, confirmation: options.confirm, requestId: options.yes ? options["idempotency-key"] ?? randomUUID() : undefined });
82
+ writeJson(deps.stdout, result);
83
+ return 0;
84
+ }
package/src/usage.js CHANGED
@@ -1,5 +1,12 @@
1
1
  // @ts-check
2
2
 
3
+ import { teamUsage } from "./team-commands.js";
4
+ import { stripeUsage } from "./stripe-commands.js";
5
+ import { feedbackUsage } from "./feedback-commands.js";
6
+ import { paymentsUsage } from "./payments-commands.js";
7
+ import { conversationsUsage } from "./conversations-commands.js";
8
+ import { sellingUsage } from "./selling-commands.js";
9
+
3
10
  export function usage() {
4
11
  return [
5
12
  "Usage: hive3 <command> [options]",
@@ -15,7 +22,7 @@ export function usage() {
15
22
  " capabilities List the accounts this key can act on and what it may do there",
16
23
  " profile <action> Manage profile text, media IDs, access, and builders; add --account <id-or-handle> for an account you help run",
17
24
  " upload <file> Upload an allowed image or document and print its storage ID",
18
- " account <action> Manage account preferences, exports, linked communities, and deletion cancellation",
25
+ " account <action> Manage account preferences, exports, and linked communities",
19
26
  " wallets <action> Manage linked wallet visibility/default selection",
20
27
  " nfts <action> Manage public NFT exposure",
21
28
  " notifications <action> Manage notifications, unread count, and notification mutes",
@@ -23,15 +30,23 @@ export function usage() {
23
30
  " communities <action> Manage community membership and role-derived admin actions",
24
31
  " posts <action> Manage posts",
25
32
  " events <action> Manage events",
33
+ " worlds [--account a] List the 3D worlds an account's events may book, with the ID to pass to events --world",
26
34
  " courses <action> Manage courses",
27
35
  " content <action> Manage content",
28
36
  " quests <action> Manage quests",
29
37
  " jobs <action> Manage jobs",
30
38
  " search <query> Search accounts, events, courses, content, quests and jobs",
31
39
  " broadcasts <action> Draft, test, schedule and send broadcast emails to an account's members",
32
- " tickets <action> View and update tickets you sell, and list tickets you own",
40
+ " tickets <action> Create, attach, edit and deactivate sold tickets; view purchased tickets",
33
41
  " assistant <action> Manage an account's AI assistant and its knowledge documents",
34
42
  " credentials <action> View credentials, award custom credentials, list yours and claimable ones",
43
+ " team <area> <action> Manage Team Tools (current staff only)",
44
+ " stripe <action> Set up and manage the account's Stripe Connect connection",
45
+ " feedback <action> Submit bugs/suggestions and follow up on support tickets",
46
+ " products <action> Manage seller products",
47
+ " subscriptions <action> Manage seller subscription plans",
48
+ " payments <action> View payment history and preview/confirm checkout, subscription and refund workflows",
49
+ " conversations <action> Read and write your DMs and accessible community conversations with separate consent",
35
50
  "",
36
51
  "Options:",
37
52
  " -v, --version Print the CLI version",
@@ -43,6 +58,7 @@ export function usage() {
43
58
  " create [--title t] [--body b] [--description d] [--content-type t] [--visibility v]",
44
59
  " update <id> [--title t] [--body b] [--description d] [--content-type t] [--visibility v]",
45
60
  " archive <id>",
61
+ " events create|update also take --world <world-id|default> to book a 3D world; get world IDs from `hive3 worlds`",
46
62
  "",
47
63
  "Account deletion is not available from the CLI; delete your account in the Hive app under Settings.",
48
64
  ].join("\n");
@@ -100,6 +116,10 @@ export function resourceUsage(kind) {
100
116
  " --content-type <type>",
101
117
  " --image-url <url>",
102
118
  " --visibility <public|protected|private>",
119
+ ...(kind === "events" ? [
120
+ " --world <world-id|default> Book a 3D world: the ID of the world the user named, from `hive3 worlds`;",
121
+ " default is the owning account's default world",
122
+ ] : []),
103
123
  " --file <json> JSON object merged with the flags above",
104
124
  "",
105
125
  "Create owner fields (managed accounts only after `hive3 capabilities` shows them):",
@@ -165,6 +185,17 @@ const commandUsageLines = {
165
185
  "Searches what your account can see. The query is 1-100 characters; quote it or pass several words.",
166
186
  "Needs the resources:read scope.",
167
187
  ],
188
+ worlds: [
189
+ "Usage: hive3 worlds [--account <id-or-handle>]",
190
+ "",
191
+ "Lists the 3D worlds the account's events may book: { worlds: [{ id, name, kind, isDefault }], needsDedicatedSetup }.",
192
+ "kind is shared (a Hive3 venue such as Hive3 Dome or Night Lounge) or dedicated (the account's own world).",
193
+ "isDefault marks the world `--world default` books. Pass the id of the world the user named to `events create --world <id>`;",
194
+ "if it isn't listed, that account can't book it. An empty list means the plan includes no world; needsDedicatedSetup means",
195
+ "a Royal Hive account must choose its own world's design on the dashboard first.",
196
+ "Needs resources:read.",
197
+ ...ACCOUNT_OPTION_LINES,
198
+ ],
168
199
  broadcasts: [
169
200
  "Usage: hive3 broadcasts <action> [options]",
170
201
  "",
@@ -184,19 +215,6 @@ const commandUsageLines = {
184
215
  "Needs broadcasts:read / broadcasts:write and an owner, admin or moderator role.",
185
216
  ...ACCOUNT_OPTION_LINES,
186
217
  ],
187
- tickets: [
188
- "Usage: hive3 tickets <action> [options]",
189
- "",
190
- "Actions:",
191
- " list [--account a] [--limit n] [--cursor c] Tickets an account sells (owners and admins)",
192
- " get <id>",
193
- " update <id> [--name n] [--description d] [--amount 10.00] [--currency USD] [--status active|inactive]",
194
- " mine [--limit n] [--cursor c] Tickets you bought",
195
- "",
196
- "Creating tickets, checkout and refunds are not available from the CLI.",
197
- "Needs tickets:read / tickets:write.",
198
- ...ACCOUNT_OPTION_LINES,
199
- ],
200
218
  assistant: [
201
219
  "Usage: hive3 assistant <action> [options]",
202
220
  "",
@@ -256,12 +274,11 @@ const commandUsageLines = {
256
274
  "Actions:",
257
275
  " get",
258
276
  " preferences [--theme t] [--muted-notifications a,b]",
259
- " export Request an export of your account data",
277
+ " export Full account archive; requires all included domain read scopes",
260
278
  " linked-communities [list]",
261
279
  " linked-communities disconnect <community-id> --confirm <community-id>",
262
- " deletion cancel Cancel a pending account deletion",
263
280
  "",
264
- "Account deletion can't be requested from the CLI; delete your account in the Hive app under Settings.",
281
+ "Account deletion is not exposed by the CLI, including Team Tools.",
265
282
  "Always acts as the signed-in account (--account is not supported).",
266
283
  ],
267
284
  wallets: [
@@ -310,10 +327,21 @@ const commandUsageLines = {
310
327
  ],
311
328
  };
312
329
 
330
+ /** @type {Record<string, () => string>} */
331
+ const dynamicUsage = {
332
+ team: teamUsage,
333
+ stripe: stripeUsage,
334
+ feedback: feedbackUsage,
335
+ payments: paymentsUsage,
336
+ conversations: conversationsUsage,
337
+ products: sellingUsage,
338
+ subscriptions: sellingUsage,
339
+ tickets: sellingUsage,
340
+ };
341
+
313
342
  /** @param {string} command */
314
343
  export function commandUsage(command) {
315
- const lines = commandUsageLines[command];
344
+ if (Object.hasOwn(dynamicUsage, command)) return dynamicUsage[command]();
345
+ const lines = Object.hasOwn(commandUsageLines, command) ? commandUsageLines[command] : undefined;
316
346
  return lines ? lines.join("\n") : undefined;
317
347
  }
318
-
319
- export const helpCommands = Object.keys(commandUsageLines);