Partner API

type PartnerClub = {
  id: string;
  name: string;
  description: string | null;
  logo: string | null;
  bannerImage: string | null;
  address: Json | null;
  contactInfo: Json | null;
  businessHours: BusinessHoursEntry[];
  timeZone: string; // IANA, e.g. "Europe/Budapest" — all wall clocks are in this zone
  currency: string; // ISO 4217, e.g. "HUF"
  membershipRequired: boolean;
  requireBookingApproval: boolean;
  bookingDecidedByLottery: boolean;
  courts: PartnerCourt[];
};

type BusinessHoursEntry = {
  dayOfWeek: number; // 0–6 (Sunday–Saturday)
  openTime: string;  // "HH:mm"
  closeTime: string;
  isClosed: boolean;
};

type PartnerCourt = {
  id: string;
  name: string;
  courtNumber: number | null;
  type: string | null;
  surface: string | null;
  amenities: Json | null;
  hourlyRate: Json | null; // raw DB; see Court pricing for NormalizedCourtPricing
  maintenanceStatus: string;
  isActive: boolean;
};

type CourtPricesResponse = {
  courts: {
    id: string;
    name: string;
    pricing: NormalizedCourtPricing;
  }[];
};

/** @tennis-booking/court-pricing */
type NormalizedCourtPricing = {
  default: HourlyRateSlot[];
  intervals: SeasonalInterval[];
};

type HourlyRateSlot = {
  price: number;
  currency: string;
  from: string; // "HH:mm"
  to: string;
  isDefault?: boolean;
};

type SeasonalInterval = {
  from: string; // YYYY-MM-DD
  to: string;
  hourlyRate: HourlyRateSlot[];
};

type TimeSlotsResponse = {
  availableTimes: string[]; // HH:mm slot starts in club-local wall time
  date: string;             // YYYY-MM-DD
  courtId: string;
  totalSlots: number;
  timeZone: string;         // IANA zone of the club
  businessHours: {
    openTime: string;
    closeTime: string;
    dayOfWeek: number;
  };
  reason?: TimeslotsEmptyReason; // when availableTimes is empty for a known reason
  message?: string;              // human-readable form of reason
};

type TimeslotsEmptyReason =
  | "club_closed"
  | "court_unavailable"
  | "maintenance"
  | "day_blocked"
  | "date_in_past"
  | "beyond_booking_window"
  | "club_not_accepting_bookings"; // additive: treat unknown values as "no slots"

type PartnerEquipment = {
  id: string;
  clubId: string;
  name: string;
  description: string | null;
  price: string | number; // Decimal from DB
  currency: string;
  stock: number;
  image: string | null;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
  availableUnits?: number; // with startTime + endTime query params
};

type PartnerBooking = {
  id: string;
  clubId: string;
  courtId: string;
  startTime: string; // club wall clock "YYYY-MM-DD HH:mm"
  endTime: string;
  duration: number; // minutes
  totalPrice: number;
  currency: string;
  status: string;
  isLotteryEntry: boolean;
  partnerDeveloperId: string | null;
  externalReference: string | null;
  /** Create only: true when an existing booking was returned (HTTP 200). */
  idempotentReplay?: boolean;
};

type PartnerBookingDetails = PartnerBooking & {
  /** Settled online or registered payments on this booking, net of refunds. */
  paidAmount: number;
  /** When an unpaid draft hold lapses; null otherwise. */
  draftExpiresAt: string | null;
  cancelledAt: string | null;
  createdAt: string | null;
};

type PartnerPaymentRegistration = {
  paymentId: string;
  status: "completed";
};

type PartnerCancelResult = {
  cancelled: true;
  bookingId: string;
  status: "cancelled";
  alreadyCancelled: boolean; // true when it was already cancelled (retry)
  cancelledAt: string | null;
};

type PartnerApiError = {
  error: {
    /** Stable machine-readable code. Branch on this. */
    code: PartnerErrorCode;
    /** Human-readable; for logs and support, not for branching. */
    message: string;
    /** Extra context; may be empty. */
    details: Record<string, unknown>;
    /** Correlates with the x-request-id response header. */
    requestId: string;
  };
};

type PartnerErrorCode =
  | "PARTNER_UNAUTHORIZED"                    // 401 missing/invalid API key
  | "PARTNER_RATE_LIMITED"                    // 429 fair-use limit (see Rate limits)
  | "PARTNER_CLUB_NOT_APPROVED"               // 403 your access request is pending/rejected
  | "PARTNER_CLUB_NOT_INTEGRABLE"             // 422 club not open to partners
  | "PARTNER_CLUB_NOT_FOUND"                  // 404 unknown, or never requested by you
  | "PARTNER_COURT_NOT_FOUND"                 // 404
  | "PARTNER_COURT_UNAVAILABLE"               // 409 maintenance / inactive
  | "PARTNER_BOOKING_NOT_FOUND"               // 404
  | "PARTNER_BOOKING_NOT_OWNED"               // 403 booking belongs to another partner
  | "PARTNER_BOOKING_NOT_CANCELLABLE"         // 409
  | "PARTNER_BOOKING_HAS_PAYMENTS"            // 409 refund required first
  | "PARTNER_BOOKING_STATE_INVALID"           // 409
  | "PARTNER_BOOKING_TOO_LONG"                // 400 longer than the club allows
  | "PARTNER_SLOT_UNAVAILABLE"                // 409 slot taken meanwhile
  | "PARTNER_EXTERNAL_REFERENCE_CONFLICT"     // 409 reference used for another slot
  | "PARTNER_REQUEST_IN_PROGRESS"             // 409 concurrent create on this reference or court; retry shortly
  | "PARTNER_VALIDATION"                      // 400 bad request payload/params
  | "PARTNER_PAYMENT_VALIDATION"              // 400 bad payment payload
  | "PARTNER_NO_COVER_IMAGE"                  // 404 club has no banner/logo
  | "PARTNER_BUSINESS_HOURS_NOT_CONFIGURED"   // 400 no hours for that weekday
  | "PARTNER_INTERNAL_ERROR"                  // 500
  | "PARTNER_ROUTE_NOT_FOUND"                 // 404 no endpoint for this method + path
  // Booking-rule codes shared with the TEKKA apps:
  | "BOOKING_SLOT_NOT_BOOKABLE"               // 409 outside hours / closed / maintenance / hold
  | "BOOKING_START_TIME_IN_PAST"              // 400
  | "BOOKING_TOO_FAR_AHEAD"                   // 400 beyond the club's booking window
  | "BOOKING_RANGE_SPANS_LOTTERY"             // 400 split lottery and instant time
  | "BOOKING_LOTTERY_ENTRY_DUPLICATE"         // 409 one lottery entry per customer
  | "FAIRPLAY_QUOTA_EXCEEDED"                 // 409 over a club fair-play limit (details: reason, limit, used, remaining)
  | "CLUB_NOT_ACCEPTING_BOOKINGS"             // 403 club inactive or not verified
  | "CLUB_NOT_BOOKABLE"                       // 422 venue has no court booking
  | "SMART_FEATURES_PARTNER_SMART_DISCOUNT_NOT_ALLOWED"; // 400 discount fields sent

// Codes are additive-only: new ones may appear, existing ones are never renamed.
// Treat an unrecognised code as a generic failure for that HTTP status.

const res = await fetch(url, { headers });
if (!res.ok) {
  const body = (await res.json()) as PartnerApiError;
  switch (body.error.code) {
    case "PARTNER_RATE_LIMITED":
      await sleep(Number(res.headers.get("Retry-After") ?? 60) * 1000);
      return retry();
    case "PARTNER_SLOT_UNAVAILABLE":
      return showSlotTaken();
    default:
      logFailure(body.error.code, body.error.requestId);
  }
}

type CheckoutTokenResponse = {
  token: string;       // opaque; single-use after successful return
  checkoutUrl: string; // redirect payer here
  expiresAt: string;   // ISO 8601, 15 min from mint
};