vairified 0.3.2 → 0.6.0

package/dist/index.cjs

@@ -27,7 +27,9 @@ __export(index_exports, {
   MatchBatchResult: () => MatchBatchResult,
   MatchesResource: () => MatchesResource,
   Member: () => Member,
+  MemberEmailMatch: () => MemberEmailMatch,
   MemberSportMap: () => MemberSportMap,
+  MembersByEmailResult: () => MembersByEmailResult,
   MembersResource: () => MembersResource,
   NotFoundError: () => NotFoundError,
   OAuthError: () => OAuthError,
@@ -307,6 +309,19 @@ var TournamentImportResult = class {
   dryRun;
   message;
   errors;
+  /**
+   * Public member ids for the ghost players THIS import created, keyed by the
+   * `ref` supplied in `ghostMembers[]`.
+   *
+   * Empty on a dry-run, and empty for entries the import matched to a player who
+   * already existed — resolving an existing email to a member requires the
+   * `key:player:lookup` scope and `members.getByEmail()`.
+   *
+   * Use these ids directly in a follow-up `matches.submit()`; without them an
+   * import reports only how many accounts it caused and you cannot address any
+   * of them.
+   */
+  createdGhostMembers;
   /** @internal */
   constructor(wire) {
     this.success = wire.success;
@@ -317,6 +332,11 @@ var TournamentImportResult = class {
     this.dryRun = wire.dryRun ?? false;
     this.message = wire.message;
     this.errors = Object.freeze(wire.errors ?? []);
+    this.createdGhostMembers = Object.freeze(
+      (wire.createdGhostMembers ?? []).map(
+        (entry) => Object.freeze({ ref: entry.ref, memberId: entry.memberId })
+      )
+    );
     Object.freeze(this);
   }
   /** True when the import succeeded without errors. */
@@ -419,10 +439,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);
   }
@@ -507,6 +539,20 @@ var Member = class {
   state;
   zip;
   country;
+  /**
+   * The DATE this member's VAIR account was created (`YYYY-MM-DD`, UTC), or
+   * `null` when the endpoint does not supply it.
+   *
+   * Present on `members.get()`, `members.getBulk()` and `members.getByEmail()` —
+   * the calls where you already know which member you asked about. **Never on
+   * `members.search()`**, which is discovery: account age is not something you
+   * can browse strangers by.
+   *
+   * Deliberately a date, not a timestamp. It exists so you can apply a
+   * new-accounts-only referral rule — crediting an ambassador only for accounts
+   * created because of their event.
+   */
+  memberSince;
   gender;
   status;
   sport;
@@ -525,6 +571,7 @@ var Member = class {
     this.state = wire.state ?? null;
     this.zip = wire.zip ?? null;
     this.country = wire.country ?? null;
+    this.memberSince = wire.memberSince ?? null;
     this.gender = wire.gender ?? null;
     this.status = Object.freeze({ ...wire.status });
     this.sport = new MemberSportMap(wire.sport);
@@ -572,6 +619,70 @@ var Member = class {
   }
 };
 
+// src/models/members-by-email-result.ts
+var MemberEmailMatch = class {
+  /** The address exactly as you supplied it, not as stored. */
+  email;
+  /** Every member holding this address. Never empty. */
+  members;
+  /** @internal */
+  constructor(wire) {
+    this.email = wire.email;
+    this.members = Object.freeze(wire.members.map((m) => new Member(m)));
+    Object.freeze(this);
+  }
+  /**
+   * The single member for this address, or `null` when the address is
+   * ambiguous (more than one match).
+   *
+   * Use this rather than `members[0]` when a wrong link is worse than no
+   * link — it refuses to guess instead of silently picking one.
+   */
+  get sole() {
+    return this.members.length === 1 ? this.members[0] ?? null : null;
+  }
+  /** Whether this address resolved to more than one member. */
+  get isAmbiguous() {
+    return this.members.length > 1;
+  }
+  toString() {
+    return `MemberEmailMatch ${this.email} -> ${this.members.length} member(s)`;
+  }
+};
+var MembersByEmailResult = class {
+  matched;
+  /** Addresses that resolved to nothing, echoed as you supplied them. */
+  notFound;
+  /** @internal */
+  constructor(wire) {
+    this.matched = Object.freeze(wire.matched.map((m) => new MemberEmailMatch(m)));
+    this.notFound = Object.freeze([...wire.notFound]);
+    Object.freeze(this);
+  }
+  /**
+   * Look up one address's match, case-insensitively.
+   *
+   * Saves callers a linear scan and, more importantly, saves them from
+   * matching case-sensitively against an address the server echoed back
+   * in whatever case they originally sent.
+   */
+  get(email) {
+    const needle = email.trim().toLowerCase();
+    return this.matched.find((m) => m.email.toLowerCase() === needle) ?? null;
+  }
+  /** Whether every requested address resolved to at least one member. */
+  get allResolved() {
+    return this.notFound.length === 0;
+  }
+  /** Total number of members across every matched address. */
+  get memberCount() {
+    return this.matched.reduce((n, m) => n + m.members.length, 0);
+  }
+  toString() {
+    return `MembersByEmailResult matched=${this.matched.length} notFound=${this.notFound.length}`;
+  }
+};
+
 // src/models/rating-update.ts
 var RatingUpdate = class {
   memberId;
@@ -620,6 +731,7 @@ var RatingUpdate = class {
 // src/resources/members.ts
 var DEFAULT_PAGE_SIZE = 20;
 var MAX_PAGE_SIZE = 100;
+var MAX_EMAILS_PER_LOOKUP = 100;
 var MembersResource = class {
   #http;
   /** @internal */
@@ -761,6 +873,70 @@ var MembersResource = class {
     });
     return rows.map((row) => new Member(row));
   }
+  /**
+   * Resolve up to 100 members by their **exact** email address.
+   *
+   * Use this to link your users to their VAIR identity when you hold
+   * their email but not their member ID — e.g. resolving a tournament
+   * roster at registration instead of waiting for each player to
+   * complete SSO.
+   *
+   * **Requires the `key:player:lookup` scope**, which is granted per
+   * partner on approval. Holding `key:player:search` does not imply it.
+   *
+   * Matching is exact and case-insensitive; there is deliberately no
+   * partial, prefix or fuzzy matching. Every address you supply comes
+   * back in either `matched` or `notFound`, so read `notFound` directly
+   * instead of diffing your input against the results.
+   *
+   * A `notFound` address is **not** proof the person has no VAIR
+   * account — unclaimed imported records are excluded from this lookup.
+   *
+   * @param emails - Email addresses to resolve (max 100).
+   * @param options - Optional filters.
+   * @param options.sport - Sport code to scope ratings (e.g. `'pickleball'`).
+   * @throws {@link ValidationError} If more than 100 addresses are
+   *   provided, or the list is empty.
+   * @category Members
+   *
+   * @example
+   * ```ts
+   * const result = await client.members.getByEmail([
+   *   'ada@example.com',
+   *   'nobody@example.com',
+   * ]);
+   *
+   * for (const match of result.matched) {
+   *   const member = match.sole; // null when the address is ambiguous
+   *   if (member) console.log(match.email, '->', member.memberId);
+   * }
+   *
+   * console.log('no VAIR account found for:', result.notFound);
+   * ```
+   */
+  async getByEmail(emails, options) {
+    if (emails.length === 0) {
+      throw new ValidationError("At least one email address is required");
+    }
+    if (emails.length > MAX_EMAILS_PER_LOOKUP) {
+      throw new ValidationError(`Maximum ${MAX_EMAILS_PER_LOOKUP} email addresses per request`);
+    }
+    const offender = emails.find((e) => e.includes(","));
+    if (offender !== void 0) {
+      throw new ValidationError(`Email address must not contain a comma: ${offender}`);
+    }
+    const query = { emails: emails.join(",") };
+    if (options?.sport) query.sport = options.sport;
+    const wire = await this.#http.request({
+      method: "GET",
+      path: "/partner/members/by-email",
+      query
+    });
+    return new MembersByEmailResult({
+      matched: wire?.matched ?? [],
+      notFound: wire?.notFound ?? []
+    });
+  }
   /**
    * Poll for rating change notifications.
    *
@@ -873,13 +1049,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")) {
@@ -981,6 +1175,207 @@ function tokenResponseFromWire(data) {
   };
 }
 
+// src/models/attribution.ts
+var MemberAttribution = class {
+  memberId;
+  /** True when some ambassador already holds credit for this member. */
+  attributed;
+  /**
+   * The member id of the ambassador holding the credit.
+   *
+   * Compare it against your own event host's member id to tell "already credited
+   * to my host — nothing to do" from "credited to somebody else — a person needs
+   * to look, because claiming it takes credit from them".
+   *
+   * `null` both when nobody holds credit and when credit is held by a record that
+   * has no member id of its own, so check {@link attributed} to tell those apart.
+   */
+  ambassadorMemberId;
+  /** The date the credit was established (`YYYY-MM-DD`), or `null`. */
+  attributedAt;
+  /** @internal */
+  constructor(wire) {
+    this.memberId = wire.memberId;
+    this.attributed = wire.attributed;
+    this.ambassadorMemberId = wire.ambassadorMemberId ?? null;
+    this.attributedAt = wire.attributedAt ?? null;
+    Object.freeze(this);
+  }
+  /** True when nobody holds credit yet, so this member can be claimed. */
+  get isClaimable() {
+    return !this.attributed;
+  }
+  /** True when credit is held by an ambassador OTHER than the one given. */
+  heldBySomeoneOtherThan(ambassadorMemberId) {
+    return this.attributed && this.ambassadorMemberId !== ambassadorMemberId;
+  }
+};
+var MembersAttributionResult = class {
+  attributions;
+  /**
+   * Member ids that matched no member. Read this rather than diffing your input
+   * against the results — every id you sent lands in one bucket or the other.
+   */
+  notFound;
+  /** @internal */
+  constructor(wire) {
+    this.attributions = Object.freeze(
+      (wire.attributions ?? []).map((a) => new MemberAttribution(a))
+    );
+    this.notFound = Object.freeze([...wire.notFound ?? []]);
+    Object.freeze(this);
+  }
+  /** Attribution for one member id, or `undefined` if it was not returned. */
+  get(memberId) {
+    return this.attributions.find((a) => a.memberId === memberId);
+  }
+  /** Members nobody holds credit for yet. */
+  get claimable() {
+    return this.attributions.filter((a) => a.isClaimable);
+  }
+};
+var AttributionResult = class {
+  /** How many members were newly attributed by this request. */
+  attributed;
+  /** One entry per member id supplied, in the order supplied. */
+  results;
+  /** @internal */
+  constructor(wire) {
+    this.attributed = wire.attributed;
+    this.results = Object.freeze(
+      (wire.results ?? []).map((r) => Object.freeze({ memberId: r.memberId, outcome: r.outcome }))
+    );
+    Object.freeze(this);
+  }
+  /** Member ids with the given outcome. */
+  withOutcome(outcome) {
+    return this.results.filter((r) => r.outcome === outcome).map((r) => r.memberId);
+  }
+  /**
+   * Members already credited to somebody. These are the ones worth a human
+   * look — it may be your own host, or it may be another ambassador.
+   */
+  get alreadyAttributed() {
+    return this.withOutcome("already_attributed");
+  }
+  /**
+   * Members rejected because their account pre-dates the event's registration
+   * page. The event did not recruit them, so no credit is due.
+   */
+  get predatedEvent() {
+    return this.withOutcome("account_predates_event");
+  }
+};
+
+// src/resources/referrals.ts
+var MAX_IDS_PER_READ = 100;
+var MAX_IDS_PER_WRITE = 500;
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+var ReferralsResource = class {
+  #http;
+  /** @internal */
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Who currently earns referral credit for these members.
+   *
+   * Use this before {@link attribute} to tell the two cases apart that matter:
+   * a member already credited to your own event host (nothing to do) and one
+   * credited to a different ambassador (a person should look, because claiming
+   * it takes credit from them).
+   *
+   * @example
+   * ```ts
+   * const result = await client.referrals.get([4873327, 4873328]);
+   *
+   * for (const a of result.claimable) {
+   *   console.log(a.memberId, 'has no credit yet');
+   * }
+   * console.log('no such member:', result.notFound);
+   * ```
+   *
+   * @throws {@link ValidationError} If the list is empty or exceeds 100 ids.
+   */
+  async get(memberIds) {
+    if (memberIds.length === 0) {
+      throw new ValidationError("At least one member id is required");
+    }
+    if (memberIds.length > MAX_IDS_PER_READ) {
+      throw new ValidationError(`Maximum ${MAX_IDS_PER_READ} member ids per request`);
+    }
+    const wire = await this.#http.request({
+      method: "GET",
+      path: "/partner/members/attribution",
+      query: { memberIds: memberIds.join(",") }
+    });
+    return new MembersAttributionResult({
+      attributions: wire?.attributions ?? [],
+      notFound: wire?.notFound ?? []
+    });
+  }
+  /**
+   * Credit an ambassador for players their event recruited.
+   *
+   * `registrationPublishedAt` is the date the event's registration page was
+   * **first published**. Accounts created before it did not come from the event
+   * and are rejected with `account_predates_event`. VAIR applies that rule
+   * itself, so every partner is held to the same one.
+   *
+   * VAIR cannot verify the date — it holds no record of your registration pages —
+   * so the value you send is recorded for audit. Send the real one.
+   *
+   * Safe to retry: attribution is one-per-player forever, enforced by the
+   * database, so a resubmitted player returns `already_attributed` and nothing
+   * changes.
+   *
+   * @example
+   * ```ts
+   * const result = await client.referrals.attribute({
+   *   referralCode: 'hillhurst-open',
+   *   registrationPublishedAt: '2026-08-01',
+   *   memberIds: [4873327, 4873328],
+   * });
+   *
+   * console.log(result.attributed, 'newly credited');
+   * console.log('need a human:', result.alreadyAttributed);
+   * console.log('too old to credit:', result.predatedEvent);
+   * ```
+   *
+   * @throws {@link ValidationError} If the list is empty or exceeds 500 ids, or
+   * the date is not `YYYY-MM-DD`.
+   */
+  async attribute(input) {
+    if (!input.referralCode.trim()) {
+      throw new ValidationError("A referral code is required");
+    }
+    if (!ISO_DATE.test(input.registrationPublishedAt)) {
+      throw new ValidationError(
+        "registrationPublishedAt must be a calendar date formatted YYYY-MM-DD"
+      );
+    }
+    if (input.memberIds.length === 0) {
+      throw new ValidationError("At least one member id is required");
+    }
+    if (input.memberIds.length > MAX_IDS_PER_WRITE) {
+      throw new ValidationError(`Maximum ${MAX_IDS_PER_WRITE} member ids per request`);
+    }
+    const wire = await this.#http.request({
+      method: "POST",
+      path: "/partner/ambassador/attribution",
+      body: {
+        referralCode: input.referralCode.trim(),
+        registrationPublishedAt: input.registrationPublishedAt,
+        memberIds: [...input.memberIds]
+      }
+    });
+    return new AttributionResult({
+      attributed: wire?.attributed ?? 0,
+      results: wire?.results ?? []
+    });
+  }
+};
+
 // src/models/webhook-delivery.ts
 var WebhookDelivery = class {
   id;
@@ -1081,6 +1476,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;
@@ -1100,9 +1503,14 @@ var Vairified = class {
   leaderboard;
   /** Webhook delivery inspection — deliveries. */
   webhooks;
+  /**
+   * Read and record ambassador referral credit. Each method needs its own
+   * per-partner permission — see {@link ReferralsResource}.
+   */
+  referrals;
   #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.");
     }
@@ -1111,7 +1519,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(", ")}`
@@ -1132,6 +1540,7 @@ var Vairified = class {
     this.oauth = new OAuthResource(this.#transport);
     this.leaderboard = new LeaderboardResource(this.#transport);
     this.webhooks = new WebhooksResource(this.#transport);
+    this.referrals = new ReferralsResource(this.#transport);
   }
   /**
    * API usage statistics for the current API key.
@@ -1175,7 +1584,9 @@ var Vairified = class {
   MatchBatchResult,
   MatchesResource,
   Member,
+  MemberEmailMatch,
   MemberSportMap,
+  MembersByEmailResult,
   MembersResource,
   NotFoundError,
   OAuthError,