@hive3/cli 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -1
- package/package.json +2 -2
- package/skills/hive3/SKILL.md +18 -2
- package/src/commands.js +22 -6
- package/src/event-placement.js +158 -0
- package/src/payments-commands.js +7 -5
- package/src/usage.js +37 -5
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.
|
|
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
|
|
@@ -245,6 +264,8 @@ hive3 communities applications <community-id>
|
|
|
245
264
|
hive3 communities approve <application-id>
|
|
246
265
|
```
|
|
247
266
|
|
|
267
|
+
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`.
|
|
268
|
+
|
|
248
269
|
### Managing another account with `--account`
|
|
249
270
|
|
|
250
271
|
`--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:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hive3/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.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 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"
|
package/skills/hive3/SKILL.md
CHANGED
|
@@ -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:
|
|
@@ -106,6 +120,8 @@ hive3 communities role <community-id> <account-id> --role moderator
|
|
|
106
120
|
|
|
107
121
|
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
122
|
|
|
123
|
+
`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
|
+
|
|
109
125
|
## Broadcasts, Tickets, Assistant, And Credentials
|
|
110
126
|
|
|
111
127
|
```bash
|
|
@@ -204,7 +220,7 @@ Use `--file` for structured fields and a stable `--idempotency-key` within its d
|
|
|
204
220
|
1. Start with `hive3 payments history|subscriptions|tickets|refunds|sales`; use command help for managed sellers.
|
|
205
221
|
2. Run `hive3 payments preview <operation...>` before a financial action. Show the canonical account, target, action, provider and amount/terms to the user.
|
|
206
222
|
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
|
|
223
|
+
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
224
|
|
|
209
225
|
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
226
|
|
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";
|
|
@@ -67,7 +68,7 @@ function takeAccountFlag(args) {
|
|
|
67
68
|
return { account, rest };
|
|
68
69
|
}
|
|
69
70
|
|
|
70
|
-
function parseListOptions(args) {
|
|
71
|
+
function parseListOptions(kind, args) {
|
|
71
72
|
const query = {};
|
|
72
73
|
for (let index = 0; index < args.length; index += 1) {
|
|
73
74
|
const flag = args[index];
|
|
@@ -87,6 +88,10 @@ function parseListOptions(args) {
|
|
|
87
88
|
} else if (flag === "--community-id") {
|
|
88
89
|
index += 1;
|
|
89
90
|
query.communityId = requiredFlagValue(flag, args[index]);
|
|
91
|
+
} else if (kind === "events" && flag === "--location") {
|
|
92
|
+
index += 1;
|
|
93
|
+
query.location = requiredFlagValue(flag, args[index]);
|
|
94
|
+
if (!EVENT_LOCATIONS.includes(query.location)) throw new Error(LOCATION_ERROR);
|
|
90
95
|
} else {
|
|
91
96
|
throw new Error(`Unknown list option: ${flag}`);
|
|
92
97
|
}
|
|
@@ -100,6 +105,8 @@ function setPayloadField(payload, key, value) {
|
|
|
100
105
|
|
|
101
106
|
async function parseResourcePayload(kind, args, includeOwner) {
|
|
102
107
|
let payload = {};
|
|
108
|
+
/** @type {Record<string, string>} */
|
|
109
|
+
const placement = {};
|
|
103
110
|
let idempotencyKey;
|
|
104
111
|
let ownerType;
|
|
105
112
|
let communityId;
|
|
@@ -126,6 +133,9 @@ async function parseResourcePayload(kind, args, includeOwner) {
|
|
|
126
133
|
} else if (kind === "events" && flag === "--world") {
|
|
127
134
|
index += 1;
|
|
128
135
|
setPayloadField(payload, "worldId", requiredFlagValue(flag, args[index]));
|
|
136
|
+
} else if (kind === "events" && isEventPlacementFlag(flag)) {
|
|
137
|
+
index += 1;
|
|
138
|
+
setEventPlacementFlag(placement, flag, requiredFlagValue(flag, args[index]));
|
|
129
139
|
} else if (flag === "--file") {
|
|
130
140
|
index += 1;
|
|
131
141
|
const filePayload = await readJsonFile(requiredFlagValue(flag, args[index]));
|
|
@@ -153,8 +163,8 @@ async function parseResourcePayload(kind, args, includeOwner) {
|
|
|
153
163
|
} else if (includeOwner && ownerType === "person") {
|
|
154
164
|
payload.owner = { type: "person" };
|
|
155
165
|
}
|
|
156
|
-
if (Object.keys(payload).length === 0) throw new Error("At least one resource field is required");
|
|
157
|
-
return { idempotencyKey, payload };
|
|
166
|
+
if (Object.keys(payload).length === 0 && Object.keys(placement).length === 0) throw new Error("At least one resource field is required");
|
|
167
|
+
return { idempotencyKey, payload, placement };
|
|
158
168
|
}
|
|
159
169
|
function parseCsv(value) {
|
|
160
170
|
return value.split(",").map((item) => item.trim()).filter(Boolean);
|
|
@@ -272,17 +282,23 @@ async function runResource(kind, args, deps) {
|
|
|
272
282
|
}
|
|
273
283
|
const client = await authenticatedClient(deps);
|
|
274
284
|
if (action === "list") {
|
|
275
|
-
writeJson(deps.stdout, await client.listResource(kind, parseListOptions(rest)));
|
|
285
|
+
writeJson(deps.stdout, await client.listResource(kind, parseListOptions(kind, rest)));
|
|
276
286
|
return;
|
|
277
287
|
}
|
|
278
288
|
if (action === "create") {
|
|
279
|
-
const { idempotencyKey, payload } = await parseResourcePayload(kind, rest, true);
|
|
289
|
+
const { idempotencyKey, payload, placement } = await parseResourcePayload(kind, rest, true);
|
|
290
|
+
if (kind === "events") applyEventPlacement(payload, placement, { creating: true });
|
|
280
291
|
writeJson(deps.stdout, await client.createResource(kind, payload, idempotencyKey));
|
|
281
292
|
return;
|
|
282
293
|
}
|
|
283
294
|
if (action === "update") {
|
|
284
295
|
const id = requiredFlagValue("resource id", rest[0]);
|
|
285
|
-
const { payload } = await parseResourcePayload(kind, rest.slice(1), false);
|
|
296
|
+
const { payload, placement } = await parseResourcePayload(kind, rest.slice(1), false);
|
|
297
|
+
if (kind === "events") {
|
|
298
|
+
// Changing one placement detail keeps the rest: the current venue, meeting and check-in mode fill the gaps.
|
|
299
|
+
const existing = Object.keys(placement).length > 0 ? (await client.getResource(kind, id)).data : null;
|
|
300
|
+
applyEventPlacement(payload, placement, { creating: false, existing });
|
|
301
|
+
}
|
|
286
302
|
writeJson(deps.stdout, await client.updateResource(kind, id, payload));
|
|
287
303
|
return;
|
|
288
304
|
}
|
|
@@ -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
|
+
}
|
package/src/payments-commands.js
CHANGED
|
@@ -10,7 +10,7 @@ export function paymentsUsage() {
|
|
|
10
10
|
hive3 payments tickets|refunds [--account <seller-id-or-handle>] [--limit <1-100>] [--cursor <cursor>]
|
|
11
11
|
hive3 payments sales [--account <seller-id-or-handle>] [--limit <1-100>] [--cursor <cursor>]
|
|
12
12
|
hive3 payments [preview] checkout subscription|ticket <id> [--provider stripe|paypal]
|
|
13
|
-
hive3 payments [preview] checkout membership --tier honey|swarm|royal [--account <owned-account>]
|
|
13
|
+
hive3 payments [preview] checkout membership --tier honey|swarm|royal [--billing month|quarter|year] [--account <owned-account>]
|
|
14
14
|
hive3 payments [preview] checkout quest-credit <account> --plan-type single|bundle
|
|
15
15
|
hive3 payments [preview] checkout metaverse-time <account> --quantity <1-100-hours>
|
|
16
16
|
hive3 payments quest-credits|metaverse-time [--account <managed-account>] [--limit <1-100>] [--cursor <cursor>]
|
|
@@ -20,10 +20,11 @@ export function paymentsUsage() {
|
|
|
20
20
|
hive3 payments [preview] subscription cancel|resume|portal <subscription-id>
|
|
21
21
|
hive3 payments [preview] subscription revise <subscription-id> --plan <new-plan-id>
|
|
22
22
|
hive3 payments [preview] membership cancel|resume|portal
|
|
23
|
-
hive3 payments [preview] membership revise --tier honey|swarm|royal
|
|
23
|
+
hive3 payments [preview] membership revise --tier honey|swarm|royal [--billing month|quarter|year]
|
|
24
24
|
hive3 payments [preview] refund request <purchased-ticket-id> [--reason <text>]
|
|
25
25
|
hive3 payments [preview] refund approve|reject <refund-request-id> [--note <text>]
|
|
26
26
|
|
|
27
|
+
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
28
|
All operations except lists/preview require --yes --confirm <exact-preview-confirm> --request-id <unique-id>.
|
|
28
29
|
Preview first, inspect the exact financial target/amount, then use its confirm string unchanged.
|
|
29
30
|
Reads need payments:read; previews/writes need payments:write. Managed sellers also need
|
|
@@ -81,12 +82,12 @@ export async function runPaymentsCommand(args, deps) {
|
|
|
81
82
|
if (seen.has(flag)) throw new Error(`${flag} may only be given once`);
|
|
82
83
|
seen.add(flag);
|
|
83
84
|
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}`);
|
|
85
|
+
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
86
|
values[flag] = requiredFlagValue(flag, flags[++index]);
|
|
86
87
|
}
|
|
87
88
|
const accepted = listing ? ["--account", "--limit", "--cursor"] : [
|
|
88
89
|
...(operation?.startsWith("checkout.") ? ["--provider"] : []),
|
|
89
|
-
...(operation === "checkout.membership" || operation === "membership.revise" ? ["--tier"] : []),
|
|
90
|
+
...(operation === "checkout.membership" || operation === "membership.revise" ? ["--tier", "--billing"] : []),
|
|
90
91
|
...(operation === "checkout.membership" ? ["--account"] : []),
|
|
91
92
|
...(operation === "checkout.quest-credit" ? ["--plan-type"] : []),
|
|
92
93
|
...(operation === "checkout.metaverse-time" ? ["--quantity"] : []),
|
|
@@ -104,6 +105,7 @@ export async function runPaymentsCommand(args, deps) {
|
|
|
104
105
|
if (values["--provider"] && !["stripe", "paypal"].includes(values["--provider"])) throw new Error("--provider must be stripe or paypal");
|
|
105
106
|
if (values["--kind"] && !["membership", "subscription", "ticket", "questCredit", "metaverseTime"].includes(values["--kind"])) throw new Error("--kind must be membership, subscription, ticket, questCredit or metaverseTime");
|
|
106
107
|
if (values["--tier"] && !["honey", "swarm", "royal"].includes(values["--tier"])) throw new Error("--tier must be honey, swarm or royal");
|
|
108
|
+
if (values["--billing"] && !["month", "quarter", "year"].includes(values["--billing"])) throw new Error("--billing must be month, quarter or year");
|
|
107
109
|
if (values["--plan-type"] && !["single", "bundle"].includes(values["--plan-type"])) throw new Error("--plan-type must be single or bundle");
|
|
108
110
|
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
111
|
const required = {
|
|
@@ -120,7 +122,7 @@ export async function runPaymentsCommand(args, deps) {
|
|
|
120
122
|
return;
|
|
121
123
|
}
|
|
122
124
|
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" };
|
|
125
|
+
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
126
|
for (const [flag, field] of Object.entries(fields)) if (values[flag] !== undefined) payload[field] = values[flag];
|
|
125
127
|
if (values["--quantity"] !== undefined) payload.quantity = Number(values["--quantity"]);
|
|
126
128
|
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
|
@@ -59,6 +59,8 @@ export function usage() {
|
|
|
59
59
|
" update <id> [--title t] [--body b] [--description d] [--content-type t] [--visibility v]",
|
|
60
60
|
" archive <id>",
|
|
61
61
|
" events create|update also take --world <world-id|default> to book a 3D world; get world IDs from `hive3 worlds`",
|
|
62
|
+
" events create|update also take --location irl|virtual|metaverse with venue, meeting and check-in flags; events list takes --location",
|
|
63
|
+
" QR check-in and Google Calendar sync are done in the Hive3 app, not the CLI",
|
|
62
64
|
"",
|
|
63
65
|
"Account deletion is not available from the CLI; delete your account in the Hive3 app under Settings.",
|
|
64
66
|
].join("\n");
|
|
@@ -97,12 +99,40 @@ const resourceWorkflowLines = {
|
|
|
97
99
|
],
|
|
98
100
|
};
|
|
99
101
|
|
|
102
|
+
const EVENT_FIELD_LINES = [
|
|
103
|
+
" --location <irl|virtual|metaverse> Event type: in person, a virtual call, or a Hive3 3D world",
|
|
104
|
+
" In person (irl):",
|
|
105
|
+
" --address <text> Venue address, public (up to 300 characters)",
|
|
106
|
+
" --venue-name <text> Venue name (up to 120 characters)",
|
|
107
|
+
" --venue-instructions <text> Getting there: parking, entrance, floor, door code (up to 1000)",
|
|
108
|
+
" --check-in <self|door> self (default): guests scan the event QR code; door: hosts scan each guest's pass",
|
|
109
|
+
" Virtual:",
|
|
110
|
+
" --meeting-url <https-url> Join link, shown only to hosts and approved guests",
|
|
111
|
+
" --meeting-provider <zoom|google_meet|microsoft_teams|x_spaces|discord|youtube|other>",
|
|
112
|
+
" Inferred from the link when omitted",
|
|
113
|
+
" --meeting-instructions <text> Joining details: passcode, dial-in number (up to 1000)",
|
|
114
|
+
" Metaverse:",
|
|
115
|
+
" --world <world-id|default> Book a 3D world: the ID of the world the user named, from `hive3 worlds`;",
|
|
116
|
+
" default is the owning account's default world. Only metaverse events book a world",
|
|
117
|
+
" --file may carry location, venue, meeting and checkInMode; these flags win over it. On update the event's",
|
|
118
|
+
" current venue, meeting and check-in mode are kept for anything not given; --location irl|virtual leaves a world.",
|
|
119
|
+
" Output includes location, venue, meeting (url only in the owner/admin/moderator view) and checkInMode.",
|
|
120
|
+
" QR check-in (event QR, door scanning) and Google Calendar sync are in the Hive3 app only.",
|
|
121
|
+
];
|
|
122
|
+
|
|
123
|
+
const QUEST_OBJECTIVE_LINES = [
|
|
124
|
+
" Event objective types: in_person_events_attended (checked in at an in-person event),",
|
|
125
|
+
" virtual_events_attended (joined a virtual event), metaverse_events_attended (attended a world event)",
|
|
126
|
+
];
|
|
127
|
+
|
|
100
128
|
export function resourceUsage(kind) {
|
|
101
129
|
return [
|
|
102
130
|
`Usage: hive3 ${kind} <action> [options]`,
|
|
103
131
|
"",
|
|
104
132
|
"Actions:",
|
|
105
|
-
|
|
133
|
+
kind === "events"
|
|
134
|
+
? " list [--limit n] [--cursor c] [--owner-type person|community] [--community-id id] [--location irl|virtual|metaverse]"
|
|
135
|
+
: " list [--limit n] [--cursor c] [--owner-type person|community] [--community-id id]",
|
|
106
136
|
" get <id>",
|
|
107
137
|
" create [fields] [--owner-type person|community --community-id id] [--idempotency-key key]",
|
|
108
138
|
" update <id> [fields]",
|
|
@@ -116,11 +146,9 @@ export function resourceUsage(kind) {
|
|
|
116
146
|
" --content-type <type>",
|
|
117
147
|
" --image-url <url>",
|
|
118
148
|
" --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
|
-
] : []),
|
|
149
|
+
...(kind === "events" ? EVENT_FIELD_LINES : []),
|
|
123
150
|
" --file <json> JSON object merged with the flags above",
|
|
151
|
+
...(kind === "quests" ? QUEST_OBJECTIVE_LINES : []),
|
|
124
152
|
"",
|
|
125
153
|
"Create owner fields (managed accounts only after `hive3 capabilities` shows them):",
|
|
126
154
|
" --owner-type <person|community>",
|
|
@@ -257,6 +285,10 @@ const commandUsageLines = {
|
|
|
257
285
|
" overview|widgets|welcome-page save|import --file <json>",
|
|
258
286
|
" overview|widgets|welcome-page export --file <output-path>",
|
|
259
287
|
"",
|
|
288
|
+
"The overview JSON may include \"hiddenTabs\": tab ids hidden from the account page for everyone (activity, communities,",
|
|
289
|
+
"offerings, credentials, affiliates, events, metaverse, content, courses, jobs, nfts, quests, streams). Overview always",
|
|
290
|
+
"shows; without hiddenTabs every tab is on. save replaces the whole config, so start from get or export.",
|
|
291
|
+
"",
|
|
260
292
|
"Options for every action above:",
|
|
261
293
|
ACCOUNT_FLAG_LINE,
|
|
262
294
|
" Reads need the communities:read scope, writes communities:write, plus a live owner/admin/moderator role.",
|