vairified 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -157,6 +157,7 @@ interface PartnerMemberWire {
     readonly state?: string;
     readonly zip?: string;
     readonly country?: string;
+    readonly memberSince?: string;
     readonly gender?: Gender;
     readonly status: MemberStatusWire;
     readonly sport?: Readonly<Record<string, SportRatingWire>>;
@@ -164,6 +165,30 @@ interface PartnerMemberWire {
     readonly email?: string;
     readonly grantedScopes?: readonly string[];
 }
+/**
+ * One resolved address in a {@link MembersByEmailResultWire}.
+ *
+ * `members` is always an array: an email address is not a unique key in
+ * VAIR, so one address can resolve to more than one member.
+ *
+ * @category Members
+ */
+interface PartnerMemberEmailMatchWire {
+    readonly email: string;
+    readonly members: readonly PartnerMemberWire[];
+}
+/**
+ * Raw envelope returned by `GET /partner/members/by-email`.
+ *
+ * Every requested address appears in exactly one of `matched` or
+ * `notFound` — the endpoint never silently drops one.
+ *
+ * @category Members
+ */
+interface MembersByEmailResultWire {
+    readonly matched: readonly PartnerMemberEmailMatchWire[];
+    readonly notFound: readonly string[];
+}
 /**
  * Raw rating change notification.
  *
@@ -356,6 +381,10 @@ interface PlayerRankOptions {
  *
  * @category Matches
  */
+interface TournamentImportCreatedGhostWire {
+    readonly ref: string;
+    readonly memberId: number;
+}
 interface TournamentImportResultWire {
     readonly success: boolean;
     readonly matchesImported: number;
@@ -365,6 +394,7 @@ interface TournamentImportResultWire {
     readonly dryRun?: boolean;
     readonly message?: string;
     readonly errors?: readonly string[];
+    readonly createdGhostMembers?: readonly TournamentImportCreatedGhostWire[];
 }
 /**
  * Wire shape for a single webhook delivery attempt.
@@ -405,6 +435,24 @@ interface ApiErrorResponse {
     readonly error?: string;
     readonly statusCode?: number;
 }
+type AttributionOutcome = 'attributed' | 'already_attributed' | 'account_predates_event' | 'not_found';
+interface MemberAttributionWire {
+    readonly memberId: number;
+    readonly attributed: boolean;
+    readonly ambassadorMemberId?: number | null;
+    readonly attributedAt?: string;
+}
+interface MembersAttributionResultWire {
+    readonly attributions?: readonly MemberAttributionWire[];
+    readonly notFound?: readonly number[];
+}
+interface AttributionResultWire {
+    readonly attributed: number;
+    readonly results?: readonly {
+        readonly memberId: number;
+        readonly outcome: AttributionOutcome;
+    }[];
+}
 
 /**
  * {@link LeaderboardResource} — read-only leaderboard queries.
@@ -464,6 +512,17 @@ declare class MatchBatchResult {
  * @module
  */
 
+/**
+ * One ghost player created by a tournament import.
+ *
+ * @category Matches
+ */
+interface TournamentImportCreatedGhost {
+    /** The email or phone you supplied for this person in `ghostMembers[]`. */
+    readonly ref: string;
+    /** The public member id allocated to them, usable in `matches.submit()`. */
+    readonly memberId: number;
+}
 /**
  * Result of a tournament import submission.
  *
@@ -478,6 +537,19 @@ declare class TournamentImportResult {
     readonly dryRun: boolean;
     readonly message: string | undefined;
     readonly errors: readonly string[];
+    /**
+     * 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.
+     */
+    readonly createdGhostMembers: readonly TournamentImportCreatedGhost[];
     /** @internal */
     constructor(wire: TournamentImportResultWire);
     /** True when the import succeeded without errors. */
@@ -683,6 +755,20 @@ declare class Member {
     readonly state: string | null;
     readonly zip: string | null;
     readonly country: string | null;
+    /**
+     * 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.
+     */
+    readonly memberSince: string | null;
     readonly gender: Gender | null;
     readonly status: MemberStatusWire;
     readonly sport: MemberSportMap;
@@ -713,6 +799,74 @@ declare class Member {
     toString(): string;
 }
 
+/**
+ * {@link MembersByEmailResult} — result of an email → member lookup.
+ *
+ * @module
+ */
+
+/**
+ * One requested address that resolved to at least one member.
+ *
+ * {@link members} is always an array. An email address is not a unique
+ * key in VAIR — an unclaimed imported record can share an address with a
+ * claimed account — so never assume a single element without checking.
+ *
+ * @category Members
+ */
+declare class MemberEmailMatch {
+    /** The address exactly as you supplied it, not as stored. */
+    readonly email: string;
+    /** Every member holding this address. Never empty. */
+    readonly members: readonly Member[];
+    /** @internal */
+    constructor(wire: PartnerMemberEmailMatchWire);
+    /**
+     * 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(): Member | null;
+    /** Whether this address resolved to more than one member. */
+    get isAmbiguous(): boolean;
+    toString(): string;
+}
+/**
+ * Result of a {@link MembersResource.getByEmail} call.
+ *
+ * Every address you supplied appears in exactly one of {@link matched} or
+ * {@link notFound} — the endpoint never silently drops one, so consume
+ * {@link notFound} directly rather than diffing your input against the
+ * results.
+ *
+ * A `notFound` address is not proof the person has no VAIR account:
+ * unclaimed imported records are deliberately excluded from this lookup.
+ *
+ * @category Members
+ */
+declare class MembersByEmailResult {
+    readonly matched: readonly MemberEmailMatch[];
+    /** Addresses that resolved to nothing, echoed as you supplied them. */
+    readonly notFound: readonly string[];
+    /** @internal */
+    constructor(wire: MembersByEmailResultWire);
+    /**
+     * 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: string): MemberEmailMatch | null;
+    /** Whether every requested address resolved to at least one member. */
+    get allResolved(): boolean;
+    /** Total number of members across every matched address. */
+    get memberCount(): number;
+    toString(): string;
+}
+
 /**
  * {@link RatingUpdate} — a single rating change notification.
  *
@@ -850,6 +1004,50 @@ declare class MembersResource {
     getBulk(ids: number[], options?: {
         sport?: string;
     }): Promise<Member[]>;
+    /**
+     * 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);
+     * ```
+     */
+    getByEmail(emails: readonly string[], options?: {
+        sport?: string;
+    }): Promise<MembersByEmailResult>;
     /**
      * Poll for rating change notifications.
      *
@@ -1050,6 +1248,170 @@ declare class OAuthResource {
     }[]>;
 }
 
+/**
+ * {@link MemberAttribution}, {@link MembersAttributionResult} and
+ * {@link AttributionResult} — ambassador referral credit.
+ *
+ * @module
+ */
+
+/**
+ * Who currently earns referral credit for one member.
+ *
+ * @category Referrals
+ */
+declare class MemberAttribution {
+    readonly memberId: number;
+    /** True when some ambassador already holds credit for this member. */
+    readonly attributed: boolean;
+    /**
+     * 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.
+     */
+    readonly ambassadorMemberId: number | null;
+    /** The date the credit was established (`YYYY-MM-DD`), or `null`. */
+    readonly attributedAt: string | null;
+    /** @internal */
+    constructor(wire: MemberAttributionWire);
+    /** True when nobody holds credit yet, so this member can be claimed. */
+    get isClaimable(): boolean;
+    /** True when credit is held by an ambassador OTHER than the one given. */
+    heldBySomeoneOtherThan(ambassadorMemberId: number): boolean;
+}
+/**
+ * Attribution for a batch of members, plus the ids that matched nothing.
+ *
+ * @category Referrals
+ */
+declare class MembersAttributionResult {
+    readonly attributions: readonly MemberAttribution[];
+    /**
+     * 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.
+     */
+    readonly notFound: readonly number[];
+    /** @internal */
+    constructor(wire: MembersAttributionResultWire);
+    /** Attribution for one member id, or `undefined` if it was not returned. */
+    get(memberId: number): MemberAttribution | undefined;
+    /** Members nobody holds credit for yet. */
+    get claimable(): readonly MemberAttribution[];
+}
+/**
+ * Outcome of submitting attribution for a batch of members.
+ *
+ * @category Referrals
+ */
+declare class AttributionResult {
+    /** How many members were newly attributed by this request. */
+    readonly attributed: number;
+    /** One entry per member id supplied, in the order supplied. */
+    readonly results: readonly Readonly<{
+        memberId: number;
+        outcome: AttributionOutcome;
+    }>[];
+    /** @internal */
+    constructor(wire: AttributionResultWire);
+    /** Member ids with the given outcome. */
+    withOutcome(outcome: AttributionOutcome): readonly number[];
+    /**
+     * 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(): readonly number[];
+    /**
+     * 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(): readonly number[];
+}
+
+/**
+ * {@link ReferralsResource} — read and record ambassador referral credit.
+ *
+ * @module
+ */
+
+/**
+ * Read and record which ambassador earns referral credit for a player.
+ *
+ * Each method needs its own API-key permission, granted per partner:
+ * `key:referral:read` for {@link get} and `key:referral:write` for
+ * {@link attribute}. Neither is implied by a general read, write or admin key —
+ * reading attribution exposes who recruited whom, and writing it decides who
+ * earns commission.
+ *
+ * @category Resources
+ */
+declare class ReferralsResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpTransport);
+    /**
+     * 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.
+     */
+    get(memberIds: readonly number[]): Promise<MembersAttributionResult>;
+    /**
+     * 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`.
+     */
+    attribute(input: {
+        referralCode: string;
+        registrationPublishedAt: string;
+        memberIds: readonly number[];
+    }): Promise<AttributionResult>;
+}
+
 /**
  * {@link WebhookDelivery} and {@link WebhookDeliveriesResult} — webhook
  * delivery inspection models.
@@ -1202,6 +1564,11 @@ declare class Vairified {
     readonly leaderboard: LeaderboardResource;
     /** Webhook delivery inspection — deliveries. */
     readonly webhooks: WebhooksResource;
+    /**
+     * Read and record ambassador referral credit. Each method needs its own
+     * per-partner permission — see {@link ReferralsResource}.
+     */
+    readonly referrals: ReferralsResource;
     constructor(options?: VairifiedOptions);
     /**
      * API usage statistics for the current API key.
@@ -1300,4 +1667,4 @@ declare class OAuthError extends VairifiedError {
     constructor(message?: string, errorCode?: string, response?: unknown);
 }
 
-export { type ApiErrorResponse, AuthenticationError, type AuthorizationResponse, DEFAULT_SCOPES, ENVIRONMENTS, type GameInput, type Gender, type LeaderboardOptions, LeaderboardResource, type MatchBatch, MatchBatchResult, type MatchBatchResultWire, type MatchInput, MatchesResource, Member, MemberSportMap, type MemberStatusWire, MembersResource, NotFoundError, type OAuthConfig, OAuthError, OAuthResource, type OAuthScope, type PartnerMemberWire, type PartnerRatingUpdateWire, type PlayerRankOptions, RateLimitError, type RatingSplitWire, RatingUpdate, SCOPES, type SearchFilters, SportRating, type SportRatingWire, type TokenResponse, TournamentImportResult, type TournamentImportResultWire, Vairified, type VairifiedEnvironment, VairifiedError, type VairifiedOptions, ValidationError, WebhookDeliveriesResult, type WebhookDeliveriesResultWire, WebhookDelivery, type WebhookDeliveryWire, WebhooksResource, describeScope, describeScopes, generateState, getAuthorizationUrl, validateScope };
+export { type ApiErrorResponse, AuthenticationError, type AuthorizationResponse, DEFAULT_SCOPES, ENVIRONMENTS, type GameInput, type Gender, type LeaderboardOptions, LeaderboardResource, type MatchBatch, MatchBatchResult, type MatchBatchResultWire, type MatchInput, MatchesResource, Member, MemberEmailMatch, MemberSportMap, type MemberStatusWire, MembersByEmailResult, type MembersByEmailResultWire, MembersResource, NotFoundError, type OAuthConfig, OAuthError, OAuthResource, type OAuthScope, type PartnerMemberEmailMatchWire, type PartnerMemberWire, type PartnerRatingUpdateWire, type PlayerRankOptions, RateLimitError, type RatingSplitWire, RatingUpdate, SCOPES, type SearchFilters, SportRating, type SportRatingWire, type TokenResponse, TournamentImportResult, type TournamentImportResultWire, Vairified, type VairifiedEnvironment, VairifiedError, type VairifiedOptions, ValidationError, WebhookDeliveriesResult, type WebhookDeliveriesResultWire, WebhookDelivery, type WebhookDeliveryWire, WebhooksResource, describeScope, describeScopes, generateState, getAuthorizationUrl, validateScope };