@hive3/cli 0.5.1 → 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.
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
 
@@ -117,6 +117,10 @@ hive3 posts list
117
117
  hive3 posts get <post-id>
118
118
  hive3 posts create --body "Hello Hive"
119
119
  hive3 events create --title "Launch" --description "Details" --visibility public
120
+ hive3 events create --file slots.json --title "Meetup" --location irl --address "1 Market St, San Francisco" --venue-name "The Hall" --check-in door
121
+ hive3 events create --file slots.json --title "Office hours" --location virtual --meeting-url https://zoom.us/j/123
122
+ hive3 events update <event-id> --venue-instructions "Side entrance, 2nd floor"
123
+ hive3 events list --location virtual
120
124
  hive3 worlds
121
125
  hive3 events create --file event.json --world <world-id>
122
126
  hive3 courses create --file course.json --idempotency-key course-001
@@ -135,6 +139,21 @@ hive3 posts create --body "Moderator update" --owner-type community --community-
135
139
 
136
140
  Events created through the CLI require RSVP approval by default; put `"autoEnroll": true` in the `--file` payload to auto-accept attendees. Resource lists are newest first, and `--cursor` pages through every item. Complex payloads should use `--file <json>`. The JSON file must contain an object and is merged with command-line flags.
137
141
 
142
+ Every event has a type, `location`: `irl` (shown "In person"), `virtual` or `metaverse`. `events create|update` take:
143
+
144
+ - `--location irl|virtual|metaverse`
145
+ - In person: `--address <text>` (public, up to 300 characters), `--venue-name <text>` (up to 120), `--venue-instructions <text>` ("Getting there", up to 1000) and `--check-in self|door` (default `self`: guests scan one event QR code and walk-ins can sign up on the spot; `door`: each guest has a personal pass QR that the host scans).
146
+ - Virtual: `--meeting-url <https-url>` (required), `--meeting-provider zoom|google_meet|microsoft_teams|x_spaces|discord|youtube|other` (inferred from the link when omitted) and `--meeting-instructions <text>` (passcode, dial-in; up to 1000).
147
+ - Metaverse: `--world <world-id|default>` (below). Only metaverse events can book a world.
148
+
149
+ The same fields can come from `--file` JSON as `location`, `venue`, `meeting` and `checkInMode`; the flags win. Without `--location` the type follows the flags (meeting flags mean virtual, venue flags in person). On update, the event's current venue, meeting and check-in mode are kept for anything you don't change (the CLI reads the event first), a new `--address` drops the old map pin, and `--location irl|virtual` moves the event out of its world. The CLI checks values with the API's wording before sending, for example `location must be irl, virtual or metaverse`, `checkInMode must be self or door`, `Virtual events need a meeting link that starts with https://.` and `Only metaverse events can book a world.`
150
+
151
+ Event JSON includes `location`, `venue` (`address`, `name`, `instructions`, `city`, `placeId`, `latitude`, `longitude`, or `null`), `meeting` and `checkInMode` (`self`/`door` for in-person events, otherwise `null`). `meeting.url` and `meeting.instructions` appear only in the owner/admin/moderator view; everyone else gets `meeting: { "provider": ... }`. `hive3 events list --location irl|virtual|metaverse` lists only that type.
152
+
153
+ QR check-in (showing, printing or resetting the event QR, scanning passes at the door) and Google Calendar sync are done in the Hive3 app, not the CLI or API. In-person attendance is recorded by check-in; `events attendance` remains the organizer's manual record.
154
+
155
+ Quest event objectives count one type each: `in_person_events_attended`, `virtual_events_attended` and `metaverse_events_attended` (set `type` on each objective in the quest `--file` JSON).
156
+
138
157
  `events create|update --world <world-id|default>` books a 3D world for the event (it sets `worldId`). Run `hive3 worlds [--account <id-or-handle>]` first: it lists the worlds the owning account may book as `{ "worlds": [{ "id", "name", "kind": "shared" | "dedicated", "isDefault" }], "needsDedicatedSetup" }` (needs `resources:read`; another account also needs `communities:read`, the key's allowlist and a live owner/admin/moderator role). Honey Bee accounts list every shared world (Hive3 Dome, Night Lounge), Swarm only its default shared world chosen on the dashboard, Royal Hive only its own world (`needsDedicatedSetup: true` until its design is chosen), and Worker Bee none. Pass the `id` of the world you mean; a world that isn't listed can't be booked for that account. `default` picks the world listed with `isDefault: true`. A world event needs exactly one time slot in `eventSlots`, may spend metaverse time, and returns `409` when the slot overlaps another booking; a Worker Bee account, or a Royal Hive account whose world isn't set up yet, gets `400` and nothing is created. Without `--world` (or `worldId`) the event is not in a world. Each key owner can create 50 events per day (shared with the app).
139
158
 
140
159
  ## Uploads
@@ -152,7 +171,14 @@ Allowed image types: GIF, JPEG, PNG, WebP up to 8 MB. Allowed document types: PD
152
171
 
153
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.
154
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
+
155
180
  ```bash
181
+ hive3 events rsvps --upcoming
156
182
  hive3 events participants <event-id>
157
183
  hive3 events rsvp <event-id> --enroll true
158
184
  hive3 events approve <event-id> <enrollment-id>
@@ -160,12 +186,14 @@ hive3 events deny <event-id> <enrollment-id>
160
186
  hive3 events attendance <event-id> <enrollment-id>
161
187
 
162
188
  hive3 courses enroll <course-id>
189
+ hive3 courses enrollments --active
163
190
  hive3 courses enrollments <course-id>
164
191
  hive3 courses approve <course-id> <account-id>
165
192
  hive3 courses deny <course-id> <account-id>
166
193
  hive3 courses complete <course-id> <lesson-id>
167
194
 
168
195
  hive3 quests enroll <quest-id>
196
+ hive3 quests enrollments --active
169
197
  hive3 quests enrollments <quest-id>
170
198
  hive3 quests approve <quest-id> <enrollment-id>
171
199
  hive3 quests deny <quest-id> <enrollment-id>
@@ -233,18 +261,27 @@ hive3 account export
233
261
  hive3 account linked-communities
234
262
  hive3 account linked-communities disconnect <community-id> --confirm <community-id>
235
263
  hive3 wallets list
264
+ hive3 wallets balances
236
265
  hive3 wallets default <wallet-address>
237
266
  hive3 wallets visibility <wallet-address> --public true
238
267
  hive3 wallets remove <wallet-address> --confirm <wallet-address>
239
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
240
274
  hive3 notifications list --unread-only
241
275
  hive3 notifications unread-count
242
276
  hive3 notifications mutes set --scope <scope> --muted true
243
277
  hive3 comments create --post-id <post-id> --content "Nice work"
278
+ hive3 communities mine
244
279
  hive3 communities applications <community-id>
245
280
  hive3 communities approve <application-id>
246
281
  ```
247
282
 
283
+ The overview config may include `"hiddenTabs": ["content", "quests"]` to hide account page tabs from everyone (tab ids: activity, communities, offerings, credentials, affiliates, events, metaverse, content, courses, jobs, nfts, quests, streams; Overview always shows). Without `hiddenTabs` every tab is on. `profile overview get|export` return it and `save` stores it; `save` replaces the whole config, so start from `get` or `export`.
284
+
248
285
  ### Managing another account with `--account`
249
286
 
250
287
  `--account <id-or-handle>` lets you act on an account where you are owner, admin or moderator. Give it once, after the action. It is supported by:
@@ -348,10 +385,14 @@ hive3 payments sales --account <seller>
348
385
  hive3 payments preview checkout ticket <ticket-id>
349
386
  hive3 payments checkout ticket <ticket-id> --yes --confirm "<preview.confirm>" --request-id <unique-id>
350
387
  hive3 payments preview subscription cancel <purchased-subscription-id>
388
+ hive3 payments balances
389
+ hive3 payments balances --account <managed-account>
351
390
  ```
352
391
 
353
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.
354
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
+
355
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.
356
397
 
357
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.5.1",
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/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"
@@ -57,7 +57,9 @@ Personal examples:
57
57
  hive3 posts list
58
58
  hive3 posts get <post-id>
59
59
  hive3 posts create --body "Update from Hive3"
60
- hive3 events create --title "Launch" --description "Details" --visibility public
60
+ hive3 events create --title "Launch" --description "Details" --visibility public --file slots.json --location irl --address "1 Market St, San Francisco" --check-in self
61
+ hive3 events create --title "Office hours" --file slots.json --location virtual --meeting-url https://zoom.us/j/123
62
+ hive3 events list --location virtual
61
63
  hive3 courses create --file course.json
62
64
  hive3 content update <content-id> --file content.json
63
65
  hive3 quests create --file quest.json
@@ -72,6 +74,16 @@ hive3 posts create --body "Moderator update" --owner-type community --community-
72
74
 
73
75
  Supported resource families are `posts`, `events`, `courses`, `content`, `quests`, and `jobs`. Supported actions are `list`, `get <id>`, `create`, `update <id>`, and `archive <id>`. Use `--file <json>` for complex events, courses, content, quests, and jobs. `--owner-type`/`--community-id` on `list` choose whose items to list; `--owner-type` alone is not a type filter.
74
76
 
77
+ Every event has a type, `location`: `irl` (shown "In person"), `virtual`, or `metaverse` (a Hive3 3D world). Pick it from what the user describes and set it with `--location`:
78
+
79
+ - In person: `--address <text>` (public, up to 300 characters), optional `--venue-name`, `--venue-instructions` ("Getting there": parking, entrance, door code) and `--check-in self|door` (default `self`: guests scan one event QR code; `door`: each guest shows a personal pass that the host scans). Attendance at in-person events is recorded only by QR check-in at the venue.
80
+ - Virtual: `--meeting-url <https link>` (required), optional `--meeting-provider zoom|google_meet|microsoft_teams|x_spaces|discord|youtube|other` (inferred from the link when omitted) and `--meeting-instructions` (passcode, dial-in). The join link is shown only to hosts and approved guests; event output includes `meeting.url` only when the API returns it to your key (owner/admin/moderator view), otherwise just `meeting.provider`.
81
+ - Metaverse: `--world <id|default>`, below. Only metaverse events can book a world.
82
+
83
+ The same fields can come from `--file` JSON (`location`, `venue`, `meeting`, `checkInMode`); flags win. On `events update`, the event's current venue, meeting and check-in mode are kept for anything you don't change; pass `--location` to switch type (switching to `irl` or `virtual` takes the event out of its world). Event output includes `location`, `venue`, `meeting` and `checkInMode` (`null` unless in person). `hive3 events list --location irl|virtual|metaverse` filters by type.
84
+
85
+ QR check-in (showing or resetting the event QR, scanning passes, approving at the door) and Google Calendar sync are done in the Hive3 app in a browser; the CLI and API can't do them. Point the user to the event page or Settings → Account → Google Calendar.
86
+
75
87
  Never add `--world` to an online or in-person event; without `--world` the event is not in a world. For a 3D world event, book the world the user means:
76
88
 
77
89
  - When the user names a venue or world (for example "the Dome", "Night Lounge", "our own world"), run `hive3 worlds` (add `--account <id-or-handle>` when the event belongs to another account, the same account as `--community-id`), match the name against the listed worlds, and pass that world's `id` with `--world <id>`. `kind: "dedicated"` is the account's own world.
@@ -80,6 +92,8 @@ Never add `--world` to an online or in-person event; without `--world` the event
80
92
 
81
93
  A world event needs exactly one slot in `eventSlots` and may spend the account's metaverse time. A `400` (no world for this plan, Royal Hive world not set up, world not bookable) or `409` (slot already booked) means nothing changed: report it rather than retrying, switching worlds, or dropping `--world`.
82
94
 
95
+ Quest event objectives count one event type each: `in_person_events_attended` (checked in at an in-person event), `virtual_events_attended` (joined a virtual event) and `metaverse_events_attended` (attended a world event). Put the type in each objective of the quest `--file` JSON, with `targetEventId` when it must be one event; match the type to that event's `location`.
96
+
83
97
  ## Account, Social, And Community Commands
84
98
 
85
99
  Use these only when the requested work calls for them:
@@ -96,9 +110,16 @@ hive3 account preferences --theme dark
96
110
  hive3 account linked-communities
97
111
  hive3 wallets visibility <wallet-address> --public true
98
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
99
119
  hive3 notifications list --unread-only
100
120
  hive3 notifications unread-count
101
121
  hive3 comments create --post-id <post-id> --content "Nice work"
122
+ hive3 communities mine
102
123
  hive3 communities applications <community-id>
103
124
  hive3 communities members <community-id>
104
125
  hive3 communities role <community-id> <account-id> --role moderator
@@ -106,6 +127,10 @@ hive3 communities role <community-id> <account-id> --role moderator
106
127
 
107
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.
108
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
+
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.
133
+
109
134
  ## Broadcasts, Tickets, Assistant, And Credentials
110
135
 
111
136
  ```bash
@@ -139,18 +164,21 @@ hive3 credentials award <credential-id> --handles @alice,bob --yes
139
164
 
140
165
  ## Workflow Commands
141
166
 
142
- 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):
143
168
 
144
169
  ```bash
170
+ hive3 events rsvps --upcoming
145
171
  hive3 events participants <event-id>
146
172
  hive3 events rsvp <event-id> --enroll true
147
173
  hive3 events approve <event-id> <enrollment-id>
148
174
  hive3 events attendance <event-id> <enrollment-id>
149
175
 
176
+ hive3 courses enrollments --active
150
177
  hive3 courses enrollments <course-id>
151
178
  hive3 courses approve <course-id> <account-id>
152
179
  hive3 courses complete <course-id> <lesson-id>
153
180
 
181
+ hive3 quests enrollments --active
154
182
  hive3 quests enrollments <quest-id>
155
183
  hive3 quests evidence submit <quest-id> --objective-id <objective-id> --content "https://proof.example" --file evidence.json
156
184
  hive3 quests evidence approve <quest-id> <evidence-id>
@@ -160,6 +188,8 @@ hive3 jobs applications <job-id>
160
188
  hive3 jobs status <application-id> --status accepted
161
189
  ```
162
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
+
163
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.
164
194
 
165
195
  ## Uploads And JSON Files
@@ -204,7 +234,7 @@ Use `--file` for structured fields and a stable `--idempotency-key` within its d
204
234
  1. Start with `hive3 payments history|subscriptions|tickets|refunds|sales`; use command help for managed sellers.
205
235
  2. Run `hive3 payments preview <operation...>` before a financial action. Show the canonical account, target, action, provider and amount/terms to the user.
206
236
  3. Only after exact approval, repeat that operation with `--yes --confirm "<preview.confirm>" --request-id <unique-id>`. Do not guess the confirmation or reuse an ID for different work.
207
- 4. Open checkout/portal/revision links privately. The owner completes required provider approval; do not accept attestations or legal terms for them. Some confirmed actions take effect at once with no browser step: `membership revise` to a higher tier charges the saved payment method immediately for the prorated difference, and `refund approve` sends the refund. Say so in the approval request.
237
+ 4. Open checkout/portal/revision links privately. The owner completes required provider approval; do not accept attestations or legal terms for them. Some confirmed actions take effect at once with no browser step: `membership revise` to a higher tier or a longer `--billing` period charges the saved payment method immediately (the new price less credit for unused time), and `refund approve` sends the refund. A lower tier or shorter period starts at renewal with no charge today. Say so in the approval request.
208
238
 
209
239
  Supported operations include membership, creator-subscription and ticket checkout/finalization; Stripe quest-credit/metaverse-time checkout; subscription/membership cancellation, resume and billing portals; supported plan revision; and buyer refund requests plus authorized seller review. Managed-account platform membership checkout is owner-only; ongoing management uses the beneficiary's own login. Stripe creator-plan revision and legacy PayPal platform membership management are not supported by the current app.
210
240
 
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
@@ -8,6 +8,7 @@ import { clearConfig, loadConfig } from "./config.js";
8
8
  import { runExtendedCommand } from "./extended-commands.js";
9
9
  import { login, loginUsage, parseLoginArgs } from "./login.js";
10
10
  import { runSkill } from "./skill.js";
11
+ import { applyEventPlacement, EVENT_LOCATIONS, isEventPlacementFlag, LOCATION_ERROR, setEventPlacementFlag } from "./event-placement.js";
11
12
  import { authenticatedClient, parseBoolean, postFileToUploadUrl, requiredFlagValue, terminalText, writeJson, writeLine } from "./shared.js";
12
13
  import { CURRENT_VERSION, updateUsage } from "./update.js";
13
14
  import { commandUsage, resourceUsage, usage } from "./usage.js";
@@ -17,9 +18,10 @@ import { runFeedbackCommand } from "./feedback-commands.js";
17
18
  import { runPaymentsCommand } from "./payments-commands.js";
18
19
  import { runConversationsCommand } from "./conversations-commands.js";
19
20
  import { runSellingCommand } from "./selling-commands.js";
21
+ import { runNftList, runWalletBalances } from "./my-commands-balances.js";
20
22
 
21
23
  // Commands that run with no arguments.
22
- 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"]);
23
25
 
24
26
  function defaultDeps(overrides = {}) {
25
27
  return {
@@ -67,7 +69,7 @@ function takeAccountFlag(args) {
67
69
  return { account, rest };
68
70
  }
69
71
 
70
- function parseListOptions(args) {
72
+ function parseListOptions(kind, args) {
71
73
  const query = {};
72
74
  for (let index = 0; index < args.length; index += 1) {
73
75
  const flag = args[index];
@@ -87,6 +89,10 @@ function parseListOptions(args) {
87
89
  } else if (flag === "--community-id") {
88
90
  index += 1;
89
91
  query.communityId = requiredFlagValue(flag, args[index]);
92
+ } else if (kind === "events" && flag === "--location") {
93
+ index += 1;
94
+ query.location = requiredFlagValue(flag, args[index]);
95
+ if (!EVENT_LOCATIONS.includes(query.location)) throw new Error(LOCATION_ERROR);
90
96
  } else {
91
97
  throw new Error(`Unknown list option: ${flag}`);
92
98
  }
@@ -100,6 +106,8 @@ function setPayloadField(payload, key, value) {
100
106
 
101
107
  async function parseResourcePayload(kind, args, includeOwner) {
102
108
  let payload = {};
109
+ /** @type {Record<string, string>} */
110
+ const placement = {};
103
111
  let idempotencyKey;
104
112
  let ownerType;
105
113
  let communityId;
@@ -126,6 +134,9 @@ async function parseResourcePayload(kind, args, includeOwner) {
126
134
  } else if (kind === "events" && flag === "--world") {
127
135
  index += 1;
128
136
  setPayloadField(payload, "worldId", requiredFlagValue(flag, args[index]));
137
+ } else if (kind === "events" && isEventPlacementFlag(flag)) {
138
+ index += 1;
139
+ setEventPlacementFlag(placement, flag, requiredFlagValue(flag, args[index]));
129
140
  } else if (flag === "--file") {
130
141
  index += 1;
131
142
  const filePayload = await readJsonFile(requiredFlagValue(flag, args[index]));
@@ -153,8 +164,8 @@ async function parseResourcePayload(kind, args, includeOwner) {
153
164
  } else if (includeOwner && ownerType === "person") {
154
165
  payload.owner = { type: "person" };
155
166
  }
156
- if (Object.keys(payload).length === 0) throw new Error("At least one resource field is required");
157
- return { idempotencyKey, payload };
167
+ if (Object.keys(payload).length === 0 && Object.keys(placement).length === 0) throw new Error("At least one resource field is required");
168
+ return { idempotencyKey, payload, placement };
158
169
  }
159
170
  function parseCsv(value) {
160
171
  return value.split(",").map((item) => item.trim()).filter(Boolean);
@@ -272,17 +283,23 @@ async function runResource(kind, args, deps) {
272
283
  }
273
284
  const client = await authenticatedClient(deps);
274
285
  if (action === "list") {
275
- writeJson(deps.stdout, await client.listResource(kind, parseListOptions(rest)));
286
+ writeJson(deps.stdout, await client.listResource(kind, parseListOptions(kind, rest)));
276
287
  return;
277
288
  }
278
289
  if (action === "create") {
279
- const { idempotencyKey, payload } = await parseResourcePayload(kind, rest, true);
290
+ const { idempotencyKey, payload, placement } = await parseResourcePayload(kind, rest, true);
291
+ if (kind === "events") applyEventPlacement(payload, placement, { creating: true });
280
292
  writeJson(deps.stdout, await client.createResource(kind, payload, idempotencyKey));
281
293
  return;
282
294
  }
283
295
  if (action === "update") {
284
296
  const id = requiredFlagValue("resource id", rest[0]);
285
- const { payload } = await parseResourcePayload(kind, rest.slice(1), false);
297
+ const { payload, placement } = await parseResourcePayload(kind, rest.slice(1), false);
298
+ if (kind === "events") {
299
+ // Changing one placement detail keeps the rest: the current venue, meeting and check-in mode fill the gaps.
300
+ const existing = Object.keys(placement).length > 0 ? (await client.getResource(kind, id)).data : null;
301
+ applyEventPlacement(payload, placement, { creating: false, existing });
302
+ }
286
303
  writeJson(deps.stdout, await client.updateResource(kind, id, payload));
287
304
  return;
288
305
  }
@@ -447,6 +464,7 @@ async function runAccount(args, deps) {
447
464
 
448
465
  async function runWallets(args, deps) {
449
466
  const [action, ...rest] = args;
467
+ if (action === "balances") return await runWalletBalances(rest, deps);
450
468
  const client = await authenticatedClient(deps);
451
469
  if (action === "list") {
452
470
  if (rest.length > 0) throw new Error(`Unknown wallets list option: ${rest[0]}`);
@@ -481,6 +499,7 @@ async function runWallets(args, deps) {
481
499
 
482
500
  async function runNfts(args, deps) {
483
501
  const [action, ...rest] = args;
502
+ if (action === "list") return await runNftList(rest, deps);
484
503
  if (action !== "visibility") throw new Error(`Unknown nfts action: ${action || ""}`.trim());
485
504
  if (rest[0] !== "--public") throw new Error("--public is required");
486
505
  const enabled = parseBoolean(requiredFlagValue("--public", rest[1]), "--public");
@@ -0,0 +1,158 @@
1
+ // @ts-check
2
+
3
+ /**
4
+ * Event type flags for `hive3 events create|update`: where an event happens (in person, a virtual call, or a
5
+ * Hive3 world) and the venue/meeting details that go with it. Errors use the API's exact wording so a
6
+ * rejected flag reads the same as a rejected request.
7
+ */
8
+
9
+ export const EVENT_LOCATIONS = ["irl", "virtual", "metaverse"];
10
+ export const MEETING_PROVIDERS = ["zoom", "google_meet", "microsoft_teams", "x_spaces", "discord", "youtube", "other"];
11
+ const CHECK_IN_MODES = ["self", "door"];
12
+
13
+ export const LOCATION_ERROR = "location must be irl, virtual or metaverse";
14
+ const CHECK_IN_ERROR = "checkInMode must be self or door";
15
+ const MEETING_LINK_ERROR = "Virtual events need a meeting link that starts with https://.";
16
+ const PROVIDER_ERROR = "meeting.provider must be zoom, google_meet, microsoft_teams, x_spaces, discord, youtube or other";
17
+ const ADDRESS_ERROR = "In-person events need an address.";
18
+ const WORLD_ERROR = "Only metaverse events can book a world.";
19
+ const NEEDS_WORLD_ERROR = "Metaverse events need a world.";
20
+ const VENUE_FLAGS_ERROR = "--address, --venue-name, --venue-instructions and --check-in are for in-person events (--location irl)";
21
+ const MEETING_FLAGS_ERROR = "--meeting-url, --meeting-provider and --meeting-instructions are for virtual events (--location virtual)";
22
+
23
+ /** CLI flag → key in the parsed placement flags, with the API's length limit for text values. */
24
+ const PLACEMENT_FLAGS = {
25
+ "--location": { key: "location" },
26
+ "--address": { key: "address", field: "address", max: 300 },
27
+ "--venue-name": { key: "venueName", field: "name", max: 120 },
28
+ "--venue-instructions": { key: "venueInstructions", field: "instructions", max: 1000 },
29
+ "--check-in": { key: "checkInMode" },
30
+ "--meeting-url": { key: "meetingUrl" },
31
+ "--meeting-provider": { key: "meetingProvider" },
32
+ "--meeting-instructions": { key: "meetingInstructions", field: "instructions", max: 1000 },
33
+ };
34
+ const VENUE_FLAG_KEYS = ["address", "venueName", "venueInstructions", "checkInMode"];
35
+ const MEETING_FLAG_KEYS = ["meetingUrl", "meetingProvider", "meetingInstructions"];
36
+ /** Google Places details that describe the old address; a new address makes them wrong. */
37
+ const PLACE_DETAIL_KEYS = ["city", "placeId", "latitude", "longitude"];
38
+
39
+ /** @param {string} flag */
40
+ export function isEventPlacementFlag(flag) {
41
+ return Object.hasOwn(PLACEMENT_FLAGS, flag);
42
+ }
43
+
44
+ /** Same rule as the API: no scheme means https, and only https links up to 2048 characters pass. */
45
+ function isHttpsUrl(value) {
46
+ if (typeof value !== "string" || !value.trim()) return false;
47
+ const trimmed = value.trim();
48
+ const candidate = /^[a-z][a-z0-9+.-]*:/i.test(trimmed) ? trimmed : `https://${trimmed}`;
49
+ try {
50
+ const parsed = new URL(candidate);
51
+ return parsed.protocol === "https:" && parsed.toString().length <= 2048;
52
+ } catch {
53
+ return false;
54
+ }
55
+ }
56
+
57
+ /**
58
+ * Validates one placement flag value and records it in `flags`.
59
+ * @param {Record<string, string>} flags
60
+ * @param {string} flag
61
+ * @param {string} value
62
+ */
63
+ export function setEventPlacementFlag(flags, flag, value) {
64
+ const spec = PLACEMENT_FLAGS[flag];
65
+ if (spec.key === "location" && !EVENT_LOCATIONS.includes(value)) throw new Error(LOCATION_ERROR);
66
+ if (spec.key === "checkInMode" && !CHECK_IN_MODES.includes(value)) throw new Error(CHECK_IN_ERROR);
67
+ if (spec.key === "meetingProvider" && !MEETING_PROVIDERS.includes(value)) throw new Error(PROVIDER_ERROR);
68
+ if (spec.key === "meetingUrl" && !isHttpsUrl(value)) throw new Error(MEETING_LINK_ERROR);
69
+ if (spec.max !== undefined && value.trim().length > spec.max) {
70
+ throw new Error(`${spec.field} must be ${spec.max} characters or fewer`);
71
+ }
72
+ flags[spec.key] = value;
73
+ }
74
+
75
+ function objectOrNull(value) {
76
+ return value && typeof value === "object" && !Array.isArray(value) ? value : null;
77
+ }
78
+
79
+ /**
80
+ * The type the API will give the event: an explicit location, else a booked or kept world, else the
81
+ * meeting or venue being sent, else the event's current type.
82
+ */
83
+ function targetLocation(payload, flags, existing, hasVenue, hasMeeting) {
84
+ const explicit = flags.location ?? payload.location;
85
+ if (explicit !== undefined) return explicit;
86
+ if (payload.worldId !== undefined || existing?.location === "metaverse") return "metaverse";
87
+ if (hasMeeting) return "virtual";
88
+ if (hasVenue) return "irl";
89
+ return existing?.location;
90
+ }
91
+
92
+ /**
93
+ * Builds `location`, `venue`, `meeting` and `checkInMode` on an events payload from the flags, on top of
94
+ * `--file` JSON (flags win), and checks the result the way the API will. On update, `existing` is the
95
+ * current event: when it keeps its type, its venue, meeting and check-in mode fill whatever the flags and
96
+ * file leave out, so changing one detail never clears the others.
97
+ * @param {Record<string, any>} payload mutated in place
98
+ * @param {Record<string, string>} flags from setEventPlacementFlag
99
+ * @param {{ creating: boolean; existing?: Record<string, any> | null }} options
100
+ */
101
+ export function applyEventPlacement(payload, flags, options) {
102
+ const { creating, existing = null } = options;
103
+ const venueFlags = VENUE_FLAG_KEYS.some((key) => flags[key] !== undefined);
104
+ const meetingFlags = MEETING_FLAG_KEYS.some((key) => flags[key] !== undefined);
105
+ const fileVenue = objectOrNull(payload.venue);
106
+ const fileMeeting = objectOrNull(payload.meeting);
107
+ if (flags.location !== undefined) payload.location = flags.location;
108
+ const explicit = payload.location;
109
+ if (explicit !== undefined && !EVENT_LOCATIONS.includes(/** @type {string} */ (explicit))) throw new Error(LOCATION_ERROR);
110
+ const target = targetLocation(payload, flags, existing, venueFlags || fileVenue !== null, meetingFlags || fileMeeting !== null);
111
+ if ((target === "irl" || target === "virtual") && payload.worldId !== undefined) throw new Error(WORLD_ERROR);
112
+ if (creating && explicit === "metaverse" && payload.worldId === undefined) throw new Error(NEEDS_WORLD_ERROR);
113
+ if (venueFlags && target !== "irl") throw new Error(VENUE_FLAGS_ERROR);
114
+ if (meetingFlags && target !== "virtual") throw new Error(MEETING_FLAGS_ERROR);
115
+ const keepsType = Boolean(existing) && existing.location === target;
116
+ // The API only switches type on an explicit `location` or a sent venue/meeting; say it outright so a lone
117
+ // detail such as --check-in can't be silently dropped by the API keeping the stored type.
118
+ if (existing && !keepsType && explicit === undefined && (target === "irl" || target === "virtual")) payload.location = target;
119
+
120
+ if (target === "irl") {
121
+ const base = fileVenue ?? (keepsType ? objectOrNull(existing.venue) : null);
122
+ const venue = { ...(base ?? {}) };
123
+ if (flags.address !== undefined && flags.address.trim() !== venue.address) {
124
+ for (const key of PLACE_DETAIL_KEYS) delete venue[key];
125
+ venue.address = flags.address.trim();
126
+ }
127
+ if (flags.venueName !== undefined) venue.name = flags.venueName;
128
+ if (flags.venueInstructions !== undefined) venue.instructions = flags.venueInstructions;
129
+ if ((flags.venueName !== undefined || flags.venueInstructions !== undefined) && !venue.address) throw new Error(ADDRESS_ERROR);
130
+ if (existing && !keepsType && !venue.address) throw new Error(ADDRESS_ERROR);
131
+ if (Object.keys(venue).length > 0) payload.venue = venue;
132
+ if (flags.checkInMode !== undefined) payload.checkInMode = flags.checkInMode;
133
+ else if (payload.checkInMode === undefined && keepsType && existing.checkInMode) payload.checkInMode = existing.checkInMode;
134
+ if (payload.checkInMode !== undefined && !CHECK_IN_MODES.includes(/** @type {string} */ (payload.checkInMode))) {
135
+ throw new Error(CHECK_IN_ERROR);
136
+ }
137
+ }
138
+
139
+ if (target === "virtual") {
140
+ const base = fileMeeting ?? (keepsType ? objectOrNull(existing.meeting) : null);
141
+ const meeting = { ...(base ?? {}) };
142
+ if (flags.meetingUrl !== undefined) {
143
+ // A new link from another provider must not keep the old provider; the API infers it from the URL.
144
+ if (flags.meetingUrl !== meeting.url && fileMeeting?.provider === undefined) delete meeting.provider;
145
+ meeting.url = flags.meetingUrl;
146
+ }
147
+ if (flags.meetingProvider !== undefined) meeting.provider = flags.meetingProvider;
148
+ if (flags.meetingInstructions !== undefined) meeting.instructions = flags.meetingInstructions;
149
+ if (Object.keys(meeting).length > 0) payload.meeting = meeting;
150
+ if (payload.meeting !== undefined || explicit === "virtual") {
151
+ if (!isHttpsUrl(meeting.url)) throw new Error(MEETING_LINK_ERROR);
152
+ const provider = meeting.provider;
153
+ if (provider !== undefined && provider !== null && provider !== "" && !MEETING_PROVIDERS.includes(provider)) {
154
+ throw new Error(PROVIDER_ERROR);
155
+ }
156
+ }
157
+ }
158
+ }
@@ -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)
@@ -10,20 +11,22 @@ export function paymentsUsage() {
10
11
  hive3 payments tickets|refunds [--account <seller-id-or-handle>] [--limit <1-100>] [--cursor <cursor>]
11
12
  hive3 payments sales [--account <seller-id-or-handle>] [--limit <1-100>] [--cursor <cursor>]
12
13
  hive3 payments [preview] checkout subscription|ticket <id> [--provider stripe|paypal]
13
- hive3 payments [preview] checkout membership --tier honey|swarm|royal [--account <owned-account>]
14
+ hive3 payments [preview] checkout membership --tier honey|swarm|royal [--billing month|quarter|year] [--account <owned-account>]
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>
20
22
  hive3 payments [preview] subscription cancel|resume|portal <subscription-id>
21
23
  hive3 payments [preview] subscription revise <subscription-id> --plan <new-plan-id>
22
24
  hive3 payments [preview] membership cancel|resume|portal
23
- hive3 payments [preview] membership revise --tier honey|swarm|royal
25
+ hive3 payments [preview] membership revise --tier honey|swarm|royal [--billing month|quarter|year]
24
26
  hive3 payments [preview] refund request <purchased-ticket-id> [--reason <text>]
25
27
  hive3 payments [preview] refund approve|reject <refund-request-id> [--note <text>]
26
28
 
29
+ Membership billing: month (full price), quarter (10% off, paid every 3 months) or year (20% off, paid yearly). Checkout defaults to month; revise keeps the current period.
27
30
  All operations except lists/preview require --yes --confirm <exact-preview-confirm> --request-id <unique-id>.
28
31
  Preview first, inspect the exact financial target/amount, then use its confirm string unchanged.
29
32
  Reads need payments:read; previews/writes need payments:write. Managed sellers also need
@@ -59,6 +62,11 @@ export async function runPaymentsCommand(args, deps) {
59
62
  const preview = args[0] === "preview";
60
63
  const remaining = preview ? args.slice(1) : args;
61
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
+ }
62
70
  const listing = lists.includes(group);
63
71
  if (preview && listing) throw new Error("preview applies only to payment operations");
64
72
  if (!listing && !Object.hasOwn(verbs, group)) throw new Error(`Unknown payments command: ${group}`);
@@ -81,12 +89,12 @@ export async function runPaymentsCommand(args, deps) {
81
89
  if (seen.has(flag)) throw new Error(`${flag} may only be given once`);
82
90
  seen.add(flag);
83
91
  if (flag === "--yes") { yes = true; continue; }
84
- if (!["--account", "--limit", "--cursor", "--provider", "--kind", "--tier", "--plan", "--plan-type", "--quantity", "--order", "--checkout-intent", "--paypal-subscription", "--reason", "--note", "--confirm", "--request-id"].includes(flag)) throw new Error(`Unknown payments option: ${flag}`);
92
+ if (!["--account", "--limit", "--cursor", "--provider", "--kind", "--tier", "--billing", "--plan", "--plan-type", "--quantity", "--order", "--checkout-intent", "--paypal-subscription", "--reason", "--note", "--confirm", "--request-id"].includes(flag)) throw new Error(`Unknown payments option: ${flag}`);
85
93
  values[flag] = requiredFlagValue(flag, flags[++index]);
86
94
  }
87
95
  const accepted = listing ? ["--account", "--limit", "--cursor"] : [
88
96
  ...(operation?.startsWith("checkout.") ? ["--provider"] : []),
89
- ...(operation === "checkout.membership" || operation === "membership.revise" ? ["--tier"] : []),
97
+ ...(operation === "checkout.membership" || operation === "membership.revise" ? ["--tier", "--billing"] : []),
90
98
  ...(operation === "checkout.membership" ? ["--account"] : []),
91
99
  ...(operation === "checkout.quest-credit" ? ["--plan-type"] : []),
92
100
  ...(operation === "checkout.metaverse-time" ? ["--quantity"] : []),
@@ -104,6 +112,7 @@ export async function runPaymentsCommand(args, deps) {
104
112
  if (values["--provider"] && !["stripe", "paypal"].includes(values["--provider"])) throw new Error("--provider must be stripe or paypal");
105
113
  if (values["--kind"] && !["membership", "subscription", "ticket", "questCredit", "metaverseTime"].includes(values["--kind"])) throw new Error("--kind must be membership, subscription, ticket, questCredit or metaverseTime");
106
114
  if (values["--tier"] && !["honey", "swarm", "royal"].includes(values["--tier"])) throw new Error("--tier must be honey, swarm or royal");
115
+ if (values["--billing"] && !["month", "quarter", "year"].includes(values["--billing"])) throw new Error("--billing must be month, quarter or year");
107
116
  if (values["--plan-type"] && !["single", "bundle"].includes(values["--plan-type"])) throw new Error("--plan-type must be single or bundle");
108
117
  if (values["--quantity"] !== undefined && (!Number.isInteger(Number(values["--quantity"])) || Number(values["--quantity"]) < 1 || Number(values["--quantity"]) > 100)) throw new Error("--quantity must be an integer from 1 to 100");
109
118
  const required = {
@@ -120,7 +129,7 @@ export async function runPaymentsCommand(args, deps) {
120
129
  return;
121
130
  }
122
131
  const payload = { operation, target: operation === "checkout.membership" && values["--account"] ? values["--account"] : target };
123
- const fields = { "--provider": "provider", "--kind": "kind", "--tier": "tier", "--plan": "newPlanId", "--plan-type": "planType", "--order": "orderId", "--checkout-intent": "checkoutIntentId", "--paypal-subscription": "paypalSubscriptionId", "--reason": "reason", "--note": "reviewNote" };
132
+ const fields = { "--provider": "provider", "--kind": "kind", "--tier": "tier", "--billing": "billingPeriod", "--plan": "newPlanId", "--plan-type": "planType", "--order": "orderId", "--checkout-intent": "checkoutIntentId", "--paypal-subscription": "paypalSubscriptionId", "--reason": "reason", "--note": "reviewNote" };
124
133
  for (const [flag, field] of Object.entries(fields)) if (values[flag] !== undefined) payload[field] = values[flag];
125
134
  if (values["--quantity"] !== undefined) payload.quantity = Number(values["--quantity"]);
126
135
  writeJson(deps.stdout, preview ? await client.preview(payload) : await client.operate(payload, { confirmed: true, confirm: values["--confirm"], requestId: values["--request-id"] }));
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",
@@ -59,6 +61,8 @@ export function usage() {
59
61
  " update <id> [--title t] [--body b] [--description d] [--content-type t] [--visibility v]",
60
62
  " archive <id>",
61
63
  " events create|update also take --world <world-id|default> to book a 3D world; get world IDs from `hive3 worlds`",
64
+ " events create|update also take --location irl|virtual|metaverse with venue, meeting and check-in flags; events list takes --location",
65
+ " QR check-in and Google Calendar sync are done in the Hive3 app, not the CLI",
62
66
  "",
63
67
  "Account deletion is not available from the CLI; delete your account in the Hive3 app under Settings.",
64
68
  ].join("\n");
@@ -70,12 +74,14 @@ const ACCOUNT_FLAG_LINE = " --account <id-or-handle> Act on an account you own
70
74
  const resourceWorkflowLines = {
71
75
  posts: [" like <post-id> Toggle your like on a post"],
72
76
  events: [
77
+ " rsvps [--upcoming] List your own RSVPs and their status",
73
78
  " participants <event-id> List RSVPs (managers only)",
74
79
  " rsvp <event-id> [--enroll true|false] [--file json] RSVP or withdraw your RSVP",
75
80
  " approve|deny <event-id> <enrollment-id> Decide an RSVP",
76
81
  " attendance <event-id> <enrollment-id> [--attended true|false] [--file json]",
77
82
  ],
78
83
  courses: [
84
+ " enrollments [--active] List your own course enrollments and progress",
79
85
  " enrollments <course-id> List enrollments (managers only)",
80
86
  " enroll <course-id> [--enroll true|false] [--file json] Enroll or withdraw",
81
87
  " approve|deny <course-id> <account-id> Decide an enrollment",
@@ -83,6 +89,7 @@ const resourceWorkflowLines = {
83
89
  ],
84
90
  content: [],
85
91
  quests: [
92
+ " enrollments [--active] List your own quests, status and progress",
86
93
  " enrollments <quest-id> List enrollments (managers only)",
87
94
  " enroll <quest-id> [--enroll true|false] [--file json] Enroll or withdraw",
88
95
  " approve|deny <quest-id> <enrollment-id> Decide an enrollment",
@@ -97,12 +104,40 @@ const resourceWorkflowLines = {
97
104
  ],
98
105
  };
99
106
 
107
+ const EVENT_FIELD_LINES = [
108
+ " --location <irl|virtual|metaverse> Event type: in person, a virtual call, or a Hive3 3D world",
109
+ " In person (irl):",
110
+ " --address <text> Venue address, public (up to 300 characters)",
111
+ " --venue-name <text> Venue name (up to 120 characters)",
112
+ " --venue-instructions <text> Getting there: parking, entrance, floor, door code (up to 1000)",
113
+ " --check-in <self|door> self (default): guests scan the event QR code; door: hosts scan each guest's pass",
114
+ " Virtual:",
115
+ " --meeting-url <https-url> Join link, shown only to hosts and approved guests",
116
+ " --meeting-provider <zoom|google_meet|microsoft_teams|x_spaces|discord|youtube|other>",
117
+ " Inferred from the link when omitted",
118
+ " --meeting-instructions <text> Joining details: passcode, dial-in number (up to 1000)",
119
+ " Metaverse:",
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. Only metaverse events book a world",
122
+ " --file may carry location, venue, meeting and checkInMode; these flags win over it. On update the event's",
123
+ " current venue, meeting and check-in mode are kept for anything not given; --location irl|virtual leaves a world.",
124
+ " Output includes location, venue, meeting (url only in the owner/admin/moderator view) and checkInMode.",
125
+ " QR check-in (event QR, door scanning) and Google Calendar sync are in the Hive3 app only.",
126
+ ];
127
+
128
+ const QUEST_OBJECTIVE_LINES = [
129
+ " Event objective types: in_person_events_attended (checked in at an in-person event),",
130
+ " virtual_events_attended (joined a virtual event), metaverse_events_attended (attended a world event)",
131
+ ];
132
+
100
133
  export function resourceUsage(kind) {
101
134
  return [
102
135
  `Usage: hive3 ${kind} <action> [options]`,
103
136
  "",
104
137
  "Actions:",
105
- " list [--limit n] [--cursor c] [--owner-type person|community] [--community-id id]",
138
+ kind === "events"
139
+ ? " list [--limit n] [--cursor c] [--owner-type person|community] [--community-id id] [--location irl|virtual|metaverse]"
140
+ : " list [--limit n] [--cursor c] [--owner-type person|community] [--community-id id]",
106
141
  " get <id>",
107
142
  " create [fields] [--owner-type person|community --community-id id] [--idempotency-key key]",
108
143
  " update <id> [fields]",
@@ -116,11 +151,9 @@ export function resourceUsage(kind) {
116
151
  " --content-type <type>",
117
152
  " --image-url <url>",
118
153
  " --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
- ] : []),
154
+ ...(kind === "events" ? EVENT_FIELD_LINES : []),
123
155
  " --file <json> JSON object merged with the flags above",
156
+ ...(kind === "quests" ? QUEST_OBJECTIVE_LINES : []),
124
157
  "",
125
158
  "Create owner fields (managed accounts only after `hive3 capabilities` shows them):",
126
159
  " --owner-type <person|community>",
@@ -257,6 +290,10 @@ const commandUsageLines = {
257
290
  " overview|widgets|welcome-page save|import --file <json>",
258
291
  " overview|widgets|welcome-page export --file <output-path>",
259
292
  "",
293
+ "The overview JSON may include \"hiddenTabs\": tab ids hidden from the account page for everyone (activity, communities,",
294
+ "offerings, credentials, affiliates, events, metaverse, content, courses, jobs, nfts, quests, streams). Overview always",
295
+ "shows; without hiddenTabs every tab is on. save replaces the whole config, so start from get or export.",
296
+ "",
260
297
  "Options for every action above:",
261
298
  ACCOUNT_FLAG_LINE,
262
299
  " Reads need the communities:read scope, writes communities:write, plus a live owner/admin/moderator role.",
@@ -286,11 +323,34 @@ const commandUsageLines = {
286
323
  "",
287
324
  "Actions:",
288
325
  " list",
326
+ " balances Your Hive3 wallet's native and USDC balance on each network (read-only)",
289
327
  " default <address>",
290
328
  " visibility <address> --public true|false",
291
329
  " remove <address> --confirm <address>",
292
330
  ],
293
- 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
+ ],
294
354
  notifications: [
295
355
  "Usage: hive3 notifications <action> [options]",
296
356
  "",
@@ -317,6 +377,7 @@ const commandUsageLines = {
317
377
  "Usage: hive3 communities <action> [options]",
318
378
  "",
319
379
  "Actions:",
380
+ " mine Your memberships and pending applications",
320
381
  " join|apply|leave <community-id> [--message text]",
321
382
  " applications <community-id> Moderators and above",
322
383
  " approve|deny <application-id> Moderators and above",