@go-labs-sg/event-tech 1.1.0 → 1.2.0

package/README.md

@@ -99,6 +99,58 @@ et lucky-draw participants list --event-id <id> --page 1 --per-page 100
 
 Commands emit deterministic JSON envelopes. Authentication credentials are never included in successful output, and bearer credentials are redacted from errors.
 
+### Event Passport
+
+`et passport` uses the same typed procedures and event permissions as the web app.
+Read `et --help` for all commands. Examples below use illustrative IDs and are not
+an instruction to change a live event:
+
+```sh
+et passport overview --event-id <id>
+et passport login-options --event-id <id>
+et passport mine --event-id <id>
+et passport station upsert --event-id <id> --station-json '{"name":"Balance trail","collection":{"collectionMode":"STAFF_SCORE","maxPoints":20}}'
+et passport station print-get --event-id <id> --station-id <id>
+et passport station print-issue --event-id <id> --station-id <id> --expected-printed-qr-version <last-read-version>
+et passport station print-revoke --event-id <id> --station-id <id> --expected-printed-qr-version <last-read-version> --allow-state-change --target <same-event-id>
+et passport collect --event-id <id> --station-id <id> --profile-code <participant-code> --points 15
+et passport claim --event-id <id> --code <station-code>
+et passport participant detail --event-id <id> --participant-id <id>
+et passport export --event-id <id>
+```
+
+Station collection modes are `SELF_SCAN`, `STAFF_SCAN` and `STAFF_SCORE`.
+`SELF_SCAN` uses a reusable printable QR; `STAFF_SCAN` is stamp-only; only
+`STAFF_SCORE` accepts `collection.maxPoints` and a collection `--points` value.
+Zero is valid. Repeat collection returns the original receipt without changing
+points. Omit `collection` on an existing station edit to preserve its current
+mode, including the legacy rotating-QR mode. Issuing/revoking printed codes uses
+the last observed version to reject stale writes. Issue/rotation requires setup
+permission; any event Operator can collect at any station.
+
+`settings update --settings-json <json>` replaces the reward settings, so read
+and copy the existing link, thresholds and redemption cap rather than clearing
+them accidentally. Its JSON requires `linkedDrawEventId`,
+`luckyDrawStampThreshold`, `prizeStampThreshold` and
+`maxRedemptionsPerParticipant`; optional `loginMethods` is
+`{"emailOtp":true,"google":false,"guest":true}`. Omit `loginMethods` to preserve
+it. At least email OTP or Google must remain enabled for recovery, and enabling
+Google requires configured provider credentials. Points never replace the
+existing stamp-based reward thresholds.
+
+`stamp correct`, `redemption reverse`, station/prize archive and print revocation
+require `--allow-state-change --target <same-event-id>`; correction/reversal also
+require a reason. Scored corrections accept `--points` and preserve historical
+scores on revocation. Prize setup and redemption commands remain in `et --help`.
+Participant reads/exports include points and nullable guest contact emails; do
+not treat a null contact as an account lookup key.
+
+Guest enrollment/account linking is browser-only: it requires the original guest
+cookie and verified email/Google authentication. `mine` can read only the passport
+owned by the current CLI identity; it cannot recover a guest by name or assume a
+participant ID. No CLI auth transport or organiser access boundary is bypassed.
+See the [Passport workflow and rollout gates](../../../docs/design/event-tech-passport-event-type.md).
+
 ### Deprecated event types
 
 Scavenger Hunt (Amazing Race) and Gardens by the Bay are deprecated and frozen.

package/dist/index.js

@@ -6863,6 +6863,45 @@ Usage:
   et lucky-draw pre-draw --event-id <id> --prize-count <n>
   et lucky-draw participants replace --event-id <id> (--participants <json-array> | --participants-file <path>) --allow-state-change --target <same-event-id>
   et lucky-draw participants list --event-id <id> [--page <n>] [--per-page <n>]
+  et passport overview --event-id <id>
+  et passport mine --event-id <id>
+  et passport login-options --event-id <id>
+  et passport export --event-id <id>
+  et passport settings update --event-id <id> --settings-json <json>
+  et passport station upsert --event-id <id> --station-json <json>
+  et passport station hidden --event-id <id> --station-id <id> --hidden <true|false>
+  et passport station archive --event-id <id> --station-id <id> --allow-state-change --target <same-event-id>
+  et passport station print-get --event-id <id> --station-id <id>
+  et passport station print-issue --event-id <id> --station-id <id> --expected-printed-qr-version <n>
+  et passport station print-revoke --event-id <id> --station-id <id> --expected-printed-qr-version <n> --allow-state-change --target <same-event-id>
+  et passport station start-qr --event-id <id> --station-id <id>
+  et passport station qr-status --event-id <id> --session-id <id>
+  et passport collect --event-id <id> --station-id <id> --profile-code <code> [--points <n>]
+  et passport claim --event-id <id> --code <code>
+  et passport participant search --event-id <id> [--query <text>]
+  et passport participant detail --event-id <id> --participant-id <id>
+  et passport stamp correct --event-id <id> --station-id <id> --participant-id <id> --stamped <true|false> --reason <text> [--points <n>] --allow-state-change --target <same-event-id>
+  et passport prize upsert --event-id <id> --prize-json <json>
+  et passport prize archive --event-id <id> --prize-id <id> --allow-state-change --target <same-event-id>
+  et passport redemption create --event-id <id> --participant-id <id> --prize-id <id>
+  et passport redemption reverse --event-id <id> --redemption-id <id> --reason <text> --allow-state-change --target <same-event-id>
+
+Event Passport:
+  Uses the same typed procedures and event permissions as the web app.
+  Station collection modes: SELF_SCAN, STAFF_SCAN, STAFF_SCORE.
+  Include collection.maxPoints only for STAFF_SCORE; zero is a valid score.
+  Omit collection on an existing station to preserve its current mode.
+  Station JSON supports id/name/description/location/imageKey/order/opensAt/closesAt/collection.
+  Date-time fields are ISO strings or null; order defaults to zero.
+  Settings JSON requires linkedDrawEventId, luckyDrawStampThreshold, prizeStampThreshold,
+  maxRedemptionsPerParticipant; optional loginMethods is {emailOtp,google,guest}.
+  Keep email OTP or Google enabled for guest recovery. Omit loginMethods to preserve it.
+  Printed QR issue/revoke requires the last observed print version; stale versions conflict.
+  claim scans a station QR; collect scans a participant profile QR as an event operator.
+  Repeat scans never add a second stamp or change its original points.
+  Destructive corrections, archive, reverse and print revoke require explicit target confirmation.
+  Points are scores only; existing stamp-based Lucky Draw and prize thresholds still apply.
+  Guest enrollment and account-linking require the browser; CLI uses existing device-approved auth.
 
 Lucky draw:
   pre-draw immediately saves winners for the next unassigned prizes in order.
@@ -6933,6 +6972,334 @@ var writeError = (runtime, error) => {
   runtime.stderr.write(serialize({ ok: false, error: { code: errorCode(error), message } }));
 };
 
+// src/commands/passport.ts
+var flag = (flags, name, required = true) => {
+  const value = flags.get(name);
+  if (value === true || required && !value)
+    throw new CliUsageError(`--${name} requires a value.`);
+  return value;
+};
+var requiredFlag = (flags, name) => {
+  const value = flag(flags, name);
+  if (!value)
+    throw new CliUsageError(`--${name} is required.`);
+  return value;
+};
+var integer2 = (value, name, minimum = 0) => {
+  const parsed = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+  if (typeof parsed !== "number" || !Number.isSafeInteger(parsed) || parsed < minimum || parsed > 2147483647) {
+    throw new CliUsageError(`${name} must be a whole number from ${minimum} to 2147483647.`);
+  }
+  return parsed;
+};
+var boolean3 = (value, name) => {
+  if (value === true || value === "true")
+    return true;
+  if (value === false || value === "false")
+    return false;
+  throw new CliUsageError(`${name} must be true or false.`);
+};
+var text = (value, name, maximum) => {
+  if (typeof value !== "string" || !value.trim() || value.trim().length > maximum)
+    throw new CliUsageError(`${name} must be a non-empty string of at most ${maximum} characters.`);
+  return value.trim();
+};
+var nullableText = (value, name, maximum) => {
+  if (value == null)
+    return null;
+  if (typeof value !== "string" || value.trim().length > maximum)
+    throw new CliUsageError(`${name} must be a string of at most ${maximum} characters or null.`);
+  return value.trim();
+};
+var object2 = (value, name) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new CliUsageError(`${name} must be an object.`);
+  return Object.fromEntries(Object.entries(value));
+};
+var json = (value, name) => {
+  try {
+    const parsed = JSON.parse(value);
+    return object2(parsed, name);
+  } catch (error) {
+    if (error instanceof CliUsageError)
+      throw error;
+    throw new CliUsageError(`${name} must be valid JSON.`);
+  }
+};
+var keys = (value, allowed, name) => {
+  if (Object.keys(value).some((key) => !allowed.includes(key)))
+    throw new CliUsageError(`${name} contains unsupported fields.`);
+};
+var date2 = (value, name) => {
+  if (value == null)
+    return null;
+  if (typeof value !== "string" || !/^\d{4}-\d\d-\d\dT/.test(value))
+    throw new CliUsageError(`${name} must be an ISO date-time or null.`);
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime()))
+    throw new CliUsageError(`${name} must be a valid ISO date-time.`);
+  return parsed;
+};
+var parsePassportStationInput = (raw, eventId) => {
+  const value = json(raw, "--station-json");
+  keys(value, [
+    "id",
+    "name",
+    "description",
+    "location",
+    "imageKey",
+    "order",
+    "opensAt",
+    "closesAt",
+    "collection"
+  ], "Station");
+  let collection;
+  if (value.collection !== undefined) {
+    const item = object2(value.collection, "collection");
+    if (item.collectionMode === "STAFF_SCORE") {
+      keys(item, ["collectionMode", "maxPoints"], "collection");
+      collection = {
+        collectionMode: "STAFF_SCORE",
+        maxPoints: integer2(item.maxPoints, "maxPoints")
+      };
+    } else if (item.collectionMode === "SELF_SCAN" || item.collectionMode === "STAFF_SCAN") {
+      keys(item, ["collectionMode"], "collection");
+      collection = { collectionMode: item.collectionMode };
+    } else
+      throw new CliUsageError("collectionMode must be SELF_SCAN, STAFF_SCAN or STAFF_SCORE.");
+  }
+  return {
+    eventId,
+    ...value.id === undefined ? {} : { id: text(value.id, "id", 200) },
+    name: text(value.name, "name", 100),
+    description: nullableText(value.description, "description", 1000),
+    location: nullableText(value.location, "location", 200),
+    imageKey: nullableText(value.imageKey, "imageKey", 2048),
+    order: integer2(value.order ?? 0, "order"),
+    opensAt: date2(value.opensAt, "opensAt"),
+    closesAt: date2(value.closesAt, "closesAt"),
+    ...collection ? { collection } : {}
+  };
+};
+var parsePassportSettingsInput = (raw, eventId) => {
+  const value = json(raw, "--settings-json");
+  keys(value, [
+    "luckyDrawStampThreshold",
+    "prizeStampThreshold",
+    "maxRedemptionsPerParticipant",
+    "linkedDrawEventId",
+    "loginMethods"
+  ], "Settings");
+  const threshold = (item, name) => item === null ? null : integer2(item, name, 1);
+  let loginMethods;
+  if (value.loginMethods !== undefined) {
+    const methods = object2(value.loginMethods, "loginMethods");
+    keys(methods, ["emailOtp", "google", "guest"], "loginMethods");
+    if (typeof methods.emailOtp !== "boolean" || typeof methods.google !== "boolean" || typeof methods.guest !== "boolean")
+      throw new CliUsageError("loginMethods values must be JSON booleans.");
+    loginMethods = {
+      emailOtp: methods.emailOtp,
+      google: methods.google,
+      guest: methods.guest
+    };
+    if (!loginMethods.emailOtp && !loginMethods.google)
+      throw new CliUsageError("Keep email OTP or Google available for recovery.");
+  }
+  if (value.linkedDrawEventId === undefined)
+    throw new CliUsageError("linkedDrawEventId is required (use null to disable).");
+  return {
+    eventId,
+    luckyDrawStampThreshold: threshold(value.luckyDrawStampThreshold, "luckyDrawStampThreshold"),
+    prizeStampThreshold: threshold(value.prizeStampThreshold, "prizeStampThreshold"),
+    maxRedemptionsPerParticipant: integer2(value.maxRedemptionsPerParticipant, "maxRedemptionsPerParticipant", 1),
+    linkedDrawEventId: value.linkedDrawEventId === null ? null : text(value.linkedDrawEventId, "linkedDrawEventId", 200),
+    ...loginMethods ? { loginMethods } : {}
+  };
+};
+var runPassportCommand = async (input) => {
+  const { flags, positionals } = input;
+  const action = positionals.slice(1).join(" ");
+  const allowed = ["event-id"];
+  const eventId = requiredFlag(flags, "event-id");
+  const event = { eventId };
+  const station = () => ({
+    eventId,
+    stationId: requiredFlag(flags, "station-id")
+  });
+  const version = () => integer2(requiredFlag(flags, "expected-printed-qr-version"), "--expected-printed-qr-version");
+  const confirm = () => {
+    allowed.push("allow-state-change", "target");
+    if (flags.get("allow-state-change") !== true || requiredFlag(flags, "target") !== eventId)
+      throw new CliUsageError("This operation requires --allow-state-change and --target exactly equal to --event-id.");
+  };
+  let operation;
+  switch (action) {
+    case "overview":
+      operation = () => api2.event.passport.getPassportOverview.query(event);
+      break;
+    case "mine":
+      operation = () => api2.event.passport.getMyPassport.query(event);
+      break;
+    case "login-options":
+      operation = () => api2.event.passport.getPassportLoginOptions.query(event);
+      break;
+    case "export":
+      operation = () => api2.event.passport.getPassportExportData.query(event);
+      break;
+    case "settings update": {
+      allowed.push("settings-json");
+      const payload = parsePassportSettingsInput(requiredFlag(flags, "settings-json"), eventId);
+      operation = () => api2.event.passport.updatePassportSettings.mutate(payload);
+      break;
+    }
+    case "station upsert": {
+      allowed.push("station-json");
+      const payload = parsePassportStationInput(requiredFlag(flags, "station-json"), eventId);
+      operation = () => api2.event.passport.upsertPassportStation.mutate(payload);
+      break;
+    }
+    case "station print-get": {
+      allowed.push("station-id");
+      const payload = station();
+      operation = () => api2.event.passport.getStationPrintQr.query(payload);
+      break;
+    }
+    case "station print-issue":
+    case "station print-revoke": {
+      allowed.push("station-id", "expected-printed-qr-version");
+      const payload = { ...station(), expectedPrintedQrVersion: version() };
+      if (action === "station print-revoke")
+        confirm();
+      operation = action === "station print-issue" ? () => api2.event.passport.issueStationPrintQr.mutate(payload) : () => api2.event.passport.revokeStationPrintQr.mutate(payload);
+      break;
+    }
+    case "station archive": {
+      allowed.push("station-id");
+      confirm();
+      const payload = station();
+      operation = () => api2.event.passport.archivePassportStation.mutate(payload);
+      break;
+    }
+    case "station hidden": {
+      allowed.push("station-id", "hidden");
+      const payload = {
+        ...station(),
+        hidden: boolean3(requiredFlag(flags, "hidden"), "--hidden")
+      };
+      operation = () => api2.event.passport.setPassportStationHidden.mutate(payload);
+      break;
+    }
+    case "station start-qr": {
+      allowed.push("station-id");
+      const payload = station();
+      operation = () => api2.event.passport.startStationQr.mutate(payload);
+      break;
+    }
+    case "station qr-status": {
+      allowed.push("session-id");
+      const payload = { eventId, sessionId: requiredFlag(flags, "session-id") };
+      operation = () => api2.event.passport.getStationQrStatus.query(payload);
+      break;
+    }
+    case "collect": {
+      allowed.push("station-id", "profile-code", "points");
+      const points = flag(flags, "points", false);
+      const payload = {
+        ...station(),
+        profileCode: requiredFlag(flags, "profile-code"),
+        ...points === undefined ? {} : { points: integer2(points, "--points") }
+      };
+      operation = () => api2.event.passport.collectPassportStampByStaff.mutate(payload);
+      break;
+    }
+    case "claim": {
+      allowed.push("code");
+      const payload = { eventId, code: requiredFlag(flags, "code") };
+      operation = () => api2.event.passport.claimPassportStamp.mutate(payload);
+      break;
+    }
+    case "stamp correct": {
+      allowed.push("station-id", "participant-id", "stamped", "reason", "points");
+      confirm();
+      const points = flag(flags, "points", false);
+      const payload = {
+        ...station(),
+        participantId: requiredFlag(flags, "participant-id"),
+        stamped: boolean3(requiredFlag(flags, "stamped"), "--stamped"),
+        reason: requiredFlag(flags, "reason"),
+        ...points === undefined ? {} : { points: integer2(points, "--points") }
+      };
+      operation = () => api2.event.passport.correctPassportStamp.mutate(payload);
+      break;
+    }
+    case "participant detail": {
+      allowed.push("participant-id");
+      const payload = {
+        eventId,
+        participantId: requiredFlag(flags, "participant-id")
+      };
+      operation = () => api2.event.passport.getPassportParticipantDetail.query(payload);
+      break;
+    }
+    case "participant search": {
+      allowed.push("query");
+      const payload = { eventId, query: flag(flags, "query", false) ?? "" };
+      operation = () => api2.event.passport.searchPassportParticipants.query(payload);
+      break;
+    }
+    case "prize upsert": {
+      allowed.push("prize-json");
+      const value = json(requiredFlag(flags, "prize-json"), "--prize-json");
+      keys(value, ["id", "name", "description", "stock", "order"], "Prize");
+      const payload = {
+        eventId,
+        ...value.id === undefined ? {} : { id: text(value.id, "id", 200) },
+        name: text(value.name, "name", 100),
+        description: nullableText(value.description, "description", 1000),
+        stock: integer2(value.stock, "stock"),
+        order: integer2(value.order ?? 0, "order")
+      };
+      operation = () => api2.event.passport.upsertPassportPrize.mutate(payload);
+      break;
+    }
+    case "prize archive": {
+      allowed.push("prize-id");
+      confirm();
+      const payload = { eventId, prizeId: requiredFlag(flags, "prize-id") };
+      operation = () => api2.event.passport.archivePassportPrize.mutate(payload);
+      break;
+    }
+    case "redemption create": {
+      allowed.push("prize-id", "participant-id");
+      const payload = {
+        eventId,
+        prizeId: requiredFlag(flags, "prize-id"),
+        participantId: requiredFlag(flags, "participant-id")
+      };
+      operation = () => api2.event.passport.redeemPassportPrize.mutate(payload);
+      break;
+    }
+    case "redemption reverse": {
+      allowed.push("redemption-id", "reason");
+      confirm();
+      const payload = {
+        eventId,
+        redemptionId: requiredFlag(flags, "redemption-id"),
+        reason: requiredFlag(flags, "reason")
+      };
+      operation = () => api2.event.passport.reversePassportRedemption.mutate(payload);
+      break;
+    }
+    default:
+      throw new CliUsageError("Unknown passport command. Run et --help for supported commands.");
+  }
+  const unknown = [...flags.keys()].filter((key) => key !== "api-url" && !allowed.includes(key));
+  if (unknown.length)
+    throw new CliUsageError(`Unknown option(s): ${unknown.map((key) => `--${key}`).join(", ")}.`);
+  await input.authenticate();
+  writeSuccess(input.runtime, await operation());
+};
+
 // src/cli.ts
 var getInstalledCliVersion = () => {
   try {
@@ -7155,6 +7522,15 @@ var runCommand = async (parsed, runtime, credentialStore, apiBaseUrl, configureA
     writeSuccess(runtime, { version: cliVersion });
     return;
   }
+  if (group === "passport") {
+    await runPassportCommand({
+      positionals: parsed.positionals,
+      flags: parsed.flags,
+      runtime,
+      authenticate: ensureAuthentication
+    });
+    return;
+  }
   if (group === "auth" && action === "login" && subAction === undefined) {
     assertPositionalCount(parsed, 2);
     assertOnlyFlags(parsed, ["no-browser"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/event-tech",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Event Tech CLI for managing Event Tech resources through the Go Labs API.",
   "type": "module",
   "main": "./dist/index.js",