vairified 0.3.1 → 0.4.0

package/README.md

@@ -69,12 +69,13 @@ const member = await client.members.get('vair_mem_xxx');
 console.log(member.name);                      // Full name
 console.log(member.displayName);                // "Mike B."
 console.log(member.ratingFor('pickleball'));    // 3.915
-console.log(member.status.isVairified);         // true
+console.log(member.sport.get('pickleball')?.isVairified);   // true (per-sport)
 
 // Dict-like access to rating splits for a specific sport
 const pb = member.sport.get('pickleball');
 if (pb) {
   console.log(pb.rating, pb.abbr);              // 3.915 VO
+  console.log(pb.isVairified, pb.isVairPro);    // per-sport status flags
   console.log(pb.get('overall-open')?.rating);  // 3.915
   console.log(pb.has('singles-open'));          // true
   for (const [key, split] of pb) {
@@ -357,6 +358,60 @@ export VAIRIFIED_ENV="staging"   # optional; default: production
 const client = new Vairified();   // reads both env vars
 ```
 
+## React Native
+
+The SDK keeps its **zero-dependency** promise on React Native too — it doesn't bundle
+any polyfills. Instead it feature-detects the platform primitives it needs and expects
+your app to provide the two that Hermes lacks.
+
+### Required polyfills
+
+Install them and import each **once, at your app entry** (e.g. the top of `index.js`),
+before any SDK call:
+
+```bash
+npm install react-native-get-random-values react-native-url-polyfill
+```
+
+```ts
+// index.js — must run before `import { Vairified } from 'vairified'`
+import 'react-native-get-random-values'; // Web Crypto for generateState()
+import 'react-native-url-polyfill/auto';  // WHATWG URL / URLSearchParams
+```
+
+- **`react-native-get-random-values`** backs `crypto.getRandomValues`, which
+  `generateState()` uses for CSRF tokens. Without it, `generateState()` throws a
+  descriptive error (not a bare `ReferenceError`); you can also skip it and pass your
+  own high-entropy `state` string to `oauth.authorize()`.
+- **`react-native-url-polyfill`** provides a complete `URL`/`URLSearchParams`. Hermes'
+  built-ins are incomplete, so request-URL and authorization-URL building need this.
+
+### Pass `apiKey` and `env` explicitly
+
+React Native has no `process.env`, so the `VAIRIFIED_API_KEY` / `VAIRIFIED_ENV` fallbacks
+never resolve there (the SDK guards against the missing global rather than crashing).
+Always construct the client explicitly:
+
+```ts
+const client = new Vairified({ apiKey: 'vair_pk_xxx', env: 'production' });
+```
+
+### Token topology — never ship the API key in the app
+
+The secret partner API key (`X-API-Key`) **must never ship in a mobile app binary**.
+Split the OAuth flow across the app and your backend:
+
+1. **App:** open the authorization URL using your public `client_id` (your `PartnerApp`
+   slug) — build it with `getAuthorizationUrl({ redirectUri, clientId })` — and capture
+   the `myapp://callback` deep link to read the `code` (and `state`).
+2. **Your backend:** perform the code exchange there with a `Vairified` client that holds
+   the secret key — `client.oauth.exchangeToken({ code, redirectUri })`, and likewise
+   `refresh()` / `revoke()`. The SDK injects `X-API-Key` on these calls, so they belong
+   on the server, never in the app.
+
+The app sends the captured `code` to your backend over your own authenticated channel;
+the backend returns only the resulting access token (or a session) to the app.
+
 ## Error Handling
 
 The SDK maps HTTP status codes to typed exceptions. All typed exceptions inherit from
@@ -410,7 +465,8 @@ member.displayName                // "Mike B."
 member.firstName / lastName
 member.gender                     // 'MALE' | 'FEMALE' | 'OTHER' | 'UNKNOWN' | null
 member.age / city / state / zip / country
-member.status.isVairified         // grouped status flags
+member.status.isWheelchair        // global status flags
+member.status.isAmbassador
 member.status.isConnected
 member.sport                      // MemberSportMap
 member.sports                     // readonly string[] of sport codes
@@ -418,12 +474,19 @@ member.ratingFor('pickleball')    // number | null
 member.split('overall-open')      // RatingSplitWire | null
 ```
 
+VAIRification & VAIR-Pro status are **per-sport** — read them off each
+`member.sport` entry, not `member.status` (see `SportRating` below).
+
 ### `SportRating` (dict-like)
 
 ```ts
 const pb = member.sport.get('pickleball');
 pb?.rating              // Primary rating for this sport
 pb?.abbr                // "VO", "VG", etc.
+pb?.isVairified         // per-sport VAIRified flag (Vairified#783)
+pb?.isRater             // per-sport rater flag
+pb?.isVairPro           // per-sport VAIR-Pro flag
+pb?.isVairProStatus     // 'PENDING' | 'ACTIVE' | null
 pb?.get('overall-open') // Any split key
 pb?.size                // Number of splits
 pb?.has('singles-40+')  // Membership check
@@ -432,6 +495,16 @@ for (const [key, split] of pb ?? []) { /* iterate */ }
 
 ## Migrating
 
+**From 0.3.x → 0.4.0 (breaking):** VAIRification & VAIR-Pro status are now
+**per-sport** (Vairified#783). `isVairified`, `isRater`, `isVairPro`, and
+`isVairProStatus` moved off the member `status` object onto each per-sport
+entry — read them via `member.sport.get(code)?.isVairified` instead of
+`member.status.isVairified`. The `status` object keeps only the genuinely
+global flags (`isWheelchair`, `isAmbassador`, `isConnected`). This mirrors
+the backend: a player can be VAIRified / a VAIR Pro in one sport but not
+another. Publish only after the backend #788 reaches production — against
+the old prod shape the per-sport flags default to `false`/`null`.
+
 **From 0.2.x → 0.3.0:** All OAuth scope strings gained a `user:` prefix
 (`profile:read` → `user:profile:read`). Update any hardcoded scope arrays.
 New: `members.getBulk()`, `matches.tournamentImport()`, `webhooks.deliveries()`.

package/dist/index.cjs

@@ -419,10 +419,22 @@ var SportRating = class {
   rating;
   /** Category abbreviation for the primary rating (e.g. `'VO'`). */
   abbr;
+  /** Player is VAIRified in this sport (has a verified, non-recreational rating). */
+  isVairified;
+  /** Player is an active VAIR Pro (can rate) in this sport. Alias of {@link isVairPro}. */
+  isRater;
+  /** Player is an active VAIR Pro (can rate) in this sport. */
+  isVairPro;
+  /** VAIR-Pro lifecycle status in this sport (`'ACTIVE'` / `'PENDING'` / `null`). */
+  isVairProStatus;
   #splits;
   constructor(wire) {
     this.rating = wire.rating;
     this.abbr = wire.abbr;
+    this.isVairified = wire.isVairified ?? false;
+    this.isRater = wire.isRater ?? false;
+    this.isVairPro = wire.isVairPro ?? false;
+    this.isVairProStatus = wire.isVairProStatus ?? null;
     this.#splits = new Map(Object.entries(wire.ratingSplits ?? {}));
     Object.freeze(this);
   }
@@ -655,7 +667,7 @@ var MembersResource = class {
    * ```
    */
   async get(playerId, options = {}) {
-    const query = { id: playerId };
+    const query = { memberId: playerId };
     if (options.sport !== void 0) {
       query.sport = Array.isArray(options.sport) ? options.sport.join(",") : options.sport;
     }
@@ -846,9 +858,12 @@ function getAuthorizationUrl(config, options = {}) {
   const scopeList = ensureProfileRead(options.scopes ?? DEFAULT_SCOPES);
   const params = new URLSearchParams({
     redirect_uri: config.redirectUri,
-    scope: scopeList.join(","),
+    scope: scopeList.join(" "),
     response_type: "code"
   });
+  if (config.clientId) {
+    params.set("client_id", config.clientId);
+  }
   if (options.state) {
     params.set("state", options.state);
   }
@@ -870,13 +885,31 @@ function describeScopes(scopes) {
   }));
 }
 function generateState() {
-  const bytes = new Uint8Array(32);
-  crypto.getRandomValues(bytes);
-  let binary = "";
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte);
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto?.getRandomValues !== "function") {
+    throw new Error(
+      "generateState() needs Web Crypto (crypto.getRandomValues), which is unavailable in this runtime. Node 19+ and browsers have it built in; on React Native / Hermes, install 'react-native-get-random-values' and import it once at your app entry before using the SDK \u2014 or pass your own high-entropy `state` string to oauth.authorize()."
+    );
   }
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  const bytes = new Uint8Array(32);
+  webCrypto.getRandomValues(bytes);
+  return base64UrlNoPad(bytes);
+}
+var B64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function base64UrlNoPad(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] ?? 0;
+    const b1 = bytes[i + 1] ?? 0;
+    const b2 = bytes[i + 2] ?? 0;
+    const hasB1 = i + 1 < bytes.length;
+    const hasB2 = i + 2 < bytes.length;
+    out += B64URL_ALPHABET[b0 >> 2] ?? "";
+    out += B64URL_ALPHABET[(b0 & 3) << 4 | b1 >> 4] ?? "";
+    if (hasB1) out += B64URL_ALPHABET[(b1 & 15) << 2 | b2 >> 6] ?? "";
+    if (hasB2) out += B64URL_ALPHABET[b2 & 63] ?? "";
+  }
+  return out;
 }
 function ensureProfileRead(scopes) {
   if (scopes.includes("user:profile:read")) {
@@ -909,13 +942,13 @@ var OAuthResource = class {
       method: "POST",
       path: "/partner/oauth/authorize",
       body: {
-        redirectUri: options.redirectUri,
-        scope: scopeList.join(","),
+        redirect_uri: options.redirectUri,
+        scope: scopeList.join(" "),
         state: options.state
       }
     });
     return {
-      authorizationUrl: data?.authorizationUrl ?? "",
+      authorizationUrl: data?.authorization_url ?? "",
       code: data?.code ?? "",
       state: options.state
     };
@@ -925,7 +958,13 @@ var OAuthResource = class {
     const data = await this.#http.request({
       method: "POST",
       path: "/partner/oauth/token",
-      body: { code: options.code, redirectUri: options.redirectUri }
+      // RFC 6749 §4.1.3 — the endpoint requires `grant_type` and the
+      // snake_case `redirect_uri` (which must match the authorize request).
+      body: {
+        grant_type: "authorization_code",
+        code: options.code,
+        redirect_uri: options.redirectUri
+      }
     });
     return tokenResponseFromWire(data);
   }
@@ -934,7 +973,8 @@ var OAuthResource = class {
     const data = await this.#http.request({
       method: "POST",
       path: "/partner/oauth/refresh",
-      body: { refreshToken }
+      // RFC 6749 §6 — refresh grant, snake_case body.
+      body: { grant_type: "refresh_token", refresh_token: refreshToken }
     });
     return tokenResponseFromWire(data);
   }
@@ -943,7 +983,7 @@ var OAuthResource = class {
     const data = await this.#http.request({
       method: "POST",
       path: "/partner/oauth/revoke",
-      body: { playerId }
+      body: { player_id: playerId }
     });
     return data ?? {};
   }
@@ -961,13 +1001,13 @@ var OAuthResource = class {
 };
 function tokenResponseFromWire(data) {
   const scopeRaw = data?.scope ?? "";
-  const scopeList = scopeRaw.length > 0 ? scopeRaw.split(",") : [];
+  const scopeList = scopeRaw.length > 0 ? scopeRaw.split(/\s+/).filter(Boolean) : Array.isArray(data?.scopes) ? data.scopes : [];
   return {
-    accessToken: data?.accessToken ?? "",
-    refreshToken: data?.refreshToken ?? null,
-    expiresIn: data?.expiresIn ?? 3600,
+    accessToken: data?.access_token ?? "",
+    refreshToken: data?.refresh_token ?? null,
+    expiresIn: data?.expires_in ?? 3600,
     scope: Object.freeze(scopeList),
-    playerId: data?.playerId ?? ""
+    playerId: data?.player_id ?? ""
   };
 }
 
@@ -1071,6 +1111,14 @@ var ENVIRONMENTS = Object.freeze({
   local: "http://localhost:3001/api/v1"
 });
 var DEFAULT_TIMEOUT_MS = 3e4;
+function readEnv(name) {
+  try {
+    if (typeof process === "undefined") return void 0;
+    return process.env?.[name];
+  } catch {
+    return void 0;
+  }
+}
 var Vairified = class {
   /** The resolved API key this client is using. */
   apiKey;
@@ -1092,7 +1140,7 @@ var Vairified = class {
   webhooks;
   #transport;
   constructor(options = {}) {
-    const apiKey = options.apiKey ?? process.env.VAIRIFIED_API_KEY ?? "";
+    const apiKey = options.apiKey ?? readEnv("VAIRIFIED_API_KEY") ?? "";
     if (apiKey.length === 0) {
       throw new Error("API key required. Pass { apiKey } or set VAIRIFIED_API_KEY.");
     }
@@ -1101,7 +1149,7 @@ var Vairified = class {
       this.baseUrl = options.baseUrl.replace(/\/+$/, "");
       this.env = options.env ?? "production";
     } else {
-      const envName = options.env ?? process.env.VAIRIFIED_ENV ?? "production";
+      const envName = options.env ?? readEnv("VAIRIFIED_ENV") ?? "production";
       if (options.env && !(envName in ENVIRONMENTS)) {
         throw new Error(
           `Unknown environment: ${envName}. Use one of: ${Object.keys(ENVIRONMENTS).join(", ")}`