vairified 0.4.0 → 0.6.0

package/README.md

@@ -52,7 +52,7 @@ Every operation lives on a sub-resource that mirrors the REST path:
 
 | Sub-resource            | Operations                                                       |
 |-------------------------|------------------------------------------------------------------|
-| `client.members`        | `get`, `getBulk`, `search`, `find`, `ratingUpdates`              |
+| `client.members`        | `get`, `getBulk`, `getByEmail`, `search`, `find`, `ratingUpdates` |
 | `client.matches`        | `submit`, `tournamentImport`, `testWebhook`                      |
 | `client.oauth`          | `authorize`, `exchangeToken`, `refresh`, `revoke`                |
 | `client.webhooks`       | `deliveries`                                                     |
@@ -100,6 +100,34 @@ const pb = await client.members.getBulk([4873327], { sport: 'pickleball' });
 
 Unknown IDs are silently omitted — the returned array may be shorter than the input.
 
+### Look members up by email
+
+Resolve up to 100 members by their **exact** email address — useful for linking
+your users to their VAIR identity when you hold their email but not their member
+ID, instead of waiting for each player to complete SSO:
+
+```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);
+}
+
+// Read notFound directly — don't diff your input against the results
+console.log('no VAIR account found for:', result.notFound);
+```
+
+Requires the **`key:player:lookup`** scope, granted per partner on approval —
+holding `key:player:search` does not imply it. Ask VAIR to enable it for your app.
+
+Unlike `getBulk`, **nothing is silently dropped**: every address you supply comes
+back in either `matched` or `notFound`. Matching is exact and case-insensitive
+(no partial or fuzzy matching), and `match.members` is an array because an email
+is not a unique key in VAIR — use `.sole` or check `.isAmbiguous` rather than
+assuming a single result. A `notFound` address is not proof the person has no VAIR
+account: unclaimed imported records are excluded from this lookup.
+
 ### Filter ratings to specific sports
 
 ```ts

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. */
@@ -519,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;
@@ -537,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);
@@ -584,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;
@@ -632,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 */
@@ -773,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.
    *
@@ -1011,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;
@@ -1138,6 +1503,11 @@ 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 ?? readEnv("VAIRIFIED_API_KEY") ?? "";
@@ -1170,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.
@@ -1213,7 +1584,9 @@ var Vairified = class {
   MatchBatchResult,
   MatchesResource,
   Member,
+  MemberEmailMatch,
   MemberSportMap,
+  MembersByEmailResult,
   MembersResource,
   NotFoundError,
   OAuthError,