@hive3/cli 0.7.0 → 0.8.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/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Command-line client for the Hive3 public API. The CLI always uses the API key of the account you sign in with. Accounts in Hive3 are unified: a personal profile and a community are the same kind of account, so the CLI can act on your own account and on any account where you currently are owner, admin or moderator. Run `hive3 capabilities` to see which accounts your key can act on and what it may do there. (The API still calls these "communities" and "person" in some field names.)
4
4
 
5
- Version 0.5 adds separately approved conversations, seller products/subscription plans/event tickets, confirmed payment management, Stripe Connect, feedback tickets, and `hive3 worlds` for choosing which 3D world an event books. Existing keys do not gain new scopes automatically. 0.5.1 names itself Hive3 CLI in all messages, and its agent skill checks for updates at the start of a session. 0.6.0 adds `--billing month|quarter|year` to membership checkout and revise: quarterly is 10% off and paid every 3 months, yearly is 20% off and paid once a year. 0.7.0 adds event types: `events create|update --location irl|virtual|metaverse` with venue (`--address`, `--venue-name`, `--venue-instructions`, `--check-in self|door`) and meeting (`--meeting-url`, `--meeting-provider`, `--meeting-instructions`) flags, `events list --location`, the `in_person_events_attended` quest objective, and `hiddenTabs` in the overview config.
5
+ Version 0.5 adds separately approved conversations, seller products/subscription plans/event tickets, confirmed payment management, Stripe Connect, feedback tickets, and `hive3 worlds` for choosing which 3D world an event books. Existing keys do not gain new scopes automatically. 0.5.1 names itself Hive3 CLI in all messages, and its agent skill checks for updates at the start of a session. 0.6.0 adds `--billing month|quarter|year` to membership checkout and revise: quarterly is 10% off and paid every 3 months, yearly is 20% off and paid once a year. 0.7.0 adds event types: `events create|update --location irl|virtual|metaverse` with venue (`--address`, `--venue-name`, `--venue-instructions`, `--check-in self|door`) and meeting (`--meeting-url`, `--meeting-provider`, `--meeting-instructions`) flags, `events list --location`, the `in_person_events_attended` quest objective, and `hiddenTabs` in the overview config. 0.8.0 lists your own data: `events rsvps`, `courses enrollments` and `quests enrollments` without an id, `communities mine`, `credits`, `wallets balances`, `nfts list`, `referrals` and `payments balances`.
6
6
 
7
7
  ## Install And Login
8
8
 
@@ -171,7 +171,14 @@ Allowed image types: GIF, JPEG, PNG, WebP up to 8 MB. Allowed document types: PD
171
171
 
172
172
  Workflow commands use `/api/v1/workflows/*` and print JSON for agents. Resource participant/application lists require management rights; `jobs applications` without a job ID lists your own applications. Personal RSVP/enrollment/applications use your audience and entitlement rights, not a managed-target allowlist.
173
173
 
174
+ `events rsvps` lists your own RSVPs (newest first, at most 200) and `courses enrollments` without a course ID lists your own course enrollments. Each row has a `status` of `approved`, `pending` (waiting for the organizer) or `declined`; events also carry their times, location and `attendedAt`, courses their lesson progress. Archived items and items you can no longer see are left out; `locked: true` marks one you can see but no longer open. `--upcoming` keeps events that have not finished; `--active` leaves out completed courses. Cancel with `events rsvp <event-id> --enroll false` or `courses enroll <course-id> --enroll false`.
175
+
176
+ `quests enrollments` without a quest ID lists your own quests (newest first, at most 100) with the same `status` and `locked`, the quest's `questStatus`, `endsAt` and `rewards` (credential names) and, for approved enrollments you can open, `progress`: `percent`, `completed` and each objective's count against its target, with evidence counts for objectives that need evidence. `--active` leaves out completed quests. Leave with `quests enroll <quest-id> --enroll false`.
177
+
178
+ `communities mine` lists the communities and accounts you belong to, as My Hive shows them, with your `role` there and `joinedAt` (needs `communities:read`). Applications to private communities still waiting for a decision come first with `status: "pending"`. Join or leave with `communities join|apply|leave <community-id>`.
179
+
174
180
  ```bash
181
+ hive3 events rsvps --upcoming
175
182
  hive3 events participants <event-id>
176
183
  hive3 events rsvp <event-id> --enroll true
177
184
  hive3 events approve <event-id> <enrollment-id>
@@ -179,12 +186,14 @@ hive3 events deny <event-id> <enrollment-id>
179
186
  hive3 events attendance <event-id> <enrollment-id>
180
187
 
181
188
  hive3 courses enroll <course-id>
189
+ hive3 courses enrollments --active
182
190
  hive3 courses enrollments <course-id>
183
191
  hive3 courses approve <course-id> <account-id>
184
192
  hive3 courses deny <course-id> <account-id>
185
193
  hive3 courses complete <course-id> <lesson-id>
186
194
 
187
195
  hive3 quests enroll <quest-id>
196
+ hive3 quests enrollments --active
188
197
  hive3 quests enrollments <quest-id>
189
198
  hive3 quests approve <quest-id> <enrollment-id>
190
199
  hive3 quests deny <quest-id> <enrollment-id>
@@ -252,14 +261,21 @@ hive3 account export
252
261
  hive3 account linked-communities
253
262
  hive3 account linked-communities disconnect <community-id> --confirm <community-id>
254
263
  hive3 wallets list
264
+ hive3 wallets balances
255
265
  hive3 wallets default <wallet-address>
256
266
  hive3 wallets visibility <wallet-address> --public true
257
267
  hive3 wallets remove <wallet-address> --confirm <wallet-address>
258
268
  hive3 nfts visibility --public false
269
+ hive3 nfts list --limit 20
270
+ hive3 credits
271
+ hive3 credits usage --days 7
272
+ hive3 credits history --limit 20
273
+ hive3 referrals
259
274
  hive3 notifications list --unread-only
260
275
  hive3 notifications unread-count
261
276
  hive3 notifications mutes set --scope <scope> --muted true
262
277
  hive3 comments create --post-id <post-id> --content "Nice work"
278
+ hive3 communities mine
263
279
  hive3 communities applications <community-id>
264
280
  hive3 communities approve <application-id>
265
281
  ```
@@ -369,10 +385,14 @@ hive3 payments sales --account <seller>
369
385
  hive3 payments preview checkout ticket <ticket-id>
370
386
  hive3 payments checkout ticket <ticket-id> --yes --confirm "<preview.confirm>" --request-id <unique-id>
371
387
  hive3 payments preview subscription cancel <purchased-subscription-id>
388
+ hive3 payments balances
389
+ hive3 payments balances --account <managed-account>
372
390
  ```
373
391
 
374
392
  `subscriptions` manages the seller's plans; `payments subscriptions` manages the buyer's billing obligations. Inspect the preview's exact account/provider/target/amount and approve the effect before using its confirmation. Every financial operation needs `--yes`, the unchanged current preview `--confirm`, and a unique `--request-id`. Rechecks apply before provider effects; never supply client prices, payees or arbitrary provider administration fields.
375
393
 
394
+ `payments balances` shows the quest credits (per plan: remaining of total) and metaverse minutes an account has left now, from its plan's monthly allowance plus purchases that have not been used or expired; `--account` follows the seller rules above. `credits` shows your AI credit balance (purchased credits and what is left of this month's free allowance), and `credits usage|calls|history` what they were spent on, in credits as the app shows them plus exact `micros` (needs `payments:read`). `wallets balances` reads your Hive3 wallet's native and USDC balance on each network live, and `nfts list` the NFTs of your linked wallets (both need `account:read`). `referrals` shows your referral code, share link and counts; the code exists once you have opened Settings → Referrals in the app. All of these are read-only and only ever show your own account, or one you run with `--account`.
395
+
376
396
  Supported flows: Stripe/PayPal creator-subscription and ticket checkout/finalization; Stripe platform membership, quest-credit and metaverse-time checkout; subscription/membership cancel/resume/portals; supported platform tier and PayPal creator-plan revision; buyer refund requests and seller owner/admin review. Checkout and approval links are private owner browser handoffs. Managed platform membership checkout is owner-only and bound to its original payer; ongoing management uses the beneficiary's own login.
377
397
 
378
398
  Financial attempts have durable receipts and no automatic retry after uncertain outcomes. Recover the original checkout/refund rather than opening a second purchase. Verified distinct legacy/late obligations retain separate manageable/refundable records; duplicates are reported instead of overwriting the first billing identity. Pending/failed refunds are not completed refunds and do not revoke purchased access.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hive3/cli",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "Command-line client for Hive3's public API.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -18,7 +18,7 @@
18
18
  "access": "public"
19
19
  },
20
20
  "scripts": {
21
- "check": "node --check bin/hive.js && node --check src/api-client.js && node --check src/area-commands.js && node --check src/commands.js && node --check src/config.js && node --check src/event-placement.js && node --check src/extended-commands.js && node --check src/login.js && node --check src/shared.js && node --check src/update.js && node --check src/usage.js && node --check src/skill.js && node --check src/team-client.js && node --check src/team-commands.js && node --check src/stripe-client.js && node --check src/stripe-commands.js && node --check src/feedback-client.js && node --check src/feedback-commands.js && node --check src/feedback-replay.js && node --check src/payments-client.js && node --check src/payments-commands.js && node --check src/selling-client.js && node --check src/selling-commands.js && node --check src/conversations-client.js && node --check src/conversations-commands.js && node --check scripts/validate-skill.mjs",
21
+ "check": "node --check bin/hive.js && node --check src/api-client.js && node --check src/area-commands.js && node --check src/commands.js && node --check src/config.js && node --check src/event-placement.js && node --check src/extended-commands.js && node --check src/login.js && node --check src/shared.js && node --check src/update.js && node --check src/usage.js && node --check src/skill.js && node --check src/team-client.js && node --check src/team-commands.js && node --check src/stripe-client.js && node --check src/stripe-commands.js && node --check src/feedback-client.js && node --check src/feedback-commands.js && node --check src/feedback-replay.js && node --check src/payments-client.js && node --check src/payments-commands.js && node --check src/selling-client.js && node --check src/selling-commands.js && node --check src/conversations-client.js && node --check src/conversations-commands.js && node --check src/my-commands-balances.js && node --check scripts/validate-skill.mjs",
22
22
  "test": "node --test test/*.test.mjs",
23
23
  "typecheck": "tsc -p tsconfig.json",
24
24
  "validate:skill": "node scripts/validate-skill.mjs"
@@ -110,9 +110,16 @@ hive3 account preferences --theme dark
110
110
  hive3 account linked-communities
111
111
  hive3 wallets visibility <wallet-address> --public true
112
112
  hive3 nfts visibility --public false
113
+ hive3 credits
114
+ hive3 credits usage --days 30
115
+ hive3 wallets balances
116
+ hive3 nfts list
117
+ hive3 referrals
118
+ hive3 payments balances
113
119
  hive3 notifications list --unread-only
114
120
  hive3 notifications unread-count
115
121
  hive3 comments create --post-id <post-id> --content "Nice work"
122
+ hive3 communities mine
116
123
  hive3 communities applications <community-id>
117
124
  hive3 communities members <community-id>
118
125
  hive3 communities role <community-id> <account-id> --role moderator
@@ -120,6 +127,8 @@ hive3 communities role <community-id> <account-id> --role moderator
120
127
 
121
128
  Use the exact command's help for account targeting. Profile/builders, broadcasts, assistant, credentials, worlds, product listing/creation, seller tickets/history and Stripe Connect support designated managed-account selectors. Resource creation uses `--owner-type community --community-id`; personal participation and private inboxes remain the signed-in person's actions. Managed work needs the required community scope, key allowlist, and current role; seller/payment administration needs owner/admin rather than moderator. Team scopes do not grant another person's inbox or buyer billing.
122
129
 
130
+ The user's own balances are read-only: `hive3 credits` (AI credits: purchased and this month's free allowance; `usage`, `calls`, `history` for what they were spent on; needs `payments:read`), `hive3 wallets balances` (the Hive3 wallet's native and USDC funds per network, read live), `hive3 nfts list` (NFTs of linked wallets), `hive3 referrals` (code, share link, signups and paid referrals; the code exists once the user has opened Settings → Referrals) and `hive3 payments balances [--account <account-you-run>]` (quest credits and metaverse minutes left). Nothing in the CLI can send wallet funds or buy credits; point the user to the app for that.
131
+
123
132
  `hive3 profile overview get` and `hive3 profile overview save --file overview.json` also carry the account page's tabs as `hiddenTabs`: an array of tab ids to hide from everyone (activity, communities, offerings, credentials, affiliates, events, metaverse, content, courses, jobs, nfts, quests, streams). Overview always shows. Leaving `hiddenTabs` out, or an empty array, turns every tab on; tabs other than the defaults (Activity, Communities, Credentials, Affiliates) still appear only once the account has something in them. `save` replaces the whole config, so start from `get` (or `export`) and change only what the user asked for.
124
133
 
125
134
  ## Broadcasts, Tickets, Assistant, And Credentials
@@ -155,18 +164,21 @@ hive3 credentials award <credential-id> --handles @alice,bob --yes
155
164
 
156
165
  ## Workflow Commands
157
166
 
158
- Use workflow commands for operational management after resources exist:
167
+ Use workflow commands for operational management after resources exist, and to see the user's own RSVPs, course enrollments and quests (`quests enrollments` without an id gives each quest's status, progress and rewards; `communities mine` lists the communities the user belongs to and pending applications):
159
168
 
160
169
  ```bash
170
+ hive3 events rsvps --upcoming
161
171
  hive3 events participants <event-id>
162
172
  hive3 events rsvp <event-id> --enroll true
163
173
  hive3 events approve <event-id> <enrollment-id>
164
174
  hive3 events attendance <event-id> <enrollment-id>
165
175
 
176
+ hive3 courses enrollments --active
166
177
  hive3 courses enrollments <course-id>
167
178
  hive3 courses approve <course-id> <account-id>
168
179
  hive3 courses complete <course-id> <lesson-id>
169
180
 
181
+ hive3 quests enrollments --active
170
182
  hive3 quests enrollments <quest-id>
171
183
  hive3 quests evidence submit <quest-id> --objective-id <objective-id> --content "https://proof.example" --file evidence.json
172
184
  hive3 quests evidence approve <quest-id> <evidence-id>
@@ -176,6 +188,8 @@ hive3 jobs applications <job-id>
176
188
  hive3 jobs status <application-id> --status accepted
177
189
  ```
178
190
 
191
+ `hive3 events rsvps` and `hive3 courses enrollments` (no course ID) list the signed-in user's own RSVPs and enrollments, newest first, at most 200. `status` is `approved`, `pending` (waiting for the organizer) or `declined`; `locked: true` means the user can see the item but can no longer open it. `--upcoming` keeps events that have not finished; `--active` leaves out completed courses. To cancel, use `events rsvp <event-id> --enroll false` or `courses enroll <course-id> --enroll false` (a declined one can only be changed by the organizer).
192
+
179
193
  Workflow outputs are JSON. Participant, enrollment, and application lists include people's primary email addresses for managers, so do not repeat them beyond what the task needs. Attendance can be recorded only for approved RSVPs on non-archived events (an unapproved RSVP returns 409 "Approved RSVP required"), and recorded attendance can't be cleared. Events created through the CLI need RSVP approval unless the payload sets `autoEnroll: true`. Deleting another person's comment needs `communities:moderate` or `communities:write`. If a 429 appears (RSVPs are limited to 10 per minute and 100 per day), stop and report instead of retrying. Before approving, denying, recording attendance, or changing application status, identify the target resource and the account/application/evidence ID in your summary and confirm the user intended that action.
180
194
 
181
195
  ## Uploads And JSON Files
package/src/api-client.js CHANGED
@@ -189,6 +189,9 @@ export function createApiClient(options) {
189
189
  listCommunityMembers(communityId) {
190
190
  return request("GET", `/communities/${encodeURIComponent(communityId)}/members`);
191
191
  },
192
+ listMyCommunities() {
193
+ return request("GET", "/communities/mine");
194
+ },
192
195
  listWallets() {
193
196
  return request("GET", "/wallets");
194
197
  },
package/src/commands.js CHANGED
@@ -18,9 +18,10 @@ import { runFeedbackCommand } from "./feedback-commands.js";
18
18
  import { runPaymentsCommand } from "./payments-commands.js";
19
19
  import { runConversationsCommand } from "./conversations-commands.js";
20
20
  import { runSellingCommand } from "./selling-commands.js";
21
+ import { runNftList, runWalletBalances } from "./my-commands-balances.js";
21
22
 
22
23
  // Commands that run with no arguments.
23
- const SIMPLE_COMMANDS = new Set(["login", "logout", "update", "whoami", "capabilities", "worlds"]);
24
+ const SIMPLE_COMMANDS = new Set(["login", "logout", "update", "whoami", "capabilities", "worlds", "credits", "referrals"]);
24
25
 
25
26
  function defaultDeps(overrides = {}) {
26
27
  return {
@@ -463,6 +464,7 @@ async function runAccount(args, deps) {
463
464
 
464
465
  async function runWallets(args, deps) {
465
466
  const [action, ...rest] = args;
467
+ if (action === "balances") return await runWalletBalances(rest, deps);
466
468
  const client = await authenticatedClient(deps);
467
469
  if (action === "list") {
468
470
  if (rest.length > 0) throw new Error(`Unknown wallets list option: ${rest[0]}`);
@@ -497,6 +499,7 @@ async function runWallets(args, deps) {
497
499
 
498
500
  async function runNfts(args, deps) {
499
501
  const [action, ...rest] = args;
502
+ if (action === "list") return await runNftList(rest, deps);
500
503
  if (action !== "visibility") throw new Error(`Unknown nfts action: ${action || ""}`.trim());
501
504
  if (rest[0] !== "--public") throw new Error("--public is required");
502
505
  const enabled = parseBoolean(requiredFlagValue("--public", rest[1]), "--public");
@@ -3,6 +3,7 @@
3
3
  import { runAreaCommand } from "./area-commands.js";
4
4
  import { authenticatedClient, parseBoolean, readJsonObject as readJsonFile, requiredFlagValue, writeJson } from "./shared.js";
5
5
  import { runUpdateCommand } from "./update.js";
6
+ import { runMyBalancesCommand } from "./my-commands-balances.js";
6
7
 
7
8
  async function parseWorkflowPayload(args, allowedFlags = []) {
8
9
  const payload = {};
@@ -184,9 +185,21 @@ async function runPostsExtended(args, deps) {
184
185
  return true;
185
186
  }
186
187
 
188
+ /** `[--flag]` as the only option, sent as `?flag=true`. */
189
+ function ownListQuery(command, rest, flag) {
190
+ const [option, ...extra] = rest;
191
+ if (option !== undefined && option !== `--${flag}`) throw new Error(`Unknown ${command} option: ${option}`);
192
+ if (extra.length > 0) throw new Error(`Unknown ${command} option: ${extra[0]}`);
193
+ return option ? { [flag]: "true" } : undefined;
194
+ }
195
+
187
196
  async function runEventsWorkflow(args, deps) {
188
197
  const [action, ...rest] = args;
189
198
  const client = await authenticatedClient(deps);
199
+ if (action === "rsvps") {
200
+ writeJson(deps.stdout, await client.workflowGet("events/rsvps", ownListQuery("events rsvps", rest, "upcoming")));
201
+ return true;
202
+ }
190
203
  if (action === "participants") {
191
204
  const eventId = requiredFlagValue("event id", rest[0]);
192
205
  if (rest.length > 1) throw new Error(`Unknown events participants option: ${rest[1]}`);
@@ -225,6 +238,10 @@ async function runEventsWorkflow(args, deps) {
225
238
  async function runCoursesWorkflow(args, deps) {
226
239
  const [action, ...rest] = args;
227
240
  const client = await authenticatedClient(deps);
241
+ if (action === "enrollments" && (rest.length === 0 || rest[0].startsWith("--"))) {
242
+ writeJson(deps.stdout, await client.workflowGet("courses/enrollments", ownListQuery("courses enrollments", rest, "active")));
243
+ return true;
244
+ }
228
245
  if (action === "enrollments") {
229
246
  const courseId = requiredFlagValue("course id", rest[0]);
230
247
  if (rest.length > 1) throw new Error(`Unknown courses enrollments option: ${rest[1]}`);
@@ -265,6 +282,10 @@ async function runCoursesWorkflow(args, deps) {
265
282
  async function runQuestsWorkflow(args, deps) {
266
283
  const [action, ...rest] = args;
267
284
  const client = await authenticatedClient(deps);
285
+ if (action === "enrollments" && (rest.length === 0 || rest[0].startsWith("--"))) {
286
+ writeJson(deps.stdout, await client.workflowGet("quests/enrollments", ownListQuery("quests enrollments", rest, "active")));
287
+ return true;
288
+ }
268
289
  if (action === "enrollments") {
269
290
  const questId = requiredFlagValue("quest id", rest[0]);
270
291
  if (rest.length > 1) throw new Error(`Unknown quests enrollments option: ${rest[1]}`);
@@ -386,6 +407,11 @@ function parseAccessOptions(args) {
386
407
  async function runCommunities(args, deps) {
387
408
  const [action, ...rest] = args;
388
409
  const client = await authenticatedClient(deps);
410
+ if (action === "mine") {
411
+ if (rest.length > 0) throw new Error(`Unknown communities mine option: ${rest[0]}`);
412
+ writeJson(deps.stdout, await client.listMyCommunities());
413
+ return;
414
+ }
389
415
  if (action === "join" || action === "apply" || action === "leave") {
390
416
  const parsed = parseMembershipOptions(action, rest);
391
417
  writeJson(deps.stdout, await client.communityMembership(parsed.communityId, parsed.payload));
@@ -459,6 +485,7 @@ export async function runExtendedCommand(command, args, deps) {
459
485
  await runCommunities(args, deps);
460
486
  return true;
461
487
  }
488
+ if (await runMyBalancesCommand(command, args, deps)) return true;
462
489
  if (await runAreaCommand(command, args, deps)) return true;
463
490
  if (command === "events") return await runEventsWorkflow(args, deps);
464
491
  if (command === "courses") return await runCoursesWorkflow(args, deps);
@@ -0,0 +1,135 @@
1
+ // @ts-check
2
+
3
+ import { authenticatedClient, requiredFlagValue, writeJson } from "./shared.js";
4
+
5
+ /** @typedef {Parameters<typeof authenticatedClient>[0]} CliDeps */
6
+
7
+ /**
8
+ * Read-only views of the signed-in account's own balances: AI credits, referrals, Hive3 wallet funds, NFTs, and
9
+ * quest credits / metaverse time. Nothing here can spend, move or change anything.
10
+ */
11
+
12
+ /**
13
+ * Parses `--flag value` pairs, allowing only `allowed`, each at most once.
14
+ * @param {string} command
15
+ * @param {string[]} args
16
+ * @param {string[]} allowed
17
+ * @returns {Record<string, string>}
18
+ */
19
+ function flagValues(command, args, allowed) {
20
+ /** @type {Record<string, string>} */
21
+ const values = {};
22
+ for (let index = 0; index < args.length; index += 1) {
23
+ const flag = args[index];
24
+ if (!allowed.includes(flag)) throw new Error(`Unknown ${command} option: ${flag}`);
25
+ if (Object.hasOwn(values, flag)) throw new Error(`${flag} may only be given once`);
26
+ index += 1;
27
+ values[flag] = requiredFlagValue(flag, args[index]);
28
+ }
29
+ return values;
30
+ }
31
+
32
+ /**
33
+ * @param {string} flag
34
+ * @param {string | undefined} value
35
+ * @param {number} max
36
+ */
37
+ function checkedLimit(flag, value, max) {
38
+ if (value === undefined) return undefined;
39
+ const limit = Number(value);
40
+ if (!Number.isInteger(limit) || limit < 1 || limit > max) throw new Error(`${flag} must be an integer from 1 to ${max}`);
41
+ return String(limit);
42
+ }
43
+
44
+ /**
45
+ * `hive3 credits [usage|calls|history]`.
46
+ * @param {string[]} args
47
+ * @param {CliDeps} deps
48
+ */
49
+ async function runCredits(args, deps) {
50
+ const [action, ...rest] = args;
51
+ const client = await authenticatedClient(deps);
52
+ if (action === undefined || action === "balance") {
53
+ if (rest.length > 0) throw new Error(`Unknown credits option: ${rest[0]}`);
54
+ writeJson(deps.stdout, await client.request("GET", "/ai-credits"));
55
+ return;
56
+ }
57
+ if (action === "usage") {
58
+ const values = flagValues("credits usage", rest, ["--days", "--time-zone"]);
59
+ if (values["--days"] !== undefined && !["7", "30", "90"].includes(values["--days"])) throw new Error("--days must be 7, 30 or 90");
60
+ writeJson(deps.stdout, await client.request("GET", "/ai-credits/usage", {
61
+ query: { days: values["--days"], timeZone: values["--time-zone"] ?? Intl.DateTimeFormat().resolvedOptions().timeZone },
62
+ }));
63
+ return;
64
+ }
65
+ if (action === "calls" || action === "history") {
66
+ const values = flagValues(`credits ${action}`, rest, ["--limit", "--cursor"]);
67
+ writeJson(deps.stdout, await client.request("GET", `/ai-credits/${action}`, {
68
+ query: { cursor: values["--cursor"], limit: checkedLimit("--limit", values["--limit"], 50) },
69
+ }));
70
+ return;
71
+ }
72
+ throw new Error(`Unknown credits action: ${action}`);
73
+ }
74
+
75
+ /**
76
+ * `hive3 referrals`.
77
+ * @param {string[]} args
78
+ * @param {CliDeps} deps
79
+ */
80
+ async function runReferrals(args, deps) {
81
+ if (args.length > 0) throw new Error(`Unknown referrals option: ${args[0]}`);
82
+ writeJson(deps.stdout, await (await authenticatedClient(deps)).request("GET", "/referrals/mine"));
83
+ }
84
+
85
+ /**
86
+ * Handles `credits` and `referrals`; false for any other command.
87
+ * @param {string} command
88
+ * @param {string[]} args
89
+ * @param {CliDeps} deps
90
+ */
91
+ export async function runMyBalancesCommand(command, args, deps) {
92
+ if (command === "credits") {
93
+ await runCredits(args, deps);
94
+ return true;
95
+ }
96
+ if (command === "referrals") {
97
+ await runReferrals(args, deps);
98
+ return true;
99
+ }
100
+ return false;
101
+ }
102
+
103
+ /**
104
+ * `hive3 wallets balances`: the Hive3 wallet's funds on each network.
105
+ * @param {string[]} args
106
+ * @param {CliDeps} deps
107
+ */
108
+ export async function runWalletBalances(args, deps) {
109
+ if (args.length > 0) throw new Error(`Unknown wallets balances option: ${args[0]}`);
110
+ writeJson(deps.stdout, await (await authenticatedClient(deps)).request("GET", "/wallets/hive3/balances"));
111
+ }
112
+
113
+ /**
114
+ * `hive3 nfts list [--limit n]`.
115
+ * @param {string[]} args
116
+ * @param {CliDeps} deps
117
+ */
118
+ export async function runNftList(args, deps) {
119
+ const values = flagValues("nfts list", args, ["--limit"]);
120
+ writeJson(deps.stdout, await (await authenticatedClient(deps)).request("GET", "/nfts/mine", {
121
+ query: { limit: checkedLimit("--limit", values["--limit"], 200) },
122
+ }));
123
+ }
124
+
125
+ /**
126
+ * `hive3 payments balances [--account <managed-account>]`.
127
+ * @param {string[]} args
128
+ * @param {CliDeps} deps
129
+ */
130
+ export async function runPaymentBalances(args, deps) {
131
+ const values = flagValues("payments balances", args, ["--account"]);
132
+ writeJson(deps.stdout, await (await authenticatedClient(deps)).request("GET", "/payments/balances", {
133
+ query: { account: values["--account"] },
134
+ }));
135
+ }
@@ -2,6 +2,7 @@
2
2
 
3
3
  import { authenticatedClient, requiredFlagValue, writeJson, writeLine } from "./shared.js";
4
4
  import { createPaymentsClient } from "./payments-client.js";
5
+ import { runPaymentBalances } from "./my-commands-balances.js";
5
6
 
6
7
  export function paymentsUsage() {
7
8
  return `Payments (private JSON output)
@@ -14,6 +15,7 @@ export function paymentsUsage() {
14
15
  hive3 payments [preview] checkout quest-credit <account> --plan-type single|bundle
15
16
  hive3 payments [preview] checkout metaverse-time <account> --quantity <1-100-hours>
16
17
  hive3 payments quest-credits|metaverse-time [--account <managed-account>] [--limit <1-100>] [--cursor <cursor>]
18
+ hive3 payments balances [--account <managed-account>] Quest credits and metaverse time left now
17
19
  hive3 payments [preview] finalize stripe <session-id> --kind membership|subscription|ticket|questCredit|metaverseTime
18
20
  hive3 payments [preview] finalize subscription <plan-id> --checkout-intent <id> --paypal-subscription <id>
19
21
  hive3 payments [preview] finalize ticket <ticket-id> --order <order-id>
@@ -60,6 +62,11 @@ export async function runPaymentsCommand(args, deps) {
60
62
  const preview = args[0] === "preview";
61
63
  const remaining = preview ? args.slice(1) : args;
62
64
  const [group, ...rest] = remaining;
65
+ if (group === "balances") {
66
+ if (preview) throw new Error("preview applies only to payment operations");
67
+ await runPaymentBalances(rest, deps);
68
+ return;
69
+ }
63
70
  const listing = lists.includes(group);
64
71
  if (preview && listing) throw new Error("preview applies only to payment operations");
65
72
  if (!listing && !Object.hasOwn(verbs, group)) throw new Error(`Unknown payments command: ${group}`);
package/src/usage.js CHANGED
@@ -23,8 +23,10 @@ export function usage() {
23
23
  " profile <action> Manage profile text, media IDs, access, and builders; add --account <id-or-handle> for an account you help run",
24
24
  " upload <file> Upload an allowed image or document and print its storage ID",
25
25
  " account <action> Manage account preferences, exports, and linked communities",
26
- " wallets <action> Manage linked wallet visibility/default selection",
27
- " nfts <action> Manage public NFT exposure",
26
+ " wallets <action> List linked wallets, see Hive3 wallet funds, manage visibility/default selection",
27
+ " nfts <action> List your NFTs and manage public NFT exposure",
28
+ " credits [action] See your AI credit balance, usage, charged calls and credit history",
29
+ " referrals See your referral code, share link and referral counts",
28
30
  " notifications <action> Manage notifications, unread count, and notification mutes",
29
31
  " comments <action> Manage post comments",
30
32
  " communities <action> Manage community membership and role-derived admin actions",
@@ -72,12 +74,14 @@ const ACCOUNT_FLAG_LINE = " --account <id-or-handle> Act on an account you own
72
74
  const resourceWorkflowLines = {
73
75
  posts: [" like <post-id> Toggle your like on a post"],
74
76
  events: [
77
+ " rsvps [--upcoming] List your own RSVPs and their status",
75
78
  " participants <event-id> List RSVPs (managers only)",
76
79
  " rsvp <event-id> [--enroll true|false] [--file json] RSVP or withdraw your RSVP",
77
80
  " approve|deny <event-id> <enrollment-id> Decide an RSVP",
78
81
  " attendance <event-id> <enrollment-id> [--attended true|false] [--file json]",
79
82
  ],
80
83
  courses: [
84
+ " enrollments [--active] List your own course enrollments and progress",
81
85
  " enrollments <course-id> List enrollments (managers only)",
82
86
  " enroll <course-id> [--enroll true|false] [--file json] Enroll or withdraw",
83
87
  " approve|deny <course-id> <account-id> Decide an enrollment",
@@ -85,6 +89,7 @@ const resourceWorkflowLines = {
85
89
  ],
86
90
  content: [],
87
91
  quests: [
92
+ " enrollments [--active] List your own quests, status and progress",
88
93
  " enrollments <quest-id> List enrollments (managers only)",
89
94
  " enroll <quest-id> [--enroll true|false] [--file json] Enroll or withdraw",
90
95
  " approve|deny <quest-id> <enrollment-id> Decide an enrollment",
@@ -318,11 +323,34 @@ const commandUsageLines = {
318
323
  "",
319
324
  "Actions:",
320
325
  " list",
326
+ " balances Your Hive3 wallet's native and USDC balance on each network (read-only)",
321
327
  " default <address>",
322
328
  " visibility <address> --public true|false",
323
329
  " remove <address> --confirm <address>",
324
330
  ],
325
- nfts: ["Usage: hive3 nfts visibility --public true|false"],
331
+ nfts: [
332
+ "Usage: hive3 nfts <action> [options]",
333
+ "",
334
+ "Actions:",
335
+ " list [--limit 1-200] NFTs held by your linked wallets (default 50)",
336
+ " visibility --public true|false",
337
+ ],
338
+ credits: [
339
+ "Usage: hive3 credits [action] [options]",
340
+ "",
341
+ "Actions:",
342
+ " (none) | balance Purchased credits and what is left of this month's free allowance",
343
+ " usage [--days 7|30|90] [--time-zone tz] What credits were spent on: totals, per model, per day (default 30 days, your time zone)",
344
+ " calls [--limit 1-50] [--cursor c] Charged model calls and generations, newest first",
345
+ " history [--limit 1-50] [--cursor c] Credit history: purchases, gifts, top-ups, spending and returns",
346
+ "Needs payments:read. Read-only; buy or gift credits in the Hive3 app.",
347
+ ],
348
+ referrals: [
349
+ "Usage: hive3 referrals",
350
+ "",
351
+ "Shows your referral code and share link, how many people signed up through it and how many have paid.",
352
+ "The code is created the first time you open Settings → Referrals in the app. Needs account:read.",
353
+ ],
326
354
  notifications: [
327
355
  "Usage: hive3 notifications <action> [options]",
328
356
  "",
@@ -349,6 +377,7 @@ const commandUsageLines = {
349
377
  "Usage: hive3 communities <action> [options]",
350
378
  "",
351
379
  "Actions:",
380
+ " mine Your memberships and pending applications",
352
381
  " join|apply|leave <community-id> [--message text]",
353
382
  " applications <community-id> Moderators and above",
354
383
  " approve|deny <application-id> Moderators and above",