dupr-js-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,516 @@
+type AuthMode = {
+    type: "clientCredentials";
+    clientKey: string;
+    clientSecret: string;
+} | {
+    type: "staticBearer";
+    bearerToken: string;
+} | {
+    type: "none";
+};
+interface RequestInfo {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+}
+interface ResponseInfo {
+    status: number;
+    url: string;
+    durationMs: number;
+}
+interface RetryOptions {
+    /** Max number of retry attempts after the initial failure. @default 3 */
+    maxRetries?: number;
+    /** Base delay in ms before the first retry. Doubles on each attempt. @default 1_000 */
+    baseDelayMs?: number;
+    /** Max delay cap in ms (prevents infinite backoff). @default 30_000 */
+    maxDelayMs?: number;
+}
+interface DuprClientOptions {
+    /** @default "https://uat.mydupr.com/api" */
+    baseUrl?: string;
+    /** API version prefix used in all paths. @default "v1.0" */
+    version?: string;
+    /** Request timeout in milliseconds. @default 30_000 */
+    timeoutMs?: number;
+    auth?: AuthMode;
+    /** Custom User-Agent header. */
+    userAgent?: string;
+    /** Inject a custom fetch implementation (useful for testing or polyfilling). */
+    customFetch?: typeof fetch;
+    /** Called before every request. Useful for logging or tracing. */
+    onRequest?: (info: RequestInfo) => void;
+    /** Called after every response (including errors). */
+    onResponse?: (info: ResponseInfo) => void;
+    /** Retry behaviour for transient errors (5xx, network failures, 429). Pass `false` to disable. */
+    retry?: RetryOptions | false;
+}
+interface ResolvedRetryOptions {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+interface ResolvedConfig {
+    baseUrl: string;
+    version: string;
+    timeoutMs: number;
+    auth: AuthMode;
+    userAgent: string;
+    customFetch: typeof fetch;
+    retry: ResolvedRetryOptions | false;
+    onRequest?: (info: RequestInfo) => void;
+    onResponse?: (info: ResponseInfo) => void;
+    /** Runtime override for the bearer token — set via `client.setBearerToken()`. */
+    overrideBearerToken?: string;
+}
+
+declare class HttpClient {
+    private readonly config;
+    private token;
+    private tokenExpiresAt;
+    constructor(config: ResolvedConfig);
+    private getBearerToken;
+    get<T>(path: string, init?: RequestInit): Promise<T>;
+    post<T>(path: string, body?: unknown, init?: RequestInit): Promise<T>;
+    delete<T>(path: string, body?: unknown, init?: RequestInit): Promise<T>;
+    request<T>(method: string, path: string, init?: RequestInit): Promise<T>;
+    private rawRequest;
+}
+
+type MatchFormat = "SINGLES" | "DOUBLES";
+type MatchSource = "PARTNER" | "CLUB";
+type Gender = "MALE" | "FEMALE";
+type RatingType = "SINGLES" | "DOUBLES";
+type WebhookTopic = "RATING";
+type ApiStatus = "SUCCESS" | "FAILURE";
+interface ApiWrapper<T = unknown> {
+    status: ApiStatus;
+    message?: string;
+    result?: T;
+}
+interface TokenResponse {
+    token?: string;
+    accessToken?: string;
+    expiresIn?: number;
+}
+interface UserInfo {
+    duprId: string;
+    fullName: string;
+    singlesRating?: number;
+    doublesRating?: number;
+    singlesProvisional?: boolean;
+    doublesProvisional?: boolean;
+}
+interface ExtendedUserInfo extends UserInfo {
+    email?: string;
+}
+interface ClubMembership {
+    clubId: string;
+    clubName: string;
+    role: string;
+}
+interface ClubMembershipResult {
+    clubs: ClubMembership[];
+}
+type ClubMembershipResponse = ApiWrapper<ClubMembershipResult>;
+interface ExternalSearchFilter {
+    gender?: Gender;
+    location?: ExternalFilterLocation;
+    rating?: ExternalRatingFilter;
+    age?: ExternalAgeRangeFilter;
+}
+interface ExternalFilterLocation {
+    lat: number;
+    lng: number;
+    address?: string;
+    radiusInMeters?: number;
+}
+interface ExternalRatingFilter {
+    min?: number;
+    max?: number;
+    type?: RatingType;
+    reliable?: boolean;
+}
+interface ExternalAgeRangeFilter {
+    min?: number;
+    max?: number;
+}
+interface ExternalSearchRequest {
+    query: string;
+    offset: number;
+    limit: number;
+    filters?: ExternalSearchFilter;
+}
+interface ExternalBatchUserDetailRequest {
+    duprIds: string[];
+}
+interface ExternalInviteRequest {
+    firstName: string;
+    lastName: string;
+    email: string;
+}
+interface RatingCoach {
+    id: string;
+    metadata: Record<string, string>;
+}
+interface GetProvisionalRatingRequest {
+    duprId: string;
+}
+interface CreateProvisionalRatingRequest {
+    duprId: string;
+    provisionalSinglesRating?: number;
+    provisionalDoublesRating?: number;
+    coach?: RatingCoach;
+}
+interface UpdateProvisionalRatingRequest {
+    duprId: string;
+    provisionalSinglesRating?: number;
+    provisionalDoublesRating?: number;
+}
+interface DeleteProvisionalRatingRequest {
+    duprId: string;
+}
+interface ExternalMatchPlayer {
+    duprId: string;
+}
+interface ExternalMatchTeam {
+    /** 1 player for SINGLES, 2 for DOUBLES */
+    players: ExternalMatchPlayer[];
+    /** Scores per game, aligned with the opposing team's scores array */
+    scores: number[];
+}
+interface ExternalMatchRequest {
+    /** Your universally unique identifier — must not be reused across matches */
+    identifier: string;
+    /** yyyy-MM-dd */
+    matchDate: string;
+    matchFormat: MatchFormat;
+    teams: [ExternalMatchTeam, ExternalMatchTeam];
+    source: MatchSource;
+    eventId?: number;
+    clubId?: number;
+}
+interface ExternalUpdateMatchRequest {
+    matchId: string;
+    matchDate?: string;
+    teams?: [ExternalMatchTeam, ExternalMatchTeam];
+}
+interface ExternalDeleteMatchRequest {
+    matchCode: string;
+    identifier: string;
+}
+interface ExternalMatchSearchRequest {
+    duprId: string;
+    offset?: number;
+    limit?: number;
+}
+interface MatchResponse {
+    matchCode?: string;
+    hashedMatchCode?: string;
+    identifier?: string;
+    matchDate?: string;
+    matchFormat?: MatchFormat;
+    teams?: ExternalMatchTeam[];
+}
+interface SubscriptionItemRequest {
+    productId: string;
+    promotionId: string;
+}
+interface TargetUserRequest {
+    duprId?: string;
+    email?: string;
+}
+interface AttributionRequest {
+    clientKeyId: number;
+}
+interface GrantExternalSubscriptionRequest {
+    user: TargetUserRequest;
+    item: SubscriptionItemRequest;
+    attribution: AttributionRequest;
+    metadata?: Record<string, string>;
+}
+interface PlayerRatingSubscribeRequest {
+    duprIds: string[];
+}
+interface ExternalClubMemberRequest {
+    clubId: string;
+}
+interface ExternalClubMatchSearchRequest {
+    clubId: string;
+    offset?: number;
+    limit?: number;
+}
+interface CreateEventRequestV1 {
+    name: string;
+    description?: string;
+    startDate: string;
+    endDate: string;
+    location?: string;
+    clubId?: number;
+}
+interface UpdateEventRequestV1 {
+    eventId: string;
+    name?: string;
+    description?: string;
+    startDate?: string;
+    endDate?: string;
+}
+interface GetEventRequestV1 {
+    eventIds: string[];
+}
+interface DeleteEventRequestV1 {
+    eventIds: string[];
+}
+interface CreateEventResponseV1 {
+    eventId?: string;
+    name?: string;
+}
+interface UpdateEventResponseV1 {
+    eventId?: string;
+}
+interface GetEventResponseV1 {
+    events?: Array<{
+        eventId: string;
+        name: string;
+        description?: string;
+        startDate?: string;
+        endDate?: string;
+        location?: string;
+    }>;
+}
+interface DeleteEventResponseV1 {
+    deleted?: string[];
+}
+interface ClientHookRequest {
+    webhookUrl: string;
+    topics: WebhookTopic[];
+}
+interface UserWebhookRequest {
+    duprIds: string[];
+    topic: WebhookTopic;
+}
+interface WebhookSchema {
+    topic: string;
+    schema: Record<string, unknown>;
+}
+
+interface AuthCodeTokenResponse extends TokenResponse {
+    refresh_token?: string;
+    token_type?: string;
+    scope?: string;
+}
+interface AuthorizationUrlParams {
+    /** Your OAuth redirect URI, must match what is registered with DUPR. */
+    redirectUri: string;
+    /** OAuth scopes to request (e.g. ["user.read"]). Defaults to empty. */
+    scopes?: string[];
+    /** Opaque value passed through the flow to prevent CSRF. Recommended. */
+    state?: string;
+}
+declare class AuthModule {
+    private readonly http;
+    private readonly config;
+    constructor(http: HttpClient, config: ResolvedConfig);
+    /**
+     * Explicitly request a new access token using client credentials.
+     * Normally you don't need to call this — the HTTP client handles token refresh automatically.
+     */
+    getToken(): Promise<TokenResponse>;
+    /**
+     * Build the DUPR authorization URL to redirect the user to for login.
+     * The `authorizationUrl` config option must be set (see above note).
+     */
+    getAuthorizationUrl(params: AuthorizationUrlParams): string;
+    /**
+     * Exchange an authorization code (from the OAuth callback) for access + refresh tokens.
+     * Uses `POST /auth/{version}/token` with `grant_type=authorization_code`.
+     */
+    exchangeCode(params: {
+        code: string;
+        redirectUri: string;
+    }): Promise<AuthCodeTokenResponse>;
+    /**
+     * Obtain a new access token using a refresh token from a previous Authorization Code flow.
+     * Uses `POST /auth/{version}/token` with `grant_type=refresh_token`.
+     */
+    refreshToken(refreshToken: string): Promise<AuthCodeTokenResponse>;
+}
+
+declare class UsersModule {
+    private readonly http;
+    private readonly cfg;
+    constructor(http: HttpClient, cfg: ResolvedConfig);
+    /** GET /user/{version}/{id} — basic player profile */
+    getUser(duprId: string): Promise<ApiWrapper<UserInfo>>;
+    /** GET /user/{version}/{id}/details — extended profile (requires USER_EMAIL::VIEW permission) */
+    getExtendedUser(duprId: string): Promise<ApiWrapper<ExtendedUserInfo>>;
+    /** GET /user/{version}/{id}/clubs — club memberships for a player */
+    getClubMemberships(duprId: string): Promise<ClubMembershipResponse>;
+    /** POST /user/{version}/search — full-text player search with optional filters */
+    search(req: ExternalSearchRequest): Promise<ApiWrapper<UserInfo[]>>;
+    /** POST /user/{version}/batch — fetch multiple players by DUPR ID in one request */
+    getBatch(req: ExternalBatchUserDetailRequest): Promise<ApiWrapper<UserInfo[]>>;
+    /** POST /user/{version}/invite — pre-generate a DUPR ID and send an invite email */
+    invite(req: ExternalInviteRequest): Promise<ApiWrapper<{
+        duprId: string;
+    }>>;
+    /** POST /user/{version}/subscription/grants — grant a subscription to a user */
+    grantSubscription(req: GrantExternalSubscriptionRequest): Promise<ApiWrapper>;
+    /** POST /user/{version}/provisional_rating — get provisional ratings for a player */
+    getProvisionalRating(req: GetProvisionalRatingRequest): Promise<ApiWrapper>;
+    /** POST /user/{version}/provisional_rating/create */
+    createProvisionalRating(req: CreateProvisionalRatingRequest): Promise<ApiWrapper>;
+    /** POST /user/{version}/provisional_rating/update */
+    updateProvisionalRating(req: UpdateProvisionalRatingRequest): Promise<ApiWrapper>;
+    /** DELETE /user/{version}/provisional_rating/delete */
+    deleteProvisionalRating(req: DeleteProvisionalRatingRequest): Promise<ApiWrapper>;
+}
+
+interface GetDuprIdByEmailRequest {
+    email: string;
+}
+interface DuprIdByEmailResponse {
+    duprId?: string;
+}
+declare class PlayersModule {
+    private readonly http;
+    private readonly cfg;
+    constructor(http: HttpClient, cfg: ResolvedConfig);
+    /** POST /{version}/player/duprid-by-email — resolve a DUPR ID from an email address */
+    getDuprIdByEmail(req: GetDuprIdByEmailRequest): Promise<ApiWrapper<DuprIdByEmailResponse>>;
+}
+
+interface PlayerRatingHistoryRequest {
+    duprId: string;
+    offset?: number;
+    limit?: number;
+}
+interface PlayerRatingHistoryEntry {
+    date?: string;
+    singlesRating?: number;
+    doublesRating?: number;
+}
+declare class PlayerRatingModule {
+    private readonly http;
+    private readonly cfg;
+    constructor(http: HttpClient, cfg: ResolvedConfig);
+    /** POST /history — get rating history for a player */
+    getHistory(req: PlayerRatingHistoryRequest): Promise<ApiWrapper<PlayerRatingHistoryEntry[]>>;
+    /** GET /{version}/subscribe/rating-changes — list currently subscribed DUPR IDs */
+    getSubscriptions(): Promise<ApiWrapper<{
+        duprIds: string[];
+    }>>;
+    /** POST /{version}/subscribe/rating-changes — subscribe to rating-change events for a list of players */
+    subscribe(req: PlayerRatingSubscribeRequest): Promise<ApiWrapper>;
+    /** DELETE /{version}/subscribe/rating-changes — unsubscribe from rating-change events */
+    unsubscribe(req: PlayerRatingSubscribeRequest): Promise<ApiWrapper>;
+}
+
+interface AnnotateMatchRequest {
+    matchId: string;
+    annotation: Record<string, unknown>;
+}
+declare class MatchesModule {
+    private readonly http;
+    private readonly cfg;
+    constructor(http: HttpClient, cfg: ResolvedConfig);
+    /** GET /match/{version}/{id} — view a single match */
+    get(matchId: string): Promise<ApiWrapper<MatchResponse>>;
+    /** POST /match/{version}/create — submit a new match result */
+    create(match: ExternalMatchRequest): Promise<ApiWrapper<MatchResponse>>;
+    /** POST /match/{version}/batch — submit multiple match results in one call */
+    createBulk(matches: ExternalMatchRequest[]): Promise<ApiWrapper<MatchResponse[]>>;
+    /** POST /match/{version}/update — update an existing match */
+    update(req: ExternalUpdateMatchRequest): Promise<ApiWrapper<MatchResponse>>;
+    /** DELETE /match/{version}/delete — delete a match */
+    delete(req: ExternalDeleteMatchRequest): Promise<ApiWrapper>;
+    /** POST /match/{version}/annotate — attach vendor-specific metadata to a match */
+    annotate(req: AnnotateMatchRequest): Promise<ApiWrapper>;
+    /** DELETE /match/{version}/annotate/{matchId} — remove a match annotation */
+    deleteAnnotation(matchId: string): Promise<ApiWrapper>;
+    /** POST /match/history/search — search a player's match history */
+    searchHistory(req: ExternalMatchSearchRequest): Promise<ApiWrapper<MatchResponse[]>>;
+}
+
+declare class ClubsModule {
+    private readonly http;
+    private readonly cfg;
+    constructor(http: HttpClient, cfg: ResolvedConfig);
+    /** POST /club/{version}/members — get ratings for all members of a club */
+    membersRating(req: ExternalClubMemberRequest): Promise<ApiWrapper<UserInfo[]>>;
+    /** POST /club/{version}/match/search — search matches associated with a club */
+    searchMatches(req: ExternalClubMatchSearchRequest): Promise<ApiWrapper<MatchResponse[]>>;
+}
+
+declare class EventsModule {
+    private readonly http;
+    private readonly cfg;
+    constructor(http: HttpClient, cfg: ResolvedConfig);
+    /** POST /events/{version}/create */
+    create(req: CreateEventRequestV1): Promise<ApiWrapper<CreateEventResponseV1>>;
+    /** GET /events/{version}/get */
+    get(req: GetEventRequestV1): Promise<ApiWrapper<GetEventResponseV1>>;
+    /** POST /events/{version}/update */
+    update(req: UpdateEventRequestV1): Promise<ApiWrapper<UpdateEventResponseV1>>;
+    /** POST /events/{version}/delete */
+    delete(req: DeleteEventRequestV1): Promise<ApiWrapper<DeleteEventResponseV1>>;
+}
+
+declare class WebhooksModule {
+    private readonly http;
+    private readonly cfg;
+    constructor(http: HttpClient, cfg: ResolvedConfig);
+    /** POST /{version}/webhook — register a webhook endpoint */
+    register(req: ClientHookRequest): Promise<ApiWrapper>;
+    /** GET /{version}/topic — list all available webhook topics */
+    getTopics(): Promise<ApiWrapper<string[]>>;
+    /** GET /{version}/webhook/schema — list available webhook schemas */
+    listSchemas(): Promise<ApiWrapper<WebhookSchema[]>>;
+    /** GET /{version}/webhook/schema/{topic} — get the JSON schema for a specific topic */
+    getSchema(topic: string): Promise<ApiWrapper<WebhookSchema>>;
+    /** POST /user/{version}/subscribe/webhook-event — subscribe specific users to a webhook topic */
+    subscribeUsers(req: UserWebhookRequest): Promise<ApiWrapper>;
+    /** DELETE /user/{version}/subscribe/webhook-event — unsubscribe specific users from a webhook topic */
+    unsubscribeUsers(req: UserWebhookRequest): Promise<ApiWrapper>;
+}
+
+declare class DuprClient {
+    readonly config: ResolvedConfig;
+    readonly auth: AuthModule;
+    readonly users: UsersModule;
+    readonly players: PlayersModule;
+    readonly playerRating: PlayerRatingModule;
+    readonly matches: MatchesModule;
+    readonly clubs: ClubsModule;
+    readonly events: EventsModule;
+    readonly webhooks: WebhooksModule;
+    constructor(opts?: DuprClientOptions);
+    /** Override the bearer token at runtime — useful when your backend handles auth separately. */
+    setBearerToken(token: string): void;
+    /** Clear the runtime bearer token override and fall back to configured auth. */
+    clearBearerToken(): void;
+}
+
+declare class DuprApiError extends Error {
+    readonly statusCode: number;
+    readonly details?: unknown | undefined;
+    readonly duprRequestId?: string | undefined;
+    constructor(message: string, statusCode: number, details?: unknown | undefined, duprRequestId?: string | undefined);
+}
+declare class AuthenticationError extends DuprApiError {
+    constructor(message: string, statusCode: number, details?: unknown, duprRequestId?: string);
+}
+declare class ValidationError extends DuprApiError {
+    constructor(message: string, statusCode: number, details?: unknown, duprRequestId?: string);
+}
+declare class NotFoundError extends DuprApiError {
+    constructor(message: string, statusCode: number, details?: unknown, duprRequestId?: string);
+}
+declare class RateLimitError extends DuprApiError {
+    constructor(message: string, statusCode: number, details?: unknown, duprRequestId?: string);
+}
+declare class ServerError extends DuprApiError {
+    constructor(message: string, statusCode: number, details?: unknown, duprRequestId?: string);
+}
+
+export { type ApiStatus, type ApiWrapper, type AttributionRequest, type AuthCodeTokenResponse, type AuthMode, AuthModule, AuthenticationError, type AuthorizationUrlParams, type ClientHookRequest, type ClubMembership, type ClubMembershipResponse, ClubsModule, type CreateEventRequestV1, type CreateEventResponseV1, type CreateProvisionalRatingRequest, type DeleteEventRequestV1, type DeleteEventResponseV1, type DeleteProvisionalRatingRequest, DuprApiError, DuprClient, type DuprClientOptions, EventsModule, type ExtendedUserInfo, type ExternalAgeRangeFilter, type ExternalBatchUserDetailRequest, type ExternalClubMatchSearchRequest, type ExternalClubMemberRequest, type ExternalDeleteMatchRequest, type ExternalFilterLocation, type ExternalInviteRequest, type ExternalMatchPlayer, type ExternalMatchRequest, type ExternalMatchSearchRequest, type ExternalMatchTeam, type ExternalRatingFilter, type ExternalSearchFilter, type ExternalSearchRequest, type ExternalUpdateMatchRequest, type Gender, type GetEventRequestV1, type GetEventResponseV1, type GetProvisionalRatingRequest, type GrantExternalSubscriptionRequest, type MatchFormat, type MatchResponse, type MatchSource, MatchesModule, NotFoundError, PlayerRatingModule, type PlayerRatingSubscribeRequest, PlayersModule, RateLimitError, type RatingCoach, type RatingType, type RequestInfo, type ResolvedConfig, type ResolvedRetryOptions, type ResponseInfo, type RetryOptions, ServerError, type SubscriptionItemRequest, type TargetUserRequest, type TokenResponse, type UpdateEventRequestV1, type UpdateEventResponseV1, type UpdateProvisionalRatingRequest, type UserInfo, type UserWebhookRequest, UsersModule, ValidationError, type WebhookSchema, type WebhookTopic, WebhooksModule };