fhir-kit-client/dist/client.d.ts

FHIR Client

import { HttpClient } from './http-client.js';
import { Pagination } from './pagination.js';
import type { ClientConfig, FhirResource, HttpMethod, OpPatch, RequestOptions, SearchParams, SmartAuthMetadata } from './types.js';
export interface ReadParams {
    resourceType: string;
    id: string;
    options?: RequestOptions;
}
export interface VreadParams {
    resourceType: string;
    id: string;
    version: string;
    options?: RequestOptions;
}
export interface CreateParams {
    resourceType: string;
    body: FhirResource;
    options?: RequestOptions;
}
export interface UpdateParams {
    resourceType: string;
    /** Resource id for a direct update. Mutually exclusive with `searchParams`. */
    id?: string;
    /** Conditional update parameters. Mutually exclusive with `id`. */
    searchParams?: SearchParams;
    body: FhirResource;
    options?: RequestOptions;
}
export interface DeleteParams {
    resourceType: string;
    id: string;
    options?: RequestOptions;
}
export interface PatchParams {
    resourceType: string;
    id: string;
    /** Array of RFC 6902 JSON Patch operations. */
    jsonPatch: OpPatch[];
    options?: RequestOptions;
}
export interface BundleParams {
    /**
     * A FHIR Bundle resource. The `Bundle.type` field (`'batch'` or `'transaction'`)
     * determines how the server processes the bundle.
     */
    body: FhirResource;
    options?: RequestOptions;
}
export interface OperationParams {
    /** Operation name with or without leading `$` (e.g. `'$everything'` or `'everything'`). */
    name: string;
    resourceType?: string;
    id?: string;
    method?: 'GET' | 'POST';
    input?: FhirResource | SearchParams;
    options?: RequestOptions;
}
/**
 * Parameters for the top-level {@link Client#search} dispatcher.
 * Provide `compartment + resourceType` for compartment search,
 * `resourceType` alone for type-level search, or just `searchParams` for system search.
 */
export interface SearchCallParams {
    resourceType?: string;
    compartment?: {
        resourceType: string;
        id: string;
    };
    searchParams?: SearchParams;
    options?: RequestOptions;
}
export interface ResourceSearchParams {
    resourceType: string;
    searchParams?: SearchParams;
    options?: RequestOptions;
}
export interface SystemSearchParams {
    searchParams?: SearchParams;
    options?: RequestOptions;
}
export interface CompartmentSearchParams {
    resourceType: string;
    compartment: {
        resourceType: string;
        id: string;
    };
    searchParams?: SearchParams;
    options?: RequestOptions;
}
export interface HistoryParams {
    resourceType?: string;
    id?: string;
    options?: RequestOptions;
}
export interface PaginationParams {
    bundle: FhirResource & {
        link: Array<{
            relation: string;
            url: string;
        }>;
    };
    options?: RequestOptions;
}
export interface RawRequestParams {
    method?: HttpMethod;
    options?: RequestOptions;
    body?: unknown;
}
/**
 * FHIR REST client. Provides typed methods for all FHIR interactions.
 *
 * @example
 * ```ts
 * import { Client } from 'fhir-kit-client';
 *
 * const client = new Client({ baseUrl: 'https://r4.smarthealthit.org' });
 * const patient = await client.read({ resourceType: 'Patient', id: '123' });
 * ```
 */
export declare class Client {
    /** Underlying HTTP client — exposed for advanced use cases. */
    readonly httpClient: HttpClient;
    /** Pagination helper. */
    readonly pagination: Pagination;
    private readonly resolver;
    /**
     * @param config - Client configuration. `baseUrl` is required.
     * @throws If `baseUrl` is blank or not a string.
     */
    constructor({ baseUrl, customHeaders, requestOptions, requestSigner, bearerToken }?: ClientConfig);
    /**
     * Return the raw `Request` and `Response` objects attached to a FHIR
     * response value by the HTTP layer.
     *
     * @param requestResponse - A FHIR resource returned by any client method.
     * @returns `{ request, response }` — either may be `undefined` for synthetic responses.
     */
    static httpFor(requestResponse: FhirResource): {
        request: Request | undefined;
        response: Response | undefined;
    };
    /** FHIR server base URL. */
    get baseUrl(): string;
    set baseUrl(url: string);
    /** Custom headers sent with every request. */
    get customHeaders(): Record<string, string>;
    set customHeaders(headers: Record<string, string>);
    /** Set the OAuth2 bearer token used for Authorization headers. */
    set bearerToken(token: string);
    /**
     * Resolve a FHIR reference to a resource.
     *
     * - **Absolute URL** (`http://...`): fetches directly or creates a new client for a foreign base URL.
     * - **Relative URL** (`Patient/123`): fetches from this client's `baseUrl`.
     * - **Contained reference** (`#id`): resolved from `context.contained[]`.
     * - **Bundle-scoped reference**: resolved from `context.entry[].fullUrl`.
     *
     * @param params.reference - The reference string to resolve.
     * @param params.context - Optional Bundle or resource that may contain the referenced resource.
     * @param params.options - Per-request options.
     * @returns The resolved FHIR resource.
     */
    resolve({ reference, context, options, }: {
        reference: string;
        context?: FhirResource;
        options?: RequestOptions;
    }): Promise<FhirResource>;
    /**
     * Fetch SMART OAuth 2.0 authorization metadata from the server.
     *
     * Races three sources simultaneously and resolves with the first successful
     * response: `.well-known/smart-configuration`, `metadata` (CapabilityStatement),
     * and `.well-known/openid-configuration`. Rejects only if all three fail.
     *
     * @param params.options - Per-request options.
     * @returns SMART auth metadata containing `authorizeUrl`, `tokenUrl`, etc.
     */
    smartAuthMetadata({ options }?: {
        options?: RequestOptions;
    }): Promise<SmartAuthMetadata>;
    /**
     * Fetch the server's CapabilityStatement.
     *
     * @param options - Per-request options.
     * @returns The CapabilityStatement resource.
     */
    capabilityStatement(options?: RequestOptions): Promise<FhirResource>;
    /**
     * Execute a raw request against the FHIR server. Useful for endpoints not
     * covered by higher-level methods.
     *
     * @param requestUrl - Path or absolute URL to request.
     * @param params.method - HTTP method (default: `'GET'`).
     * @param params.options - Per-request options.
     * @param params.body - Request body (will be JSON-serialized if an object).
     * @returns The parsed FHIR response.
     *
     * @example
     * ```ts
     * client.request('Patient/123')
     * client.request('Patient/123', { method: 'DELETE' })
     * client.request('Patient', { method: 'POST', body: newPatient })
     * ```
     */
    request(requestUrl: string, { method, options, body }?: RawRequestParams): Promise<FhirResource>;
    /**
     * Read a resource by type and id (FHIR `read` interaction).
     *
     * @param params.resourceType - FHIR resource type (e.g. `'Patient'`).
     * @param params.id - Resource id.
     * @param params.options - Per-request options.
     * @returns The requested resource.
     * @throws If `resourceType` is invalid or the server returns an error.
     */
    read({ resourceType, id, options }: ReadParams): Promise<FhirResource>;
    /**
     * Read a specific version of a resource (FHIR `vread` interaction).
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.id - Resource id.
     * @param params.version - Version id.
     * @param params.options - Per-request options.
     * @returns The specified version of the resource.
     * @throws If `resourceType` is invalid or the server returns an error.
     */
    vread({ resourceType, id, version, options }: VreadParams): Promise<FhirResource>;
    /**
     * Create a new resource (FHIR `create` interaction).
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.body - The resource to create.
     * @param params.options - Per-request options.
     * @returns The created resource (with server-assigned id).
     * @throws If `resourceType` is invalid or the server returns an error.
     */
    create({ resourceType, body, options }: CreateParams): Promise<FhirResource>;
    /**
     * Delete a resource by type and id (FHIR `delete` interaction).
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.id - Resource id.
     * @param params.options - Per-request options.
     * @returns The server's response (often an OperationOutcome).
     * @throws If `resourceType` is invalid or the server returns an error.
     */
    delete({ resourceType, id, options }: DeleteParams): Promise<FhirResource>;
    /**
     * Update a resource (FHIR `update` interaction).
     *
     * Supports conditional update via `searchParams` (sets the `If-Match`
     * criteria). Provide either `id` or `searchParams`, not both.
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.id - Resource id (mutually exclusive with `searchParams`).
     * @param params.searchParams - Conditional update criteria (mutually exclusive with `id`).
     * @param params.body - The updated resource.
     * @param params.options - Per-request options.
     * @returns The updated resource.
     * @throws If `resourceType` is invalid, both or neither of `id`/`searchParams` are provided,
     *   or the server returns an error.
     */
    update({ resourceType, id, searchParams, body, options }: UpdateParams): Promise<FhirResource>;
    /**
     * Patch a resource using JSON Patch (RFC 6902) (FHIR `patch` interaction).
     *
     * Sends `Content-Type: application/json-patch+json`.
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.id - Resource id.
     * @param params.jsonPatch - Array of RFC 6902 patch operations.
     * @param params.options - Per-request options.
     * @returns The patched resource.
     * @throws If `resourceType` is invalid or the server returns an error.
     */
    patch({ resourceType, id, jsonPatch, options }: PatchParams): Promise<FhirResource>;
    /**
     * Submit a batch Bundle (FHIR `batch` interaction).
     *
     * The `body.type` field must be `'batch'`. Each entry is processed
     * independently; partial failures are reported per-entry in the response.
     *
     * @param params.body - A FHIR Bundle resource with `type: 'batch'`.
     * @param params.options - Per-request options.
     * @returns The batch response Bundle.
     */
    batch({ body, options }: BundleParams): Promise<FhirResource>;
    /**
     * Submit a transaction Bundle (FHIR `transaction` interaction).
     *
     * The `body.type` field must be `'transaction'`. All entries succeed or
     * fail together (atomic).
     *
     * @param params.body - A FHIR Bundle resource with `type: 'transaction'`.
     * @param params.options - Per-request options.
     * @returns The transaction response Bundle.
     */
    transaction({ body, options }: BundleParams): Promise<FhirResource>;
    /**
     * Invoke a FHIR operation (`$name`) at the system, type, or instance level.
     *
     * @param params.name - Operation name with or without leading `$`.
     * @param params.resourceType - Scopes the operation to a resource type (type/instance level).
     * @param params.id - Scopes the operation to a specific instance (instance level).
     * @param params.method - `'GET'` or `'POST'` (default: `'POST'`).
     * @param params.input - Parameters resource (POST) or query parameters (GET).
     * @param params.options - Per-request options.
     * @returns The operation output resource.
     */
    operation({ name, resourceType, id, method, input, options }: OperationParams): Promise<FhirResource>;
    /**
     * Return the next page of a Bundle search result.
     *
     * @param params.bundle - A Bundle with a `link` array containing a `next` relation.
     * @param params.options - Per-request options.
     * @returns The next page Bundle, or `undefined` if there is no next page.
     */
    nextPage({ bundle, options }: PaginationParams): Promise<FhirResource> | undefined;
    /**
     * Return the previous page of a Bundle search result.
     *
     * @param params.bundle - A Bundle with a `link` array containing a `previous` relation.
     * @param params.options - Per-request options.
     * @returns The previous page Bundle, or `undefined` if there is no previous page.
     */
    prevPage({ bundle, options }: PaginationParams): Promise<FhirResource> | undefined;
    /**
     * Search for resources. Dispatches to the appropriate search variant based on parameters:
     *
     * - `compartment + resourceType` → compartment search
     * - `resourceType` only → type-level search
     * - `searchParams` only → system-wide search
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.compartment - Compartment `{ resourceType, id }`.
     * @param params.searchParams - Search query parameters.
     * @param params.options - Per-request options. Set `postSearch: true` to use POST.
     * @returns A search result Bundle.
     * @throws If `resourceType` is invalid or insufficient parameters are provided.
     */
    search({ resourceType, compartment, searchParams, options }?: SearchCallParams): Promise<FhirResource>;
    /**
     * Search within a specific resource type (FHIR type-level search).
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.searchParams - Query parameters.
     * @param params.options - Per-request options. Set `postSearch: true` to POST to `_search`.
     * @returns A search result Bundle.
     */
    resourceSearch({ resourceType, searchParams, options }: ResourceSearchParams): Promise<FhirResource>;
    /**
     * System-wide search across all resource types.
     *
     * @param params.searchParams - Query parameters.
     * @param params.options - Per-request options. Set `postSearch: true` to POST to `/_search`.
     * @returns A search result Bundle.
     */
    systemSearch({ searchParams, options }?: SystemSearchParams): Promise<FhirResource>;
    /**
     * Search within a FHIR compartment.
     *
     * @param params.resourceType - Resource type to search within the compartment.
     * @param params.compartment - Compartment `{ resourceType, id }`.
     * @param params.searchParams - Query parameters.
     * @param params.options - Per-request options.
     * @returns A search result Bundle.
     */
    compartmentSearch({ resourceType, compartment, searchParams, options, }: CompartmentSearchParams): Promise<FhirResource>;
    private baseSearch;
    /**
     * Retrieve history. Dispatches to instance-, type-, or system-level history
     * based on the parameters provided.
     *
     * @param params.resourceType - Scopes to type or instance history.
     * @param params.id - Combined with `resourceType` for instance history.
     * @param params.options - Per-request options.
     * @returns A history Bundle.
     */
    history({ resourceType, id, options }?: HistoryParams): Promise<FhirResource>;
    /**
     * Instance-level history for a specific resource.
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.id - Resource id.
     * @param params.options - Per-request options.
     * @returns A history Bundle.
     */
    resourceHistory({ resourceType, id, options, }: {
        resourceType: string;
        id: string;
        options?: RequestOptions;
    }): Promise<FhirResource>;
    /**
     * Type-level history for all instances of a resource type.
     *
     * @param params.resourceType - FHIR resource type.
     * @param params.options - Per-request options.
     * @returns A history Bundle.
     */
    typeHistory({ resourceType, options }: {
        resourceType: string;
        options?: RequestOptions;
    }): Promise<FhirResource>;
    /**
     * System-level history across all resource types.
     *
     * @param params.options - Per-request options.
     * @returns A history Bundle.
     */
    systemHistory({ options }?: {
        options?: RequestOptions;
    }): Promise<FhirResource>;
}
//# sourceMappingURL=client.d.ts.map