@indiegems/gem-web-sdk 24.0.1 → 24.1.0

package/docs/arcade-and-store.md

@@ -318,9 +318,8 @@ game never names a SKU ([below](#a-pass-by-its-slug-showpass)). `showOffer(skuId
 sheet for any other SKU, such as a bundle.
 
 `showOffer(skuId)` asks the Arcade to draw one SKU from `offers()` in its own sheet, over your paused
-and hidden game. The Arcade draws the art, what the player gets, a sale if one is running, and, for a
-pass the player already holds, how long it has left. The sheet's Buy opens the same checkout
-`purchase` opens.
+and hidden game. The Arcade draws the art, what the player gets and a sale if one is running. The
+sheet's Buy opens the same checkout `purchase` opens.
 
 Pick by who can say what the offer is:
 
@@ -330,20 +329,24 @@ Pick by who can say what the offer is:
 | Your button     | says what it buys and shows `priceDisplay`           | says what it opens, such as "Get VIP"                           |
 | The press opens | the checkout, straight away                          | the Arcade's sheet, then the checkout if the player presses Buy |
 | Perks and sales | not available to you                                 | always current, in the player's language                        |
-| A holder sees   | the same Buy button                                  | what they already have, and how to add time                     |
+| A held pass     | your button cannot tell                              | the Arcade decides whether the holder is offered it again       |
 
 - **Never write an offer's perks into your game.** They change without a new build of your game, and
   yours would go stale. Your button only needs the offer's name.
 - **Do not show a price on the button.** The sheet shows the right one for this player, which a
   sale or a pass can change, and `priceDisplay` does not say either of those. If you want a price on
   screen, draw the offer yourself and use `purchase`.
-- **The sheet does not tell you what the player holds.** It tells the player, so a button that
-  stays up for a holder is fine: they see what they already have, and choose from there. To change
-  your own screen for a holder, read `gem.me.passes` ([§11](#11-what-the-player-holds-and-a-vip-door)).
+- **The sheet does not tell you what the player holds.** To change your own screen for a holder,
+  read `gem.me.passes` ([§11](#11-what-the-player-holds-and-a-vip-door)).
+- **A player who already holds a pass may or may not be offered it again.** The Arcade decides,
+  and your game must not assume either. `passOnSale` answers for a holder as it does for anyone:
+  where it is `false`, `showPass` answers `unavailable` / `not_found` and opens nothing.
 - **Hide the button when the pass is not on sale.** `passOnSale(slug)` says so, and is `false`
-  where the store is off, for a player the platform won't sell it to, once the player has declined
-  its sheet twice today, and on an older Arcade. A pass that is not on sale answers
-  `unavailable` / `not_found`, and the player would have pressed a button that does nothing.
+  where the store is off, for a player the platform won't sell it to, and on an older Arcade. A
+  player closing its sheet never takes it off sale. A pass that is not on sale answers
+  `unavailable` / `not_found`, and the player would have pressed a button that does nothing. To
+  test as a VIP holder before VIP is on sale, give yourself VIP with gemctl
+  ([§11](#testing-what-a-vip-player-sees)).
 - **Read `showOfferAvailable`, not `available`.** An older Arcade can sell through `purchase` and
   still not draw this sheet. It answers `unavailable` / `unsupported` and sends nothing. Hide the
   button there.
@@ -351,9 +354,10 @@ Pick by who can say what the offer is:
 Every rule of `purchase` holds ([§9](#9-buying-from-the-arcade-store)), and the answers are the
 same, with one addition. `declined` / `cancelled` also covers the player leaving the sheet without
 pressing Buy, and you are not told which of the two they closed. Nothing backs off: the player's
-next press on either button opens it again. A pass is the exception: after the player declines its
-sheet **twice in a day**, the Arcade stops offering it to them until tomorrow, and `passOnSale`
-answers `false`. Your game cannot reset that count.
+next press on either button opens it again. That holds for a pass too: **there is no limit on how
+often your game opens a pass's sheet**, and a player closing it any number of times leaves
+`passOnSale` and `upsells` as they were. The Arcade records how often each pass sheet is opened in
+your game and how long it stays open, for reporting; it never uses that to stop an offer.
 
 ### A pass, by its slug: `showPass`
 
@@ -376,7 +380,8 @@ something:
   answers `ok` like anyone else.
 - **After a paid sheet it waits a little.** It reads `gem.me.passes` for about ten seconds before it
   settles for `pending`, because the payment provider's notice can trail the checkout.
-- **A player who already holds the pass** sees how long they have left and can add time.
+- **A player who already holds the pass** may or may not be offered it again. Where they are not,
+  the answer is `unavailable` / `not_found`, as for any pass that is not on sale to the player.
 
 ### At a reward: the VIP extra roll
 
@@ -393,7 +398,7 @@ openButton.onclick = async () => {
   const upsell = preview.upsells[0];
   if (upsell) {
     // "VIP: +1 roll, 45 Coins" — upsell.name, and the extras locked, never what a roll would land on.
-    const choice = await vipCard.ask(upsell); // Get VIP and Continue, with equal weight
+    const choice = await vipCard.ask(upsell); // Get VIP, or Continue
     if (choice === 'get') await gem.store.showPass(upsell.pass);
     openButton.focus(); // focus goes back where it was
   }
@@ -403,11 +408,11 @@ openButton.onclick = async () => {
 ```
 
 `upsells` is already empty wherever no upsell may be shown: for a minor, a store that is off, a pass
-the player declined twice today or already holds, and a claim no pass would change. So an empty
-list means draw no card. **Upsell only before the grant**, once per reward moment: the platform
-holds nothing back, so a pass bought afterwards cannot reach a chest already opened.
+the player already holds, and a claim no pass would change. A player declining a pass's sheet does
+not empty it. So an empty list means draw no card. **The offer comes before the grant**: the
+platform holds nothing back, so a pass bought afterwards cannot reach a chest already opened.
 [inventory-and-catalogs.md](inventory-and-catalogs.md#offering-vip-before-a-reward-the-upsell) has
-the rest of the rules, every one a must, and `bonuses` in full.
+how the upsell works, the one rule for it (disclose a bonus roll's odds), and `bonuses` in full.
 
 ## 11. What the player holds, and a VIP door
 
@@ -416,7 +421,7 @@ const passes = await gem.me.passes.list();
 // [{ pass: 'vip', held: true, daysLeft: 7, endsAt: '2026-11-29T12:34:56Z' }]
 
 const vip = await gem.me.passes.get('vip'); // one pass by its slug
-if (vip.held) drawVipBadge(vip.daysLeft === 7 ? '7+ days left' : `${vip.daysLeft} days left`);
+if (vip.held) drawVipBadge(vip.daysLeft < 7 ? `VIP · ${vip.daysLeft} days left` : 'VIP');
 ```
 
 `gem.me.passes` says which store passes the player holds. **VIP is the pass `vip`**, its offering
@@ -428,8 +433,9 @@ slug. Key on the slug, which is stable and not localized, and never on a display
 - **A pass is a slug, whether it is held, and how many days it has left.** No price, no name, no
   perks, nothing about how the player got it, and nothing about a pass that has ended.
 - **`daysLeft` is whole days, rounded up and capped at 7**: `7` means "7 or more", and is also what
-  a pass held with no end reads (support can grant one). `0` when it is not held. Show `7` as
-  "7+ days left", never as a date.
+  a pass held with no end reads (support can grant one). `0` when it is not held. **`7` is not a
+  week's notice:** a pass can read `7` for as long as it is held, and a lower count can rise again.
+  Show a count only below `7`, or show `7` as "7+ days left". Never show a date.
 - **`endsAt` is deprecated.** It is the exact end, to the second, and two games could match that
   value to link one player's accounts, so the platform will stop sending it. Use `daysLeft`.
 - **A guest holds nothing.** When the Arcade says the player is a guest, every pass reads
@@ -579,6 +585,26 @@ export default defineServer((gem) => ({
 `gem.match.playerBoost(playerId)` reads the player's Boost for **display** — "2x Coins" on a results
 screen — never for a decision.
 
+### Testing what a VIP player sees
+
+VIP may not be on sale where you test yet, so `passOnSale('vip')` reads `false` and you cannot buy
+it to test your door, badge or upsell. Give it instead, for 1 to 30 days, with gemctl:
+
+```sh
+gemctl org test-accounts pass grant <org-id> me vip --days 7            # your own account
+gemctl org test-accounts pass grant <org-id> "Playtest 3" vip --days 7  # one of the org's test accounts
+```
+
+- **You need the Contributor role or above** in the organization. `me` reaches your own account and
+  no one else's; any other name is one of the organization's test accounts.
+- **It is not a purchase.** VIP held this way reads like a bought one in `gem.me.passes`,
+  `gem.match.playerPasses` and a `holds_pass` requirement, but no purchase is recorded, it is never
+  revenue, and nothing renews it: it ends after the days you gave.
+- **One VIP at a time per account.** An account that already holds VIP, granted or bought, is
+  refused until it ends. The organization's audit log records every grant.
+- **A personal access token is refused:** sign in to gemctl as yourself.
+  `gemctl org test-accounts pass grant --help` has the rest.
+
 ## 12. Outcomes and reasons
 
 | Call              | `ok`                      | `declined`          | `unavailable`                                                                                                 |