@vahidkaargar/customized-api-client 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+import { AxiosRequestConfig, InternalAxiosRequestConfig, AxiosResponse, AxiosInstance } from 'axios';
+
+/** Mode B (default): `baseURL` already includes `/api/v1`. Mode A: origin only; client prefixes `/api/v1`. */
+type BaseUrlMode = 'modeB' | 'modeA';
+type AuthConfig = {
+    readonly type: 'bearer';
+    readonly getToken: TokenProvider;
+} | {
+    readonly type: 'partner-bearer';
+    readonly getSecret: TokenProvider;
+};
+type TokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
+type TransformResponseKeysMode = 'none' | 'camelCase-attributes-meta';
+interface RetryOptions {
+    readonly maxAttempts?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: number;
+    readonly jitterRatio?: number;
+}
+interface IdempotencyReplayContext {
+    readonly url?: string;
+    readonly method?: string;
+}
+interface ApiClientConfig {
+    readonly baseURL: string;
+    /** Default Mode B — see `BaseUrlMode`. */
+    readonly baseUrlMode?: BaseUrlMode;
+    readonly auth?: AuthConfig;
+    readonly getAcceptLanguage?: () => string | null | undefined | Promise<string | null | undefined>;
+    readonly defaultHeaders?: Readonly<Record<string, string>>;
+    readonly timeout?: number;
+    readonly retry?: RetryOptions;
+    readonly generateIdempotencyKey?: () => string;
+    readonly onIdempotencyReplay?: (ctx: Readonly<IdempotencyReplayContext>) => void;
+    readonly onUnauthorized?: (error: unknown) => void | Promise<void>;
+    readonly onDeprecated?: (info: Readonly<DeprecationInfo>) => void;
+    readonly transformResponseKeys?: TransformResponseKeysMode;
+    readonly maxBodyLogLength?: number;
+}
+interface DeprecationInfo {
+    readonly deprecation?: string;
+    readonly sunset?: string;
+    readonly rawHeaders: Readonly<Record<string, string>>;
+}
+declare const DEFAULT_TIMEOUT_MS = 30000;
+declare const DEFAULT_PAGE_SIZE_CAP = 100;
+
+/**
+ * Minimal JSON:API wire shapes used by the client (snake_case on wire).
+ */
+interface JsonApiResourceLinkage {
+    readonly type: string;
+    readonly id: string;
+}
+interface JsonApiResourceObject {
+    readonly type: string;
+    readonly id: string;
+    readonly attributes?: Record<string, unknown>;
+    readonly relationships?: Record<string, unknown>;
+    readonly meta?: Record<string, unknown>;
+    readonly links?: Record<string, string | null | undefined>;
+}
+type JsonApiPrimaryData = JsonApiResourceObject | readonly JsonApiResourceObject[] | null;
+interface JsonApiDocument<TData extends JsonApiPrimaryData = JsonApiPrimaryData> {
+    readonly data: TData;
+    readonly included?: readonly JsonApiResourceObject[];
+    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly links?: Readonly<Record<string, string | null | undefined>>;
+}
+interface JsonApiErrorObject {
+    readonly id?: string;
+    readonly status?: string;
+    readonly code?: string;
+    readonly title?: string;
+    readonly detail?: string;
+    readonly source?: {
+        readonly pointer?: string;
+        readonly parameter?: string;
+    };
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+interface JsonApiErrorDocument {
+    readonly errors: readonly JsonApiErrorObject[];
+}
+
+/** Normalized subset of interesting response headers */
+interface NormalizedResponseHeaders {
+    readonly etag?: string;
+    readonly contentLanguage?: string;
+    readonly idempotentReplayed: boolean;
+    readonly retryAfterSeconds?: number;
+}
+interface JsonApiSuccessBody {
+    readonly kind: 'jsonapi-success';
+    readonly status: 200 | 201;
+    readonly headers: NormalizedResponseHeaders;
+    readonly document: JsonApiDocument;
+}
+interface NoContentBody {
+    readonly kind: 'no-content';
+    readonly status: 204;
+    readonly headers: NormalizedResponseHeaders;
+}
+interface AcceptedBody {
+    readonly kind: 'accepted';
+    readonly status: 202;
+    readonly location: string;
+    readonly rawBody?: unknown;
+    readonly headers: NormalizedResponseHeaders;
+}
+interface MultiStatusItem {
+    readonly httpStatus: number;
+    readonly body?: unknown;
+}
+interface MultiStatusBody {
+    readonly kind: 'multi-status';
+    readonly status: 207;
+    readonly items: readonly MultiStatusItem[];
+    readonly headers: NormalizedResponseHeaders;
+}
+type ClientSuccess = JsonApiSuccessBody | NoContentBody | AcceptedBody | MultiStatusBody;
+interface OkResult<T extends ClientSuccess> {
+    readonly ok: true;
+    readonly value: T;
+}
+interface ErrResult<E> {
+    readonly ok: false;
+    readonly error: E;
+}
+type Result<T extends ClientSuccess, E> = OkResult<T> | ErrResult<E>;
+
+declare class ApiClientError extends Error {
+    #private;
+    readonly status: number;
+    readonly errors: readonly JsonApiErrorObject[];
+    readonly primaryCode?: string | undefined;
+    readonly responseHeaders?: Readonly<Record<string, string>> | undefined;
+    readonly retryAfterSeconds?: number | undefined;
+    readonly requestMethod?: string | undefined;
+    readonly name = "ApiClientError";
+    constructor(status: number, errors: readonly JsonApiErrorObject[], primaryCode?: string | undefined, responseHeaders?: Readonly<Record<string, string>> | undefined, retryAfterSeconds?: number | undefined, requestMethod?: string | undefined, options?: ErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+declare function isApiClientError(value: unknown): value is ApiClientError;
+
+interface RequestCallOptions {
+    readonly idempotencyKey?: string;
+    readonly ifMatchVersion?: number;
+}
+interface ApiClient {
+    readonly get: (path: string, opts?: RequestCallOptions) => Promise<ClientSuccess>;
+    readonly head: (path: string, opts?: RequestCallOptions) => Promise<ClientSuccess>;
+    readonly post: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccess>;
+    readonly patch: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccess>;
+    readonly put: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccess>;
+    readonly delete: (path: string, opts?: RequestCallOptions) => Promise<ClientSuccess>;
+    readonly request: (ax: AxiosRequestConfig, opts?: RequestCallOptions) => Promise<ClientSuccess>;
+    readonly getByUrl: (fullUrl: string, opts?: RequestCallOptions) => Promise<ClientSuccess>;
+    readonly patchWithVersion: (path: string, data: unknown, version: number, opts?: Omit<RequestCallOptions, 'ifMatchVersion'>) => Promise<ClientSuccess>;
+    readonly safeGet: (path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
+    readonly safePost: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
+    readonly safePatch: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
+    readonly safePut: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
+    readonly safeDelete: (path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
+    readonly safeHead: (path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
+    readonly safeRequest: (ax: AxiosRequestConfig, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
+}
+declare function createApiClient(config: ApiClientConfig): ApiClient;
+
+declare function isAuthenticationError(e: unknown): boolean;
+declare function isForbiddenError(e: unknown): boolean;
+declare function isPreconditionRequiredError(e: unknown): boolean;
+declare function isPreconditionFailedError(e: unknown): boolean;
+declare function isValidationError(e: unknown): boolean;
+declare function isConflictError(e: unknown): boolean;
+declare function isPayloadTooLargeError(e: unknown): boolean;
+declare function isRetryablePerPolicy(e: unknown): boolean;
+
+/**
+ * Truncate a value for safe logging (respects `maxBodyLogLength` from config when passed).
+ */
+declare function truncateForLog(body: unknown, maxLen?: number): string;
+/**
+ * Redact sensitive header values for logging and error surfaces.
+ */
+declare function redactHeaderRecord(headers: Record<string, string>): Record<string, string>;
+
+declare function applyJsonApiHeaders(config: InternalAxiosRequestConfig, method: string): InternalAxiosRequestConfig;
+
+declare const IDEMPOTENCY_MAX_LENGTH = 64;
+declare function defaultIdempotencyKey(): string;
+declare function assertValidIdempotencyKey(key: string): void;
+declare function isMutationMethod(method: string): boolean;
+
+declare function formatIfMatch(version: number): string;
+
+declare function resolveAcceptLanguage(provider?: () => string | null | undefined | Promise<string | null | undefined>): Promise<string | undefined>;
+
+declare function resolveAuthorizationHeader(auth: AuthConfig | undefined): Promise<string | undefined>;
+
+/**
+ * Path for axios `url` (combined with `baseURL`). No duplicate `/api/v1`, no `//`.
+ */
+declare function resolveResourcePath(baseURL: string, path: string, mode: BaseUrlMode): string;
+/**
+ * Prepare request URL for axios — if `fullUrl` is absolute http(s), return as-is for getByUrl.
+ */
+declare function normalizeHttpUrl(fullUrl: string): string;
+
+declare function parseJsonApiDocument(payload: unknown): JsonApiDocument;
+
+declare function parseJsonApiErrorBody(status: number, rawBody: unknown, headers: Readonly<Record<string, string>>, requestMethod?: string): ApiClientError;
+
+/**
+ * Best-effort normalization for 207 bodies — structure varies by backend.
+ */
+declare function parseMultiStatusBody(raw: unknown): readonly MultiStatusItem[];
+
+type HeadersLike = Headers | Record<string, string | undefined>;
+declare function flattenAxiosHeaders(headers: unknown): Record<string, string>;
+declare function getHeader(headers: Record<string, string>, name: string): string | undefined;
+
+/**
+ * Resolve absolute Location for 202 per project-plan (relative to response URL when needed).
+ */
+declare function resolveAcceptedLocation(headers: HeadersLike, requestUrl: string): string;
+
+interface OffsetPagination {
+    readonly kind: 'offset';
+    readonly page: number;
+    readonly totalPages?: number;
+    readonly total?: number;
+}
+interface CursorPagination {
+    readonly kind: 'cursor';
+    readonly hasMore: boolean;
+    readonly nextCursor?: string;
+}
+interface UnknownPagination {
+    readonly kind: 'unknown';
+}
+declare function parsePaginationKind(meta: Readonly<Record<string, unknown>> | undefined, links: Readonly<Record<string, string | null | undefined>> | undefined): OffsetPagination | CursorPagination | UnknownPagination;
+declare function getNextPageUrl(links: Readonly<Record<string, string | null | undefined>> | undefined): string | undefined;
+
+interface NormalizeOptions {
+    readonly transformResponseKeys?: TransformResponseKeysMode;
+    readonly requestUrl: string;
+    readonly requestMethod?: string;
+}
+declare function normalizeAxiosResponse(response: AxiosResponse<unknown>, options: NormalizeOptions): ClientSuccess;
+
+interface RetryPolicyContext {
+    readonly method: string;
+    readonly status?: number;
+    /** First JSON:API error `code` when present */
+    readonly primaryErrorCode?: string;
+    readonly isNetworkError: boolean;
+}
+/** Pure policy per [.cursor/tasks/project-plan.md §7](../tasks/project-plan.md). */
+declare function retryAllowed(ctx: RetryPolicyContext): boolean;
+
+/** Parse Retry-After header: delta-seconds or HTTP-date. */
+declare function parseRetryAfterSeconds(value: string | undefined): number | undefined;
+
+interface DispatchOptions {
+    readonly retry?: RetryOptions;
+    readonly getPrimaryErrorCodeFromBody?: (body: unknown) => string | undefined;
+}
+declare function dispatchWithRetry<TData = unknown>(instance: AxiosInstance, config: AxiosRequestConfig, options: DispatchOptions): Promise<AxiosResponse<TData>>;
+
+interface JsonApiQueryInput {
+    readonly filter?: Readonly<Record<string, string | number | boolean | undefined>>;
+    readonly sort?: readonly string[];
+    readonly fields?: Readonly<Record<string, readonly string[]>>;
+    readonly include?: readonly string[];
+}
+declare function buildJsonApiQuery(input: JsonApiQueryInput): Record<string, string>;
+declare function buildOffsetPageParams(input: {
+    readonly number: number;
+    readonly size: number;
+}): Record<string, string | number>;
+declare function buildCursorPageParams(input: {
+    readonly cursor: string;
+    readonly size: number;
+}): Record<string, string | number>;
+
+type IncludedIndex = ReadonlyMap<string, JsonApiResourceObject>;
+declare function indexIncluded(included: readonly JsonApiResourceObject[] | undefined): IncludedIndex;
+declare function resolveIncluded(ref: JsonApiResourceLinkage, index: IncludedIndex): JsonApiResourceObject | undefined;
+
+declare function readResourceVersion(resource: JsonApiResourceObject, etagHeader?: string): number | undefined;
+declare function etagFromResponseHeaders(headerBag: unknown): string | undefined;
+
+type ValidationGroups = Record<string, readonly string[]>;
+declare function groupValidationErrorsByPointer(errors: readonly JsonApiErrorObject[]): ValidationGroups;
+
+declare function createHealthCheck(target: ApiClientConfig | Pick<HealthGettable, 'get'>): () => Promise<boolean>;
+interface HealthGettable {
+    get: (path: string) => Promise<unknown>;
+}
+
+declare function parseDeprecationHeaders(headerBag: unknown): DeprecationInfo | null;
+
+/** Shallow camelCase keys for `attributes` and `meta` only — copies document where needed. */
+declare function applyTransformKeys(doc: JsonApiDocument, mode: TransformResponseKeysMode): JsonApiDocument;
+
+interface PollOptions {
+    readonly maxAttempts?: number;
+    readonly delayMs?: number;
+}
+declare function pollAsyncResult(client: ApiClient, initial: Extract<ClientSuccess, {
+    kind: 'accepted';
+}>, options?: PollOptions): Promise<ClientSuccess>;
+
+declare const PACKAGE_VERSION: string;
+
+export { type AcceptedBody, type ApiClient, type ApiClientConfig, ApiClientError, type AuthConfig, type BaseUrlMode, type ClientSuccess, type CursorPagination, DEFAULT_PAGE_SIZE_CAP, DEFAULT_TIMEOUT_MS, type DeprecationInfo, type ErrResult, IDEMPOTENCY_MAX_LENGTH, type IdempotencyReplayContext, type IncludedIndex, type JsonApiDocument, type JsonApiErrorDocument, type JsonApiErrorObject, type JsonApiPrimaryData, type JsonApiQueryInput, type JsonApiResourceLinkage, type JsonApiResourceObject, type JsonApiSuccessBody, type MultiStatusBody, type MultiStatusItem, type NoContentBody, type NormalizedResponseHeaders, type OffsetPagination, type OkResult, PACKAGE_VERSION, type PollOptions, type RequestCallOptions, type Result, type RetryOptions, type TokenProvider, type TransformResponseKeysMode, type UnknownPagination, type ValidationGroups, applyJsonApiHeaders, applyTransformKeys, assertValidIdempotencyKey, buildCursorPageParams, buildJsonApiQuery, buildOffsetPageParams, createApiClient, createHealthCheck, defaultIdempotencyKey, dispatchWithRetry, etagFromResponseHeaders, flattenAxiosHeaders, formatIfMatch, getHeader, getNextPageUrl, groupValidationErrorsByPointer, indexIncluded, isApiClientError, isAuthenticationError, isConflictError, isForbiddenError, isMutationMethod, isPayloadTooLargeError, isPreconditionFailedError, isPreconditionRequiredError, isRetryablePerPolicy, isValidationError, normalizeAxiosResponse, normalizeHttpUrl, parseDeprecationHeaders, parseJsonApiDocument, parseJsonApiErrorBody, parseMultiStatusBody, parsePaginationKind, parseRetryAfterSeconds, pollAsyncResult, readResourceVersion, redactHeaderRecord, resolveAcceptLanguage, resolveAcceptedLocation, resolveAuthorizationHeader, resolveIncluded, resolveResourcePath, retryAllowed, truncateForLog };