Reading and changing a subscription

curl -sS "$BASE/api/subscriptions/SUB_1757155200_A1B2C3D4" \
  -H "X-Game-Secret-Key: $GAME_SECRET"

const sub = await invo.subscriptions.get("SUB_1757155200_A1B2C3D4");
// sub.status, sub.paidThrough (entitlement), sub.currentPeriodEnd (billing window, NOT entitlement)

const { status, json } = await invo("GET", "/api/subscriptions/SUB_1757155200_A1B2C3D4");
if (status === 200) {
  const sub = json.subscription;
  const entitledUntil = sub.paid_through;      // null until something has been paid
}

sub = invo.subscriptions.get("SUB_1757155200_A1B2C3D4")
# sub.status, sub.paid_through (entitlement), sub.current_period_end (billing window, NOT entitlement)

status, res = invo("GET", "/api/subscriptions/SUB_1757155200_A1B2C3D4")
if status == 200:
    sub = res["subscription"]
    entitled_until = sub["paid_through"]        # None until something has been paid

curl -sS "$BASE/api/subscriptions/player?player_email=member%40example.com&status=live" \
  -H "X-Game-Secret-Key: $GAME_SECRET"

const page = await invo.subscriptions.listForPlayer("member@example.com", {
  status: ["live"],           // or ["live", "canceled"], or omit for all
  limit: 50,
  offset: 0,
});
// page.subscriptions, page.pagination.hasMore

const qs = new URLSearchParams({ player_email: "member@example.com", status: "live", limit: "50", offset: "0" });
const { json } = await invo("GET", "/api/subscriptions/player?" + qs);
const live = json.subscriptions;                 // [] for a player who does not exist yet

page = invo.subscriptions.list_for_player("member@example.com", status=["live"], limit=50, offset=0)
# page.subscriptions, page.pagination.has_more

_, res = invo("GET", "/api/subscriptions/player",
              params={"player_email": "member@example.com", "status": "live", "limit": 50, "offset": 0})
live = res["subscriptions"]                      # [] for a player who does not exist yet

curl -sS -X POST "$BASE/api/subscriptions/SUB_1757155200_A1B2C3D4/cancel" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"at_period_end": true, "reason": "member request"}'

const res = await invo.subscriptions.cancel("SUB_1757155200_A1B2C3D4", {
  atPeriodEnd: true,                // false ends it now
  reason: "member request",
});
revokeAt(res.subscription.subscriptionId, res.accessUntil);
if (res.terminatedImmediately) {
  // nothing had been paid, so at-period-end was downgraded to immediate (res.downgradeReason)
}

const { status, json } = await invo("POST", "/api/subscriptions/SUB_1757155200_A1B2C3D4/cancel", {
  at_period_end: true,
  reason: "member request",
});
if (status === 200) {
  revokeAt(json.subscription.subscription_id, json.access_until);
  if (json.already_canceled) { /* json.final_status; nothing changed */ }
  if (json.terminated_immediately) { /* json.downgrade_reason === "NO_PAID_PERIOD" */ }
}

res = invo.subscriptions.cancel("SUB_1757155200_A1B2C3D4", at_period_end=True, reason="member request")
revoke_at(res.subscription.subscription_id, res.access_until)
if res.terminated_immediately:
    pass   # nothing had been paid; at-period-end was downgraded (res.downgrade_reason)

status, res = invo("POST", "/api/subscriptions/SUB_1757155200_A1B2C3D4/cancel",
                   {"at_period_end": True, "reason": "member request"})
if status == 200:
    revoke_at(res["subscription"]["subscription_id"], res["access_until"])
    if res.get("already_canceled"):
        pass   # res["final_status"]; nothing changed
    if res.get("terminated_immediately"):
        pass   # res["downgrade_reason"] == "NO_PAID_PERIOD"

curl -sS -X POST "$BASE/api/subscriptions/SUB_1757155200_A1B2C3D4/amount" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": "14.99"}'

const res = await invo.subscriptions.changeAmount("SUB_1757155200_A1B2C3D4", "14.99");
// res.changeQueued, res.appliesFromPeriodSeq; the current window still bills at res.oldAmountUsd

const { status, json } = await invo("POST", "/api/subscriptions/SUB_1757155200_A1B2C3D4/amount",
  { amount_usd: "14.99" });
if (status === 409 && json.error_code === "STEAM_REAUTHORIZATION_REQUIRED") {
  // Steam: start a new subscription at json.requested_amount_usd, then cancel this one
}

res = invo.subscriptions.change_amount("SUB_1757155200_A1B2C3D4", "14.99")
# res.change_queued, res.applies_from_period_seq; the current window still bills at res.old_amount_usd

status, res = invo("POST", "/api/subscriptions/SUB_1757155200_A1B2C3D4/amount", {"amount_usd": "14.99"})
if status == 409 and res.get("error_code") == "STEAM_REAUTHORIZATION_REQUIRED":
    pass   # Steam: start a new subscription at res["requested_amount_usd"], then cancel this one

curl -sS -X POST "$BASE/api/subscriptions/SUB_1757155200_A1B2C3D4/payment-method" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"player_card_id": 42, "wallet_only": false}'

// attach (or replace) the card; also converts a wallet-only subscription
const res = await invo.subscriptions.setPaymentMethod("SUB_1757155200_A1B2C3D4", { playerCardId: 42 });

// or make an existing card subscription wallet-only from the next charge
await invo.subscriptions.setPaymentMethod("SUB_1757155200_A1B2C3D4", { walletOnly: true });

const { status, json } = await invo("POST", "/api/subscriptions/SUB_1757155200_A1B2C3D4/payment-method",
  { player_card_id: 42, wallet_only: false });
if (status === 200) { /* json.replaced, json.card */ }
else if (json.error_code === "NOT_A_CARD_SUBSCRIPTION") { /* Steam subscription */ }

res = invo.subscriptions.set_payment_method("SUB_1757155200_A1B2C3D4", player_card_id=42)
# or: invo.subscriptions.set_payment_method("SUB_...", wallet_only=True)

status, res = invo("POST", "/api/subscriptions/SUB_1757155200_A1B2C3D4/payment-method",
                   {"player_card_id": 42, "wallet_only": False})
if status == 200:
    pass   # res["replaced"], res["card"]
elif res.get("error_code") == "NOT_A_CARD_SUBSCRIPTION":
    pass   # Steam subscription