@bulutklinik/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,509 @@
+/** Supported UI/content languages for the `lang` header. */
+type Lang = "tr" | "en" | "de" | "az";
+/**
+ * Envelope `resultType` state codes returned by the Bulutklinik API.
+ * A call is successful only when HTTP is 2xx AND resultType === Success (0).
+ */
+declare const ResultType: {
+    readonly Success: 0;
+    readonly Error: 1;
+    readonly Logout: 2;
+    readonly Update: 3;
+    readonly Refresh: 4;
+};
+type ResultTypeValue = (typeof ResultType)[keyof typeof ResultType];
+/** The standard response envelope wrapping every API response. */
+interface Envelope<T = unknown> {
+    resultType?: number;
+    /** May be a string label or a numeric code depending on the endpoint. */
+    errorType?: string | number;
+    errorMessage?: string;
+    successMessage?: string;
+    data?: T;
+}
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Pluggable token persistence. The default is in-memory; provide a custom
+ * implementation to persist tokens to a file, database or secure storage.
+ * All methods may be synchronous or return a promise.
+ */
+interface TokenStore {
+    getAccessToken(): MaybePromise<string | null>;
+    getRefreshToken(): MaybePromise<string | null>;
+    setTokens(accessToken: string, refreshToken: string | null): MaybePromise<void>;
+    clear(): MaybePromise<void>;
+}
+/** In-memory token store (default). Tokens are lost when the process exits. */
+declare class MemoryTokenStore implements TokenStore {
+    #private;
+    constructor(seed?: {
+        accessToken?: string | null;
+        refreshToken?: string | null;
+    });
+    getAccessToken(): string | null;
+    getRefreshToken(): string | null;
+    setTokens(accessToken: string, refreshToken: string | null): void;
+    clear(): void;
+}
+
+type Environment = "production" | "test" | "local";
+declare const ENVIRONMENT_BASE_URLS: Record<Environment, string>;
+type FetchLike = typeof fetch;
+interface ClientOptions {
+    /** Named environment preset. Ignored when `baseUrl` is provided. Default: `production`. */
+    environment?: Environment;
+    /** Explicit base URL (e.g. `https://api.bulutklinik.com/api/v3`). Overrides `environment`. */
+    baseUrl?: string;
+    /** Default `lang` header. Default: `tr`. */
+    lang?: Lang;
+    /** OAuth client id — used by `auth.connect` and for token refresh. */
+    clientId?: string;
+    /** OAuth client secret — used by `auth.connect` and for token refresh. */
+    clientSecret?: string;
+    /** Bearer token for the partner (`teusan`) endpoint. */
+    partnerToken?: string;
+    /** Pluggable token persistence. Default: in-memory. */
+    tokenStore?: TokenStore;
+    /** Per-request timeout in milliseconds. Default: 30000. */
+    timeoutMs?: number;
+    /** Injectable fetch implementation. Default: global `fetch`. */
+    fetch?: FetchLike;
+}
+interface ResolvedConfig {
+    baseUrl: string;
+    lang: Lang;
+    clientId?: string;
+    clientSecret?: string;
+    partnerToken?: string;
+    tokenStore: TokenStore;
+    timeoutMs: number;
+    fetchImpl: FetchLike;
+}
+
+type AuthMode = "public" | "bearer" | "partner";
+interface RequestSpec {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    auth: AuthMode;
+    body?: unknown;
+    lang?: Lang;
+}
+/**
+ * Low-level transport. Builds requests, unwraps the response envelope, maps
+ * failures to typed errors, and performs a single silent token refresh + retry
+ * on a 401 / `resultType 4`. Concurrent refreshes share one in-flight promise.
+ */
+declare class HttpClient {
+    readonly tokenStore: TokenStore;
+    readonly clientId: string | undefined;
+    readonly clientSecret: string | undefined;
+    private readonly baseUrl;
+    private readonly lang;
+    private readonly partnerToken;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private refreshInFlight;
+    constructor(config: ResolvedConfig);
+    request<T>(spec: RequestSpec): Promise<T>;
+    /** Force a token refresh using the stored refresh token. Throws on failure. */
+    refresh(): Promise<void>;
+    private send;
+    private dispatch;
+    private readEnvelope;
+    private ensureRefreshed;
+    private performRefresh;
+    private toError;
+}
+
+type LoginMode = "email" | "identity" | "phone" | "user_id" | "social" | "afterRegister";
+interface ConnectInput {
+    apiUserName: string;
+    /** Required except `social` / `afterRegister` modes. */
+    apiUserPassword?: string;
+    loginMode: LoginMode;
+    /** Defaults to the client's configured `clientId`. */
+    clientId?: string;
+    /** Defaults to the client's configured `clientSecret`. */
+    clientSecret?: string;
+    /** Some installs require this in `phone` mode. */
+    withPhoneNumber?: string;
+}
+interface LoginData {
+    access_token?: string;
+    refresh_token?: string;
+    password_policy?: unknown;
+    /** Present (instead of tokens) when 2FA is required — an encrypted blob. */
+    response?: string;
+}
+type LoginResult = {
+    twoFactorRequired: false;
+    passwordPolicy?: unknown;
+} | {
+    twoFactorRequired: true;
+    twoFactorResponse: string;
+};
+interface TwoFactorInput {
+    smsVerificationCode: string;
+    /** The encrypted blob from `connect`'s 2FA challenge (`twoFactorResponse`). */
+    response: string;
+}
+interface RegisterInput {
+    name: string;
+    surname: string;
+    /** Should equal `phoneNumber` (the `+CC` form) — used as the afterRegister username. */
+    apiUserName: string;
+    /** Must start with `+` and country code, e.g. `+90 555 111 22 33`. */
+    phoneNumber: string;
+    password: string;
+    smsVerificationCode: string;
+    /** Encrypted blob from the prior SMS-verification step. */
+    response: string;
+    acceptUserAgreement?: 0 | 1;
+    clientId?: string;
+    clientSecret?: string;
+}
+type DoctorListType = "interview" | "appointment";
+interface QuickSearchInput {
+    searchText: string;
+    listType?: DoctorListType | null;
+    location?: string | null;
+}
+interface QuickSearchResult {
+    searchedBranches?: unknown[];
+    searchedDoctors?: unknown[];
+    searchedCompanies?: unknown[];
+    searchedGivenTreatments?: unknown[];
+    searchedBlogs?: unknown[];
+    queryText?: string;
+    [k: string]: unknown;
+}
+interface SearchParams {
+    withFreeText?: string;
+    withDoctorName?: string;
+    withBranchName?: string;
+    /** `-1` excludes psychology/diet. */
+    withBranchId?: number | null;
+    withLocationName?: string;
+    withLocationId?: number | null;
+    withCompanyName?: string;
+    withCompanyId?: number | null;
+    withGivenTreatments?: string;
+    withExpertyId?: number | null;
+    withInstitutionId?: number | null;
+    withNearestSlotDayRange?: number | null;
+}
+type OrderParam = "name" | "point" | "slot" | "order";
+type OtherParam = "isKizilay" | "isQuestionable" | "isInterviewable" | "isAppointmentable";
+interface DoctorSearchInput {
+    searchParams?: SearchParams;
+    orderParams?: OrderParam[];
+    otherParams?: OtherParam[];
+    /** >= 1. */
+    currentPage: number;
+    /** 10–100. Default 20. */
+    perPageLimit?: number;
+}
+interface DoctorSummary {
+    doctor_id: number;
+    name?: string;
+    surname?: string;
+    branch_name?: string;
+    star_rate?: number;
+    nearest_slot?: string | null;
+    isInterviewable?: boolean;
+    isAppointmentable?: boolean;
+    url?: string;
+    user_image?: string;
+    [k: string]: unknown;
+}
+interface DoctorSearchResult {
+    foundDoctorsCount: number;
+    foundDoctors: DoctorSummary[];
+    [k: string]: unknown;
+}
+interface Branch {
+    sysbrnch_id?: number;
+    branch_name?: string;
+    [k: string]: unknown;
+}
+interface Location {
+    location_id?: number;
+    [k: string]: unknown;
+}
+type DoctorDetail = Record<string, unknown>;
+interface SchedulerInput {
+    doctorId: number | string;
+    /** `Y-m-d`, today..+21. When omitted, `scheduleStep` + `schedulePage` page the window. */
+    scheduleDate?: string | null;
+    scheduleStep?: number | string;
+    schedulePage?: number | string;
+    /** `interview` → online slots; anything else → physical. */
+    listType: DoctorListType;
+}
+interface Slot {
+    slotId: number;
+    /** `HH:mm:ss`. */
+    slotStart: string;
+    /** `HH:mm:ss`. */
+    slotEnd: string;
+    available: boolean;
+}
+/** Date-keyed (`Y-m-d`) map → slots for that day. Empty days are `[]`. */
+type SchedulerResult = Record<string, Slot[]>;
+type AppointmentType = "interview" | "appointment";
+interface ReserveInterviewInput {
+    doctorId: number | string;
+    /** `Y-m-d H:i`, today..+21. */
+    appointmentDate: string;
+    appointmentType?: AppointmentType;
+}
+interface PhysicalAppointmentInput {
+    doctorId: number | string;
+    /** `Y-m-d H:i`. */
+    appointmentDate: string;
+}
+type DiscountCheckType = "question" | "appointment" | "lab" | "special" | "physicallyAppointment" | "tmcLab" | "program";
+interface DiscountCheckInput {
+    checkType: DiscountCheckType;
+    discountCode: string;
+    /** Required except `lab` / `tmcLab` / `program`. */
+    doctorId?: number | string;
+    orderId?: number | string;
+    specialServiceId?: number | string;
+    programSlug?: string;
+}
+type DiscountResult = Record<string, unknown>;
+interface CardInfo {
+    cardHolder: string;
+    cardNumber: string;
+    /** `m`. */
+    cardExpMonth: string;
+    /** `Y`. */
+    cardExpYear: string;
+    cardCvv: string;
+}
+interface SavedCard {
+    id: number;
+    card_holder_name?: string;
+    /** Masked. */
+    card_number?: string;
+    card_type?: string;
+    created_at?: string;
+    [k: string]: unknown;
+}
+interface PaymentInput {
+    doctorId: number | string;
+    /** `Y-m-d H:i`. */
+    appointmentDate: string;
+    appointmentType?: AppointmentType;
+    is3D: boolean;
+    termsAccept: boolean;
+    /** A new card (all-or-none) … */
+    cardInfo?: CardInfo;
+    /** … or a saved card id (from `getCards`). */
+    cardId?: number | string;
+    /** `1` tokenizes the card. */
+    saveCard?: 0 | 1;
+    discountCode?: string;
+    /** Opaque encrypted blob, passed through verbatim. */
+    caseDetail?: string;
+}
+/** On 3DS success, `payment3DUrl` is a browser URL to open. */
+interface PaymentResult {
+    payment3DUrl?: string;
+    [k: string]: unknown;
+}
+type MeasureType = "tension" | "glucose" | "pulse" | "fever" | "weight" | "length" | "waist" | "hip" | "fat" | "muscle" | "calorie" | "step" | "sleep";
+/** 1=day, 2=week, 3=month, 4=year. */
+type GraphPeriod = 1 | 2 | 3 | 4;
+/** A single measurement. `date_time` is `Y-m-d H:i`; other fields depend on `type`. */
+interface MeasureRecord {
+    type: MeasureType;
+    date_time: string;
+    [field: string]: string | number;
+}
+/** Fields for the single-type endpoints (`date_time` + the type's own fields). */
+interface MeasureFields {
+    date_time: string;
+    [field: string]: string | number;
+}
+interface PartnerHealthInput {
+    identity?: string;
+    phoneNumber?: string;
+    data: MeasureRecord[];
+}
+
+/** Online reservation, physical appointment and cancellation. */
+declare class AppointmentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Reserve an online (interview) slot. Resolves to `null` on success. */
+    reserveInterview(input: ReserveInterviewInput): Promise<null>;
+    /** Create a physical appointment. */
+    addPhysical(input: PhysicalAppointmentInput): Promise<unknown>;
+    /** Cancel an appointment by event id (`cln_events.id`). */
+    cancel(eventId: number | string): Promise<unknown>;
+}
+
+/** Login, 2FA, token refresh, registration and logout. */
+declare class AuthResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Log in. On success tokens are stored automatically and
+     * `{ twoFactorRequired: false }` is returned. If 2FA is enabled the result is
+     * `{ twoFactorRequired: true, twoFactorResponse }` — pass that blob to
+     * {@link connectWithTwoFactor} together with the SMS code.
+     */
+    connect(input: ConnectInput): Promise<LoginResult>;
+    /** Complete a 2FA login with the SMS code and the challenge blob. */
+    connectWithTwoFactor(input: TwoFactorInput): Promise<void>;
+    /** Register a new patient (afterRegister auto-login). Stores tokens on success. */
+    register(input: RegisterInput): Promise<void>;
+    /** Manually refresh the access token using the stored refresh token. */
+    refresh(): Promise<void>;
+    /** Revoke the current tokens server-side and clear the local token store. */
+    disconnect(): Promise<void>;
+    private storeTokens;
+}
+
+/** Branches, locations, quick/filtered doctor search and doctor detail. */
+declare class DoctorsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    branches(): Promise<Branch[]>;
+    locations(): Promise<Location[]>;
+    quickSearch(input: QuickSearchInput): Promise<QuickSearchResult>;
+    search(input: DoctorSearchInput): Promise<DoctorSearchResult>;
+    detail(id: number | string, corporate?: number | string): Promise<DoctorDetail>;
+}
+
+/** Health measurements: CRUD, latest, history list, graph and partner submission. */
+declare class MeasuresResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Submit multiple measurements of any types in one call (primary entrypoint). */
+    addList(records: MeasureRecord[]): Promise<unknown>;
+    /** Submit a single measurement of one type. */
+    add(type: MeasureType, fields: MeasureFields): Promise<unknown>;
+    update(type: MeasureType, input: {
+        id: number | string;
+    } & MeasureFields): Promise<unknown>;
+    delete(type: MeasureType, id: number | string): Promise<unknown>;
+    /** Latest value of each measurement type. */
+    last(): Promise<Record<string, unknown>>;
+    /** Paginated history for one type. `glucoseType` (0/1) applies only to glucose. */
+    list(type: MeasureType, page: number | string, glucoseType?: 0 | 1): Promise<unknown>;
+    /** Grouped graph data. `period`: 1=day, 2=week, 3=month, 4=year. */
+    graph(type: MeasureType, period: GraphPeriod, page: number | string, glucoseType?: 0 | 1): Promise<unknown>;
+    /** Partner (teusan) submission — uses the configured partner token. */
+    partnerHealthInformation(input: PartnerHealthInput): Promise<unknown>;
+}
+
+/** Discount check, saved cards and the 3DS payment entrypoint. */
+declare class PaymentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Validate a discount code. Note: this endpoint lives under the `patients` prefix. */
+    checkDiscountCode(input: DiscountCheckInput): Promise<DiscountResult>;
+    getCards(): Promise<{
+        cards: SavedCard[];
+    }>;
+    saveCard(card: CardInfo): Promise<unknown>;
+    /**
+     * Start an appointment payment. The amount is computed server-side. On a 3DS
+     * flow the result carries `payment3DUrl` — a browser URL to open; the SDK does
+     * not follow it. 3DS capture happens via the bank → server callback.
+     */
+    pay(input: PaymentInput): Promise<PaymentResult>;
+    deleteCard(cardId: number | string): Promise<unknown>;
+}
+
+/** Doctor availability (materialized slots). */
+declare class SlotsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Fetch a doctor's free slots. Returns a date-keyed map of slots. Build the
+     * next step's `appointmentDate` as `"<date> <slotStart>"` (drop the seconds).
+     */
+    schedule(input: SchedulerInput): Promise<SchedulerResult>;
+}
+
+/**
+ * The Bulutklinik API client. Construct once and reuse; service groups are
+ * exposed as properties.
+ *
+ * @example
+ * ```ts
+ * const client = new BulutklinikClient({
+ *   environment: "test",
+ *   clientId: "…",
+ *   clientSecret: "…",
+ * });
+ * await client.auth.connect({ apiUserName: "…", apiUserPassword: "…", loginMode: "email" });
+ * const result = await client.doctors.quickSearch({ searchText: "kardiyo" });
+ * ```
+ */
+declare class BulutklinikClient {
+    readonly auth: AuthResource;
+    readonly doctors: DoctorsResource;
+    readonly slots: SlotsResource;
+    readonly appointments: AppointmentsResource;
+    readonly payments: PaymentsResource;
+    readonly measures: MeasuresResource;
+    /** The active token store (also accepts a custom one via options). */
+    readonly tokenStore: TokenStore;
+    private readonly http;
+    constructor(options?: ClientOptions);
+}
+
+interface ApiErrorContext {
+    httpStatus: number;
+    resultType?: number;
+    errorType?: string | number;
+    data?: unknown;
+    method: string;
+    path: string;
+    retryAfter?: number;
+}
+/** Base class for every error thrown by the SDK. */
+declare class BulutklinikError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Network failure, timeout, DNS or TLS error — no HTTP response was received. */
+declare class TransportError extends BulutklinikError {
+    constructor(message: string, cause?: unknown);
+}
+/** An HTTP response was received but the call was not successful. */
+declare class ApiError extends BulutklinikError {
+    readonly httpStatus: number;
+    readonly resultType: number | undefined;
+    readonly errorType: string | number | undefined;
+    readonly data: unknown;
+    readonly method: string;
+    readonly path: string;
+    constructor(message: string, ctx: ApiErrorContext);
+}
+/** 422 / errorType=validation. */
+declare class ValidationError extends ApiError {
+}
+/** 401, a logout (resultType 2), or a failed token refresh. */
+declare class AuthenticationError extends ApiError {
+}
+/** 403 — authenticated but not permitted / out of scope. */
+declare class AuthorizationError extends ApiError {
+}
+/** 404. */
+declare class NotFoundError extends ApiError {
+}
+/** 429 — throttled. Carries `retryAfter` (seconds) when the header is present. */
+declare class RateLimitError extends ApiError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, ctx: ApiErrorContext);
+}
+
+export { ApiError, type AppointmentType, AppointmentsResource, AuthResource, AuthenticationError, AuthorizationError, type Branch, BulutklinikClient, BulutklinikError, type CardInfo, type ClientOptions, type ConnectInput, type DiscountCheckInput, type DiscountCheckType, type DiscountResult, type DoctorDetail, type DoctorListType, type DoctorSearchInput, type DoctorSearchResult, type DoctorSummary, DoctorsResource, ENVIRONMENT_BASE_URLS, type Envelope, type Environment, type FetchLike, type GraphPeriod, type Lang, type Location, type LoginData, type LoginMode, type LoginResult, type MeasureFields, type MeasureRecord, type MeasureType, MeasuresResource, MemoryTokenStore, NotFoundError, type OrderParam, type OtherParam, type PartnerHealthInput, type PaymentInput, type PaymentResult, PaymentsResource, type PhysicalAppointmentInput, type QuickSearchInput, type QuickSearchResult, RateLimitError, type RegisterInput, type ReserveInterviewInput, ResultType, type ResultTypeValue, type SavedCard, type SchedulerInput, type SchedulerResult, type SearchParams, type Slot, SlotsResource, type TokenStore, TransportError, type TwoFactorInput, ValidationError };